New Coalignment API

.circleci/config.yml

@@ -32,7 +32,7 @@ jobs:
       jobname:
         type: string
     docker:
-      - image: cimg/python:3.12
+      - image: cimg/python:3.13
     environment: TOXENV=<< parameters.jobname >>
     steps:
       - run: *no-backports
@@ -56,7 +56,7 @@ jobs:
       jobname:
         type: string
     docker:
-      - image: cimg/python:3.12
+      - image: cimg/python:3.13
     environment:
       TOXENV: << parameters.jobname >>
       GIT_SSH_COMMAND: ssh -i ~/.ssh/id_rsa_6464b6a8248237ca368fd4690777d921
@@ -97,13 +97,13 @@ workflows:
           matrix:
             parameters:
               jobname:
-                - "py312-figure"
+                - "py313-figure"
       - deploy-reference-images:
           name: baseline-<< matrix.jobname >>
           matrix:
             parameters:
               jobname:
-                - "py312-figure"
+                - "py313-figure"
           requires:
             - << matrix.jobname >>
           filters:

_typos.toml

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

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)

changelog/293.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/asda.rst

@@ -1 +1,7 @@
+ASDA (`sunkit_image.asda`)
+**************************
+
+This package contains an implementation of the `Automated Swirl Detection
+Algorithm (ASDA) <https://ui.adsabs.harvard.edu/abs/2019ApJ...872...22L/abstract>`__.
+
 .. automodapi:: sunkit_image.asda

docs/code_ref/coalignment.rst

@@ -1 +1,16 @@
+Coalignment (`sunkit_image.coalignment`)
+****************************************
+
+Routines to perform coalignment of solar images.
+
 .. automodapi:: sunkit_image.coalignment
+
+.. automodapi:: sunkit_image.coalignment.interface
+    :no-inheritance-diagram:
+    :skip: coalign_map
+
+.. automodapi:: sunkit_image.coalignment.register
+
+.. automodapi:: sunkit_image.coalignment.match_template
+
+.. automodapi:: sunkit_image.coalignment.phase_cross_correlation

docs/code_ref/enhance.rst

@@ -1 +1,6 @@
+Enhancement (`sunkit_image.enhance`)
+************************************
+
+This package contains enhancement routines for solar physics data.
+
 .. automodapi:: sunkit_image.enhance

docs/code_ref/granule.rst

@@ -1 +1,6 @@
+Granule Detection (`sunkit_image.granule`)
+******************************************
+
+This package contains functions that will segment images for granule detection.
+
 .. automodapi:: sunkit_image.granule

docs/code_ref/radial.rst

@@ -1 +1,7 @@
+Radial Enhancement (`sunkit_image.radial`)
+******************************************
+
+This package contains functions that can be used to enhance the regions above a
+given radius.
+
 .. automodapi:: sunkit_image.radial

docs/code_ref/stara.rst

@@ -1 +1,7 @@
+Sunspot Tracking And Recognition (`sunkit_image.stara`)
+*******************************************************
+
+This package contains an implementation of the `Sunspot Tracking And Recognition
+Algorithm (STARA) <https://doi.org/10.1007/s11207-009-9420-z>`__.
+
 .. automodapi:: sunkit_image.stara

docs/code_ref/time_lag.rst

@@ -1 +1,9 @@
+Time lag (`sunkit_image.time_lag`)
+**********************************
+
+This package contains functions for calculating the cross-correlation and time
+lag between intensity cubes.
+
+Useful for understanding time variability in EUV light curves.
+
 .. automodapi:: sunkit_image.time_lag

docs/code_ref/trace.rst

@@ -1 +1,6 @@
+Loop tracing (`sunkit_image.trace`)
+***********************************
+
+This package contains functions that will the trace out coronal loop-like structures in an image.
+
 .. automodapi:: sunkit_image.trace

docs/code_ref/utils.rst

@@ -1 +1,4 @@
+Utilities (`sunkit_image.utils`)
+********************************
+
 .. automodapi:: sunkit_image.utils

docs/conf.py

@@ -39,7 +39,7 @@
 elif _version.is_devrelease:
     version = release = f"{_version.base_version}.dev{_version.dev}"
 is_development = _version.is_devrelease
-is_release = not(_version.is_prerelease or _version.is_devrelease)
+is_release = not (_version.is_prerelease or _version.is_devrelease)
 
 project = "sunkit_image"
 author = "The SunPy Community"
@@ -105,7 +105,7 @@
     ),
     "matplotlib": ("https://matplotlib.org/stable", None),
     "sunpy": ("https://docs.sunpy.org/en/stable/", None),
-    "ndcube": ('https://docs.sunpy.org/projects/ndcube/en/stable/', None),
+    "ndcube": ("https://docs.sunpy.org/projects/ndcube/en/stable/", None),
     "astropy": ("https://docs.astropy.org/en/stable/", None),
     "dask": ("https://docs.dask.org/en/latest", None),
     "skimage": ("https://scikit-image.org/docs/stable/", None),

docs/how_to_guide/adding_a_coalignment_method.rst

@@ -0,0 +1,57 @@
+.. _sunkit-image-how-to-guide-add-a-new-coalignment-method:
+
+****************************
+Add a New Coalignment Method
+****************************
+
+In addition to the coalignment methods provided in sunkit-image, users can also write their own
+coalignment methods and "register" these methods with sunkit-image such that they can be used through the same interface as the builtin methods without having to alter the underlying
+sunkit-image package.
+
+At a minimum, your new coalignment function should do the following:
+
+1. Take the following inputs:
+
+   - ``target_array`` : The 2D array to be coaligned.
+   - ``reference_array`` : The 2D array to align to.
+   - ``**kwargs``: Optional keyword arguments used by your method
+
+2. Decide the values of the affine transformation - translation, scale and rotation. In most cases, this means calculating the shifts in the x- and y-directions needed to align ``input_array`` with ``target_array``.
+
+3. Return an instance of `~sunkit_image.coalignment.interface.AffineParams` with the results of your coalignment procedure.
+
+Additionally, registered methods are expected to handled NaNs and Infs should they arise as a result of your coalignment procedure.
+The :func:`~sunkit_image.coalignment.coalign_map` function does not make any attempt to filter out
+these non-finite values.
+
+To register your new coalignment method, you can use the :func:`~sunkit_image.coalignment.register.register_coalignment_method` decorator to register your new method with a custom name. An example of how to use this decorator is shown below:
+
+.. code-block:: python
+
+    from sunkit_image.coalignment.interface import AffineParams, register_coalignment_method
+
+    @register_coalignment_method("my_custom_coalignment_method")
+    def my_coalignment_method(target_array, reference_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)
+
+
+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)
+
+If your coalignment method has been successfully registered, you should now be able to call it
+through the `~sunkit_image.coalignment.coalign_map` interface:
+
+.. code-block:: python
+
+    from sunkit_image.coalignment import coalign_map
+
+    coaligned_map = coalign_map(target_map, reference_map, method='my_custom_coalignment_method')

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/advanced_wow.py

@@ -63,27 +63,29 @@
 # gamma-stretched input, with weight "h".
 
 gamma = 4
-bilateral_denoised_merged_wow = enhance.wow(submap_193, bilateral=1, denoise_coefficients=denoise_coefficients, gamma=gamma, h=0.99)
+bilateral_denoised_merged_wow = enhance.wow(
+    submap_193, bilateral=1, denoise_coefficients=denoise_coefficients, gamma=gamma, h=0.99
+)
 
 ###########################################################################
 # Finally, we will plot the full set of outputs created and
 # compare that to the original image.
 
 fig = plt.figure(figsize=(8, 12))
 variations = {
-    f'Input | Gamma = {gamma} stretch': {'map': submap_193, 'stretch': PowerStretch(1 / gamma)},
-    'WOW | Linear stretch': {'map': default_wow, 'stretch': LinearStretch()},
-    'Denoised WOW': {'map': denoised_wow, 'stretch': LinearStretch()},
-    'Edge-aware WOW': {'map': bilateral_wow, 'stretch': LinearStretch()},
-    'Edge-aware & denoised WOW': {'map': bilateral_denoised_wow, 'stretch': LinearStretch()},
-    'Merged with input': {'map': bilateral_denoised_merged_wow, 'stretch': LinearStretch()}
+    f"Input | Gamma = {gamma} stretch": {"map": submap_193, "stretch": PowerStretch(1 / gamma)},
+    "WOW | Linear stretch": {"map": default_wow, "stretch": LinearStretch()},
+    "Denoised WOW": {"map": denoised_wow, "stretch": LinearStretch()},
+    "Edge-aware WOW": {"map": bilateral_wow, "stretch": LinearStretch()},
+    "Edge-aware & denoised WOW": {"map": bilateral_denoised_wow, "stretch": LinearStretch()},
+    "Merged with input": {"map": bilateral_denoised_merged_wow, "stretch": LinearStretch()},
 }
 interval = AsymmetricPercentileInterval(1, 99.9)
 for i, (title, image) in enumerate(variations.items()):
-    ax = fig.add_subplot(3, 2, i + 1, projection=image['map'])
-    image['map'].plot(norm=ImageNormalize(image['map'].data, interval=interval, stretch=image['stretch']))
+    ax = fig.add_subplot(3, 2, i + 1, projection=image["map"])
+    image["map"].plot(norm=ImageNormalize(image["map"].data, interval=interval, stretch=image["stretch"]))
     ax.set_title(title)
-    ax.axis('off')
+    ax.axis("off")
 
 fig.tight_layout()
 

examples/aligning_aia_with_eis_maps.py

@@ -0,0 +1,92 @@
+"""
+=====================
+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_map
+
+###################################################################################
+# 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 download the AIA data we will use as a reference image.
+# We want 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.
+# 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_map(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=(10, 7.5), layout="constrained")
+ax = fig.add_subplot(121, projection=eis_map)
+eis_map.plot(
+    axes=ax,
+    title="Before coalignment",
+    aspect=eis_map.scale.axis2 / eis_map.scale.axis1,
+    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, sharex=ax, sharey=ax)
+coaligned_eis_map.plot(
+    axes=ax,
+    title="After coalignment",
+    aspect=coaligned_eis_map.scale.axis2 / coaligned_eis_map.scale.axis1,
+    cmap="Blues_r",
+    norm=ImageNormalize(stretch=AsinhStretch()),
+)
+aia_map.draw_contours([800] * aia_map.unit, axes=ax)
+
+####################################################################################
+# We can also visualize this shift by overlaying the extent of the two EIS
+# maps on the AIA image we used to perform the coalignment.
+
+fig = plt.figure(figsize=(8, 8))
+ax = fig.add_subplot(projection=aia_map)
+aia_map.plot(axes=ax)
+eis_map.draw_extent(axes=ax, color="C0", label="Original")
+coaligned_eis_map.draw_extent(axes=ax, color="C1", label="Coaligned")
+ax.set_xlim(1700, 2500)
+ax.set_ylim(1200, 2200)
+ax.legend()
+
+plt.show()

examples/radial_gradient_filters.py

@@ -48,12 +48,7 @@
 # choose them according to your requirements. These can be changed by tweaking the following keywords: ``mean_attenuation_range`` and ``std_attenuation_range``.
 
 order = 20
-base_fnrgf = radial.fnrgf(
-    aia_map,
-    radial_bin_edges=radial_bin_edges,
-    order=order,
-    application_radius=1 * u.R_sun
-)
+base_fnrgf = radial.fnrgf(aia_map, radial_bin_edges=radial_bin_edges, order=order, application_radius=1 * u.R_sun)
 
 ###########################################################################
 # Now we will also use the final filter, RHEF.

pyproject.toml

@@ -45,8 +45,6 @@ watroo = ["watroo"]
 tests = [
   "sunkit_image[all]",
   "dask",
-# NumPy>=2.4 not compatible with some helpers in astropy<7.2
-  "numpy<2.4",
   "pytest-astropy",
   "pytest-mpl",
   "pytest-xdist",

sunkit_image/_dev/scm_version.py

@@ -5,8 +5,8 @@
 try:
     from setuptools_scm import get_version
 
-    version = get_version(root=Path('../..'), relative_to=__file__)
+    version = get_version(root=Path("../.."), relative_to=__file__)
 except ImportError:
     raise
 except Exception as e:
-    raise ValueError('setuptools_scm can not determine version.') from e
+    raise ValueError("setuptools_scm can not determine version.") from e

sunkit_image/asda.py

@@ -1,8 +1,3 @@
-"""
-This module contains an implementation of the Automated Swirl Detection
-Algorithm (ASDA).
-"""
-
 import warnings
 from itertools import product