trans
The transform model defines a set of operations which can be used to construct expressions mapping coordinates and other objects defined in one coordinate space to a different coordinate space.
For many applications, this mapping should work in either direction. One option would be to define entirely separate mapping sequences to describe these two transformations. However, this approach is bulky and requires more maintanence as any change to one object would require equivalent changes be made to the other. Since many operations have a natural inverse, a safer, more compact and flexible approach is to use a single object to describe both transformations. With this approach, a change to the one transform automatically applies to both directions.
This model defines operations with sufficient information to define both forward and inverse transformations wherever possible. For cases where a natural inverse cannot be defined, we provide a means of explicitly assigning separate operation specifications for the forward and inverse directions.
In this model, we describe two flavors of operations:
* Arithmatic operations performing a particular action
* Workflow operations to build and link complex operations
- combine operations in parallel or series
- combine operations for explicit forward and inverse flow
- manage axis sets between steps
WCS Transform Model
Arnold Rots, Mark Cresitello-Dittmar, David Berry, Steven Crawford, Nadia Dencheva, Perry Greenfield, Tim Jenness, Omar Laurino, Stuart Mumford, Erik Tollerud
1.0
0.0
2019-09-16T08:14:30
ivoa
http://www.ivoa.net/xml/VODML/20180519/IVOA-v1.0.vo-dml.xml
http://volute.g-vo.org/svn/trunk/projects/dm/vo-dml/models/ivoa/vo-dml/IVOA-v1.0.html
InterpolationMethod
InterpolationMethod
Enumeration of interpolation methods to control the interpretation of data between known points in operations such as Lookup.
InterpolationMethod.None
None
No interpolation method specified, interpretation between points is undefined.
InterpolationMethod.Nearest
Nearest
Nearest neighbor is selected
InterpolationMethod.Linear
Linear
Assume a linear progression between points.
InterpolationMethod.Spline
Spline
Perform a spline interpolation through the points. 2-dimensional only.
SkyProjectionType
SkyProjectionType
Enumeration of non-linear celestial projection algorithm codes as listed in Table 13 of the FITS WCS paper II.
SkyProjectionType.AZP
AZP
Zenithal perspective
SkyProjectionType.SZP
SZP
Slant zenithal perspective
SkyProjectionType.TAN
TAN
Gnomonic (Tangent plane projection)
SkyProjectionType.STG
STG
Stereographic
SkyProjectionType.SIN
SIN
Slant orthographic (Sine projection)
SkyProjectionType.ARC
ARC
Zenithal equidistant
SkyProjectionType.ZPN
ZPN
Zenithal polynomial
SkyProjectionType.ZEA
ZEA
Zenithal equal-area
SkyProjectionType.AIR
AIR
Airy
SkyProjectionType.CYP
CYP
Cylindrical perspective
SkyProjectionType.CEA
CEA
Cylindrical equal-area
SkyProjectionType.CAR
CAR
Plate carree
SkyProjectionType.MER
MER
Mercator
SkyProjectionType.SFL
SFL
Sanson-Flamsteed
SkyProjectionType.PAR
PAR
Parabolic
SkyProjectionType.MOL
MOL
Mollweide
SkyProjectionType.AIT
AIT
Hammer-Aitoff
SkyProjectionType.COP
COP
Conic perspective
SkyProjectionType.COE
COE
Conic equal-area
SkyProjectionType.COD
COD
Conic equidistant
SkyProjectionType.COO
COO
Conic orthomorphic
SkyProjectionType.BON
BON
Bonne equal-area
SkyProjectionType.PCO
PCO
Polyconic
SkyProjectionType.TSC
TSC
Tangential spherical cube
SkyProjectionType.CSC
CSC
COBE Quadrilateralized spherical cube
SkyProjectionType.QSC
QSC
Quadrilateralized spherical cube
SpectralProjectionType
SpectralProjectionType
Enumeration of non-linear spectral projection algorithm codes as listed in Table 2 of the FITS WCS paper III.
NOTE: We exclude the TAB code from this list, that type is handled by the Lookup operation in this model.
SpectralProjectionType.F2W
F2W
Frequency - Wavelength
SpectralProjectionType.F2V
F2V
Frequency - Apparent radial velocity
SpectralProjectionType.F2A
F2A
Frequency - Air wavelength
SpectralProjectionType.W2F
W2F
Wavelength - Frequency
SpectralProjectionType.W2V
W2V
Wavelength - Apparent radial velocity
SpectralProjectionType.W2A
W2A
Wavelength - Air wavelength
SpectralProjectionType.V2F
V2F
Apparent radial velocity - Frequency
SpectralProjectionType.V2W
V2W
Apparent radial velocity - Wavelength
SpectralProjectionType.V2A
V2A
Apparent radial velocity - Air wavelength
SpectralProjectionType.A2F
A2F
Air wavelength - Frequency
SpectralProjectionType.A2W
A2W
Air wavelength - Wavelength
SpectralProjectionType.A2V
A2V
Air wavelength - Apparent radial velocity
SpectralProjectionType.LOG
LOG
Logarithm
SpectralProjectionType.GRI
GRI
Grism
SpectralProjectionType.GRA
GRA
Grism in air
SpectralCoordType
SpectralCoordType
Enumeration of spectral coordinate types as listed in Table 1 of the FITS WCS paper III.
SpectralCoordType.FREQ
FREQ
Frequency
SpectralCoordType.ENER
ENER
Energy
SpectralCoordType.WAVN
WAVN
Wavenumber
SpectralCoordType.VRAD
VRAD
Radio velocity
SpectralCoordType.WAVE
WAVE
Vacuum wavelength
SpectralCoordType.VOPT
VOPT
Optical velocity
SpectralCoordType.ZOPT
ZOPT
Redshift
SpectralCoordType.AWAV
AWAV
Air wavelength
SpectralCoordType.VELO
VELO
Apparent radial velocity
SpectralCoordType.BETA
BETA
Beta factor (v/c)
TMapping
TMapping
Bi-directional mapping, contains the forward and inverse transform operation specifications. Many operations, such as a shift, rotation, and many matrix operations, have a natural inverse. For these cases, it is not necessary to define and propogate both the forward and inverse operations since the inverse can be easily derived from the forward. In other cases, an explicit inverse specification may be needed.
This class serves as the building block, from which arbitrarily complex operations can be built.
TMapping.invert
invert
Boolean flag indicating that the inverse operation should be applied. If missing, it is assumed to be "False".
For many operations, the inverse transformation can be directly derived from the forward transform. For instance, the inverse of a transform that simply adds a constant to each input is a transform of the same type, with a negated constant. However, there are potentially operations for which this cannot be done. For instance, a transform that maps 3D Cartesian coodinates to spherical coordinates cannot be re-written to represent its inverse. This flag indicates that it should be used in its inverse sense.
In addition, the invert flag allows a complex compound transformation to be be inverted simply by toggling its invert flag. Without such a flag each component would need to be re-written to represent its inverse (if possible), and the order of serial transformations would need to be reversed - a much more complex and error prone process.
ivoa:boolean
0
1
TAtomic
TAtomic
Single stage bi-directional mapping.
trans:TMapping
TAtomic.forward
forward
The forward transform operation specification.
trans:TForward
1
1
TAtomic.inverse
inverse
The inverse transform operation specification.
trans:TInverse
0
1
TCompound
TCompound
Abstract class to facilitate the combination of Mappings in various ways.
trans:TMapping
TCompound.map
map
Components of the complex operation. Depending on how the operations are combined, the interpretation of the components will change.
trans:TMapping
1
-1
true
TCompose
TCompose
A complex operation which executes the component maps in sequence.
This allows the building of multi-stage transforms such as a Matrix operation followed by a WCS Projection.
trans:TCompound
TConcatenate
TConcatenate
Combines operations in parallel. This class enables the building of an operation which covers the full dimension space of the input. Axes are distributed to the component operations in order. For example, to perform a shift on a 2-dimensional coordinate (x,y), one would join two Shift operations giving the offset in x and y respectively. Since this class is an operation itself, it can be used as a component in other complex operations.
trans:TCompound
TOperation
TOperation
Uni-directional transform operation, executes the contained function.
TOperation.operation
operation
Transform operation specification.
trans:TFunction
1
1
TForward
TForward
Defines the forward transform operation of the mapping.
trans:TOperation
TInverse
TInverse
Defines the inverse transform operation of the mapping.
trans:TOperation
TFunction
TFunction
Transform Function (TFunction) defines a mathematical operation to be performed on its inputs.
Permute
Permute
Permute the order and possibly number of dimensions between operations. This operation facilitates the workflow through the operation sequence. It is comprised of an ordered axismap list defining the output axis sequence in terms of the source (input) axes. It supports the reorder, duplication, and dropping of dimensions.
Reorder Example: We have a 3-dimensional coordinate (x,y,z) and wish to perform a 2-dimensional transform on the (x,z) plane. Define a Permute operation to reorder the axes from (x,y,z) to (y,x,z) using an axismap list specifying the new axis order, [2,1,3]. The results feed into the next step ( 1D + 2D operations ).
Duplicate Example: We have 2-dimensional coordinate (x,y) feeding two Polynomial2D operations to form (x',y'). Define a Permute operation with axismap list specifying sourceAxis set [1,2,1,2]. The result feeds into the next step ( Polynomial2D + Polynomial2D operations).
Drop Example: We have a 5-dimensional input feeding into a 3x3 Matrix operation. Define a Permute operation selecting the relevant axis set [1,3,5], the remaining axes, [2,4], are dropped.
Add Example: We have a 2-dimensional operation feeding into axes [1,3] of a 3-dimensional operation. Define a Permute operation with numSourceAxes=2; and sourceAxis set [1,0,2] where output axis 2 also specifies the fixed seed value.
trans:TFunction
Permute.numSourceAxes
numSourceAxes
The number of input axes. Used to verify dimensional coverage in forward and inverse directions. For example, numSourceAxes=4 with axismap=[1,3] indicates that axes [2,4] have been dropped.
ivoa:nonnegativeInteger
1
1
Permute.axismap
axismap
Ordered list defining the number and order of the resulting axis set. Each entry provides the source (input) dimension for that output dimension.
trans:PermuteAxis
0
-1
true
PermuteAxis
PermuteAxis
Entry for the Permute operation, this object defines the mapping of input dimension to output dimension. The output dimension is determined from its order in the axismap list.
PermuteAxis.sourceAxis
sourceAxis
Source (input) dimension number, 1 based.
ivoa:nonnegativeInteger
1
1
PermuteAxis.seedValue
seedValue
Value to assign for the new dimensional axis.
ivoa:real
0
1
Unit
Unit
A 1-Dimensional operation which makes no change to the inputs. ( X' = X )
trans:TFunction
Shift
Shift
A 1-Dimensional operation defining a simple offset. ( X' = X + offset )
trans:TFunction
Shift.offset
offset
The amount of offset to apply.
ivoa:real
1
1
Scale
Scale
A 1-Dimensional operator for simple scaling. ( X' = factor*X )
trans:TFunction
Scale.factor
factor
The scale factor.
ivoa:real
1
1
Rotate2D
Rotate2D
A 2-Dimensional rotation operation.
trans:TFunction
Rotate2D.angle
angle
Rotation angle, in degrees, from the positive direction of axis 1 toward the positive direction of axis 2.
ivoa:real
1
1
EulerRotation
EulerRotation
Defines a rotation operation in a 3-dimensional cartesian coordinate space, defined as a series of rotations about the native axes (x,y,z).
trans:TFunction
EulerRotation.eulerAngle
eulerAngle
Rotation angle about specified axis.
trans:EulerAngle
1
-1
EulerAngle
EulerAngle
Angular rotation about a particular axis of a 3-dimensional cartesian coordinate space.
EulerAngle.rotationAxis
rotationAxis
Identifies the axis of rotation. MUST be 'x', 'y', or 'z'.
ivoa:string
1
1
EulerAngle.angle
angle
Angle of rotation, in degrees. Angle sign follows the right-hand rule, where positive values indicate clockwise rotation (looking in +axis direction), negative values for counter-clockwise.
ivoa:real
1
1
Matrix
Matrix
An M x N matrix operation. Each cell of the matrix is provided by a MatrixElement object. Missing elements should be considered to equal 0.
trans:TFunction
element maxlength = M*N
Matrix.M
M
Number of rows in the matrix.
ivoa:nonnegativeInteger
1
1
Matrix.N
N
Number of columns in the matrix.
ivoa:nonnegativeInteger
1
1
Matrix.element
element
Collection of MatrixElements which define each cell of the matrix. The total number of elements MUST NOT exceed M*N, any missing elements result in a cell with value=0.0.
trans:MatrixElement
0
-1
MatrixElement
MatrixElement
The value of cell m,n in an M x N matrix.
MatrixElement.m
m
Matrix cell row number.
ivoa:nonnegativeInteger
1
1
MatrixElement.n
n
Matrix cell column number.
ivoa:nonnegativeInteger
1
1
MatrixElement.value
value
Matrix cell value.
ivoa:real
1
1
Projection
Projection
Abstract head of World Coordinate System (WCS) projection operations. We do not attempt to define the operations here, but instead, provide extensions which support the transforms described in the FITS WCS papers II and III.
trans:TFunction
Projection.param
param
Set of 0 or more parameters providing supplemental metadata required to execute a particular projection algorithm. The number and meaning of the parameters depends on the algorithm. They are typically in the from of keyword/value pairs, so we provide a simple ProjectionParam element to accommodate these. The detailed content specification is left to the WCS paper.
trans:ProjectionParam
0
-1
ProjectionParam
ProjectionParam
Simple parameter specification for WCS Projections. The parameter is modeled as a simple name/value pair. The details of expectations for the various projection algorithms is left to the WCS paper describing the algorithm.
ProjectionParam.name
name
The parameter name as described in the WCS papers for each operation type.
ivoa:string
1
1
ProjectionParam.value
value
The value for the parameter.
ivoa:real
1
1
SkyProjection
SkyProjection
This class corresponds to the Spherical Projection component of the FITS WCS paper II. As in the paper, this operation describes the mapping between the intermediate "Projection Plane" and the "Native Spherical" coordinate systems. This model supports all defined projection types, where the appropriate code is specified in the algorithm attribute. All projection parameters are to be provided through the ProjectionParam list according to the descriptions given in the FITS WCS paper.
trans:Projection
SkyProjection.algorithm
algorithm
The projection algorithm to apply. The value MUST be taken from the enumeration of standard sky projection algorithms. Extracted from 'ctype' in the FITS WCS representations.
trans:SkyProjectionType
1
1
SkyProjRotate
SkyProjRotate
This class extends SkyProjection to include the Spherical Rotation component of the FITS WCS paper II. This operation describes the mapping between the "Native Spherical" and "Celestial" coordinate systems. The reference values are provided at the appropriate attribute, while all other parameters (e.g. LONPOLE, LATPOLE) are to be provided through the ProjectionParam list according to the descriptions given in the FITS WCS paper.
trans:SkyProjection
SkyProjRotate.referenceValue
referenceValue
The target reference values in each dimension. Equivalent to 'crval' in FITS WCS representations.
ivoa:real
2
2
SpectralProjection
SpectralProjection
This class represents a nonlinear one-dimensional spectral transform as detailed in the FITS WCS paper III.
trans:Projection
SpectralProjection.referenceValue
referenceValue
The target reference value for the axis. Equivalent to 'crval' in FITS WCS representations.
ivoa:real
1
1
SpectralProjection.algorithm
algorithm
The projection algorithm to apply. The value MUST be taken from the enumeration of non-linear spectral projection algorithms. Extracted from 'ctype' in FITS WCS representations.
trans:SpectralProjectionType
1
1
SpectralProjection.coordType
coordType
The resulting spectral coordinate type code. Values MUST be taken from the enumerated list of spectral coordinate types. Extracted from 'ctype' in FITS WCS representations.
trans:SpectralCoordType
1
1
Polynomial
Polynomial
Abstract head of a family of Polynomial distortion operations.
trans:TFunction
Polynomial.order
order
The order, or degree, of the polynomial expression.
ivoa:nonnegativeInteger
1
1
Polynomial1D
Polynomial1D
A 1-Dimensional Polynomial transform represented by the expression: X' = SUM( Ci*X**i), i=0..order. Each term is provided by a PolyCoeff1D object. Missing terms are considered to have a coefficient of 0.0.
trans:Polynomial
Polynomial1D.term
term
A term in the polynomial expression.
trans:PolyCoeff1D
1
-1
PolyCoeff1D
PolyCoeff1D
A term of the polynomial expression. This object provides the coefficient (c) and power (p) of the term, forming the expression c*X**p.
PolyCoeff1D.coeff
coeff
Multiplicitive coefficient of the term.
ivoa:real
1
1
PolyCoeff1D.power
power
The power to raise the value for this term.
ivoa:nonnegativeInteger
1
1
Polynomial2D
Polynomial2D
A 2-Dimensional Polynomial transform represented by the expression: X' = SUMi,j( Cij*X**i*Y**j), i+j<=order. Each term is provided by a PolyCoeff2D object. Missing terms are considered to have a coefficient of 0.0.
trans:Polynomial
Polynomial2D.term
term
A term in the polynomial expression.
trans:PolyCoeff2D
1
-1
PolyCoeff2D
PolyCoeff2D
A term of the polynomial expression. This object provides the coefficient (c) and power (p) of the term, forming the expression c*X**p[0]*Y**p[1].
PolyCoeff2D.coeff
coeff
Multiplicitive coefficient of the term.
ivoa:real
1
1
PolyCoeff2D.power
power
The power to raise the values for this term in each dimension.
ivoa:nonnegativeInteger
2
2
Lookup
Lookup
Defines a lookup table operation. The Lookup is comprised of a series of value pairs (LookupEntry). All members of the series MUST be of the same type.
Handling Enumerated data:
A common usage of a Lookup operation is to map image pixel index to an enumeration, such as a Polarization state. This can be handled by two means:
1) Define a numeric equivalent for each enumeration literal, and use NumericEntry types. Casting to the corresponding literal occurs outside of the operation.
2) Your local model can define a LookupEntry extension which maps the native value directly the target EnumerationLiteral.
The details of either approach for particular enumerations is considered outside the scope of this document.
trans:TFunction
Lookup.interpolation
interpolation
Specifies the form of interpolation, if any, prescribed to be performed.
trans:InterpolationMethod
0
1
Lookup.bounds_error
bounds_error
Flag to specify behaviour outside the lookup table data bounds. True indicates an error condition, False indicates that the associated "fill" entry should be returned. If no "fill" entry is provided, the value should be extrapolated.
ivoa:boolean
0
1
Lookup.entry
entry
Set of lookup table entries forming a discrete mapping from the native space to the target space.
trans:LookupEntry
1
-1
true
LookupEntry
LookupEntry
This is an abstract head of lookup table entry objects. Each entry provides a discrete translation of a 'native' value to the corresponding 'target' value.
LookupEntry.fill
fill
When TRUE, the entry provides values to be used outside the Lookup table data domain. MUST only appear first or last in the sequence. If missing, it is considered to be FALSE.
ivoa:boolean
0
1
NumericEntry
NumericEntry
A 1-Dimensional discrete mapping of numeric values.
trans:LookupEntry
NumericEntry.nativeValue
nativeValue
The native, or reference, value of the lookup entry.
ivoa:real
1
1
NumericEntry.targetValue
targetValue
The target, or resulting, value of the lookup entry.
ivoa:real
1
1
NumericEntry2D
NumericEntry2D
A 2-Dimensional discrete mapping of numeric values.
trans:LookupEntry
NumericEntry2D.nativeValue
nativeValue
The native, or reference, value of the lookup entry.
ivoa:real
2
2
NumericEntry2D.targetValue
targetValue
The target, or resulting, value of the lookup entry.
ivoa:real
2
2
StringEntry
StringEntry
A 1-Dimensional discrete mapping of an integer counter to a corresponding string form. Since the result is non-numeric, a Lookup operation with StringEntry-s can only be used at the end of a Transform sequence.
trans:LookupEntry
StringEntry.nativeValue
nativeValue
The native, or reference, value of the lookup entry.
ivoa:integer
1
1
StringEntry.targetValue
targetValue
The target, or resulting, value of the lookup entry.
ivoa:string
1
1