WCS
GWCS.jl exports the names in the first three sections of this page. The pipeline functions after them, and the names on the other API pages, are public but not exported: use them as GWCS.Step, or import them with using GWCS: Step.
Reading and writing
GWCS.WCS — Type
WCS(steps::Step...; name="", pixel_shape=nothing, bounding_box=nothing)A WCS pipeline: a sequence of coordinate frames, each Step holding a frame and the transform to the next, from the input (pixel) frame to the output (world) frame. Construction validates the pipeline and compiles its transforms once, for fast repeated evaluation with pixel_to_world and world_to_pixel. A WCS is immutable; editing functions such as set_transform return a new one.
Each step's transform maps its frame's dimension to the next frame's. The last step has no transform, and frame names are unique. An invalid pipeline throws an ArgumentError or a DimensionMismatch.
pixel_shape gives the image size along each pixel axis, with nothing for an axis without one. bounding_box, a BoundingBox or CompoundBoundingBox over the pixel axes, limits the input domain.
When every step has an analytical inverse, the WCS inverse composes them. Otherwise world_to_pixel solves numerically, which needs as many world as pixel axes.
Examples
julia> using GWCS
julia> using GWCS: Frame2D, Scale, Shift, Step
julia> wcs = WCS(Step(Frame2D(name="detector"), Shift(1.0) & Scale(2.0)), Step(Frame2D(name="world")));
julia> available_frames(wcs)
("detector", "world")
julia> pixel_n_dim(wcs), world_n_dim(wcs)
(2, 2)Python equivalent: gwcs.WCS, which takes the steps as a list of (frame, transform) pairs.
GWCS.parse_wcs — Function
parse_wcs(node::AbstractDict; registry=default_transform_registry()) -> WCS
parse_wcs(yaml::AbstractString; registry=default_transform_registry()) -> WCSBuild a WCS from a tag:stsci.edu:gwcs/wcs metadata node, such as ASDF.load_file(filename)["wcs"] with ASDF.jl loaded, or from YAML text holding one. An astropy FITS WCS stored with asdf-astropy's wcs tag is read through parse_fits_wcs. Transforms are parsed by the tags registered in registry; see register_transform!.
Metadata that is malformed, uses an unsupported tag or schema version, or describes an invalid pipeline throws an ArgumentError naming its path in the tree. Properties GWCS.jl does not model are kept and written back by write_asdf.
GWCS.parse_fits_wcs — Function
parse_fits_wcs(header::AbstractDict; key=' ', preserve_units=false, minerr=0.0, legacy=:warn) -> WCS
parse_fits_wcs(header::FITSIO.FITSHeader; kwargs...) -> WCS
parse_fits_wcs(hdu::FITSIO.HDU; kwargs...) -> WCS
parse_fits_wcs(cards::FITSFiles.Cards; kwargs...) -> WCS
parse_fits_wcs(hdu::FITSFiles.HDU; kwargs...) -> WCS
parse_fits_wcs(hdus::AbstractVector{<:FITSFiles.HDU}, index; kwargs...) -> WCSBuild a WCS from a FITS image header. key=' ' selects the primary WCS, and a letter selects that alternate WCS. A header that is not a valid WCS throws an ArgumentError.
The header is a dictionary of keywords to values, or, with FITSIO.jl or FITSFiles.jl loaded, one of the objects above. To read the lookup-table and -TAB arrays a header refers to, pass a FITSIO.jl HDU, or FITSFiles.jl HDUs with the index of the HDU holding the WCS.
Pixel coordinates are zero-based, as everywhere in GWCS.jl, so FITS pixel p is GWCS pixel p .- 1; CRPIX needs no adjustment. World coordinates keep the header's axis order. They are in degrees for celestial axes, SI units for spectral axes, and seconds from the reference epoch for time axes, unless preserve_units=true keeps the header's CUNIT values.
A distortion whose D2IMERR or CPERR error estimate is below minerr is dropped, as astropy does. Legacy conventions that WCSLIB and astropy accept, such as NCP, AIPS spectral types, EPOCH, and zero-padded keyword indices, are repaired with one warning per parse when legacy=:warn, silently when legacy=:quiet, and rejected when legacy=:error.
Python equivalent: astropy.wcs.WCS, which evaluates the header with WCSLIB rather than building a GWCS pipeline.
GWCS.find_all_fits_wcs — Function
find_all_fits_wcs(header; preserve_units=false, minerr=0.0, legacy=:warn) -> Dict{Char,WCS}Build a WCS from every primary and alternate WCS representation in a FITS header, keyed by its letter (' ' for the primary). The header forms and keywords are those of parse_fits_wcs. A malformed representation throws an ArgumentError naming its key.
Python equivalent: astropy.wcs.find_all_wcs.
GWCS.write_asdf — Function
write_asdf(filename, wcs::WCS; key="wcs")Write wcs to an ASDF file under key; requires loading ASDF.jl. To write it alongside other values, pass a document to ASDF.write_file or save, which write GWCS objects anywhere in it. parse_wcs reads the WCS back.
Python equivalent: asdf.AsdfFile({key: wcs}).write_to(filename).
Evaluation
GWCS.pixel_to_world — Function
pixel_to_world(wcs, pixels...; with_bounding_box=true, fill_value=NaN, strict=false, origin=0) -> SVector
pixel_to_world(wcs, pixels::AbstractMatrix; kwargs...) -> MatrixReturn the world coordinate of a pixel, in transform order and in the output frame's units. The pixel is given as separate numbers, a vector, or a tuple; a matrix holds one pixel per column and returns one world coordinate per column.
Pixels are zero-based: the center of the first pixel is 0 on every axis. origin=1 takes one-based pixels, as Julia array indices and FITS number them, by shifting every pixel axis by one; world coordinates are never shifted.
A pixel outside the bounding box, or one without a world coordinate, gives fill_value on every world axis. with_bounding_box=false ignores the bounding box. strict=true throws a DomainError for these pixels instead, and the error names the step and transform where the coordinate is undefined. With strict=true, a pixel that is already NaN gives NaN rather than an error.
Examples
using GWCS
using GWCS: Frame2D, Scale, Shift, Step
wcs = WCS(Step(Frame2D(name="detector"), Shift(1.0) & Scale(2.0)), Step(Frame2D(name="world")))
pixel_to_world(wcs, 1.0, 2.0) # [2.0, 4.0]
pixel_to_world(wcs, 2.0, 3.0; origin=1) # [2.0, 4.0]Python equivalent: gwcs.WCS.pixel_to_world_values; Python's pixel_to_world returns astropy coordinate objects instead.
GWCS.world_to_pixel — Function
world_to_pixel(wcs, world...; with_bounding_box=true, fill_value=NaN, strict=false, origin=0,
tolerance=1e-5, maxiter=30, initial_guess=nothing, max_backtracks=12, quiet=false) -> SVector
world_to_pixel(wcs, world::AbstractMatrix; kwargs...) -> MatrixReturn the zero-based pixel of a world coordinate given in transform order and in the output frame's units, or the one-based pixel with origin=1. Coordinate forms, with_bounding_box, fill_value, and strict act as in pixel_to_world: a world coordinate without a pixel, or whose pixel is outside the bounding box, gives fill_value.
A WCS with an analytical inverse evaluates it. Otherwise a damped Newton solver inverts the forward transform, which needs as many world as pixel axes; with unequal dimensions, world_to_pixel throws an ArgumentError. The solver stops within tolerance pixels or after maxiter iterations, and halves a step at most max_backtracks times. It starts from initial_guess, a pixel that is one-based with origin=1, or from GWCS.jl's own estimate when that is nothing.
A solve that does not converge throws NoConvergence unless quiet=true, which returns the last iterate.
Python equivalent: gwcs.WCS.world_to_pixel_values; Python's world_to_pixel takes astropy coordinate objects instead.
GWCS.pixel_to_world_jacobian — Function
pixel_to_world_jacobian(wcs, pixels...; with_bounding_box=true, fill_value=NaN, strict=false, origin=0) -> SMatrix
pixel_to_world_jacobian(wcs, pixels::AbstractMatrix; kwargs...) -> Vector{<:SMatrix}Return the Jacobian of pixel_to_world at a pixel, the world_n_dim × pixel_n_dim matrix of ∂world_i/∂pixel_j. World coordinates are in transform order and in their frame's units, so celestial axes in degrees give degrees per pixel, with no cos(latitude) factor.
Coordinate forms and keywords act as in pixel_to_world. A pixel without a result, including one whose Jacobian is undefined, gives a matrix of fill_value, or a DomainError with strict=true.
GWCS.world_to_pixel_jacobian — Function
world_to_pixel_jacobian(wcs, world...; with_bounding_box=true, fill_value=NaN, strict=false, origin=0, kwargs...) -> SMatrix
world_to_pixel_jacobian(wcs, world::AbstractMatrix; kwargs...) -> Vector{<:SMatrix}Return the Jacobian of world_to_pixel at a world coordinate, the pixel_n_dim × world_n_dim matrix of ∂pixel_i/∂world_j, with the coordinate forms, keywords, and units of world_to_pixel. With an analytical inverse it is that inverse's Jacobian. Without one it is the inverse of the forward Jacobian at the pixel the numerical inverse finds, which takes world_to_pixel's solver keywords.
An analytical inverse that approximates the forward transform, such as a fitted polynomial, has a Jacobian that differs from the inverse of the forward Jacobian by that approximation. The Jacobian of the exact inverse of the forward transform is inv(pixel_to_world_jacobian(wcs, numerical_inverse(wcs, world))).
GWCS.in_domain — Function
in_domain(wcs, pixels...; origin=0) -> Bool
in_domain(wcs, pixels::AbstractMatrix; origin=0) -> BitVectorReturn whether a pixel is finite and inside the WCS bounding box. Without a bounding box, every finite pixel is in the domain. Pixels are zero-based unless origin=1, as in pixel_to_world, and a matrix holds one pixel per column.
GWCS.in_image — Function
in_image(wcs, world...; with_bounding_box=true, origin=0, tolerance=1e-5, maxiter=30, initial_guess=nothing,
max_backtracks=12) -> Bool
in_image(wcs, world::AbstractMatrix; kwargs...) -> BitVectorReturn whether a world coordinate has a finite pixel inside the bounding box. The pixel comes from the analytical inverse or, without one, the numerical inverse that world_to_pixel uses, with its solver keywords; a solve that does not converge gives false. with_bounding_box=false skips the bounding-box test, and origin=1 reads initial_guess as a one-based pixel. A matrix holds one world coordinate per column.
Python equivalent: gwcs.WCS.in_image.
GWCS.pixel_area — Function
pixel_area(wcs, pixels...; with_bounding_box=true, fill_value=NaN, strict=false, origin=0) -> Real
pixel_area(wcs, pixels::AbstractMatrix; kwargs...) -> Vector
pixel_area(wcs, xs::AbstractUnitRange, ys::AbstractUnitRange; kwargs...) -> MatrixReturn the solid angle in steradians that a pixel covers on the sky, evaluated at the pixel center. It is |det J| cos(lat), where J is the Jacobian of the world coordinates in radians per pixel and lat is the latitude. The WCS needs 2 pixel axes and a 2D CelestialFrame output frame in deg or rad. Coordinate forms and keywords act as in pixel_to_world.
Given ranges of integer pixel coordinates, it returns the areas of the pixel grid xs × ys as a matrix indexed like data[x, y], so pixel_area(wcs, axes(data)...; origin=1) covers an image. Each area is the solid angle within the pixel's four corners rather than the value at its center, so it differs slightly from the single-pixel form.
WCS properties
GWCS.pixel_n_dim — Function
pixel_n_dim(wcs) -> IntReturn the number of pixel axes, the dimension of the WCS input frame.
Python equivalent: gwcs.WCS.pixel_n_dim.
GWCS.world_n_dim — Function
world_n_dim(wcs) -> IntReturn the number of world axes, the dimension of the WCS output frame.
Python equivalent: gwcs.WCS.world_n_dim.
GWCS.pixel_axis_names — Function
pixel_axis_names(wcs) -> NTuple{pixel_n_dim,String}Return the input frame's axis_names in transform order.
Python equivalent: gwcs.WCS.pixel_axis_names.
GWCS.world_axis_names — Function
world_axis_names(wcs) -> NTuple{world_n_dim,String}Return the output frame's axis_names in transform order.
Python equivalent: gwcs.WCS.world_axis_names.
GWCS.pixel_axis_physical_types — Function
pixel_axis_physical_types(wcs) -> NTuple{pixel_n_dim,String}Return the input frame's axis_physical_types in transform order.
Python equivalent: gwcs.WCS.input_frame.axis_physical_types.
GWCS.world_axis_physical_types — Function
world_axis_physical_types(wcs) -> NTuple{world_n_dim,String}Return the output frame's axis_physical_types in transform order, as strings such as "pos.eq.ra".
Python equivalent: gwcs.WCS.world_axis_physical_types.
GWCS.pixel_axis_units — Function
pixel_axis_units(wcs) -> NTuple{pixel_n_dim,String}Return the input frame's axis_units in transform order.
Python equivalent: gwcs.WCS.input_frame.unit, which holds astropy units rather than strings.
GWCS.world_axis_units — Function
world_axis_units(wcs) -> NTuple{world_n_dim,String}Return the output frame's axis_units in transform order, as strings such as "deg".
Python equivalent: gwcs.WCS.world_axis_units.
GWCS.pixel_axis_types — Function
pixel_axis_types(wcs) -> TupleReturn the input frame's axis_types in transform order. Each entry is an AxisType, such as GWCS.SPATIAL, or a string for a custom type.
Python equivalent: gwcs.WCS.input_frame.axes_type, which holds strings.
GWCS.world_axis_types — Function
world_axis_types(wcs) -> TupleReturn the output frame's axis_types in transform order. Each entry is an AxisType, such as GWCS.SPATIAL, or a string for a custom type.
Python equivalent: gwcs.WCS.output_frame.axes_type, which holds strings.
GWCS.axis_correlation_matrix — Function
axis_correlation_matrix(wcs) -> SMatrix{world_n_dim,pixel_n_dim,Bool}
axis_correlation_matrix(transform) -> SMatrix{output_dimension,input_dimension,Bool}Return which world axes depend on which pixel axes: entry (i, j) is true when world axis i can change with pixel axis j, both in transform order. A false entry guarantees independence, and a transform that cannot tell reports true. For a transform it is transform_dependencies.
Python equivalent: gwcs.WCS.axis_correlation_matrix, and astropy.modeling.separable.separability_matrix for a transform.
GWCS.input_frame — Function
input_frame(wcs) -> AbstractCoordinateFrameReturn the frame of the first step, whose coordinates are the WCS pixels.
Python equivalent: gwcs.WCS.input_frame.
GWCS.output_frame — Function
output_frame(wcs) -> AbstractCoordinateFrameReturn the frame of the last step, whose coordinates are the WCS world coordinates.
Python equivalent: gwcs.WCS.output_frame.
GWCS.available_frames — Function
available_frames(wcs) -> Tuple{Vararg{String}}Return the names of the WCS frames, from the input frame to the output frame.
Python equivalent: gwcs.WCS.available_frames.
GWCS.with_bounding_box — Function
with_bounding_box(wcs, bounding_box) -> WCSReturn a copy of wcs whose input domain is bounding_box, a BoundingBox or CompoundBoundingBox over the pixel axes, or that has no bounding box for nothing.
Python equivalent: setting gwcs.WCS.bounding_box, which changes the WCS in place.
GWCS.with_pixel_shape — Function
with_pixel_shape(wcs, pixel_shape) -> WCSReturn a copy of wcs with pixel_shape, the image size along each pixel axis in transform order, or with no pixel shape for nothing. An entry of nothing leaves that axis without a size.
Python equivalent: setting gwcs.WCS.pixel_shape, which changes the WCS in place.
Pipelines
GWCS.get_frame — Function
get_frame(wcs, frame) -> AbstractCoordinateFrameReturn the frame stored in wcs for frame, given as a name, a symbol, or a frame with that name. A frame not in the pipeline throws an ArgumentError.
GWCS.get_transform — Function
get_transform(wcs, from_frame, to_frame) -> Union{AbstractTransform,NoInverse}Return the transform between two frames of wcs, each given by name or as a frame. Toward the output frame it composes the steps between them; back toward the input frame it composes their inverses, and gives NoInverse when a step has none. The same frame twice gives an identity, and a frame not in the pipeline throws an ArgumentError.
Python equivalent: gwcs.WCS.get_transform.
GWCS.transform — Function
GWCS.transform(wcs, from_frame, to_frame, coords...) -> SVectorEvaluate get_transform(wcs, from_frame, to_frame) at a coordinate, given as separate numbers or a static vector. Unlike pixel_to_world, it applies no bounding box and no fill_value. A direction without an inverse throws an ArgumentError.
Python equivalent: gwcs.WCS.transform, which applies the bounding box by default.
GWCS.set_transform — Function
set_transform(wcs, from_frame, to_frame, transform) -> WCSReturn a copy of wcs whose transform from from_frame to the next frame, to_frame, is transform. Frames are given by name or as frames, and frames that are not adjacent in that order throw an ArgumentError.
Python equivalent: gwcs.WCS.set_transform, which changes the WCS in place.
GWCS.insert_transform — Function
insert_transform(wcs, frame, transform; after=false) -> WCSReturn a copy of wcs with transform inserted at frame. With after=false, it runs last in the transform leading into frame; with after=true, it runs first in the transform leaving frame. Frame metadata is unchanged, although the coordinate values in the frames it affects change.
Python equivalent: gwcs.WCS.insert_transform, which changes the WCS in place.
GWCS.prepend_transform — Function
prepend_transform(wcs, transform) -> WCSReturn a copy of wcs with transform applied to the pixels first, as insert_transform(wcs, input_frame(wcs), transform; after=true) does.
GWCS.append_transform — Function
append_transform(wcs, transform) -> WCSReturn a copy of wcs with transform applied last, before the output frame, as insert_transform(wcs, output_frame(wcs), transform) does.
GWCS.insert_frame — Function
insert_frame(wcs, input, transform, output; pixel_shape, bounding_box) -> WCSReturn a copy of wcs with a new frame joined to the pipeline by transform. Exactly one of input and output is a frame already in wcs, given by name or as a frame, and the other is the new frame.
When output is new, it is inserted right after input. transform connects them, and the transform that left input now starts at output.
When input is new, it is inserted right before output. transform connects them, and the transform that reached output now ends at input.
Either way the overall mapping changes unless transform is an identity. pixel_shape and bounding_box are accepted only when the new frame becomes the WCS input frame. Then each value wcs has needs a replacement for the new coordinates, or nothing to clear it.
Python equivalent: gwcs.WCS.insert_frame, which changes the WCS in place.
GWCS.prepend_frame — Function
prepend_frame(wcs, frame, transform; pixel_shape, bounding_box) -> WCSReturn a copy of wcs with frame as its new input frame and transform mapping it to the old one, as insert_frame(wcs, frame, transform, input_frame(wcs)) does. When wcs has a pixel shape or bounding box, pass their replacements for the new pixel coordinates, or nothing to clear them.
GWCS.append_frame — Function
append_frame(wcs, transform, frame) -> WCSReturn a copy of wcs with frame as its new output frame and transform mapping the old output frame to it, as insert_frame(wcs, output_frame(wcs), transform, frame) does.
GWCS.remove_frame — Function
remove_frame(wcs, frame) -> WCSReturn a copy of wcs without the intermediate frame, with the transforms into and out of it composed into one. The overall mapping is unchanged. Removing the input or output frame throws an ArgumentError.
GWCS.rename_frame — Function
rename_frame(wcs, frame, name) -> WCSReturn a copy of wcs with frame named name and otherwise unchanged. An empty name, or one another frame already has, throws an ArgumentError.
GWCS.fix_inputs — Function
fix_inputs(transform, fixed; atol=nothing, rtol=nothing) -> AbstractTransform
fix_inputs(wcs, fixed; atol=nothing, rtol=nothing) -> WCSReturn transform with some inputs held at constant values, as a transform of the remaining inputs in their original order. fixed is a pair, a collection of pairs, a named tuple, or a dictionary mapping each input to its value. An input is a one-based index or, for a transform with input_names, a name as a string or symbol.
When transform has an inverse, the result has a checked inverse. It verifies the fixed input values and the forward round trip within atol and rtol, and returns NaN for a coordinate outside the fixed-input slice. By default rtol is sqrt(eps) and atol scales with it. With every input fixed, the inverse has no outputs and throws a DomainError instead.
For a WCS, the inputs are pixel axes, named by the input frame's axis_names. The input frame, bounding box, and pixel shape lose the fixed axes.
Python equivalent: astropy.modeling.fix_inputs, and gwcs.WCS.fix_inputs for a WCS.
GWCS.numerical_inverse — Function
numerical_inverse(wcs, world...; tolerance=1e-5, maxiter=30, initial_guess=nothing, max_backtracks=12, quiet=false,
with_bounding_box=true, fill_value=NaN, strict=false, origin=0) -> SVectorSolve pixel_to_world(wcs, pixel) == world numerically for pixel, to tolerance pixels. The damped Newton solver is the one world_to_pixel uses without an analytical inverse, and it needs equal pixel and world dimensions. With an analytical inverse, which may only approximate the forward transform, the solver starts from that inverse's pixel and refines it against the forward transform. Nonconvergence throws NoConvergence unless quiet=true; the other keywords act as in world_to_pixel.
Python equivalent: gwcs.WCS.numerical_inverse.
GWCS.NoConvergence — Type
NoConvergenceThe exception world_to_pixel and numerical_inverse throw when the numerical inverse does not reach its tolerance. best_solution holds the last pixel, accuracy its error, and niter the iterations used.
Python equivalent: gwcs.wcs.NoConvergence.