FITS WCS

parse_fits_wcs parses one primary or alternate FITS image-header WCS into an ordinary compiled WCS, and find_all_fits_wcs returns every one in a header as a Dict{Char,WCS}. A header is a dictionary of keywords to values, or, with FITSIO.jl or FITSFiles.jl loaded, a header or HDU from those packages.

using GWCS

header = Dict(
    "NAXIS" => 2, "CTYPE1" => "RA---TAN", "CTYPE2" => "DEC--TAN",
    "CRPIX1" => 512.0, "CRPIX2" => 512.0,
    "CRVAL1" => 83.8221, "CRVAL2" => -5.3911,
    "CDELT1" => -2.7778e-4, "CDELT2" => 2.7778e-4,
)
wcs = parse_fits_wcs(header)
pixel_to_world(wcs, 511.0, 511.0)  # FITS pixel CRPIX = (512, 512) is GWCS pixel (511, 511)
2-element StaticArraysCore.SVector{2, Float64} with indices SOneTo(2):
 83.8221
 -5.3911000000000024

FITS numbers the first pixel center 1, and GWCS.jl numbers it 0. The parser adds one to pixel coordinates before the FITS stages (CRPIX, SIP, lookup tables, and prior distortions), so FITS pixel p is GWCS pixel p .- 1. Results at the same physical pixel match WCSLIB, and results at the same pixel coordinates match astropy's pixel_to_world_values.

Reading FITS files

With FITSIO.jl loaded, parse_fits_wcs reads a header or HDU from a FITS file. This writes the header above to a file and reads it back both ways:

using FITSIO

path = joinpath(mktempdir(), "image.fits")
cards = filter(!=("NAXIS"), collect(keys(header)))  # FITSIO writes NAXIS from the image
FITS(path, "w") do file
    write(file, zeros(Float32, 1024, 1024); header=FITSHeader(cards, Any[header[key] for key in cards], fill("", length(cards))))
end

FITS(path) do file
    from_hdu = parse_fits_wcs(file[1])
    from_header = parse_fits_wcs(read_header(file[1]))
    pixel_to_world(from_hdu, 511.0, 511.0), from_hdu.pixel_shape, pixel_to_world(from_header, 511.0, 511.0)
end
([83.8221, -5.3911000000000024], (1024, 1024), [83.8221, -5.3911000000000024])

With FITSFiles.jl loaded, it reads an HDU, or the HDUs of a file with the index of the one holding the WCS:

using FITSFiles

hdus = FITSFiles.fits(path)
pixel_to_world(parse_fits_wcs(hdus, 1), 511.0, 511.0)
2-element StaticArraysCore.SVector{2, Float64} with indices SOneTo(2):
 83.8221
 -5.3911000000000024

An HDU in a file, as a FITSIO.jl HDU or FITSFiles.jl HDUs with an index, also reads the lookup-table and -TAB arrays in other HDUs that the header refers to; a header alone cannot.

Output order and units

World coordinates keep the FITS axis order, including interleaved celestial, spectral, time, Stokes, and linear axes. They are in degrees for celestial axes, SI units for supported linear spectral axes, and seconds for time axes; preserve_units=true keeps supported CUNIT values instead. An image shape missing an NAXISn gives nothing for that axis.

Time axes are normalized deliberately: values in CUNITi, or in TIMEUNIT when CUNITi is absent, are converted to seconds from the header's reference epoch, so downstream code never needs to interpret TIMEUNIT; WCSLIB and astropy instead return time values in the header's unit. The supported time units are s, min, h, d, a or yr (the Julian year of 365.25 d), cy (the Julian century), ms, us, and ns. The single letters S, H, and D are rejected, because FITS reads them as siemens, henry, and debye.

Supported conventions

The parser supports:

  • PC, CD, and legacy CROTA linear forms (as in WCSLIB, CROTA applies only to a celestial axis pair);
  • all 28 FITS spherical projections with their PV parameters, and the pole parameters;
  • SIP, TPV, pre-2012 SCAMP TAN-plus-PV headers, Paper IV prior and sequent TPD polynomials, and legacy DSS and WAT-encoded TNX/ZPX polynomials, normalized to TPD at construction;
  • Paper IV D2IM/CPDIS lookup arrays and multilinear -TAB coordinate arrays;
  • Paper III spectral algorithms and GRI/GRA grism models.

SIP AP/BP and Paper IV TPD.REV coefficients only start the numerical inverse: world_to_pixel seeds the whole-WCS inverse with them and always refines against the forward WCS. Without them, the numerical inverse starts, like WCSLIB, from the solution with distortions treated as identity. CSC (COBE quadrilateralized spherical cube) is evaluated in double precision, whereas WCSLIB uses single precision, so the two differ by up to about 2e-5 degrees. Linked HDU inputs copy referenced images and table columns into the transforms during construction. Separable monotonic 1D tables have direct inverses, while coupled tables use the WCS numerical inverse.

Frames and reference metadata

The world frame has a CelestialFrame for the celestial pair, a SpectralFrame, TemporalFrame, or StokesFrame for each such axis, and one CoordinateFrame for the linear axes, combined in a CompositeFrame named world when there is more than one; each frame's axes_order places its axes at their header positions. As in astropy's wcs_to_celestial_frame, RA/DEC take ICRS, FK5, FK4, or FK4-NO-E from RADESYS and EQUINOX (FK4's obstime is its equinox) and GLON/GLAT are Galactic, and these reference frames are written to ASDF in the form astropy reads. Unlike astropy, RADESYS makes only RA/DEC equatorial, so an ecliptic header is not labeled FK5 or ICRS.

A time axis's reference time follows astropy's FITS WCS: MJDREF, or JDREF, or an ISO 8601 DATEREF that must agree with them to 0.001 day (legacy forms such as DD/MM/YY, which WCSLIB also reads, are rejected), defaulting to zero as in WCSLIB. The scale is the CTYPE, or TIMESYS for TIME, with GPS read as TAI 19 s later, and TREFPOS TOPOCENTER (with OBSGEO-X/Y/Z) or GEOCENTER gives the location.

Metadata the ASDF frame schemas cannot hold stays on the frame's reference_frame as a named tuple, and writing that frame to ASDF raises an error. That metadata is other celestial systems with their RADESYS and EQUINOX; RESTFRQ, RESTWAV, SPECSYS, SSYSOBS, VELOSYS, ZSOURCE, and SSYSSRC; and time sub-scales, the LOCAL scale, other TREFPOS values, and TREFDIR.

Legacy conventions

Headers that use deprecated or informal conventions are repaired the way WCSLIB (with all of its header-parser relaxations) and astropy (which also applies WCSLIB's wcsfix repairs) read them. With the default legacy=:warn, each parse that needs repairs emits one warning listing them; legacy=:quiet repairs silently, and legacy=:error rejects any header that needs a repair. A legacy keyword is used only when its standard spelling is absent; when both are present the standard keyword wins, except that conflicting zero-padded matrix keywords are rejected.

Legacy formInterpretation
NCP projectionSIN with PV2_1 = 0 and PV2_2 = cot(CRVAL2) on the latitude axis; rejected for a zero reference latitude
GLS projectionSFL with its fiducial point offset to the reference latitude (PV1_0 = 1, PV1_2 = CRVAL2 on the longitude axis)
FREQ, VELO, FELO with -LSR, -HEL, -OBS, and VELREFSPECSYS from the suffix, or from VELREF mod 256 when present; VELO becomes VOPT, or VRAD when VELREF ÷ 256 = 1; FELO becomes VOPT-F2W
Celestial RA/DEC (or other pairs) without a projection codeEvaluated linearly
PC00i00j, CD00i00j, and zero-padded PC0i_0j, CD0i_0j, PV0i_0m, PS0i_0mThe standard keyword
PROJPnPVi_n on the latitude axis
EPOCH, RADECSYS, VSOURCEEQUINOX, RADESYS, and the relativistic ZSOURCE
DATE-REF, MJD-REF, MJD-REFI, MJD-REFF, JD-REF, JD-REFI, JD-REFFThe hyphen-free standard keywords; JDREF* give the MJD reference epoch
Both PCi_j and CDi_jPCi_j with CDELTi; CDi_j is ignored
CDi_j with no terms for an axisUnit diagonal for that axis (WCSLIB's cdfix); CDELTi is ignored with CDi_j
SIP coefficients without a -SIP CTYPE suffixSIP is applied (astropy)
-TAN-SIP with SCAMP PVi_m terms (m ≥ 5)SIP is applied and the celestial PVi_m are ignored (astropy)
Non-standard unit spellings such as DEG, HZ, MHZ, Angstroms, SECWCSLIB's safe unit translations (astropy's default); units are otherwise case-sensitive
CROTAi on the longitude axis onlyIgnored, as in WCSLIB, with a warning

Singular linear transformation matrices are rejected. As in WCSLIB, the conic (COP, COD, COE, COO) and Bonne projections require PV2_1 rather than defaulting it, and IRAF WATi_n strings are ignored unless they encode TNX or ZPX on both axes (or CTYPE declares TNX/ZPX). WCSLIB's cylfix (re-centering cylindrical all-sky maps whose pixels extend beyond native longitude ±180°) is not applied, matching astropy's default, and DATE-OBS/OBSGEO-L,B,H repairs are not modeled.