Skip to content

docs: refactor and complete docstrings for autoarray/geometry #225

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jammy2211 merged 1 commit into from
Mar 9, 2026
Merged

docs: refactor and complete docstrings for autoarray/geometry #225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions autoarray/geometry/abstract_2d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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])
Expand Down
77 changes: 54 additions & 23 deletions autoarray/geometry/geometry_2d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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(
Expand Down Expand Up @@ -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

Expand All @@ -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.
Expand All @@ -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

Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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

Expand Down
17 changes: 12 additions & 5 deletions autoarray/geometry/geometry_2d_irregular.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading