New Coalignment API

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.13.3"
+    rev: "v0.14.0"
     hooks:
       - id: ruff
         args: ["--fix", "--unsafe-fixes"]
@@ -30,8 +30,8 @@ repos:
     hooks:
       - id: codespell
         args: [ "--write-changes" ]
-  - repo: https://github.com/crate-ci/typos
-    rev: v1
+  - repo: https://github.com/adhtruong/mirrors-typos
+    rev: v1.38.0
     hooks:
       - id: typos
   - repo: https://github.com/pre-commit/mirrors-mypy

_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`.

changelog/290.breaking.rst

@@ -5,4 +5,4 @@ Increased the minimum required versions:
 - sunpy 7.0.0 (from 6.0.0)
 - NumPy 1.26.0 (from 1.23.5)
 - Astropy 6.1.0 (from 5.3.0)
-- SciPy 1.11.0 (from 1.10.1)
+- SciPy 1.12.0 (from 1.10.1)

docs/code_ref/coalignment.rst

@@ -1 +1,20 @@
+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.register.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
+    :skip: coalign
+
+.. automodapi:: sunkit_image.coalignment.register
+
+.. automodapi:: sunkit_image.coalignment.match_template
+
+.. automodapi:: sunkit_image.coalignment.phase_cross_correlation

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.register.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,79 @@
+"""
+=====================
+Coaligning EIS to AIA
+=====================
+
+This example shows how to coalign EIS rasters to AIA images in order correct for the pointing
+uncertainty in EIS.
+"""
+import matplotlib.pyplot as plt
+
+import astropy.units as u
+from astropy.visualization import AsinhStretch, ImageNormalize
+
+import sunpy.map
+
+from sunkit_image.coalignment import coalign
+
+###################################################################################
+# For this example, we will use a preprocessed EIS raster image of the Fe XII
+# 195.119 Å line.
+# This raster image was prepared using the `eispac <https://eispac.readthedocs.io/en/latest/>`__ package.
+
+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")
+
+###################################################################################
+# Next, let's find the AIA data we will use as a reference image.
+# We will look for AIA data near the beginning of the EIS raster and we'll use the
+# 193 Å channel of AIA as it sees plasma at approximately the same temperature as
+# the 195.119 Å line in our EIS raster.
+
+# Below is the Fido query to search and download the AIA data.
+# from sunpy.net import Fido
+# from sunpy.net import attrs as a
+# query = Fido.search(
+#     a.Time(start=eis_map.date-1*u.minute, near=eis_map.date, end=eis_map.date+1*u.minute),
+#     a.Instrument.aia,
+#     a.Wavelength(193*u.angstrom)
+# )
+# aia_file = Fido.fetch(query, site='NSO')
+# For now though we have stored this file on Github so we can download it directly.
+aia_map = sunpy.map.Map("https://github.com/sunpy/data/raw/refs/heads/main/sunkit-image/aia.lev1.193A_2014_01_08T09_57_30.84Z.image_lev1.fits")
+
+####################################################################################
+# Before coaligning the images, we first resample the AIA image to the same plate
+# scale as the EIS image. This will ensure better results from our coalignment.
+
+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 and AIA using cross-correlation. By default, this function
+# uses the "match_template" method. For details of the implementation refer to the
+# documentation of `skimage.feature.match_template`.
+
+coaligned_eis_map = coalign(eis_map, aia_downsampled)
+
+####################################################################################
+# 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.
+
+fig = plt.figure(figsize=(15, 7.5))
+ax = fig.add_subplot(121, projection=eis_map)
+eis_map.plot(axes=ax,
+             title='Before coalignment',
+             aspect=eis_map.meta['cdelt2'] / eis_map.meta['cdelt1'],
+             cmap='Blues_r',
+             norm=ImageNormalize(stretch=AsinhStretch()))
+aia_map.draw_contours([800]*aia_map.unit, axes=ax)
+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([800]*aia_map.unit, axes=ax)
+
+plt.show()

pyproject.toml

@@ -34,7 +34,7 @@ dependencies = [
   "astropy>=6.1.0",
   "numpy>=1.26.0",
   "matplotlib>=3.8.0",
-  "scipy>=1.11.0",
+  "scipy>=1.12.0",
   "scikit-image>=0.20.0",
   "sunpy[map]>=7.0.0",
 ]