Merge pull request #225 from Jammy2211/feature/documentation-geometry

docs: refactor and complete docstrings for autoarray/geometry

Author: Jammy2211

autoarray/geometry/abstract_2d.py

@@ -5,15 +5,28 @@
 class AbstractGeometry2D:
     @property
     def extent(self) -> Tuple[float, float, float, float]:
+        """
+        The extent of the 2D geometry in scaled units, returned as (x_min, x_max, y_min, y_max).
+
+        This format matches the ``extent`` argument of ``matplotlib.pyplot.imshow``, with x and y
+        swapped relative to the usual (y,x) PyAutoArray convention. Subclasses must implement this.
+        """
         raise NotImplementedError
 
     @property
     def extent_square(self) -> Tuple[float, float, float, float]:
         """
-        Returns an extent where the y and x distances are the same.
+        The extent of the 2D geometry in scaled units, expanded so that the y and x ranges are equal.
+
+        This ensures that a uniform grid with square pixels can be laid over this extent, which is
+        useful for constructing interpolation grids used in visualization. The centre of the extent
+        is preserved; whichever axis has the smaller range is expanded symmetrically to match the
+        larger one.
 
-        This ensures that a uniform grid with square pixels can be laid over this extent, such that an
-        `interpolation_grid` can be computed which has square pixels. This benefits visualization.
+        Returns
+        -------
+        (x_min, x_max, y_min, y_max)
+            The square extent in scaled units following the matplotlib ``imshow`` convention.
         """
 
         y_mean = 0.5 * (self.extent[2] + self.extent[3])

autoarray/geometry/geometry_2d.py

@@ -121,8 +121,15 @@ def central_pixel_coordinates(self) -> Tuple[float, float]:
     @property
     def central_scaled_coordinates(self) -> Tuple[float, float]:
         """
-        Returns the central scaled coordinates of a 2D geometry (and therefore a 2D data structure like an ``Array2D``)
-        from the shape of that data structure.
+        The central (y,x) coordinates of the 2D geometry in scaled units.
+
+        Computed from the shape and pixel scales of the geometry, shifted by the origin. This is
+        the scaled-unit coordinate that sits at the geometric centre of the grid.
+
+        Returns
+        -------
+        Tuple[float, float]
+            The (y,x) scaled coordinates of the geometric centre.
         """
         return geometry_util.central_scaled_coordinate_2d_from(
             shape_native=self.shape_native,
@@ -134,24 +141,25 @@ def pixel_coordinates_2d_from(
         self, scaled_coordinates_2d: Tuple[float, float]
     ) -> Tuple[int, int]:
         """
-        Convert a 2D (y,x) scaled coordinate to a 2D (y,x) pixel coordinate, which are returned as integers such that
-        they do not include the decimal offset from each pixel's top-left corner relative to the input scaled coordinate.
+        Convert a 2D (y,x) scaled coordinate to a 2D (y,x) pixel coordinate, returned as integers that
+        identify the pixel containing the scaled coordinate (without sub-pixel decimal offsets).
 
-        The conversion is performed according to the 2D geometry on a uniform grid, where the pixel coordinate origin
-        is at the top left corner, such that the pixel [0,0] corresponds to the highest (most positive) y scaled
-        coordinate and lowest (most negative) x scaled coordinate on the gird.
+        The conversion is performed according to the 2D geometry on a uniform grid, where the pixel
+        coordinate origin is at the top-left corner, such that pixel [0,0] corresponds to the highest
+        (most positive) y scaled coordinate and lowest (most negative) x scaled coordinate on the grid.
 
-        The scaled coordinate is defined by an origin and coordinates are shifted to this origin before computing their
-        1D grid pixel coordinate values.
+        The geometry's origin is applied so that scaled coordinates are correctly shifted before the
+        pixel index calculation.
 
         Parameters
         ----------
         scaled_coordinates_2d
-            The 2D (y,x) coordinates in scaled units which are converted to pixel coordinates.
+            The 2D (y,x) coordinates in scaled units to convert to pixel coordinates.
 
         Returns
         -------
-        A 2D (y,x) pixel-value coordinate.
+        Tuple[int, int]
+            The 2D (y,x) integer pixel coordinates.
         """
         return geometry_util.pixel_coordinates_2d_from(
             scaled_coordinates_2d=scaled_coordinates_2d,
@@ -164,23 +172,24 @@ def scaled_coordinates_2d_from(
         self, pixel_coordinates_2d: Tuple[float, float]
     ) -> Tuple[float, float]:
         """
-        Convert a 2D (y,x) pixel coordinates to a 2D (y,x) scaled values.
+        Convert a 2D (y,x) pixel coordinate to a 2D (y,x) scaled coordinate.
 
-        The conversion is performed according to a 2D geometry on a uniform grid, where the pixel coordinate origin is at
-        the top left corner, such that the pixel [0,0] corresponds to the highest (most positive) y scaled coordinate
-        and lowest (most negative) x scaled coordinate on the gird.
+        The conversion is performed according to the 2D geometry on a uniform grid, where the pixel
+        coordinate origin is at the top-left corner, such that pixel [0,0] corresponds to the highest
+        (most positive) y scaled coordinate and lowest (most negative) x scaled coordinate on the grid.
 
-        The scaled coordinate is defined by an origin and coordinates are shifted to this origin before computing their
-        1D grid pixel coordinate values.
+        The geometry's origin is applied so that the returned scaled coordinate is correctly shifted
+        relative to the coordinate system's centre.
 
         Parameters
         ----------
-        scaled_coordinates_2d
-            The 2D (y,x) coordinates in scaled units which are converted to pixel coordinates.
+        pixel_coordinates_2d
+            The 2D (y,x) pixel coordinates to convert to scaled units.
 
         Returns
         -------
-        A 2D (y,x) pixel-value coordinate.
+        Tuple[float, float]
+            The 2D (y,x) coordinates in scaled units.
         """
 
         return geometry_util.scaled_coordinates_2d_from(
@@ -266,6 +275,11 @@ def grid_pixels_2d_from(self, grid_scaled_2d: Grid2D) -> Grid2D:
         ----------
         grid_scaled_2d
             A grid of (y,x) coordinates in scaled units.
+
+        Returns
+        -------
+        Grid2D
+            A grid of (y,x) pixel-value coordinates as floats including the sub-pixel decimal offset.
         """
         from autoarray.structures.grids.uniform_2d import Grid2D
 
@@ -283,7 +297,7 @@ def grid_pixel_centres_2d_from(self, grid_scaled_2d: Grid2D) -> Grid2D:
         returned as integers such that they map directly to the pixel they are contained within.
 
         The pixel coordinate origin is at the top left corner of the grid, such that the pixel [0,0] corresponds to
-        higher y scaled coordinate value and lowest x scaled coordinate.
+        highest y scaled coordinate value and lowest x scaled coordinate.
 
         The scaled coordinate origin is defined by the class attribute origin, and coordinates are shifted to this
         origin before computing their 1D grid pixel indexes.
@@ -292,6 +306,12 @@ def grid_pixel_centres_2d_from(self, grid_scaled_2d: Grid2D) -> Grid2D:
         ----------
         grid_scaled_2d
             The grid of (y,x) coordinates in scaled units.
+
+        Returns
+        -------
+        Grid2D
+            A grid of (y,x) integer pixel coordinates identifying which pixel each scaled coordinate
+            falls within.
         """
         from autoarray.structures.grids.uniform_2d import Grid2D
 
@@ -309,7 +329,7 @@ def grid_pixel_indexes_2d_from(self, grid_scaled_2d: Grid2D) -> Array2D:
         Convert a grid of (y,x) scaled coordinates to an array of pixel 1D indexes, which are returned as integers.
 
         The pixel coordinate origin is at the top left corner of the grid, such that the pixel [0,0] corresponds to
-        higher y scaled coordinate value and lowest x scaled coordinate.
+        highest y scaled coordinate value and lowest x scaled coordinate.
 
         For example:
 
@@ -324,6 +344,12 @@ def grid_pixel_indexes_2d_from(self, grid_scaled_2d: Grid2D) -> Array2D:
         ----------
         grid_scaled_2d
             The grid of (y,x) coordinates in scaled units.
+
+        Returns
+        -------
+        Array2D
+            A 1D array of flat pixel indexes, where each value is the integer index of the pixel
+            (counting left-to-right, top-to-bottom) that the corresponding scaled coordinate falls in.
         """
 
         from autoarray.structures.arrays.uniform_2d import Array2D
@@ -342,7 +368,7 @@ def grid_scaled_2d_from(self, grid_pixels_2d: Grid2D) -> Grid2D:
         Convert a grid of (y,x) pixel coordinates to a grid of (y,x) scaled values.
 
         The pixel coordinate origin is at the top left corner of the grid, such that the pixel [0,0] corresponds to
-        higher y scaled coordinate value and lowest x scaled coordinate.
+        highest y scaled coordinate value and lowest x scaled coordinate.
 
         The scaled coordinate origin is defined by the class attribute origin, and coordinates are shifted to this
         origin before computing their 1D grid pixel indexes.
@@ -351,6 +377,11 @@ def grid_scaled_2d_from(self, grid_pixels_2d: Grid2D) -> Grid2D:
         ----------
         grid_pixels_2d
             The grid of (y,x) coordinates in pixels.
+
+        Returns
+        -------
+        Grid2D
+            A grid of (y,x) coordinates in scaled units.
         """
         from autoarray.structures.grids.uniform_2d import Grid2D
 

autoarray/geometry/geometry_2d_irregular.py

@@ -11,18 +11,25 @@ def __init__(
         scaled_minima: Tuple[float, float],
     ):
         """
-        A 2D geometry, representing an irregular grid of (y,x) coordinates.
+        A 2D geometry for an irregular (non-uniform) grid of (y,x) coordinates.
 
-        This class is used for defining the extent of the irregular grid when visualizing it.
+        Unlike `Geometry2D` which is derived from a regular pixel grid with a fixed `shape_native`
+        and `pixel_scales`, this class stores pre-computed extent information directly. It is used
+        by `Grid2DIrregular` and similar structures to define their bounding box for visualization
+        and coordinate-space calculations.
+
+        Because the coordinates are irregular there is no uniform pixel scale, so the geometry
+        is defined purely by the scaled extent (minima, maxima) of the point distribution.
 
         Parameters
         ----------
         shape_native_scaled
-            The 2D scaled shape of the geometry defining the full extent of this object.
+            The (y, x) extent of the geometry in scaled units, i.e.
+            (scaled_maxima[0] - scaled_minima[0], scaled_maxima[1] - scaled_minima[1]).
         scaled_maxima
-            The maximum (y,x) scaled coordinates of the 2D geometry.
+            The maximum (y,x) scaled coordinates of the irregular grid.
         scaled_minima
-            The minimum (y,x) scaled coordinates of the 2D geometry.
+            The minimum (y,x) scaled coordinates of the irregular grid.
         """
         self.shape_native_scaled = shape_native_scaled
         self.scaled_maxima = scaled_maxima