coronalyze.core.geometry
========================

.. py:module:: coronalyze.core.geometry

.. autoapi-nested-parse::

   Geometric utilities for coronagraphic image analysis.

   Functions for coordinate transforms, distance calculations, and generating
   aperture positions with static array shapes for JAX compatibility.



Functions
---------

.. autoapisummary::

   coronalyze.core.geometry.get_center
   coronalyze.core.geometry.radial_distance
   coronalyze.core.geometry.calculate_n_apertures
   coronalyze.core.geometry.generate_aperture_coords


Module Contents
---------------

.. py:function:: get_center(shape)

   Get the center coordinates of an image (0-indexed geometric center).

   For an image of size N, the geometric center is at (N-1)/2.
   This matches the convention used in modeling.py for planet injection.

   Args:
       shape: Image shape (ny, nx).

   Returns:
       Center coordinates (cy, cx).


.. py:function:: radial_distance(shape, center = None)

   Calculate radial distance from center for each pixel.

   Args:
       shape: Image shape (ny, nx).
       center: Center coordinates (cy, cx). If None, uses image center.

   Returns:
       2D array of radial distances in pixels.


.. py:function:: calculate_n_apertures(radius, fwhm, exclusion_buffer = 0.5)

   Calculate the number of reference apertures at a given radius.

   Uses the Mawet et al. (2014) formula with exclusion buffer correction
   to ensure no overlap with the planet aperture on either side.

   This function provides the canonical calculation used by the SNR module,
   ensuring consistency between visualization and computation.

   Args:
       radius: Radial distance from center in pixels.
       fwhm: Full width at half maximum in pixels.
       exclusion_buffer: Gap between planet and first/last reference aperture
           in units of angular step (default 0.5). Creates a gap on both sides.

   Returns:
       Number of valid reference apertures.

   Example::

       from coronalyze.core.geometry import calculate_n_apertures
       n = calculate_n_apertures(radius=20, fwhm=5.0)
       print(f"{n} reference apertures at r=20px")


.. py:function:: generate_aperture_coords(center, radius, planet_angle, n_apertures, max_apertures = 200, fwhm = None, exclusion_buffer = 0.5)

   Generate coordinates for reference apertures at a given radius.

   Uses a fixed-size array with masking for JAX compatibility (static shapes).
   Apertures are distributed evenly around the annulus, excluding the planet position.

   Matches VIP's clockwise rotation and angle formula from planet position.

   Args:
       center: Image center (cy, cx) in pixels.
       radius: Radial distance from center in pixels.
       planet_angle: Angle of the planet position in radians.
       n_apertures: Actual number of valid apertures to use.
       max_apertures: Maximum buffer size for static array shape.
       fwhm: Full width half maximum for VIP-style angle calculation. If None,
             uses uniform distribution.
       exclusion_buffer: Gap between test and first reference aperture in
           units of angular step (default 0.0). Prevents PSF wing leakage.

   Returns:
       Tuple of (y_coords, x_coords, mask) where:
           - y_coords: Y coordinates of aperture centers (size max_apertures)
           - x_coords: X coordinates of aperture centers (size max_apertures)
           - mask: Boolean mask indicating valid apertures