Transform API

The transform protocol

GWCS.AbstractTransform — Type
AbstractTransform{Nin,Nout}

Supertype of every transform, with Nin inputs and Nout outputs fixed by the type. A transform t is callable: t(coords) takes a StaticVector of length Nin and returns an SVector of length Nout, with NaN in every output where the coordinate has no image.

A new transform subtypes AbstractTransform, defines the call, and extends the protocol where it can do better than the defaults: inverse_transform, transform_jacobian, transform_dependencies, compile_transform, and the names transform_name, input_names, and output_names. register_transform! and register_transform_serializer! let metadata read and write it.

Python equivalent: astropy.modeling.Model.

source
GWCS.inverse_transform — Function
inverse_transform(transform) -> Union{AbstractTransform,NoInverse}

Return the analytical or explicitly supplied inverse of transform, or NoInverse() when it has none. A combination of transforms has an inverse only when each part does. A new transform extends this method to supply its inverse.

Python equivalent: astropy.modeling.Model.inverse, which raises NotImplementedError when there is none.

source
GWCS.transform_jacobian — Function
transform_jacobian(transform, coords::StaticVector) -> SMatrix{output_dimension,input_dimension}

Return the Jacobian of transform at coords, the matrix of ∂output_i/∂input_j. The default differentiates the transform with ForwardDiff.jl. A transform extends this method to supply an analytical Jacobian, which every WCS Jacobian then uses.

source
GWCS.transform_dependencies — Function
transform_dependencies(transform) -> SMatrix{output_dimension,input_dimension,Bool}

Return which outputs of transform depend on which inputs: entry (i, j) is true when output i can change with input j. A false entry holds for every input and parameter value, not only where a derivative happens to be zero. The default assumes every output depends on every input; a transform with independent axes extends this method.

Python equivalent: astropy.modeling.separable.separability_matrix.

source
GWCS.compile_transform — Function
compile_transform(transform) -> AbstractTransform

Return the form of transform that a WCS evaluates, with the same dimensions. The default returns transform; a transform built for convenience extends this method to return a faster equivalent.

source
GWCS.input_dimension — Function
input_dimension(x) -> Int

Return the number of inputs of a transform, label mapper, or bounding box.

Python equivalent: astropy.modeling.Model.n_inputs.

source
GWCS.output_dimension — Function
output_dimension(transform) -> Int

Return the number of outputs of a transform.

Python equivalent: astropy.modeling.Model.n_outputs.

source
GWCS.transform_name — Function
transform_name(transform) -> Union{String,Nothing}

Return the name of a transform, or nothing when it has none. AnnotatedTransform and metadata give names.

Python equivalent: astropy.modeling.Model.name.

source
GWCS.input_names — Function
input_names(transform) -> Union{NTuple{input_dimension,String},Nothing}

Return the names of a transform's inputs, or nothing when they are unnamed. AnnotatedTransform and metadata give names, and fix_inputs accepts them.

Python equivalent: astropy.modeling.Model.inputs, which always has names.

source
GWCS.output_names — Function
output_names(transform) -> Union{NTuple{output_dimension,String},Nothing}

Return the names of a transform's outputs, or nothing when they are unnamed.

Python equivalent: astropy.modeling.Model.outputs, which always has names.

source

Composition and annotation

GWCS.compose — Function
compose(transforms...) -> AbstractTransform
first | second

Return the transform that applies transforms in order: the outputs of each are the inputs of the next. first | second is compose(first, second). Adjacent dimensions that differ throw a DimensionMismatch.

The result is simplified: nested compositions flatten, identities drop out, and adjacent shifts, scales, and affines fuse into one affine. An AnnotatedTransform is never fused, so annotated pipelines keep their structure. The inverse composes the parts' inverses in reverse order when each has one.

Python equivalent: the | operator of astropy.modeling.Model.

source
GWCS.parallel — Function
parallel(transforms...) -> AbstractTransform
first & second

Return the transform that applies transforms independently to consecutive slices of the inputs. Each takes as many inputs as its input_dimension, and their outputs are concatenated in the same order. first & second is parallel(first, second).

Nested parallels flatten, and parts that are all shifts, scales, or affines fuse into one affine. The inverse runs the parts' inverses in parallel when each has one.

Python equivalent: the & operator of astropy.modeling.Model.

source
GWCS.elementwise — Function
elementwise(operator, left, right) -> AbstractTransform
left + right, left - right, left * right, left / right, left ^ right

Return the transform that evaluates left and right on the same inputs and combines corresponding outputs with operator, which is +, -, *, /, or ^. The two must have the same dimensions, or it throws a DimensionMismatch; another operator throws an ArgumentError. The result has no inverse.

Python equivalent: the arithmetic operators of astropy.modeling.Model.

source
GWCS.AnnotatedTransform — Type
AnnotatedTransform(transform; name=nothing, inputs=nothing, outputs=nothing)

A transform that evaluates transform unchanged and carries optional name, inputs, and outputs annotations, each nothing when absent. Supplied names are nonempty, and the input and output names are each unique, with one per input or output; otherwise construction throws. The inverse swaps the input and output names. compose and parallel never fuse an annotated transform into its neighbors. annotate_transform changes some annotations and keeps the rest.

Python equivalent: the name, inputs, and outputs of astropy.modeling.Model.

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

A transform that evaluates forward and uses backward as its explicit inverse. backward maps the outputs of forward to its inputs. GWCS.jl does not check that it inverts forward exactly, so an approximate inverse such as a fitted polynomial is allowed. Its inverse is WithInverse(backward, forward).

Python equivalent: setting astropy.modeling.Model.inverse.

source

Elementary transforms

GWCS.IdentityTransform — Type
IdentityTransform{N}()

The transform that returns its N inputs unchanged. compose drops it.

Python equivalent: astropy.modeling.models.Identity.

source
GWCS.Shift — Type
Shift(offset)

The one-input transform that adds offset to its coordinate. Combine shifts of several axes with &.

Python equivalent: astropy.modeling.models.Shift.

source
GWCS.Scale — Type
Scale(factor)

The one-input transform that multiplies its coordinate by factor. A zero factor has no inverse.

Python equivalent: astropy.modeling.models.Scale.

source
GWCS.AffineTransform — Type
AffineTransform(matrix, offset)
AffineTransform(matrix)

The transform matrix * coords + offset, with as many inputs as matrix has columns and as many outputs as it has rows; offset defaults to zero. A square matrix with a nonzero determinant has an inverse.

Python equivalent: astropy.modeling.models.AffineTransformation2D, which is two-dimensional only.

source
GWCS.RemapAxes — Type
RemapAxes{Nin}(mapping)

The transform whose output i is input mapping[i] of Nin, which reorders, duplicates, or drops inputs. Indices are one-based. It has an inverse when every input appears in mapping.

Python equivalent: astropy.modeling.models.Mapping, whose indices are zero-based.

source
GWCS.ConstantTransform — Type
ConstantTransform(value; n_inputs=0)
ConstantTransform{Nin}(value)

The transform that ignores its Nin inputs and returns value as its single output, such as a constant world axis. With no inputs, it has an inverse that accepts only value and returns an empty coordinate; with inputs, it has none.

Python equivalent: astropy.modeling.models.Const1D and Const2D.

source
GWCS.Rotation2D — Type
Rotation2D(angle)

The counterclockwise rotation of (x, y) by angle degrees. A WCS evaluates it as an AffineTransform, so it fuses with neighboring affines, while the stored transform keeps its angle for metadata.

Python equivalent: astropy.modeling.models.Rotation2D.

source
GWCS.Rotation3D — Type
Rotation3D(matrix)
Rotation3D(angles, axes_order)

A rotation of Cartesian vectors (x, y, z) by a 3×3 rotation matrix, or by the rotations through angles in degrees about the axes in axes_order, a string such as "zxz", applied in that order. Its inverse is the transposed matrix.

Python equivalent: astropy.modeling.models.RotationSequence3D.

source
GWCS.Polynomial1D — Type
Polynomial1D(coefficients; domain=nothing, window=nothing)

The one-dimensional polynomial with coefficients in increasing powers, c[1] + c[2] * x + c[3] * x^2 + .... With domain and window, two (low, high) pairs given together, the input is first mapped linearly from domain to window. It has no inverse.

Python equivalent: astropy.modeling.models.Polynomial1D.

source
GWCS.Polynomial2D — Type
Polynomial2D(coefficients; domain=nothing, window=nothing)
Polynomial2D{T,C,D,W}(coefficients, domain, window)

The two-dimensional polynomial of total degree n, given by a square (n + 1) × (n + 1) coefficient matrix whose element [i + 1, j + 1] multiplies x^i * y^j; elements with i + j > n are ignored. domain and window, each a pair of (low, high) intervals for x and y, map the inputs as for Polynomial1D. It has no inverse.

The first form stores the coefficients as an SMatrix, so the degree is part of the type and evaluation unrolls. The parametric form chooses the coefficient storage C, with D and W the types of domain and window. With C = Matrix{T}, polynomials of every degree share one type and one compiled kernel, at two to three times the evaluation cost.

Python equivalent: astropy.modeling.models.Polynomial2D, whose coefficients are named c{i}_{j} for the same terms.

source
GWCS.degree — Function
degree(polynomial::Union{Polynomial1D,Polynomial2D})

Return the degree a polynomial's coefficients are stored for, whether or not its highest coefficients are zero. It is a compile-time constant for static coefficient storage.

Python equivalent: the degree attribute of astropy.modeling.models.Polynomial1D and Polynomial2D.

source
GWCS.CallableTransform — Type
CallableTransform{Nin,Nout}(forward; inverse=nothing, jacobian=nothing, dependencies=nothing, inverse_dependencies=nothing)
CallableTransform(forward, Nin, Nout; kwargs...)

A transform that calls forward(coords...) with Nin numbers. The callable returns a tuple or vector of Nout values, or a number when Nout is 1.

inverse is a callable of the same form for the inverse. jacobian(coords...) returns the Nout × Nin Jacobian; without it, ForwardDiff.jl computes the Jacobian. dependencies and inverse_dependencies, Bool matrices like transform_dependencies's, declare which outputs depend on which inputs.

A DomainError thrown by a callable gives NaN, as GWCS.jl transforms do where a coordinate has no image. It cannot be written to metadata.

source

Spherical coordinates

GWCS.SphericalToCartesian — Type
SphericalToCartesian(wrap_lon_at=360)

The transform from longitude and latitude in degrees to a Cartesian unit vector (x, y, z). wrap_lon_at, 180 or 360, sets the longitude range of the inverse, CartesianToSpherical.

Python equivalent: gwcs.geometry.SphericalToCartesian.

source
GWCS.CartesianToSpherical — Type
CartesianToSpherical(wrap_lon_at=360)

The transform from a Cartesian vector (x, y, z) to longitude and latitude in degrees, with longitude in [0, 360) for wrap_lon_at=360 or between -180 and 180 for wrap_lon_at=180.

Python equivalent: gwcs.geometry.CartesianToSpherical.

source
GWCS.NativeToCelestial — Type
NativeToCelestial(alpha_p, delta_p, phi_p)

The rotation from native spherical coordinates (phi, theta) to celestial (lon, lat), all in degrees, as FITS WCS Paper II defines it. alpha_p and delta_p are the celestial coordinates of the native pole, and phi_p is the native longitude of the celestial pole. Its inverse is CelestialToNative.

Python equivalent: astropy.modeling.models.RotateNative2Celestial.

source
GWCS.CelestialToNative — Type
CelestialToNative(alpha_p, delta_p, phi_p)

The rotation from celestial (lon, lat) to native spherical (phi, theta), all in degrees, with parameters as for NativeToCelestial, its inverse.

Python equivalent: astropy.modeling.models.RotateCelestial2Native.

source
GWCS.IntermediateToNative — Type
IntermediateToNative(projection)
IntermediateToNative{P}()

The deprojection of a spherical projection, such as GnomonicProjection: it maps projection-plane (intermediate) coordinates (x, y) in degrees to native spherical longitude and latitude (phi, theta) in degrees, as FITS WCS Paper II defines them. A point off the projection gives NaN. Its inverse is NativeToIntermediate, and celestial_transform adds the rotation to celestial coordinates.

Python equivalent: the Pix2Sky_* projections of astropy.modeling.models.

source
GWCS.NativeToIntermediate — Type
NativeToIntermediate(projection)
NativeToIntermediate{P}()

The spherical projection itself: it maps native spherical longitude and latitude (phi, theta) in degrees to projection-plane coordinates (x, y) in degrees. A point the projection does not reach gives NaN. Its inverse is IntermediateToNative.

Python equivalent: the Sky2Pix_* projections of astropy.modeling.models.

source
GWCS.celestial_transform — Function
celestial_transform(projection, reference; lonpole=nothing, latpole=90, native_reference=native_fiducial(projection),
                    offset=false) -> AbstractTransform

Return a transform from projection-plane coordinates to celestial longitude and latitude, all in degrees. It applies the deprojection by projection, then a rotation that places the fiducial point at reference, a (lon, lat) pair. lonpole and latpole are FITS LONPOLE and LATPOLE, and lonpole defaults as FITS Paper II prescribes.

native_reference is the fiducial point's native (phi, theta) in degrees, by default the projection's own (FITS PVi_1 and PVi_2 of the longitude axis). With offset=true, the projection plane is shifted so that the fiducial point is at its origin, as FITS PVi_0 of the longitude axis specifies.

Python equivalent: a Pix2Sky_* projection of astropy.modeling.models followed by RotateNative2Celestial.

source

Projections

GWCS.GnomonicProjection — Type
GnomonicProjection()

The TAN (gnomonic) zenithal projection.

Python equivalent: astropy.modeling.models.Pix2Sky_Gnomonic and Sky2Pix_Gnomonic.

source
GWCS.StereographicProjection — Type
StereographicProjection()

The STG (stereographic) zenithal projection.

Python equivalent: astropy.modeling.models.Pix2Sky_Stereographic and Sky2Pix_Stereographic.

source
GWCS.ZenithalEquidistant — Type
ZenithalEquidistant()

The ARC (zenithal equidistant) projection.

Python equivalent: astropy.modeling.models.Pix2Sky_ZenithalEquidistant and Sky2Pix_ZenithalEquidistant.

source
GWCS.ZenithalEqualArea — Type
ZenithalEqualArea()

The ZEA (zenithal equal-area) projection.

Python equivalent: astropy.modeling.models.Pix2Sky_ZenithalEqualArea and Sky2Pix_ZenithalEqualArea.

source
GWCS.ZenithalPerspective — Type
ZenithalPerspective(mu=0, gamma=0)

The AZP (zenithal perspective) projection, with mu the distance of the projection point from the sphere's center in sphere radii and gamma the tilt of the projection plane in degrees (FITS PVi_1 and PVi_2).

Python equivalent: astropy.modeling.models.Pix2Sky_ZenithalPerspective and Sky2Pix_ZenithalPerspective.

source
GWCS.SlantZenithalPerspective — Type
SlantZenithalPerspective(mu=0, phi0=0, theta0=90)

The SZP (slant zenithal perspective) projection, with mu the distance of the projection point in sphere radii and phi0 and theta0 its native longitude and latitude in degrees (FITS PVi_1 to PVi_3).

Python equivalent: astropy.modeling.models.Pix2Sky_SlantZenithalPerspective and Sky2Pix_SlantZenithalPerspective.

source
GWCS.SlantOrthographic — Type
SlantOrthographic(xi=0, eta=0)

The SIN (slant orthographic) projection, with obliqueness parameters xi and eta (FITS PVi_1 and PVi_2).

Python equivalent: astropy.modeling.models.Pix2Sky_SlantOrthographic and Sky2Pix_SlantOrthographic.

source
GWCS.AiryProjection — Type
AiryProjection(theta_b=90)

The AIR (Airy) zenithal projection, minimizing error within the native latitude theta_b in degrees (FITS PVi_1).

Python equivalent: astropy.modeling.models.Pix2Sky_Airy and Sky2Pix_Airy.

source
GWCS.ZenithalPolynomial — Type
ZenithalPolynomial(coefficients=(0.0, 1.0))

The ZPN (zenithal polynomial) projection, with coefficients those of the radius as a polynomial in the native colatitude in radians (FITS PVi_0, PVi_1, and so on).

source
GWCS.PlateCarreeProjection — Type
PlateCarreeProjection()

The CAR (plate carrée) cylindrical projection.

Python equivalent: astropy.modeling.models.Pix2Sky_PlateCarree and Sky2Pix_PlateCarree.

source
GWCS.CylindricalEqualArea — Type
CylindricalEqualArea(lambda=1)

The CEA (cylindrical equal-area) projection, with parameter lambda in (0, 1] (FITS PVi_1).

Python equivalent: astropy.modeling.models.Pix2Sky_CylindricalEqualArea and Sky2Pix_CylindricalEqualArea.

source
GWCS.CylindricalPerspective — Type
CylindricalPerspective(mu=1, lambda=1)

The CYP (cylindrical perspective) projection, with mu the distance of the projection point from the center of the generating sphere and lambda the radius of the cylinder, both in sphere radii (FITS PVi_1 and PVi_2).

Python equivalent: astropy.modeling.models.Pix2Sky_CylindricalPerspective and Sky2Pix_CylindricalPerspective.

source
GWCS.MercatorProjection — Type
MercatorProjection()

The MER (Mercator) cylindrical projection.

Python equivalent: astropy.modeling.models.Pix2Sky_Mercator and Sky2Pix_Mercator.

source
GWCS.SansonFlamsteedProjection — Type
SansonFlamsteedProjection()

The SFL (Sanson-Flamsteed) pseudocylindrical projection.

Python equivalent: astropy.modeling.models.Pix2Sky_SansonFlamsteed and Sky2Pix_SansonFlamsteed.

source
GWCS.ParabolicProjection — Type
ParabolicProjection()

The PAR (parabolic) pseudocylindrical projection.

Python equivalent: astropy.modeling.models.Pix2Sky_Parabolic and Sky2Pix_Parabolic.

source
GWCS.MollweideProjection — Type
MollweideProjection()

The MOL (Mollweide) pseudocylindrical projection.

Python equivalent: astropy.modeling.models.Pix2Sky_Molleweide and Sky2Pix_Molleweide, as astropy spells it.

source
GWCS.HammerAitoffProjection — Type
HammerAitoffProjection()

The AIT (Hammer-Aitoff) projection.

Python equivalent: astropy.modeling.models.Pix2Sky_HammerAitoff and Sky2Pix_HammerAitoff.

source
GWCS.ConicPerspective — Type
ConicPerspective(sigma, delta=0)

The COP (conic perspective) projection, with sigma the mean of the two standard parallels and delta half their difference, in degrees (FITS PVi_1 and PVi_2).

Python equivalent: astropy.modeling.models.Pix2Sky_ConicPerspective and Sky2Pix_ConicPerspective.

source
GWCS.ConicEquidistant — Type
ConicEquidistant(sigma, delta=0)

The COD (conic equidistant) projection, with sigma and delta as for ConicPerspective.

Python equivalent: astropy.modeling.models.Pix2Sky_ConicEquidistant and Sky2Pix_ConicEquidistant.

source
GWCS.ConicEqualArea — Type
ConicEqualArea(sigma, delta=0)

The COE (conic equal-area) projection, with sigma and delta as for ConicPerspective.

Python equivalent: astropy.modeling.models.Pix2Sky_ConicEqualArea and Sky2Pix_ConicEqualArea.

source
GWCS.ConicOrthomorphic — Type
ConicOrthomorphic(sigma, delta=0)

The COO (conic orthomorphic) projection, with sigma and delta as for ConicPerspective.

Python equivalent: astropy.modeling.models.Pix2Sky_ConicOrthomorphic and Sky2Pix_ConicOrthomorphic.

source
GWCS.PolyconicProjection — Type
PolyconicProjection()

The PCO (polyconic) projection.

Python equivalent: astropy.modeling.models.Pix2Sky_Polyconic and Sky2Pix_Polyconic.

source
GWCS.BonneProjection — Type
BonneProjection(theta1)

The BON (Bonne equal-area) projection, with standard parallel theta1 in degrees (FITS PVi_1).

Python equivalent: astropy.modeling.models.Pix2Sky_BonneEqualArea and Sky2Pix_BonneEqualArea.

source
GWCS.TangentialSphericalCube — Type
TangentialSphericalCube()

The TSC (tangential spherical cube) projection.

Python equivalent: astropy.modeling.models.Pix2Sky_TangentialSphericalCube and Sky2Pix_TangentialSphericalCube.

source
GWCS.COBESphericalCube — Type
COBESphericalCube()

The CSC (COBE quadrilateralized spherical cube) projection. GWCS.jl evaluates it in double precision, where WCSLIB uses single precision, so the two differ by up to about 2e-5 degrees.

Python equivalent: astropy.modeling.models.Pix2Sky_COBEQuadSphericalCube and Sky2Pix_COBEQuadSphericalCube.

source
GWCS.QuadrilateralizedSphericalCube — Type
QuadrilateralizedSphericalCube()

The QSC (quadrilateralized spherical cube) projection.

Python equivalent: astropy.modeling.models.Pix2Sky_QuadSphericalCube and Sky2Pix_QuadSphericalCube.

source
GWCS.HEALPixProjection — Type
HEALPixProjection(H=4, K=3)

The HPX (HEALPix) projection, with H facets along the equator and K facets in latitude (FITS PVi_1 and PVi_2).

Python equivalent: astropy.modeling.models.Pix2Sky_HEALPix and Sky2Pix_HEALPix.

source
GWCS.HEALPixPolarProjection — Type
HEALPixPolarProjection()

The XPH (HEALPix polar, or butterfly) projection.

Python equivalent: astropy.modeling.models.Pix2Sky_HEALPixPolar and Sky2Pix_HEALPixPolar.

source