twirl

Python package for astrometric plate solving

When the coordinates of an image (RA, dec) and the size of its field of view is approximately known, twirl can be used to compute a World Coordinate System (WCS) using GAIA reference stars.

Installation

twirl can be installed using pip:

pip install twirl

or using uv:

uv add twirl

Example Usage

twirl is designed to be complementary to the astropy package. It is used to compute a WCS by matching an image detected stars with catalog stars. To query the catalog stars, the center coordinates of the image must be known, as well as the size of the field of view. If not available, the latter can be computed using the known pixel scale of the detector.

Hence, the process starts by extracting the image RA-DEC center equatorial coordinate and compute the instrument field of view

import numpy as np

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

# Open some FITS image
hdu = fits.open("...")[0]

# get the center of the image
ra, dec = hdu.header["RA"], hdu.header["DEC"]
center = SkyCoord(ra, dec, unit=["deg", "deg"])

# and the size of its field of view
pixel = 0.66 * u.arcsec  # known pixel scale
shape = hdu.data.shape
fov = np.max(shape) * pixel.to(u.deg)

We can then query the gaia stars in the field using this information

import twirl

sky_coords = twirl.gaia_radecs(center, 1.2 * fov)[0:12]

and match the queried stars to stars detected in the image

# detect stars in the image
pixel_coords = twirl.find_peaks(hdu.data)[0:12]

# compute the World Coordinate System
wcs = twirl.compute_wcs(pixel_coords, sky_coords)

leading to a World Coordinate System object.

A more complete example is provided in docs/ipynb/wcs.ipynb

Development

Project Requirements

• Python 3.10+
• uv for Python package and environment management.

Installing Dependencies

Install all dependencies (including dev) with:

$ uv sync --group dev

Then run commands in the project environment with:

$ uv run <command>

N.B. Ensure that any dependency changes are committed to source control, so everyone has a consistent package dependency 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.