curryer.correction.psf
======================

.. py:module:: curryer.correction.psf


Attributes
----------

.. autoapisummary::

   curryer.correction.psf.logger


Functions
---------

.. autoapisummary::

   curryer.correction.psf.centroid
   curryer.correction.psf.project_psf
   curryer.correction.psf.convolve_gcp_with_psf
   curryer.correction.psf.convolve_psf_with_spacecraft_motion
   curryer.correction.psf.zero_pad_psf
   curryer.correction.psf.resample_psf_to_gcp_resolution
   curryer.correction.psf.normalize_psf


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

.. py:data:: logger

.. py:function:: centroid(weights: numpy.ndarray) -> float

   Compute center-of-mass index for a one-dimensional weight vector.

   :param weights: One-dimensional weight array.
   :type weights: np.ndarray

   :returns: Center-of-mass index position.
   :rtype: float

   :raises ValueError: If weight vector has zero total mass.


.. py:function:: project_psf(r_iss_ctrs_m: numpy.ndarray, optical_psfs: collections.abc.Iterable[curryer.correction.data_structures.OpticalPSFEntry], subimage: curryer.correction.data_structures.ImageGrid, los_set_hs: numpy.ndarray) -> curryer.correction.data_structures.ProjectedPSF

   Project optical PSF onto Earth's surface using vectorized ray tracing.

   :param r_iss_ctrs_m: Spacecraft position in ECEF coordinates, shape (3,), units: meters.
   :type r_iss_ctrs_m: np.ndarray
   :param optical_psfs: Collection of optical PSF samples at different field angles.
   :type optical_psfs: Iterable[OpticalPSFEntry]
   :param subimage: Image grid defining the observation geometry.
   :type subimage: ImageGrid
   :param los_set_hs: Line-of-sight unit vectors in instrument frame, shape (n_pixels, 3).
   :type los_set_hs: np.ndarray

   :returns: PSF projected onto Earth's surface with lat, lon, height grids.
   :rtype: ProjectedPSF

   :raises ValueError: If no optical PSF entries provided.
   :raises RuntimeError: If ray-ellipsoid intersection fails.


.. py:function:: convolve_gcp_with_psf(gcp: curryer.correction.data_structures.ImageGrid, psf: curryer.correction.data_structures.PSFGrid) -> curryer.correction.data_structures.ImageGrid

   Convolve GCP reference image with dynamic PSF using FFT.

   :param gcp: Ground control point reference image.
   :type gcp: ImageGrid
   :param psf: Point spread function to convolve with.
   :type psf: PSFGrid

   :returns: Convolved GCP image with same coordinate grids.
   :rtype: ImageGrid


.. py:function:: convolve_psf_with_spacecraft_motion(psf: curryer.correction.data_structures.ProjectedPSF, composite_img: curryer.correction.data_structures.ImageGrid, config: curryer.correction.data_structures.GeolocationConfig) -> curryer.correction.data_structures.PSFGrid

   Apply spacecraft motion blur to projected PSF.

   :param psf: Projected PSF on Earth's surface.
   :type psf: ProjectedPSF
   :param composite_img: Composite image defining spacecraft motion direction.
   :type composite_img: ImageGrid
   :param config: Configuration with PSF sampling parameters.
   :type config: GeolocationConfig

   :returns: PSF convolved with spacecraft motion blur.
   :rtype: PSFGrid


.. py:function:: zero_pad_psf(psf: curryer.correction.data_structures.PSFGrid) -> curryer.correction.data_structures.PSFGrid

   Zero-pad PSF to center its centroid on the grid.

   :param psf: Point spread function on rectilinear grid.
   :type psf: PSFGrid

   :returns: Zero-padded PSF with centered centroid.
   :rtype: PSFGrid

   :raises ValueError: If PSF lat/lon are not one-dimensional.


.. py:function:: resample_psf_to_gcp_resolution(psf: curryer.correction.data_structures.PSFGrid, gcp: curryer.correction.data_structures.ImageGrid) -> curryer.correction.data_structures.PSFGrid

   Resample PSF to match GCP reference image resolution.

   :param psf: Point spread function on rectilinear grid.
   :type psf: PSFGrid
   :param gcp: Ground control point reference defining target resolution.
   :type gcp: ImageGrid

   :returns: Resampled PSF at GCP resolution.
   :rtype: PSFGrid

   :raises ValueError: If PSF is not on a rectilinear grid.


.. py:function:: normalize_psf(psf: curryer.correction.data_structures.PSFGrid) -> curryer.correction.data_structures.PSFGrid

   Normalize PSF to unit total power.

   :param psf: Point spread function to normalize.
   :type psf: PSFGrid

   :returns: Normalized PSF with total power = 1.
   :rtype: PSFGrid

   :raises ValueError: If PSF has zero total power.