coronalyze.core.photometry
==========================

.. py:module:: coronalyze.core.photometry

.. autoapi-nested-parse::

   Convolution-based aperture photometry for coronagraphic images.

   Provides differentiable aperture kernels (soft and hard) and convolution-based
   flux map generation for efficient photometry calculations.



Functions
---------

.. autoapisummary::

   coronalyze.core.photometry.make_aperture_kernel
   coronalyze.core.photometry.flux_map
   coronalyze.core.photometry.circular_aperture_mask
   coronalyze.core.photometry.soft_aperture_mask
   coronalyze.core.photometry.aperture_photometry
   coronalyze.core.photometry.aperture_solid_angle


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

.. py:function:: make_aperture_kernel(radius, soft = False, sharpness = 10.0)

   Create a circular aperture kernel for convolution-based photometry.

   This function is cached (up to 32 configurations) to avoid repeated
   kernel creation overhead when called with the same parameters.

   Args:
       radius: Aperture radius in pixels.
       soft: If True, use sigmoid-based soft edge for differentiability.
             If False, use hard binary mask.
       sharpness: Steepness of sigmoid transition (only used if soft=True).

   Returns:
       2D aperture kernel. Not normalized (sum of counts, not average).


.. py:function:: flux_map(image, kernel)

   Generate a flux map via convolution with an aperture kernel.

   Each pixel in the output represents the integrated flux that would be
   measured if an aperture were centered at that position.

   Args:
       image: 2D image array.
       kernel: Aperture kernel from make_aperture_kernel.

   Returns:
       2D flux map with same shape as input image.


.. py:function:: circular_aperture_mask(shape, center, radius)

   Create a circular aperture mask.

   Args:
       shape: Image shape (ny, nx).
       center: Center of aperture (y, x) in pixels.
       radius: Radius of aperture in pixels.

   Returns:
       Boolean mask array with True inside the aperture.


.. py:function:: soft_aperture_mask(shape, center, radius, sharpness = 10.0)

   Create a soft (differentiable) circular aperture mask.

   Uses a sigmoid function to create a smooth transition at the aperture
   edge, enabling gradient-based optimization through the mask.

   Args:
       shape: Image shape (ny, nx).
       center: Center of aperture (y, x) in pixels.
       radius: Radius of aperture in pixels.
       sharpness: Steepness of the sigmoid transition.

   Returns:
       Soft mask array with values in [0, 1].


.. py:function:: aperture_photometry(image, center, radius)

   Perform circular aperture photometry on an image.

   Args:
       image: 2D image array.
       center: Center of aperture (y, x) in pixels.
       radius: Radius of aperture in pixels.

   Returns:
       Total flux within the aperture.


.. py:function:: aperture_solid_angle(radius_pixels, pixel_scale_arcsec)

   Calculate the solid angle of a circular aperture.

   Args:
       radius_pixels: Aperture radius in pixels.
       pixel_scale_arcsec: Pixel scale in arcseconds per pixel.

   Returns:
       Solid angle in arcsec^2.