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,2 @@
+The previous coalignment API has been deleted and replaced with a new set of imports and functions.
+Please see this example: :ref:`sphx_glr_generated_gallery_aligning_aia_with_eis_maps.py`.

docs/code_ref/coalignment.rst

@@ -1 +1,15 @@
+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.interface.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

docs/how_to_guide/adding_a_coalignment_method.rst

@@ -0,0 +1,60 @@
+.. _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.interface.register_coalignment_method`:
+
+.. code-block:: python
+
+    from sunkit_image.coalignment.interface import AffineParams, register_coalignment_method
+
+    @register_coalignment_method("my_coalign")
+    def my_coalignment_method(input_array, target_array, **kwargs):
+        # 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.
+   - ``**kwargs``: So extra arguments can be passed down the stack.
+
+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.interface 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
+
+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 EIS and AIA data we need for this example.
+#
+# For this example, we will use the EIS data from the sunpy data repository.
+# This is a preprocessed EIS 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 EIS 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 EIS 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 EIS 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 EIS 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()