New Coalignment API

_typos.toml

@@ -7,3 +7,6 @@ default.extend-ignore-identifiers-re = [
     "iy",
     "BA",
 ]
+
+[default.extend-words]
+eis = "eis"

changelog/207.breaking.rst

@@ -0,0 +1,33 @@
+**New Coalignment API in sunkit_image.coalignment**
+
+The new coalignment API, developed as part of GSoC 2024, addresses the need for a more precise and flexible approach to image coalignment within the `sunkit_image.coalignment` module.
+As solar imaging data continues to grow in complexity, the existing coalignment methods from ``sunpy.image.coalignment`` and ``sunpy.physics.solar_rotation`` were found to be scattered and lacked a unified interface, leading to confusion and redundant code.
+
+**New Features:**
+
+- **Coalignment Interface** (`sunkit_image.coalignment.interface`):
+
+  - ``coalign`` function: A high-level function for image coalignment with a specified method. Default method: :func:`~sunkit_image.coalignment.match_template.match_template_coalign`.
+  - ``AffineParams`` NamedTuple: Stores and passes affine transformation parameters.
+
+- **Template Matching Coalignment** (`sunkit_image.coalignment.match_template`):
+
+  - ``match_template_coalign`` function: A coalignment method that uses template matching.
+
+- **Decorator Utility** (`sunkit_image.coalignment.decorators`):
+
+  - ``register_coalignment_method`` decorator: Enables easy registration of coalignment methods.
+  - Global Registry: Maintains a dictionary of registered coalignment methods.
+
+**Enhancements:**
+
+- Improved Metadata Handling: Updates WCS metadata based on affine transformation parameters.
+- User Warnings: Alerts users to significant spatial or temporal separations between maps.
+
+**Documentation:**
+
+- All functions are well-documented in the API reference.
+
+**Examples**
+
+- Please find the examples related to the :ref:`adding of coalignment method <sunkit-image-how-to-guide-add-a-new-coalignment-method>` and using a coalignment method here :ref:`sphx_glr_generated_gallery_aligning_aia_with_eis_maps.py`

docs/code_ref/coalignment.rst

@@ -1 +1,17 @@
+Coalignment Package
+*******************
+
+`sunkit_image.coalignment` provides routines to perform coalignment of solar images.
+
+The main entry point is the `~sunkit_image.coalignment.coalign` function, which accepts a reference map, a target map, and a specified method for coalignment.
+This method returns a new map with updated metadata reflecting the applied affine transformations, such as scaling, rotation, and translation.
+
+The module supports various transformation methods registered via the `~sunkit_image.coalignment.decorators.register_coalignment_method` decorator, allowing for flexible coalignment strategies based on the specific needs of the data.
+
 .. automodapi:: sunkit_image.coalignment
+
+.. automodapi:: sunkit_image.coalignment.interface
+
+.. automodapi:: sunkit_image.coalignment.match_template
+
+.. automodapi:: sunkit_image.coalignment.decorators

docs/how_to_guide/adding_a_coalignment_method.rst

@@ -0,0 +1,59 @@
+.. _sunkit-image-how-to-guide-add-a-new-coalignment-method:
+
+****************************
+Add a New Coalignment Method
+****************************
+
+If you want to register a new coalignment method that can be used by :func:`~sunkit_image.coalignment.coalign`, you can use :func:`~sunkit_image.coalignment.decorators.register_coalignment_method`:
+
+.. code-block:: python
+
+    from sunkit_image.coalignment.decorators import register_coalignment_method
+    from sunkit_image.coalignment.interface import AffineParams
+
+    @register_coalignment_method("my_coalign")
+    def my_coalignment_method(input_array, template_array):
+        # Your coalignment code goes here
+        # This should encompass calculating the shifts,
+        # handling NaN values appropriately.
+        # Return the shifts in an affine style, such as the scale, rotation and translation.
+        return AffineParams(scale, rotation, translation)
+
+Decorator Parameters
+====================
+
+Currently the decorator takes one parameter:
+
+- ``name``: The name of your custom coalignment method, which in the above example is  "my_coalign".
+
+Function Requirements
+=====================
+
+Your coalignment function should:
+
+1. **Take Input Parameters**:
+
+   - ``input_array``: The 2D array to be coaligned.
+   - ``target_array``: The 2D array to align to.
+
+2. **Compute Shifts**: Calculate the shifts in the x and y directions needed to align ``input_array`` with ``target_array``.
+
+3. **Determine Affine Parameters**: Decide the values of the affine parameters - translation, scale and rotation.
+
+4. **Return**: Use the ``AffineParams`` named tuple included or provide your own that exposes the three parameters as attributes.
+
+Handling NaNs and Infs
+======================
+
+Proper handling of these values is expected to be included in the registered methods.
+The :func:`~sunkit_image.coalignment.coalign` function does not change any problematic values.
+
+Checking if the Method is Registered
+====================================
+
+To check if your method is registered, you can check if it is present in the registered methods dictionary ``REGISTERED_METHODS`` using the following code:
+
+.. code-block:: python
+
+    from sunkit_image.coalignment.decorators import REGISTERED_METHODS
+    print(REGISTERED_METHODS)

docs/how_to_guide/index.rst

@@ -0,0 +1,10 @@
+.. _sunkit-image-how-to-reference:
+
+*************
+How To Guide
+*************
+
+.. toctree::
+   :maxdepth: 1
+
+   adding_a_coalignment_method

docs/index.rst

@@ -14,6 +14,7 @@ sunkit-image
           :maxdepth: 1
 
           code_ref/index
+          how_to_guide/index
 
     .. grid-item-card:: Other info
 

examples/aligning_aia_with_eis_maps.py

@@ -0,0 +1,84 @@
+"""
+=====================
+Coaligning EIS to AIA
+=====================
+
+This example shows how to EIS data to AIA using cross-correlation which is implemented as the "match_template" method.
+"""
+# sphinx_gallery_thumbnail_number = 2 # NOQA: ERA001
+
+import matplotlib.pyplot as plt
+
+import astropy.units as u
+from astropy.visualization import AsinhStretch, ImageNormalize
+
+import sunpy.map
+from sunpy.net import Fido
+from sunpy.net import attrs as a
+
+from sunkit_image.coalignment import coalign
+
+###################################################################################
+# Firstly, let us acquire the IS and AIA data we need for this example.
+#
+# For this example, we will use the IS data from the sunpy data repository.
+# This is a preprocessed IS raster data.
+
+
+eis_map = sunpy.map.Map("https://github.com/sunpy/data/raw/main/sunkit-image/eis_20140108_095727.fe_12_195_119.2c-0.int.fits")
+
+fig = plt.figure()
+
+ax = fig.add_subplot(111, projection=eis_map)
+eis_map.plot(axes=ax, aspect=eis_map.meta['cdelt2'] / eis_map.meta['cdelt1'],
+             cmap='Blues_r', norm=ImageNormalize(stretch=AsinhStretch()))
+
+###################################################################################
+# Lets find the AIA image that we want to use as a reference.
+# We want to be using an image near the "date_average" of the IS raster.
+
+query = Fido.search(a.Time(start=eis_map.meta["date_beg"], near=eis_map.meta["date_avg"], end=eis_map.meta["date_end"]), a.Instrument('aia'), a.Wavelength(193*u.angstrom))
+aia_file = Fido.fetch(query)
+aia_map = sunpy.map.Map(aia_file)
+
+####################################################################################
+# Before coaligning the images, we first downsample the AIA image to the same plate
+# scale as the IS image. This is not done automatically.
+
+nx = (aia_map.scale.axis1 * aia_map.dimensions.x) / eis_map.scale.axis1
+ny = (aia_map.scale.axis2 * aia_map.dimensions.y) / eis_map.scale.axis2
+
+aia_downsampled = aia_map.resample(u.Quantity([nx, ny]))
+
+####################################################################################
+# Now we can coalign IS to AIA using cross-correlation. For this we would be using the
+# "match_template" method. For details of the implementation refer to the
+# documentation of `~sunkit_image.coalignment.match_template.match_template_coalign`.
+
+coaligned_eis_map = coalign(aia_downsampled, eis_map)
+
+####################################################################################
+# To check now effective this has been, we will plot the IS data and
+# overlap the bright regions from AIA before and after the coalignment.
+
+levels = [800] * aia_map.unit
+
+fig = plt.figure(figsize=(15, 7.5))
+
+# Before coalignment
+ax = fig.add_subplot(121, projection=eis_map)
+eis_map.plot(axes=ax, title='Before coalignment',
+             aspect=coaligned_eis_map.meta['cdelt2'] / coaligned_eis_map.meta['cdelt1'],
+             cmap='Blues_r', norm=ImageNormalize(stretch=AsinhStretch()))
+aia_map.draw_contours(levels, axes=ax)
+
+# After coalignment
+ax = fig.add_subplot(122, projection=coaligned_eis_map)
+coaligned_eis_map.plot(axes=ax, title='After coalignment',
+                       aspect=coaligned_eis_map.meta['cdelt2'] / coaligned_eis_map.meta['cdelt1'],
+                       cmap='Blues_r', norm=ImageNormalize(stretch=AsinhStretch()))
+aia_map.draw_contours(levels, axes=ax)
+
+fig.tight_layout()
+
+plt.show()

pytest.ini

@@ -55,7 +55,7 @@ filterwarnings =
     ignore:Please use `gaussian_filter` from the `scipy.ndimage` namespace:DeprecationWarning
     ignore:Please use `laplace` from the `scipy.ndimage` namespace:DeprecationWarning
     ignore:.*Deprecated NumPy 1.24.*:DeprecationWarning
-    ignore:'cgi' deprecated and slated for removal in Python 3.13:DeprecationWarning
+    ignore:'cgi' is deprecated and slated for removal in Python 3.13:DeprecationWarning
     # astropy/utils/iers/iers.py:1115: in auto_open good_enough = cls._today() + TimeDelta(offset, format="jd")
     ignore:datetime.datetime.utc:DeprecationWarning
     ignore:leap-second file is expired:astropy.utils.iers.iers.IERSStaleWarning