astroalign

Astroalign is a Python module designed to register (align) two stellar astronomical images, particularly when World Coordinate System (WCS) information is unavailable.

Instead of using generic point-feature matching (which often fails on stellar images due to the lack of stable structure), Astroalign uses asterism matching. It identifies similar 3-point asterisms (triangles) in both images to estimate the affine transformation between them.

Key characteristics:

• Robustness: Because it relies on geometric patterns (triangles), it is less affected by differences in point-spread function (PSF), seeing, or atmospheric conditions.
• Limitations: It may struggle with images of extended objects (few point-like sources), very crowded fields, or images containing a large number of hot pixels.
• Hot Pixel Mitigation: If hot pixels cause incorrect registration, it is recommended to use a cosmic-ray remover like CCDProc's cosmic-ray remover before using Astroalign.

When working with objects that have both .data and .mask properties (like Astropy NDData or CCDData), you can transform both simultaneously using the propagate_mask=True argument in aa.register or aa.apply_transform.

This ensures that the transformation's footprint (the area with no valid pixel information) is automatically added to the existing mask of the object.

from astropy.nddata import NDData
import numpy as np
from skimage.transform import SimilarityTransform
import astroalign as aa

# Setup NDData with data and a mask
nd = NDData([[0, 1], [2, 3]], [[True, False], [False, False]])

# Define a transform
transf = SimilarityTransform(rotation=np.pi/2., translation=(1, 0))

# Apply transform with mask propagation
aligned_image, footprint = aa.apply_transform(transf, nd, nd, propagate_mask=True)

# Create a new object with the combined mask
new_nd = NDData(aligned_image, mask=footprint)

To restrict the search to a specific Region of Interest (ROI), create a boolean mask where True represents the areas to be ignored and False represents the ROI. You can then pass a NumPy masked array to aa.register.

In the example below, we define an ROI corresponding to rows 300–900 and columns 1000–1700 across all color channels. We set the mask to False for the ROI (meaning these pixels are not masked/ignored) and True everywhere else.

import numpy as np
import astroalign as aa

# Create a mask of all True (everything is masked/ignored)
mask = np.ones_like(target, dtype="bool")

# Set the ROI to False (not masked/included in search)
mask[300:900, 1000:1700, :] = False

# Create the masked array
target_masked = np.ma.array(target, mask=mask)

# Perform registration using the masked target
registered, footprint = aa.register(source, target_masked)

# Optional: Overwrite the target with the registered source in the footprint pixels
target[~footprint] = registered[~footprint]

Persistent CCD defects like hot or dead pixels can be mistaken for legitimate sources, potentially resulting in an identity transformation. There are two ways to handle this:

1. Pre-cleaning: Use a tool like ccdproc.cosmicray_lacosmic to clean the image before passing it to astroalign.
2. Increase minimum area: Increase the min_area keyword argument (which defaults to 5) to require a larger number of connected pixels for a source to be considered valid. This helps ignore single-pixel artifacts.

Both aa.register() and aa.find_transform() support the min_area parameter.

# Option 1: Clean with ccdproc first
from ccdproc import cosmicray_lacosmic as lacosmic
clean_source, mask = lacosmic(myimage)
registered_image, footprint = aa.register(clean_source, clean_target, min_area=9)

# Option 2: Increase min_area to ignore small artifacts
import astroalign as aa
registered_image, footprint = aa.register(source, target, min_area=9)