Frames and domains

Frames

GWCS.CoordinateFrame — Type
CoordinateFrame{N}(; name, axes_names=("x0", "x1", ...), axes_order=(1, 2, ...), axis_types=(UNDEFINED, ...),
                   axis_physical_types=nothing, unit=("", ...), reference_frame=nothing)

A frame of N axes of any kind, such as pixels or focal-plane coordinates. axes_names, axis_types, axis_physical_types, and unit each hold one entry per axis, in the frame's own order. Axis types are AxisTypes or custom strings, and physical types default to "custom:<axis name>".

axes_order[i] is the transform position of frame axis i, so it labels coordinates without reordering them; the accessors such as axis_names return transform order. reference_frame holds metadata that describes the coordinates, kept for round trips.

Python equivalent: gwcs.coordinate_frames.CoordinateFrame.

source
GWCS.Frame2D — Function
Frame2D(; name, axes_names=("x", "y"), axes_order=(1, 2), axis_types=nothing, axis_physical_types=nothing,
        unit=("", ""), reference_frame=nothing) -> CoordinateFrame{2}

Return a two-axis CoordinateFrame whose axes are spatial unless axis_types says otherwise, such as a detector or focal-plane frame. Metadata writes a two-axis spatial frame without a reference frame as frame2d.

Python equivalent: gwcs.coordinate_frames.Frame2D.

source
GWCS.CelestialFrame — Type
CelestialFrame(; name, axes_names=("lon", "lat"), axes_order=(1, 2), axis_physical_types=("pos.eq.ra", "pos.eq.dec"),
               unit=("deg", "deg"), reference_frame=:ICRS)
CelestialFrame{N}(; kwargs...)

A frame of sky positions: longitude and latitude in that frame order, and with N = 3 a distance. Its axes are spatial. reference_frame identifies the celestial system; frames read from FITS or ASDF metadata hold the system it describes, such as FK5 with its equinox. Per-axis keywords are in frame order; CoordinateFrame describes axes_order.

Python equivalent: gwcs.coordinate_frames.CelestialFrame.

source
GWCS.SpectralFrame — Type
SpectralFrame(; name="spectral", axes_names=("spectral",), axes_order=(1,), axis_physical_types=nothing, unit=("",),
              reference_frame=nothing, reference_position="geocenter")

A one-axis frame of a spectral coordinate. Without axis_physical_types, the unit sets the physical type: "em.wl" for a length, "em.freq" for a frequency, "em.energy" for an energy, "spect.dopplerVeloc" for a velocity, and "custom:spectral" otherwise. reference_position is "geocenter", "barycenter", or "heliocenter". CoordinateFrame describes the shared keywords.

Python equivalent: gwcs.coordinate_frames.SpectralFrame.

source
GWCS.TemporalFrame — Type
TemporalFrame(; name="temporal", axes_names=("time",), axes_order=(1,), axis_physical_types=("time",), unit=("s",),
              reference_frame=nothing, reference_epoch=nothing, time_scale="", time_format="", location=nothing)

A one-axis frame whose coordinate is a time offset in unit from reference_epoch, which defaults to reference_frame. offset_to_time and time_to_offset convert between offsets and times. time_scale and time_format describe the epoch, for example "utc" and "mjd", and location is the observer's location for topocentric times. CoordinateFrame describes the shared keywords.

Python equivalent: gwcs.coordinate_frames.TemporalFrame.

source
GWCS.StokesFrame — Type
StokesFrame(; name="stokes", axes_names=("stokes",), axes_order=(1,), axis_physical_types=("phys.polarization.stokes",))

A unitless one-axis frame whose coordinate selects a Stokes parameter, numbered as in FITS, such as 1 to 4 for I, Q, U, and V. CoordinateFrame describes the shared keywords.

Python equivalent: gwcs.coordinate_frames.StokesFrame.

source
GWCS.CompositeFrame — Type
CompositeFrame(frames; name="composite")

A frame combining other frames, such as a celestial and a spectral frame for an image cube. Its axes are the constituents' axes, concatenated in the order given. Each constituent's axes_order gives its axes' transform positions in the whole composite, and together these must be a permutation of 1:N, where N is the total number of axes. Nested composites flatten.

Python equivalent: gwcs.coordinate_frames.CompositeFrame.

source
GWCS.EmptyFrame — Type
EmptyFrame{N}(name)

A frame with N axes known only by its name, which a step frame written as a bare string in metadata becomes. It has no axis names, physical types, units, or types, and is written back as its name.

Python equivalent: gwcs.coordinate_frames.EmptyFrame.

source
GWCS.AxisType — Type
AxisType

The kind of a frame axis: GWCS.SPATIAL, GWCS.SPECTRAL, GWCS.TIME, GWCS.STOKES, GWCS.PIXEL, or GWCS.UNDEFINED. Frames also accept these names as case-insensitive strings, with "TEMPORAL" for TIME, and keep any other nonempty string as a custom type.

Python equivalent: the strings of gwcs.coordinate_frames.CoordinateFrame.axes_type.

source
GWCS.frame_dimension — Function
frame_dimension(frame) -> Int

Return the number of axes of frame.

Python equivalent: gwcs.coordinate_frames.CoordinateFrame.naxes.

source
GWCS.axis_names — Function
axis_names(frame) -> NTuple{N,String}

Return the names of the frame's axes in transform order.

Python equivalent: gwcs.coordinate_frames.CoordinateFrame.axes_names.

source
GWCS.axis_physical_types — Function
axis_physical_types(frame) -> NTuple{N,String}

Return the physical types of the frame's axes in transform order, as IVOA UCD strings such as "pos.eq.ra" or "custom:<name>".

Python equivalent: gwcs.coordinate_frames.CoordinateFrame.axis_physical_types.

source
GWCS.axis_units — Function
axis_units(frame) -> NTuple{N,String}

Return the units of the frame's axes in transform order, as strings such as "deg", empty for a unitless axis.

Python equivalent: gwcs.coordinate_frames.CoordinateFrame.unit, which holds astropy units rather than strings.

source
GWCS.axis_types — Function
axis_types(frame) -> Tuple

Return the types of the frame's axes in transform order. Each entry is an AxisType, such as GWCS.SPATIAL, or a string for a custom type.

Python equivalent: gwcs.coordinate_frames.CoordinateFrame.axes_type, which holds strings.

source
GWCS.offset_to_time — Function
offset_to_time(frame::TemporalFrame, offset)

Return the time offset after the frame's reference epoch. With a numeric epoch in the "jd" or "mjd" format, the result is a Julian or modified Julian date, with offset converted to days from the frame's unit (d, h, min, or s). Otherwise it is reference_epoch + offset. A frame without a reference epoch, or with another numeric format, throws an ArgumentError.

source

Bounding boxes

GWCS.BoundingBox — Type
BoundingBox(intervals; order=:F)
BoundingBox{N}(intervals, axes; order=:F)

A rectangular input domain: an inclusive (lower, upper) interval for each bounded input axis. BoundingBox(intervals) bounds every axis, one interval per axis in transform order. BoundingBox{N}(intervals, axes) bounds the listed axes of N; the other axes are unconstrained, though a point in the domain must still be finite. With order=:C, the intervals are listed in the reverse order of the axes, as in NumPy's row-major convention.

A lower bound above its upper bound, a repeated axis, or an axis outside 1:N throws an ArgumentError.

Python equivalent: astropy.modeling.bounding_box.ModelBoundingBox.

source
GWCS.CompoundBoundingBox — Type
CompoundBoundingBox(boxes, selector_axes; selector_ignored=true, ignored=())
CompoundBoundingBox{N}(boxes, selector_axes; selector_ignored=true, ignored=())

An input domain that depends on the values of selector inputs, such as the spectral order of a slit spectrum. boxes maps each selector value, or a tuple of values for several selector_axes, to the BoundingBox that applies; all boxes bound the same axes. A coordinate whose selector values match no entry exactly is outside the domain.

selector_ignored says whether the boxes leave out each selector axis, as one flag or one per selector axis. ignored lists axes that no box constrains. Every axis is bounded, a selector, or ignored, or construction throws an ArgumentError. select_bounding_box returns the box for a selector value.

Python equivalent: astropy.modeling.bounding_box.CompoundBoundingBox.

source
GWCS.bounded_axes — Function
bounded_axes(box::BoundingBox) -> Tuple{Vararg{Int}}

Return the input axes box constrains, in increasing order.

source
GWCS.ignored_axes — Function
ignored_axes(box) -> Tuple{Vararg{Int}}

Return the input axes no interval of box constrains: for a BoundingBox the axes it does not bound, and for a CompoundBoundingBox the axes it ignores in every entry.

Python equivalent: astropy.modeling.bounding_box.ModelBoundingBox.ignored, which is zero-based.

source
GWCS.bounds — Function
bounds(box::BoundingBox, axis) -> Union{Tuple{T,T},Nothing}

Return the (lower, upper) interval of input axis axis, or nothing when box does not bound it. An axis outside 1:N throws a BoundsError.

source
GWCS.selector_axes — Function
selector_axes(box::CompoundBoundingBox) -> Tuple{Vararg{Int}}

Return the input axes whose values select an entry of box.

Python equivalent: the index of each entry of astropy.modeling.bounding_box.CompoundBoundingBox.selector_args, which is zero-based.

source
GWCS.selector_ignored — Function
selector_ignored(box::CompoundBoundingBox) -> Tuple{Vararg{Bool}}

Return, for each of the selector_axes, whether the boxes of box leave that axis unconstrained.

Python equivalent: the ignore of each entry of astropy.modeling.bounding_box.CompoundBoundingBox.selector_args.

source
GWCS.select_bounding_box — Function
select_bounding_box(box::CompoundBoundingBox, selector) -> BoundingBox
box[selector]

Return the BoundingBox for a selector value, or a tuple of values for several selector axes. A value with no entry throws a KeyError.

Python equivalent: astropy.modeling.bounding_box.CompoundBoundingBox[selector].

source
GWCS.grid_from_bounding_box — Function
grid_from_bounding_box(wcs; step=1, center=true, selector=nothing, fixed=(), origin=0) -> Matrix
grid_from_bounding_box(box; step=1, center=true, selector=nothing, fixed=()) -> Matrix

Return a regular grid of points covering a bounding box, one point per column, ready for pixel_to_world. Each bounded axis is sampled every step, a number or one per sampled axis. With center=true, the bounds are first rounded to the nearest pixel centers, whole numbers; with center=false, sampling starts at the lower bound and the last point can pass the upper one, as in Python GWCS.

fixed holds axis-value pairs for axes that are not sampled, and is required for an ignored axis. A compound bounding box samples the entry for selector, which is required when it has more than one entry.

For a WCS, fixed can also name axes by the input frame's axis_names, and origin=1 makes fixed values and the grid one-based; selector is a selector value, not a pixel. A WCS without a bounding box throws an ArgumentError.

Python equivalent: gwcs.wcstools.grid_from_bounding_box, which returns one array per axis rather than a matrix.

source

Region selection

GWCS.RegionSelector — Type
RegionSelector(label_mapper, selector; undefined_value=NaN)

A transform that applies a different branch in each region, such as each slice of an integral field unit. label_mapper assigns a region label to the input coordinate, and selector holds label => transform pairs with labels of the mapper's label type. The selected branch evaluates the original coordinate. A coordinate in no region gives NaN, which pixel_to_world reports as having no result.

It has an inverse when the label mapper has one, as a WithInverseLabelMapper, and every branch has one. undefined_value is kept only so ASDF metadata round-trips exactly.

Python equivalent: gwcs.selector.RegionsSelector, whose undefined_transform_value is the value it returns outside every region.

source
GWCS.selected_transform — Function
selected_transform(selector::RegionSelector, label) -> AbstractTransform

Return the transform selector applies in the region with label. A label with no transform throws a KeyError.

Python equivalent: gwcs.selector.RegionsSelector.selector[label].

source
GWCS.map_label — Function
map_label(mapper, coords...) -> Union{label,Nothing}

Return the region label of a coordinate, given as separate numbers or a vector, or nothing when it is in no region. Labels are not coordinates: they choose a branch of a RegionSelector.

Python equivalent: evaluating a gwcs.selector label mapper.

source
GWCS.ArrayLabelMapper — Type
ArrayLabelMapper(labels::AbstractMatrix; inputs_mapping=nothing, no_label=nothing, inputs=nothing, name=nothing)
ArrayLabelMapper{N}(labels; kwargs...)

A label mapper backed by a two-dimensional label array, such as a detector's slice or slit mask. Zero-based pixel coordinates are rounded to the nearest pixel center, and the label of the resulting (x, y) is labels[y + 1, x + 1], so labels is the transpose of a Julia image data[x, y]. inputs_mapping picks which two of N inputs are x and y, by default the first two. A pixel outside the array, or whose label equals no_label, has no label.

Python equivalent: gwcs.selector.LabelMapperArray.

source
GWCS.DictionaryLabelMapper — Type
DictionaryLabelMapper{N,L}(mapper; inputs_mapping=nothing, atol=1e-8, rtol=1e-5, inputs=nothing, name=nothing)
DictionaryLabelMapper(mapper, N; label_type=Float64, kwargs...)

A label mapper that selects a transform by matching one input against numeric keys. inputs_mapping picks that input, by default the first, and mapper holds key => transform pairs. A key matches the input value within atol + rtol * abs(value), NumPy's asymmetric isclose rule rather than isapprox. The selected transform evaluates all N inputs to give the label, and an input matching no key has no label.

Python equivalent: gwcs.selector.LabelMapperDict.

source
GWCS.RangeLabelMapper — Type
RangeLabelMapper{N,L}(mapper; inputs_mapping=nothing, inputs=nothing, name=nothing)
RangeLabelMapper(mapper, N; label_type=Float64, kwargs...)

A label mapper that finds which interval contains one input, chosen by inputs_mapping (by default the first). mapper holds (lower, upper) => transform pairs with non-overlapping intervals, and the transform of the interval strictly containing the input gives the label from all N inputs. An input in no interval has no label.

Python equivalent: gwcs.selector.LabelMapperRange.

source
GWCS.TransformLabelMapper — Type
TransformLabelMapper{L}(transform; no_label=nothing, inputs=input_names(transform), name=transform_name(transform))
TransformLabelMapper(transform; kwargs...)

A label mapper whose label is the single output of transform, converted to type L (by default Float64). An output equal to no_label gives no label.

Python equivalent: gwcs.selector.LabelMapper.

source
GWCS.CallableLabelMapper — Type
CallableLabelMapper{N,L}(callable; dependencies=nothing, inputs=nothing, name=nothing)
CallableLabelMapper(callable, N, L; kwargs...)

A label mapper that calls callable(coords...) with N numbers and returns its label, converted to type L, or nothing when it returns nothing. dependencies, a Bool per input, declares which inputs the label depends on; by default every input. It cannot be written to metadata.

source
GWCS.WithInverseLabelMapper — Type
WithInverseLabelMapper(forward, backward)

A label mapper that evaluates forward and uses backward as its inverse mapper. backward labels output coordinates, with the same label type as forward. A RegionSelector has an analytical inverse only with an invertible label mapper.

Python equivalent: setting inverse on a gwcs.selector label mapper.

source