twirl

Python package for astrometric plate solving

twirl is an astrometric plate solving package for Python. It is suited for cases where the Right Ascension and Declination (RA, dec) coordinates of the image center and the field of view is known, computing a World Coordinate System (WCS) based on GAIA reference stars.

twirl compute a WCS following these steps:

1. detection of stars in the image if not provided
2. catalog query using image known center
3. asterisms building and matching
4. image recombination and wcs fit using astropy.wcs

Astersisms are made of 3 or 4 points. 4 points asterisms are built following Lang et al. 2009 while 3 points asterims are based on an original algorithm.

Installation

twirl can be installed using pip:

pip install twirl

or using poetry:

poetry add twirl

Example Usage

twirl is designed to be complementary to the astropy package. It is used to compute a WCS from a set of stars detected in an image.

As a prerequisite, star detection and plate solving is suited for when the image center and field of view are known.

In this case, the image center and field of view can be provided as a SkyCoord object and a Quantity object respectively.

Use any specified header that has been stored on the FITS primary HDU to obtain the center equatorial coordinate and field of view, for this example we will assum "RA" and "DEC" are the keywords for the center equatorial coordinate.

Setup

import numpy as np

from astropy.io import fits
from astropy import units as u
from astropy.coordinates import SkyCoord

# Open some FITS image: 
hdul = fits.open("...")

# ra, dec in degrees
ra, dec = header["RA"], header["DEC"]

# Provide the center as a SkyCoord object:
center = SkyCoord(ra, dec, unit=["deg", "deg"])

center = [center.ra.value, center.dec.value]

# Utilise the image shape and pixel size in arcseconds " to obtain the field of view in degrees:
shape = data.shape

# Pixel size in arcseconds:
pixel = 0.66 * u.arcsec

# Field of view in degrees:
fov = np.max(shape)*pixel.to(u.deg).value

From here, we can pass the data, the center equatorial coordinate and the field-of-view to twirl to compute the World Coordinate System (WCS):

Twirl Usage

import twirl

# Find some starts in the image:
stars = twirl.find_peaks(data)[0:15]

# Compute the World Coordinate System:
wcs = twirl.compute_wcs(stars, center, fov)

A more complete example is provided in docs/notebooks

Development

Project Requirements

• Python 3.11.*
• Poetry for Python package and environment management.

Installing Dependencies

The twirl project manages Python package dependencies using Poetry. You'll need to follow the instructions for installation there.

Then you can start a shell session with the new environment with:

$ poetry shell

N.B. For development with vscode you will need to run the following command:

$ poetry config virtualenvs.in-project true

This will installed the poetry .venv in the root of the project and allow vscode to setup the environment correctly for development.

To start development, install all of the dependencies as:

$ poetry install

N.B. Ensure that any dependency changes are committed to source control, so everyone has a consistenct package dependecy list.

Acknowledgements

This package has made use of the algorithm from

Lang, D. et al. (2010). Astrometry.net: Blind Astrometric Calibration of Arbitrary Astronomical Images. The Astronomical Journal, 139(5), pp.1782–1800. doi:10.1088/0004-6256/139/5/1782.

implemented in

Garcia, L. J. et al. (2022). prose: a Python framework for modular astronomical images processing. MNRAS, vol. 509, no. 4, pp. 4817–4828, 2022. doi:10.1093/mnras/stab3113.

See this documentation page for the BibTeX entries.