quatrope/astroalign

A tool to align astronomical images based on asterism matching

---

ASTROALIGN is a python module that will try to align two stellar astronomical images, especially when there is no WCS information available.

It does so by finding similar 3-point asterisms (triangles) in both images and deducing the affine transformation between them.

Generic registration routines try to match feature points, using corner detection routines to make the point correspondence. These generally fail for stellar astronomical images, since stars have very little stable structure and so, in general, indistinguishable from each other. Asterism matching is more robust, and closer to the human way of matching stellar images.

Astroalign can match images of very different field of view, point-spread function, seeing and atmospheric conditions.

It may not work, or work with special care, on images of extended objects with few point-like sources or in very crowded fields.

You can find a Jupyter notebook example with the main features at http://quatrope.github.io/astroalign/.

Full documentation: https://astroalign.readthedocs.io/

Installation

Using setuptools:

$ pip install astroalign

or from this distribution with

$ python setup.py install

Performance: Optional

This library is optionally compatible with bottleneck and may offer performance improvements in some cases. Install bottleneck in your project as a peer to astroalign using:

pip install bottleneck

Astroalign will pick this optional dependency up and use it's performance improved functions for computing transforms.

Running Tests

python tests/test_align.py

Usage example

>>> import astroalign as aa
>>> aligned_image, footprint = aa.register(source_image, target_image)

In this example source_image will be interpolated by a transformation to coincide pixel to pixel with target_image and stored in aligned_image.

If we are only interested in knowing the transformation and the correspondence of control points in both images, use find_transform will return the transformation in a Scikit-Image SimilarityTransform object and a list of stars in source with the corresponding stars in target.

>>> transf, (s_list, t_list) = aa.find_transform(source, target)

source and target can each either be the numpy array of the image (grayscale or color), or an iterable of (x, y) pairs of star positions on the image.

The returned transf object is a scikit-image SimilarityTranform object that contains the transformation matrix along with the scale, rotation and translation parameters.

s_list and t_list are numpy arrays of (x, y) point correspondence between source and target. transf applied to s_list will approximately render t_list.

Related Software

There are other related software that may offer similar functionality as astroalign. This list is not exhaustive and may be others.

• astrometry.net
• reproject
• Watney Astrometry Engine
• Stellar Solver
• THRASTRO
• Montage
• Aafitrans
• astrometry

Citation

If you use astroalign in a scientific publication, we would appreciate citations to the following paper:

Astroalign: A Python module for astronomical image registration.
Beroiz, M., Cabral, J. B., & Sanchez, B.
Astronomy & Computing, Volume 32, July 2020, 100384.

---

TOROS Dev Team

[email protected]

astroalign's Issues

Update gh-pages

Update gh-pages index.html with version 2.0 API.

Hot pixels can confuse image transformation.

Typically if hot pixels dominate the number of sources, the optimal transformation will converge to the identity.

Solution: Add warning in the documentation about hot pixels.

warn on the number of reference sources used

If too many sources are used, the code can choke with too many triangles and never finish
Recommend using ~50 brightest stars on each frame.

_generate_invariants requires at least 5 sources to work, find_transform only 3.

I'm trying to run find_transform on a target image with 4 sources. The check on target_controlp is passed because there are at least 3 sources, but when it enters _generate_invariants the indx variable is forced to length=5(>4), since NUM_NEAREST_NEIGHBORS=5, and there is no check on this. Then the arrange function is not able to find the fifth source.
I'm attaching a screenshot of the errors.

failed to install with pip

OS: Windows 10 x64
command: pip install astroalign
output:

Building wheels for collected packages: sep
Building wheel for sep (setup.py) ... error
ERROR: Complete output from command 'c:\program files\python36\python.exe' -u -c 'import setuptools, tokenize;file='"'"'C:\Users\djschmi1\AppData\Local\Temp\pip-install-2ni6gba8\sep\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(file);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, file, '"'"'exec'"'"'))' bdist_wheel -d 'C:\Users\djschmi1\AppData\Local\Temp\pip-wheel-x1kosjxe' --python-tag cp36:
ERROR: running bdist_wheel
running build
running build_ext
building 'sep' extension
error: [WinError 3] The system cannot find the path specified: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\PlatformSDK\lib'

ERROR: Failed building wheel for sep
Running setup.py clean for sep
Failed to build sep
Installing collected packages: sep, astroalign
Running setup.py install for sep ... error
ERROR: Complete output from command 'c:\program files\python36\python.exe' -u -c 'import setuptools, tokenize;file='"'"'C:\Users\djschmi1\AppData\Local\Temp\pip-install-2ni6gba8\sep\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(file);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, file, '"'"'exec'"'"'))' install --record 'C:\Users\djschmi1\AppData\Local\Temp\pip-record-6b0iy0b4\install-record.txt' --single-version-externally-managed --compile:
ERROR: running install
running build
running build_ext
building 'sep' extension
error: [WinError 3] The system cannot find the path specified: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\PlatformSDK\lib'
----------------------------------------
ERROR: Command "'c:\program files\python36\python.exe' -u -c 'import setuptools, tokenize;file='"'"'C:\Users\djschmi1\AppData\Local\Temp\pip-install-2ni6gba8\sep\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(file);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, file, '"'"'exec'"'"'))' install --record 'C:\Users\djschmi1\AppData\Local\Temp\pip-record-6b0iy0b4\install-record.txt' --single-version-externally-managed --compile" failed with error code 1 in C:\Users\djschmi1\AppData\Local\Temp\pip-install-2ni6gba8\sep\

No doc for alignment using lists

The tutorial fails to mention that astroalign accepts a list of (x, y) pairs as well as image arrays.

Feature request/discussion - additional RANSAC algorithm support

I know that the docs + paper explain that astroalign becomes way more sensitive to outliers and may not work for smaller sets or require special care; have/would you consider adding support for other RANSAC algorithms? There's some variants that may combat this issue, such as Optimal RANSAC, which is described as being able to handle situations when the inlier ratio is as little as 4%.

I ask because for my use case at NASA JPL, the images being registered have very few stars that can be detected (~3-5, with 10-20 predicted), and I was curious if this idea had already been explored or not.

Feature request ? return only star list

Thank you for this awesome project, astroalign definitely allows to make fast prototyping for deep sky image processing :)

I have plenty of project that were blocked due to the lack of existence of a tool like astroalign in python.

I am building some tools that are based on the star position, that I would like to use to infer centroid, and model the psf.
To do so, I am trying to do like in the following example:

transf, (s_list, t_list) = aa.find_transform(source, target)
However, when only the star position is needed I guess there is a simple solution no ?

Thank you in advance for your help

Check warning for numpy masked arrays

np.median warns:
UserWarning: Warning: 'partition' will ignore the 'mask' of the MaskedArray.
when using median on masked arrays.

See here

Citation for Astroalign

I want to cite this work for my thesis, could you make it possible by using figshare or zenodo?
I found a nice article about that: https://guides.github.com/activities/citable-code/

Add license file

astroalign user !

hello.

with other amateur astronomers we have designed software that uses your library:
https://github.com/gehelem/als

it is a software of live stacking which makes it possible to stack images which arrives in a file and to visualize and modified this stack!

actual work in alpha/develop branch

Error "Did not meet fit acceptance criteria" should be more specific

Value error in skimage.transform.warp for float images

If image is of type f4 ('float32'), then skimage.transform.warp raises the Error:

ValueError: Images of type float must be between -1 and 1.

It won't complain if the image is of type f8 ('float64').

add __version__

Add a version variable in init.py

implement piecewise warp instead of rigid transformation

Use skimage.transform.PiecewiseAffineTransform to warp the image to fit star positions better.

get rid of scikit-image

scikit-image is a big dependency of which I only use exposure.rescale_intensity
The rescaling can be done easily with numpy.

Add API documentation

sphinx-autoodapi

Mask out-of-boundary pixels

Use cval in ndimage's interpolate and footprint in reproject to mask pixels that were out of boundary.

Return footprint of transformation

This will break the current API.

Return in all cases a footprint of pixels touched by the transformation.
For numpy masked arrays add it as mask.

Add `fill` argument for pixels with no transform

Add option to fill untouched pixels with median or fixed value.

Accept Table as input

Accept astropy's Table as input for find_transform and estimate_transform, if possible.

docstrings

Add all docstrings

Confusing docstring align_image

The implementation of align_image is confusing and order of image and image_ref are not intuitive.

Detection sigma threshold too low

This is related to #36. Solution would be to set it to something more normal like 5 and add a global to set the detection level. like

DETECTION_SIGMA_LEVEL = 5
...
thresh = DETECTION_SIGMA_LEVEL * sigma

Test with simulated images

Use make.py to generate the images to test.

No module named 'skimage'

Hey,

I am trying to use astroalign, but when I run my python script got the No module named error:

File "colorastro.py", line 5, in <module>
    import astroalign as aa
  File "<frozen zipimport>", line 259, in load_module
  File "C:\Users\Luca\AppData\Local\Programs\Python\Python38-32\lib\site-packages\astroalign-2.0.2-py3.8.egg\astroalign.py", line 64, in <module>
ModuleNotFoundError: No module named 'skimage'

I use windows 10 and I have installed astroalign with both Anaconda and Pip. I have tried to uninstall astroalign and install scikit-image but I got that it is already satisifed.

Any suggestions?

Initial Update

Hi 👊

This is my first visit to this fine repo, but it seems you have been working hard to keep all dependencies updated so far.

Once you have closed this issue, I'll create seperate pull requests for every update as soon as I find one.

That's it for now!

Happy merging! 🤖

No Issue!

Hi Martin,

I looked to astroalign with much interest. You mention that astroalign take ideas from astrometry.net. As I currently building some astronomy software as well, I look for a stacking algorithm like yours, but for FITS Images, which already have distortion parameters from astrometry.net In this case many of the calculation should be already done. Is that right ? Could you point me in the direction, how to find a solution with WCS Headers ?

Thanks for your help !

Michel

find_transform is not deterministic

if I apply the same find_transform function multiple times I don't get the same transformation.

attempting to align using coordinates fails

The function find_transform(source_list, target_list) won't work when the lists are drawn straight from a sep catalog:

rs =  sep_targ_cat[['x', 'y']]
aa.find_transform(ns, rs)

raises ValueError need more than one value to unpack

Instead a reconstruction of these coordinates lists would fix the problem:

j=0
for x, y in sep_source_cat[['x', 'y']]:
   ns[j] = x, y
   j += 1

remove astropy dependency

I think. Check.

align mask as float

To let interpolation work better, align mask as a float array, then put a threshold to convert to boolean again.

Change module globals into options

Global var's MAX_CONTROL_POINTS, PIXEL_TOL, MIN_MATCHES_FRACTION, NUM_NEAREST_NEIGHBORS could be made into keyword arguments to functions.
Also document better.

Multiple partners for list of stars

returned lists for find_transform contain sources with multiple correspondences.

Pip installation failure

Pip failed installing astroalign

> pip install astroalign

Downloading/unpacking astroalign Could not find a version that satisfies the requirement astroalign (from versions: 1.0a0, 1.0a0, 1.0a1, 1.0a2) Cleaning up... No distributions matching the version for astroalign Storing debug log for failure in /home/bruno/.pip/pip.log

pip installation failed, though a pip search did worked.

> pip search astroalign

astroalign - Astrometric Alignment of Images

apply_transform returns an image not in range 0-255

Given an image uint8, apply_transform will return an image that is not in the range 0-255.
This creates artifacts.
The only way to solve the problem is to save result in float, clamp between 0 and 255 and then reconvert to uint8

add warning for deprecated functions

Warnings

Use matrix_transform

Replace the two lines:
https://github.com/toros-astro/astroalign/blob/aa1dc0c23efa21fb1449f303b07c82cb9bcd8175/astroalign.py#L320-L321

with a call to matrix_transform

t_vertex_pred = matrix_transform(s_vertex, best_t.params)

(should be t_vertex_pred, not s_vertex_pred)

Add python 3 support

In travis CI

Add inversion test

If we calculate an affine transform t1 from image A to B, and transformation t2 from B to A, we can test wether a point p in A transforms to a point q in B using t1 and that point q will transform back to p (with errors) using t2.

Iteration limit on RANSAC too low

The limit can be made dynamic on the fraction of the triangles calculated (80% maybe)

Feature request: Add global align functions

I am currently align some images with a lot of noise. I can find sources around a small part of the image and align them. However, it requires a different transformation for the global image. Is there any feature that can convert the transformation class to another coordinate?

Codecov broken

Codecov coverage reports are not sent.

Implement property based testing

Implement property-based testing on astroalign to detect corner cases

For example, anything with stars <= 98 fails

>>> from tests.test_align import simulate_image_pair
>>> source, target = simulate_image_pair(shape=(256, 256), noise=1, stars=98)[:2]
>>> aa.register(source, target)
...
MaxIterError: Max iterations exceeded while trying to find acceptable transformation.

Provide a way for the nddata/ccddata integration in apply_transform to return the same objects

The improved integration with CCDData/NDData (i.e., things with mask and data) are great, so was glad to see that!

However, the example shown in the docs (https://astroalign.readthedocs.io/en/latest/tutorial.html#dealing-with-data-objects-with-data-and-mask-properties-nddata-ccddata-numpy-masked-arrays) prompts an idea: I wonder if apply_transform can be adapted to actually return the appropriate objects? I.e., ideally instead of:

aligned_image, footprint = aa.apply_transform(transf, nd, nd, propagate_mask=True)
new_nd = NDData(aligned_image, mask=footprint)

it would be more convenient for users if the following worked:

new_nd =  aa.apply_transform(transf, nd, ...)

That is, one of the main motivations for NDData is so that users do not have to worry about things like paying close attention to how they pass in masks.

Does that seem reasonable? I.e., is it reasonable to have apply_transform give different things depending on the input? I find that a natural pattern, but an alternative might be to have a separate method apply_transform_datamask or something like that. Or another option might be a special keyword.

add version in module

Add a

__version__ 

inside the module.

test without sep installed

Make travis env to test without sep installed

Consider moving find_transform into astropy

While thinking about #34 and after some time of keeping an eye out for the use cases, I think there are a number of places in the wider Astropy ecosystem where the asterism-matching machinery in astroalign might be useful on its own (i.e., not part of the larger astroalign workflow). So the purpose of this issue is to feel out the astroalign team (which I think means @martinberoiz, @leliel12, and @BrunoSanchez) on the idea of moving some of this functionality over to Astropy.

To be more concrete, the idea here would be to take find_transform (and the related private functions it requires) and move them to astropy.coordinates. There would probably need to be some minor changes to the interface to fit it into relevant Astropy machinery, including possibly making a few of the currently-private functions part of a slightly more flexible user-facing API. But I've already had a quick look and I think it's not much effort - I could do that myself unless someone else wants to. The rest of astroalign's functionality (i.e. the more convenient quick-and-easy interfaces and apply_transform function) would remain in astroalign since that provides a nice one-stop-shop for people just trying to solve the higher-level task that don't care about the details of the matching.

If that happens, ideally astroalign would be updated to use the Astropy implementation. The idea being that way we won't end up getting divergent code bases and we can work together to fix bugs, etc. The one downside of that approach from astroalign's perspective is it would require bringing back an astropy dependency, which I gather from #34 and #22 is potentially a concern. I think it's a bigger win to make this functionality part of the astropy core (and thereby usable in Astropy itself and more easily in other affiliated/coordinated packages), but of course I would 😉. So hence bringing the topic up before doing anything more.

Note I'm also concious of the "credit" question. To do the plan I'm proposing I would try to extract the git history so that all of the commits from astroalign that touches those parts of the code would be preserved. I think it would also make sense to request in the docs that anyone using the astropy function should also try to cite the astroalign paper (at least, if that's what the astroalign team desires).

So what do y'all think?

RANSAC

Found an example where the results aren't symmetric , i.e., the result of aligning an image A to image B works fine, but aligning B to A isn't converging. RANSAC is involved in the stacktrace error. Doing some research about RANSAC found this package scikitimage where it uses RANSAC and seems quite tested. Is there a way to test the results of ransac from here vs RANSAC from sickitimage.