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.
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.
GWCS.has_inverse — Function
has_inverse(transform) -> BoolReturn whether inverse_transform gives an inverse for transform rather than NoInverse.
Python equivalent: astropy.modeling.Model.has_inverse.
GWCS.NoInverse — Type
NoInverse()The value inverse_transform and get_transform return when there is no inverse.
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.
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.
GWCS.compile_transform — Function
compile_transform(transform) -> AbstractTransformReturn 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.
GWCS.input_dimension — Function
input_dimension(x) -> IntReturn the number of inputs of a transform, label mapper, or bounding box.
Python equivalent: astropy.modeling.Model.n_inputs.
GWCS.output_dimension — Function
output_dimension(transform) -> IntReturn the number of outputs of a transform.
Python equivalent: astropy.modeling.Model.n_outputs.
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.
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.
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.
Composition and annotation
GWCS.compose — Function
compose(transforms...) -> AbstractTransform
first | secondReturn 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.
GWCS.parallel — Function
parallel(transforms...) -> AbstractTransform
first & secondReturn 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.
GWCS.elementwise — Function
elementwise(operator, left, right) -> AbstractTransform
left + right, left - right, left * right, left / right, left ^ rightReturn 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.
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.
GWCS.annotate_transform — Function
annotate_transform(transform; name=transform_name(transform), inputs=input_names(transform),
outputs=output_names(transform)) -> AnnotatedTransformReturn transform as an AnnotatedTransform with the annotations given. An omitted keyword keeps the existing transform_name, input_names, or output_names, and nothing removes it.
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.
Elementary transforms
GWCS.IdentityTransform — Type
IdentityTransform{N}()The transform that returns its N inputs unchanged. compose drops it.
Python equivalent: astropy.modeling.models.Identity.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
GWCS.celestial_transform — Function
celestial_transform(projection, reference; lonpole=nothing, latpole=90, native_reference=native_fiducial(projection),
offset=false) -> AbstractTransformReturn 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.
Projections
GWCS.GnomonicProjection — Type
GnomonicProjection()The TAN (gnomonic) zenithal projection.
Python equivalent: astropy.modeling.models.Pix2Sky_Gnomonic and Sky2Pix_Gnomonic.
GWCS.StereographicProjection — Type
StereographicProjection()The STG (stereographic) zenithal projection.
Python equivalent: astropy.modeling.models.Pix2Sky_Stereographic and Sky2Pix_Stereographic.
GWCS.ZenithalEquidistant — Type
ZenithalEquidistant()The ARC (zenithal equidistant) projection.
Python equivalent: astropy.modeling.models.Pix2Sky_ZenithalEquidistant and Sky2Pix_ZenithalEquidistant.
GWCS.ZenithalEqualArea — Type
ZenithalEqualArea()The ZEA (zenithal equal-area) projection.
Python equivalent: astropy.modeling.models.Pix2Sky_ZenithalEqualArea and Sky2Pix_ZenithalEqualArea.
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.
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.
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.
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.
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).
GWCS.PlateCarreeProjection — Type
PlateCarreeProjection()The CAR (plate carrée) cylindrical projection.
Python equivalent: astropy.modeling.models.Pix2Sky_PlateCarree and Sky2Pix_PlateCarree.
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.
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.
GWCS.MercatorProjection — Type
MercatorProjection()The MER (Mercator) cylindrical projection.
Python equivalent: astropy.modeling.models.Pix2Sky_Mercator and Sky2Pix_Mercator.
GWCS.SansonFlamsteedProjection — Type
SansonFlamsteedProjection()The SFL (Sanson-Flamsteed) pseudocylindrical projection.
Python equivalent: astropy.modeling.models.Pix2Sky_SansonFlamsteed and Sky2Pix_SansonFlamsteed.
GWCS.ParabolicProjection — Type
ParabolicProjection()The PAR (parabolic) pseudocylindrical projection.
Python equivalent: astropy.modeling.models.Pix2Sky_Parabolic and Sky2Pix_Parabolic.
GWCS.MollweideProjection — Type
MollweideProjection()The MOL (Mollweide) pseudocylindrical projection.
Python equivalent: astropy.modeling.models.Pix2Sky_Molleweide and Sky2Pix_Molleweide, as astropy spells it.
GWCS.HammerAitoffProjection — Type
HammerAitoffProjection()The AIT (Hammer-Aitoff) projection.
Python equivalent: astropy.modeling.models.Pix2Sky_HammerAitoff and Sky2Pix_HammerAitoff.
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.
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.
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.
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.
GWCS.PolyconicProjection — Type
PolyconicProjection()The PCO (polyconic) projection.
Python equivalent: astropy.modeling.models.Pix2Sky_Polyconic and Sky2Pix_Polyconic.
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.
GWCS.TangentialSphericalCube — Type
TangentialSphericalCube()The TSC (tangential spherical cube) projection.
Python equivalent: astropy.modeling.models.Pix2Sky_TangentialSphericalCube and Sky2Pix_TangentialSphericalCube.
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.
GWCS.QuadrilateralizedSphericalCube — Type
QuadrilateralizedSphericalCube()The QSC (quadrilateralized spherical cube) projection.
Python equivalent: astropy.modeling.models.Pix2Sky_QuadSphericalCube and Sky2Pix_QuadSphericalCube.
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.
GWCS.HEALPixPolarProjection — Type
HEALPixPolarProjection()The XPH (HEALPix polar, or butterfly) projection.
Python equivalent: astropy.modeling.models.Pix2Sky_HEALPixPolar and Sky2Pix_HEALPixPolar.