eloy.alignment
==============

.. py:module:: eloy.alignment

.. autoapi-nested-parse::

   Alignment utilities for astronomical image processing.

   This module provides functions for matching, aligning, and transforming
   coordinate sets, including cross-matching, reference asterism generation,
   and rotation matrix calculation using the twirl package.



Functions
---------

.. autoapisummary::

   eloy.alignment.cross_match
   eloy.alignment.twirl_reference
   eloy.alignment.rotation_matrix


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

.. py:function:: cross_match(S1, S2, tolerance=10, return_idxs=False, none=True)

   Matches points from two sets of points based on proximity.

   :param S1: A 2D array where each row represents a point in the first set.
   :type S1: numpy.ndarray
   :param S2: A 2D array where each row represents a point in the second set.
   :type S2: numpy.ndarray
   :param tolerance: The maximum distance for a point to be considered a match.
                     Defaults to 10.
   :type tolerance: float, optional
   :param return_idxs: If True, returns the indices of the matched points.
                       Defaults to False.
   :type return_idxs: bool, optional
   :param none: If True, appends a NaN value for unmatched points in S1.
                Defaults to True.
   :type none: bool, optional

   :returns: If return_idxs is True, returns a 2D array of indices.
             Otherwise, returns two 2D arrays of matched points from S1 and S2,
             respectively. If no matches are found, returns empty arrays.
   :rtype: numpy.ndarray


.. py:function:: twirl_reference(coords)

   Creates a cKDTree and stores asterisms for reference coordinates.

   :param coords: A 2D array of reference coordinates.
   :type coords: numpy.ndarray

   :returns: Tuple (cKDTree, numpy.ndarray) containing the tree and asterisms.
   :rtype: tuple


.. py:function:: rotation_matrix(coords, ref_coords, reference, tolerance=2, refine=True, rtol=0.02)

   Calculates a rotation matrix aligning two sets of coordinates.

   :param coords: A 2D array of coordinates to be aligned.
   :type coords: numpy.ndarray
   :param ref_coords: A 2D array of reference coordinates.
   :type ref_coords: numpy.ndarray
   :param reference: Tuple (cKDTree, numpy.ndarray) for the reference coordinates.
   :type reference: tuple
   :param tolerance: Tolerance for matching points.
   :type tolerance: float, optional
   :param refine: Whether to refine the rotation matrix.
   :type refine: bool, optional
   :param rtol: Relative tolerance for the cKDTree query.
   :type rtol: float, optional

   :returns: A 3x3 numpy array representing the rotation matrix, or None if no matches are found.
   :rtype: numpy.ndarray or None