World Coordinate System¶

class fitsy.Wcs(header, alt=' ')¶

Bases: object

World Coordinate System for an HDU.

Constructed via FitsFile.wcs(), ImageHdu.wcs(), or directly from a header. Supports celestial, spectral, time and generic linear axes; SIP, TPV, TNX, -TAB and DSS distortion conventions are recognized.

Examples

>>> with fitsy.open("image.fits") as f:
...     wcs = f[0].wcs()
...     ra, dec = wcs.pixel_to_celestial(512.0, 512.0)

celestial_axes()¶

Indices of the celestial axes.

Returns:: tuple of int or None – (lon_axis, lat_axis) (zero-based), or None if no celestial pair is declared.

celestial_to_pixel(ra, dec, origin=0)¶

Inverse celestial transform.

Parameters:

ra (float) – Sky coordinates in degrees.
dec (float) – Sky coordinates in degrees.
origin (int, optional) – 0 (default) returns 0-based (px, py); 1 returns 1-based FITS pixel coordinates.

Returns:

tuple of float – Pixel coordinates in the chosen origin.

celestial_to_pixel_many(sky, origin=0)¶

Batch celestial inverse transform.

Parameters:

sky (numpy.ndarray) – Shape (N, 2) array of (ra, dec) in degrees.
origin (int, optional) – 0 (default) returns 0-based pixel coordinates, 1 returns 1-based FITS coordinates.

Returns:

numpy.ndarray – Shape (N, 2) array of pixel coordinates.

crval¶: Per-axis CRVAL reference values.

ctype¶: Per-axis CTYPE strings.

cunit¶: Per-axis CUNIT strings.

is_celestial¶: True when the WCS has a celestial axis pair.

naxis¶: Number of axes (NAXIS).

pixel_scale_at(px, py, origin=0)¶

Local pixel scale at (px, py).

Parameters:

px (float) – Pixel coordinates.
py (float) – Pixel coordinates.
origin (int, optional) – 0 (default) treats inputs as 0-based; 1 as 1-based FITS coordinates.

Returns:

tuple of float – Pixel scale in degrees per pixel along the two celestial axes.

pixel_to_celestial(px, py, origin=0)¶

Forward transform a single celestial pixel.

Parameters:

px (float) – Pixel coordinates.
py (float) – Pixel coordinates.
origin (int, optional) – 0 (default) treats inputs as 0-based; 1 as 1-based FITS coordinates.

Returns:

tuple of float – (ra, dec) (or (lon, lat)) in degrees.

pixel_to_celestial_many(pixels, origin=0)¶

Batch celestial forward transform.

Parameters:

pixels (numpy.ndarray) – Shape (N, 2) array of pixel coordinates.
origin (int, optional) – 0 (default) treats inputs as 0-based; 1 as 1-based FITS coordinates.

Returns:

numpy.ndarray – Shape (N, 2) array of (ra, dec) in degrees.

pixel_to_world(pix, origin=0)¶

Forward transform a single pixel coordinate.

Parameters:

pix (sequence of float) – Length-naxis pixel coordinate.
origin (int, optional) – 0 (default) treats pix as 0-based (numpy/C convention, matching astropy.wcs); 1 treats it as 1-based FITS coordinates.

Returns:

list of float – World coordinates with units given by cunit.

to_header(alt=' ')¶

Serialize this WCS to a fresh Header.

Parameters:: alt (str, optional) – ' ' (default) for the primary description, or 'A' through 'Z' for an alternate.
Raises:: ValueError – For spectral, -TAB, TPV, TNX or DSS WCSs (not supported on the write path).

world_to_pixel(world, origin=0)¶

Inverse transform world to pixel.

Parameters:

world (sequence of float) – Length-naxis world coordinate.
origin (int, optional) – 0 (default) returns 0-based pixel coordinates, 1 returns 1-based FITS coordinates.

Returns:

list of float – Pixel coordinate in the chosen origin.

class fitsy.WcsFit¶

Bases: object

Result of fit_wcs().

Carries the fitted Wcs and per-point residuals.

Variables:

wcs (Wcs) – The fitted world coordinate system.
rms_arcsec (float) – Root-mean-square residual across all reference points (arcsec).
max_arcsec (float) – Largest single-point residual (arcsec).

max_arcsec¶

residuals_arcsec¶

Per-point residuals as a numpy array.

Returns:: numpy.ndarray – Shape (N, 2) of (delta_alpha * cos(delta), delta_dec) in arcseconds.

rms_arcsec¶

wcs¶

fitsy.fit_wcs(pixels, sky, projection='TAN', crpix=None, crval=None, sip_order=None, fit_sip_inverse=True, frame='equatorial', origin=0)¶

Fit a celestial WCS to (pixel, sky) reference correspondences.

Parameters:

pixels (numpy.ndarray) – Shape (N, 2) array of pixel coordinates.
sky (numpy.ndarray) – Shape (N, 2) array of (ra, dec) in degrees, or more generally (lon, lat) in the chosen frame.
projection (str, optional) – Three-letter projection code (default "TAN").
crpix (tuple of float, optional) – Pin the reference pixel; otherwise solved as part of the fit. Interpreted in the same origin as pixels.
crval (tuple of float, optional) – Pin the tangent point; otherwise defaults to the spherical centroid of the sky points.
sip_order (int, optional) – Enable a SIP polynomial distortion fit of the given order (typically 2-4).
fit_sip_inverse (bool, optional) – When sip_order is given, also fit the AP/BP inverse polynomial. Default True.
frame ({'equatorial', 'galactic', 'ecliptic', 'supergalactic', 'helioecliptic'}, optional) – Celestial frame for the sky coordinates. 'equatorial' is the default and emits RA-/DEC- CTYPE pairs.
origin (int, optional) – 0 (default, numpy/C convention) treats pixels and crpix as 0-based; 1 treats them as 1-based FITS coordinates. The fitted WCS itself always carries 1-based CRPIX values per the FITS standard.

Returns:

WcsFit – Fitted WCS, residuals, and summary statistics.

Raises:

ValueError – On shape mismatches or unknown projection/frame.

Examples

>>> import numpy as np, fitsy
>>> pix = np.array([[100.0, 100.0], [200.0, 100.0], [100.0, 200.0]])
>>> sky = np.array([[10.00, -5.00], [10.05, -5.00], [10.00, -4.95]])
>>> fit = fitsy.fit_wcs(pix, sky, projection="TAN")
>>> fit.rms_arcsec
0.0