Class DatumShiftTransform
- All Implemented Interfaces:
Serializable
,Parameterized
,LenientComparable
,org.opengis.referencing.operation.MathTransform
- Direct Known Subclasses:
InterpolatedGeocentricTransform
,InterpolatedTransform
,MolodenskyFormula
There is many different datum shift methods, ranging from transformations as simple as adding a constant offset
to geographic coordinates, to more complex transformations involving conversions to geocentric coordinates and/or
interpolations in a datum shift grid. The simple cases like adding a constant offset
are handled by other MathTransform
implementations like LinearTransform
.
More complex methods are subclasses of this DatumShiftTransform
base class, but users should not assume
that this is the case of every transforms performing a datum shift.
Datum shift methods overview
The two CRS's ellipsoids have slightly different scale and rotation in space, and their center are located in a slightly different position. Consequently, geodetic datum shifts are often approximated by a constant scale, rotation and translation applied on geocentric coordinates. Those approximations are handled in SIS by concatenations ofEllipsoidToCentricTransform
with LinearTransform
instead of a specific
DatumShiftTransform
subclass.
If the geodetic datum shifts is approximated only by a geocentric translation without any scale or rotation,
and if an error of a few centimetres it acceptable, then the MolodenskyTransform
subclass can be used
as an approximation of the above method. The Molodensky method requires less floating point operations since
it applies directly on geographic coordinates, without conversions to geocentric coordinates.
Some countries go one step further and allow the above geocentric translations to be non-constant.
Instead, a different geocentric translation is interpolated for each geographic input coordinates.
This case is handled by the InterpolatedGeocentricTransform
subclass, or its
InterpolatedMolodenskyTransform
variant if a few centimetres accuracy lost can be afforded.
A simpler alternative to the above is to interpolate translations to apply directly on geographic coordinates.
This is the approach taken by NADCON and NTv2 grids.
SIS handles those datum shifts with the InterpolatedTransform
subclass.
- Since:
- 0.7
- Version:
- 1.0
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform
AbstractMathTransform.Inverse
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) final ContextualParameters
The parameters used for creating this datum shift.(package private) final DatumShiftGrid<?,
?> The grid of datum shifts from source datum to target datum, ornull
if none.private double
Conversion from (λ,φ) coordinates in radians to grid indices (x,y).private double
Conversion from (λ,φ) coordinates in radians to grid indices (x,y).private static final long
Serial number for inter-operability with different versions.private double
Conversion from (λ,φ) coordinates in radians to grid indices (x,y).private double
Conversion from (λ,φ) coordinates in radians to grid indices (x,y).Fields inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform
MAXIMUM_BUFFER_SIZE, MAXIMUM_FAILURES
-
Constructor Summary
ConstructorsConstructorDescriptionDatumShiftTransform
(org.opengis.parameter.ParameterDescriptorGroup descriptor, boolean isSource3D, boolean isTarget3D, DatumShiftGrid<?, ?> grid) Creates a datum shift transform for interpolations in geocentric domain.DatumShiftTransform
(org.opengis.parameter.ParameterDescriptorGroup descriptor, DatumShiftGrid<?, ?> grid) Creates a datum shift transform for direct interpolations in a grid. -
Method Summary
Modifier and TypeMethodDescriptionprivate void
Computes the conversion factors needed for calls toDatumShiftGrid.interpolateInCell(double, double, double[])
.protected int
Computes a hash value for this transform.private static double
diagonal
(org.opengis.referencing.operation.Matrix m, int j, int n) Returns the value on the diagonal of the given matrix, provided that all other non-translation terms are 0.(package private) static void
ensureGeocentricTranslation
(DatumShiftGrid<?, ?> grid, javax.measure.Unit<javax.measure.quantity.Length> unit) Ensures that thegrid
performs geocentric translations in the given units.boolean
equals
(Object object, ComparisonMode mode) Compares the specified object with this math transform for equality.protected ContextualParameters
Returns the parameters used for creating the complete transformation.org.opengis.parameter.ParameterValueGroup
Returns the internal parameter values of thisDatumShiftTransform
instance (ignoring context).(package private) final double
normalizedToGridX
(double x) Converts the given normalized x coordinate to grid index.(package private) final double
normalizedToGridY
(double y) Converts the given normalized x coordinate to grid index.private void
Invoked after deserialization.(package private) final void
setContextParameters
(double semiMajor, double semiMinor, javax.measure.Unit<javax.measure.quantity.Length> unit, org.opengis.referencing.datum.Ellipsoid target) Sets the semi-axis length in thecontext
parameters.Methods inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform
beforeFormat, derivative, equals, formatTo, getDomain, getParameterDescriptors, getSourceDimensions, getTargetDimensions, hashCode, inverse, isIdentity, isInverseEquals, mismatchedDimension, transform, transform, transform, transform, transform, transform, tryConcatenate
Methods inherited from class org.apache.sis.io.wkt.FormattableObject
print, toString, toString, toWKT
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.opengis.referencing.operation.MathTransform
toWKT
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
context
The parameters used for creating this datum shift. They are used for formatting Well Known Text (WKT) and error messages. Subclasses shall not use the values defined in this object for computation purpose, except at construction time.- See Also:
-
grid
The grid of datum shifts from source datum to target datum, ornull
if none.- See Also:
-
scaleX
private transient double scaleXConversion from (λ,φ) coordinates in radians to grid indices (x,y).- x = (λ - λ₀) ⋅
scaleX
= λ ⋅scaleX
+ x₀ - y = (φ - φ₀) ⋅
scaleY
= φ ⋅scaleY
+ y₀
DatumShiftGrid.getCoordinateToGrid()
transform for performance reasons. - x = (λ - λ₀) ⋅
-
scaleY
private transient double scaleYConversion from (λ,φ) coordinates in radians to grid indices (x,y).- x = (λ - λ₀) ⋅
scaleX
= λ ⋅scaleX
+ x₀ - y = (φ - φ₀) ⋅
scaleY
= φ ⋅scaleY
+ y₀
DatumShiftGrid.getCoordinateToGrid()
transform for performance reasons. - x = (λ - λ₀) ⋅
-
x0
private transient double x0Conversion from (λ,φ) coordinates in radians to grid indices (x,y).- x = (λ - λ₀) ⋅
scaleX
= λ ⋅scaleX
+ x₀ - y = (φ - φ₀) ⋅
scaleY
= φ ⋅scaleY
+ y₀
DatumShiftGrid.getCoordinateToGrid()
transform for performance reasons. - x = (λ - λ₀) ⋅
-
y0
private transient double y0Conversion from (λ,φ) coordinates in radians to grid indices (x,y).- x = (λ - λ₀) ⋅
scaleX
= λ ⋅scaleX
+ x₀ - y = (φ - φ₀) ⋅
scaleY
= φ ⋅scaleY
+ y₀
DatumShiftGrid.getCoordinateToGrid()
transform for performance reasons. - x = (λ - λ₀) ⋅
-
-
Constructor Details
-
DatumShiftTransform
DatumShiftTransform(org.opengis.parameter.ParameterDescriptorGroup descriptor, DatumShiftGrid<?, ?> grid) Creates a datum shift transform for direct interpolations in a grid. It is caller responsibility to initialize thecontext
parameters.- Parameters:
descriptor
- the contextual parameter descriptor.grid
- interpolation grid.
-
DatumShiftTransform
DatumShiftTransform(org.opengis.parameter.ParameterDescriptorGroup descriptor, boolean isSource3D, boolean isTarget3D, DatumShiftGrid<?, ?> grid) Creates a datum shift transform for interpolations in geocentric domain. It is caller responsibility to initialize thecontext
parameters.- Parameters:
descriptor
- the contextual parameter descriptor.grid
- interpolation grid in geocentric coordinates, ornull
if none.isSource3D
-true
if the source coordinates have a height.isTarget3D
-true
if the target coordinates have a height.
-
-
Method Details
-
readObject
Invoked after deserialization. This method computes the transient fields.- Parameters:
in
- the input stream from which to deserialize the datum shift grid.- Throws:
IOException
- if an I/O error occurred while reading or if the stream contains invalid data.ClassNotFoundException
- if the class serialized on the stream is not on the classpath.
-
computeConversionFactors
private void computeConversionFactors()Computes the conversion factors needed for calls toDatumShiftGrid.interpolateInCell(double, double, double[])
. This method takes only the 2 first dimensions. If a conversion factor can not be computed, then it is set to NaN. -
diagonal
private static double diagonal(org.opengis.referencing.operation.Matrix m, int j, int n) Returns the value on the diagonal of the given matrix, provided that all other non-translation terms are 0.- Parameters:
m
- the matrix from which to get the scale factor on a row.j
- the row for which to get the scale factor.n
- index of the last column.- Returns:
- the scale factor on the diagonal, or NaN.
-
ensureGeocentricTranslation
static void ensureGeocentricTranslation(DatumShiftGrid<?, ?> grid, javax.measure.Unit<javax.measure.quantity.Length> unit) throws IllegalArgumentExceptionEnsures that thegrid
performs geocentric translations in the given units. This method is invoked by constructor for validation of given arguments.This method is defined here in order to ensure a consistent behavior of
InterpolatedGeocentricTransform
withInterpolatedMolodenskyTransform
.- Parameters:
grid
- the grid to validate.unit
- the unit of semi-axis length of the source ellipsoid.- Throws:
IllegalArgumentException
- if the given grid is not valid.
-
setContextParameters
final void setContextParameters(double semiMajor, double semiMinor, javax.measure.Unit<javax.measure.quantity.Length> unit, org.opengis.referencing.datum.Ellipsoid target) Sets the semi-axis length in thecontext
parameters. This is a helper method for constructors in some (not all) subclasses.- Parameters:
semiMajor
- the semi-major axis length of the source ellipsoid.semiMinor
- the semi-minor axis length of the source ellipsoid.unit
- the unit of measurement of source ellipsoid axes.target
- the target ellipsoid.
-
getParameterValues
Returns the internal parameter values of thisDatumShiftTransform
instance (ignoring context). The parameters returned by this method do not necessarily describe the whole datum shift process, becauseDatumShiftTransform
instances are often preceeded and followed by linear conversions. It may be conversions between degrees and radians units, or conversions from geodetic coordinates to grid indices.Example: The chain of transforms of anThis method returns the parameters for the part in the middle of above example. The content of this part is highly implementation-dependent and used mostly for debugging purposes. The parameters that describe the process as a whole are rather given byInterpolatedGeocentricTransform
is:→- Geographic to geocentric conversion
- Geocentric interpolation
- Geocentric to geographic conversion
→getContextualParameters()
.- Specified by:
getParameterValues
in interfaceParameterized
- Overrides:
getParameterValues
in classAbstractMathTransform
- Returns:
- the internal parameter values for this transform.
- See Also:
-
getContextualParameters
Returns the parameters used for creating the complete transformation. Those parameters describe a sequence of normalize →this
→ denormalize transforms, not including axis swapping. Those parameters are used for formatting Well Known Text (WKT) and error messages.- Overrides:
getContextualParameters
in classAbstractMathTransform
- Returns:
- the parameter values for the sequence of
normalize →
this
→ denormalize transforms.
-
normalizedToGridX
final double normalizedToGridX(double x) Converts the given normalized x coordinate to grid index. "Normalized coordinates" are coordinates in the unit of measurement given byUnit.getSystemUnit()
. For angular coordinates, this is radians. For linear coordinates, this is metres.- Parameters:
x
- the "real world" coordinate (often longitude in radians) of the point for which to get the translation.- Returns:
- the grid index for the given coordinate. May be out of bounds.
-
normalizedToGridY
final double normalizedToGridY(double y) Converts the given normalized x coordinate to grid index. "Normalized coordinates" are coordinates in the unit of measurement given byUnit.getSystemUnit()
. For angular coordinates, this is radians. For linear coordinates, this is metres.- Parameters:
y
- the "real world" coordinate (often latitude in radians) of the point for which to get the translation.- Returns:
- the grid index for the given coordinate. May be out of bounds.
-
computeHashCode
protected int computeHashCode()Computes a hash value for this transform. This method is invoked byAbstractMathTransform.hashCode()
when first needed.- Overrides:
computeHashCode
in classAbstractMathTransform
- Returns:
- the hash code value. This value may change between different execution of the Apache SIS library.
-
equals
Compares the specified object with this math transform for equality.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classAbstractMathTransform
- Parameters:
object
- the object to compare with this transform.mode
- the strictness level of the comparison. Default toSTRICT
.- Returns:
true
if the given object is considered equals to this math transform.- See Also:
-