Detection-based astronomical image registration.
Initially built from the algorithm of
alipy2.0, spalipy
includes an
optional additional warping of the affine transformation via splines to
achieve accurate registration in the case of non-homogeneous coordinate
transforms. This is particularly useful in the case of optically distorted
or wide field-of-view images.
pip install spalipy
git clone https://github.com/Lyalpha/spalipy
cd spalipy
pip install .
If you have (geometrically) well-behaved images with a significant overlap, then good results can usually be obtained with a call such as:
align-fits-simple source.fits source_aligned.fits template.fits
Where source.fits
is the image to be aligned to the supplied template.fits
,
and source_aligned.fits
is where the result should be written.
To take advantage of all the dials and sliders to tweak the alignment, take a look at the entire parameter descriptions via:
align-fits -h
Alternatively, one can pass lower level objects to perform an alignment
interactively or within an external script, see running spalipy
interactively.
A source
image is transformed to the pixel-coordinate system of a
template
image using their respective detections as tie-points.
Matching quads of detections between
the two catalogues are used to match corresponding detections in the two
images. An initial affine transformation is calculated from a quad match,
and is applied to source
image detections. Following this, cross-matching
is performed within some tolerance to find corresponding detections across
the image. The remaining residuals between the matched detection coordinates
are used to construct 2D spline surfaces that represent the spatially-varying
residuals in x
and y
axes. These surfaces are used to calculate the
correction needed to properly register the images even in the face of
non-homogeneous coordinate transformation between the images. Flux
conservation is relatively robust so long as the pixel scale between source
and template
is the same. Proper investigation with different pixel scales
has not been performed.
Note: the affine transformation uses scipy.interpolation.affine_transform
which doesn't handle nans properly, therefore replace all nan values
in the source
image prior to running spalipy
.
spalipy
can be run in two modes - via the command-line scripts or
interactively. The second big choice is to either provide your own detection
catalogues or let spalipy
perform its own detection. Each of these scenarios
is shown below.
When using the internal detection routines, there are two command-line
scripts: align-fits
and align-fits-simple
. For narrow field-of-view
images without significant distortions, align-fits-simple
is probabably
entirely sufficient to get a good alignment. (align-fits-simple
has
a significantly reduced parameter list and sets some automatically,
for example it will always switch off spline fitting and does not
allow the user to pass existing detection catalogues.)
align-fits-simple source.fits source_aligned.fits template.fits
or
align-fits source.fits source_aligned.fits -tf template.fits
Take notice of the -tf
argument in the second example, this is because
align-fits
offers multiple ways to provide detections, as shown in the next
section.
If one already has detection catalogues from a SExtractor run, then these can be used to save repetition.
e.g. create two SExtractor
catalogues for the image:
sex -c /path/to/my/sex.config source.fits -CATALOG_NAME source.cat
sex -c /path/to/my/sex.config template.fits -CATALOG_NAME template.cat
Note: At a minimum, the SExtractor
catalogues must contain the
columns X_IMAGE, Y_IMAGE, FLUX, FWHM_IMAGE, FLAGS
.
We must use align-fits
here since align-fits-simple
does not allow us to
pass catalogues:
align-fits source.fits source_aligned.fits -sc source.cat -tc template.cat
from astropy.io import fits
from spalipy import Spalipy
source_data = fits.getdata("source.fits")
template_data = fits.getdata("template.fits")
sp = Spalipy(source_data, template_data=template_data)
sp.align()
fits.writeto("source_aligned.fits", data=sp.aligned_data)
Analagously to passing SExtractor
catalogues,
one can pass existing astropy.Table
objects when calling spalipy
interactively, for examples
as the output of a prior sep.extract()
call.
Note: At a minimum, the detection tables must contain the
columns x, y, flux, fwhm, flag
.
import sep
from astropy.io import fits
from astropy.table import Table
from spalipy import Spalipy
source_data = fits.getdata("source.fits")
template_data = fits.getdata("template.fits")
# Run sep on each set of data
# ...
# source_extracted = sep.extract(...)
# template_extracted = sep.extract(...)
source_det = Table(source_extracted)
template_det = Table(template_extracted)
sp = Spalipy(source_data, source_det=source_det, template_det=template_det)
sp.align()
fits.writeto("source_aligned.fits", data=sp.aligned_data)
When running interactively, all information is output in logging. To see these one can do
import logging
logging.getLogger().setLevel(logging.INFO) # or logging.DEBUG for more messages
prior to any of the interactive example calls.
Statistics for the transformation goodness can also be accessed via:
sp.log_transform_stats()
Several parameters should have the main focus of attention if an acceptable alignment is not being found.
min_n_match
will need to be lowered from its default of 100
, but it is
also worth raising n_det
so that the alignment uses all of your sources.
See n_det
docstring on its float vs int format, but it is safe/easy to just
set to some overly large value such that it won't limit your detection tables,
e.g. n_det=10000
.sub_tile
at a default of 2
will effectively fit an affine transformation
in each quart of the image. On extremely distorted images even this may not be
enough and so it can be raised to 3
(or even 4
). It is a balancing act
that there must still be sufficient detections in each image in each sub tile
region from which to make a fit. If you have a low number of detections,
or detections are spread strongly unevenly, this should be set to 1
.spline_order
should generally only be lowered from its default of 3
.
Setting it to zero might actually be preferable for simple alignment tasks.
Also, with a low number of detections, and particularly with regions of low
number of detections, the splines may misbehave.max_match_dist
is the tolerance in pixels when considering a source
and template
detection as matched after the affine transform. One may
increase this in the case of poorly centred detections. Note that this
has an indirect impact on min_sep
(set to 2 * max_match_dist
by
default) - when raising max_match_dist
then min_sep
correspondingly
increases, offering some guard against ambguous cross-matching in crowded
regions. However, raising it too high may mean that too few detections
pass the min_sep
criterion. In crowded fields and with well-behaved
detection centres, reducing max_match_dist
may be advisable.