GWCS.jl implements generalized world coordinate systems in Julia. A WCS is a pipeline of coordinate frames joined by transforms, from detector pixels to world coordinates such as sky positions, wavelengths, and times. Pipelines are compiled when they are built, so evaluating a coordinate is fast and allocation-free. GWCS.jl reads the WCSs in FITS headers and in the ASDF metadata Python GWCS writes, and writes the pipelines ASDF can represent back to ASDF.
pkg> add https://github.com/JuliaAstro/GWCS.jlFITS and ASDF support load automatically with FITSIO.jl, FITSFiles.jl, or ASDF.jl.
- Pixels are zero-based: the center of the first pixel is
0, as in Python GWCS and astropy.origin=1takes and returns one-based pixels, as Julia arrays and FITS number them. - Coordinates are in transform order: a frame's
axes_orderlabels its axes and never reorders them. - A coordinate without a result gives
fill_value(defaultNaN), or aDomainErrorwithstrict=true. A numerical inverse that does not converge throwsNoConvergence. - Angles are in degrees: angle parameters and the coordinates that projections and celestial rotations take and
return are in degrees. Coordinates are in the units their frame records, which
world_axis_unitsreturns.parse_fits_wcsconverts celestial axes to degrees, or keeps the header'sCUNITwithpreserve_units=true, and an ASDF frame keeps its stored units, such as arcseconds for a V2/V3 frame. - Exports: GWCS.jl exports what loading and evaluating a WCS needs. Transforms, frames, and the other building
blocks are public but not exported; import them by name, as in
using GWCS: Shift.
The documentation describes these conventions and the differences from Python GWCS in detail.
From a FITS header as a dictionary:
using GWCS
header = Dict("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)
world = pixel_to_world(wcs, 511.0, 511.0)
pixel = world_to_pixel(wcs, world)From an ASDF file, and back to one:
using ASDF, GWCS
wcs = parse_wcs(ASDF.load("roman_cal.asdf"; extensions=true)["roman"]["meta"]["wcs"])
write_asdf("wcs.asdf", wcs)From a FITS file with FITSIO.jl:
using FITSIO, GWCS
wcs = FITS("image.fits") do file
parse_fits_wcs(file[1])
endFrom a FITS file with FITSFiles.jl:
using FITSFiles, GWCS
wcs = parse_fits_wcs(FITSFiles.fits("image.fits"), 1)- Composable pipelines (
|,&, and elementwise arithmetic) compiled for inferred, allocation-free evaluation, with matrix forms for many coordinates at once - Analytical inverses, and a damped Newton numerical inverse that first inverts the analytically invertible part of
the pipeline, as astropy's
all_world2pixdoes - Jacobians in both directions, and pixel solid angles for single pixels or whole images
- Shift, scale, affine, axis remapping, constant, fixed-input, polynomial, 2D and 3D rotation, and spherical-Cartesian transforms, and all 28 FITS spherical projections
- Region-selected transforms for IFU slices, detector regions, and spectral orders, with array, dictionary, range, transform, and callable label mappers
- Bounding boxes and compound bounding boxes, with
in_domain,in_image, and grid sampling - Celestial, spectral, temporal, Stokes, composite, and generic frames, with the APE 14 axis accessors
- Non-mutating pipeline editing: insert, remove, rename, and replace frames and transforms
- FITS WCS reading: PC, CD, and CROTA linear forms; SIP, TPV, TPD, TNX, and ZPX distortions; D2IM and CPDIS lookup
tables;
-TABcoordinate arrays; spectral algorithms and grisms; time axes; and repairs for legacy conventions - Reading and writing Python GWCS's ASDF metadata, keeping properties GWCS.jl does not model
- An extension API for new transforms, including registering their metadata
- Callable transforms for prototypes and closures
- Validated against Python GWCS, astropy, and WCSLIB
The design of GWCS.jl was inspired by Python GWCS. The development of the FITS WCS features was aided by validation (see validation/) against astropy and WCSLIB. The sample headers in test/fixtures/wcslib are from WCSLIB and are
distributed under the LGPL v3; see test/fixtures/wcslib/COPYING.LESSER.