opticam.align
=============

.. py:module:: opticam.align


Functions
---------

.. autoapisummary::

   opticam.align.find_translation
   opticam.align.align_batch
   opticam.align.valid_transform


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

.. py:function:: find_translation(reference_coords, coords)

   Find the translation that maps `reference_coords` onto `coords`. An advantage of this over
   `astroalign.find_transform()` is that it requires fewer sources, however it is therefore more prone to errors. In
   general, `astroalign.find_transform()` should be used, but `find_translation()` is available if there are too few
   sources for `astroalign.find_transform()`.

   Parameters
   ----------
   reference_coords : NDArray
       The reference source coordinates.
   coords : NDArray
       The source coordinates.

   Returns
   -------
   SimilarityTransform
       The transformation matrix that maps `coords` onto `reference_coords`.


.. py:function:: align_batch(batch, reference_image_shape, reference_coords, transform_type, rotation_limit, scale_limit, translation_limit, n_alignment_sources, gains, flat_corrector, rebin_factor, remove_cosmic_rays, background, finder, threshold, logger)

   Align an image based on some reference coordinates.

   Parameters
   ----------
   file: str
       The file path.
   reference_image : NDArray
       The reference image.
   reference_coords : NDArray
       The source coordinates in the reference image.
   transform_type : Literal['affine', 'translation']
       The type of transform to use for image alignment.
   rotation_limit : float | None
       The maximum rotation limit (in degrees) for image alignment.
   scale_limit : float | None
       The maximum scaling limit for image alignment.
   translation_limit : List[float] | None
       The maximum translation limit for image alignment.
   n_alignment_sources : int
       The (maximum) number of sources to use for image alignment.

   Returns
   -------
   Tuple[NDArray, Dict[str, float], Dict[str, Dict[str, float]]]
       The stacked image, transforms, and background results.


.. py:function:: valid_transform(file, transform, rotation_limit, scale_limit, translation_limit, logger)

   Find whether a transform is valid given some transform limits.

   Parameters
   ----------
   file : str
       The file being transformed.
   transform : SimilarityTransform
       The transform.
   rotation_limit : float | None
       The rotation limit.
   scale_limit : float | None
       The scale limit.
   translation_limit : List[float] | None
       The translation limit.

   Returns
   -------
   bool
       Whether the transform is valid.