C
 dimension of the coordinate unit (usually Angle
).T
 dimension of the translation unit (usually Angle
or Length
).public abstract class DatumShiftGrid<C extends Quantity<C>,T extends Quantity<T>> extends Object implements Serializable
Geodetic datum changes can be implemented by translations in geographic
or geocentric coordinates. Translations given by DatumShiftGrid
instances are often, but not always,
applied directly on geographic coordinates (λ,φ). But some algorithms rather apply the
translations in geocentric coordinates (X,Y,Z). This DatumShiftGrid
class can describe both cases, but will be used with different MathTransform
implementations.
Steps for calculation of a translation vector:
getCoordinateUnit()
.getCoordinateToGrid()
.interpolateInCell(…)
.isCellValueRatio()
.getTranslationUnit()
.interpolateAt(…)
method performs all those steps.
But that method is provided only for convenience; it is not used by Apache SIS.
For performance reasons SIS MathTransform
implementations perform all the abovecited steps themselves,
and apply the interpolated translations on coordinate values in their own step between above steps 3 and 4.
InterpolatedTransform
directly on the given (λ,φ) coordinates.
InterpolatedGeocentricTransform
).
DatumShiftGrid
can describe the small corrections part.
interpolateInCell(double, double, double[])
where the two first double
values are (x,y) grid indices.getCellValue(int, int, int)
where the two last int
values are (x,y) grid indices.derivativeInCell(double, double)
where the values are (x,y) grid indices.DatumShiftGrid
to interpolate translation vectors
in more than two dimensions. See the above datum shift by geocentric translations use case for
an example.
DatumShiftTransform
,
Serialized FormDefined in the sisreferencing
module
Modifier  Constructor and Description 

protected 
DatumShiftGrid(DatumShiftGrid<C,T> other)
Creates a new datum shift grid with the same grid geometry (size and units) than the given grid.

protected 
DatumShiftGrid(Unit<C> coordinateUnit,
LinearTransform coordinateToGrid,
int[] gridSize,
boolean isCellValueRatio,
Unit<T> translationUnit)
Creates a new datum shift grid for the given size and units.

Modifier and Type  Method and Description 

Matrix 
derivativeInCell(double gridX,
double gridY)
Returns the derivative at the given grid indices.

boolean 
equals(Object other)
Returns
true if the given object is a grid containing the same data than this grid. 
double 
getCellMean(int dim)
Returns an average translation value for the given dimension.

abstract double 
getCellPrecision()
Returns an estimation of cell value precision (not to be confused with accuracy).

abstract double 
getCellValue(int dim,
int gridX,
int gridY)
Returns the translation stored at the given twodimensional grid indices for the given dimension.

LinearTransform 
getCoordinateToGrid()
Conversion from the "real world" coordinates to grid indices including fractional parts.

Unit<C> 
getCoordinateUnit()
Returns the unit of measurement of input values, before conversion to grid indices.

Envelope 
getDomainOfValidity()
Returns the domain of validity of input coordinates that can be specified to the
interpolateAt(…) method. 
int[] 
getGridSize()
Returns the number of cells along each axis in the grid.

abstract int 
getTranslationDimensions()
Returns the number of dimensions of the translation vectors interpolated by this datum shift grid.

Unit<T> 
getTranslationUnit()
Returns the unit of measurement of output values, as interpolated by the
interpolateAt(…) method. 
int 
hashCode()
Returns a hash code value for this datum shift grid.

double[] 
interpolateAt(double... ordinates)
Interpolates the translation to apply for the given coordinate.

void 
interpolateInCell(double gridX,
double gridY,
double[] vector)
Interpolates the translation to apply for the given twodimensional grid indices.

boolean 
isCellValueRatio()
Returns
true if the translation values in the cells are divided by the cell size. 
double 
normalizedToGridX(double x)
Converts the given normalized x ordinate to grid index.

double 
normalizedToGridY(double y)
Converts the given normalized x ordinate to grid index.

protected DatumShiftGrid(Unit<C> coordinateUnit, LinearTransform coordinateToGrid, int[] gridSize, boolean isCellValueRatio, Unit<T> translationUnit)
Meaning of argument values is documented more extensively in getCoordinateUnit()
,
getCoordinateToGrid()
, isCellValueRatio()
and getTranslationUnit()
methods. The argument order is roughly the order in which they are used in the process of
interpolating translation vectors.
coordinateUnit
 the unit of measurement of input values, before conversion to grid indices by coordinateToGrid
.coordinateToGrid
 conversion from the "real world" coordinates to grid indices including fractional parts.gridSize
 number of cells along each axis in the grid. The length of this array shall be equal to coordinateToGrid
target dimensions.isCellValueRatio
 true
if results of interpolateInCell(…)
are divided by grid cell size.translationUnit
 the unit of measurement of output values.protected DatumShiftGrid(DatumShiftGrid<C,T> other)
other
 the other datum shift grid from which to copy the grid geometry.public int[] getGridSize()
coordinateToGrid
target dimensions.public Envelope getDomainOfValidity() throws TransformException
interpolateAt(…)
method. Coordinates outside that domain of
validity will still be accepted, but the extrapolated results may be very wrong.
The unit of measurement for the coordinate values in the returned envelope is
given by getCoordinateUnit()
. The envelope CRS is undefined.
TransformException
 if an error occurred while computing the envelope.public Unit<C> getCoordinateUnit()
Units.DEGREE
, but other units are allowed.getTranslationUnit()
,
AbstractCoordinateOperation.getInterpolationCRS()
public LinearTransform getCoordinateToGrid()
MathTransform
shall be in the unit of measurement
given by getCoordinateUnit()
.
The output points are grid indices with integer values in the center of grid cells.
This transform is usually twodimensional, in which case conversions from (x,y)
coordinates to (gridX
, gridY
) indices can be done with the following formulas:
getCoordinateUnit()
.coordinateToGrid
transform for the above formulas can be represented by the following matrix:
┌ ┐ │ 1/Δx 0 x₀/Δx │ │ 0 1/Δy y₀/Δy │ │ 0 0 1 │ └ ┘
public final double normalizedToGridX(double x)
Unit.getSystemUnit()
.
For angular coordinates, this is radians. For linear coordinates, this is metres.x
 the "real world" ordinate (often longitude in radians) of the point for which to get the translation.public final double normalizedToGridY(double y)
Unit.getSystemUnit()
.
For angular coordinates, this is radians. For linear coordinates, this is metres.y
 the "real world" ordinate (often latitude in radians) of the point for which to get the translation.public abstract int getTranslationDimensions()
public Unit<T> getTranslationUnit()
interpolateAt(…)
method.
Apache SIS MathTransform
implementations restrict the translation units to the following values:
InterpolatedTransform
, the translation
unit shall be the same than the coordinate unit.InterpolatedGeocentricTransform
,
the translation unit shall be the same than the unit of source ellipsoid axis lengths.interpolateAt(…)
.getCoordinateUnit()
,
interpolateAt(double...)
public double[] interpolateAt(double... ordinates) throws TransformException
getCoordinateUnit()
.
The output values are in the unit given by getTranslationUnit()
.
The length of the returned array is given by getTranslationDimensions()
.
getCoordinateToGrid()
.interpolateInCell(double, double, double[])
.isCellValueRatio()
returns true
, delta transform
the translation vector by the inverse of the conversion given at step 1.ordinates
 the "real world" ordinate (often longitude and latitude, but not necessarily)
of the point for which to get the translation.TransformException
 if an error occurred while computing the translation vector.public void interpolateInCell(double gridX, double gridY, double[] vector)
vector
array, which shall have a length of at least getTranslationDimensions()
.
The output unit of measurement is the same than the one documented in getCellValue(int, int, int)
.
getTranslationDimensions()
.
gridX
index into the [0 … gridSize[0]
 2] range, inclusive.gridY
index into the [0 … gridSize[1]
 2] range, inclusive.getCellValue(int, int, int)
, get the cell values around the given indices.vector[dim]
.gridX
 first grid ordinate of the point for which to get the translation.gridY
 second grid ordinate of the point for which to get the translation.vector
 a preallocated array where to write the translation vector.public Matrix derivativeInCell(double gridX, double gridY)
gridX
and gridY
, because empirical tests suggest that the accuracy of such interpolation
is uncertain.gridX
 first grid ordinate of the point for which to get the translation.gridY
 second grid ordinate of the point for which to get the translation.public abstract double getCellValue(int dim, int gridX, int gridY)
isCellValueRatio()
boolean:
false
, the value returned by this method shall be in the unit of measurement
given by getTranslationUnit()
.true
, the value returned by this method is the ratio of the translation divided by the
distance between grid cells in the dim dimension (Δx or Δy in the
constructor javadoc).dim
 the dimension of the translation vector component to get,
from 0 inclusive to getTranslationDimensions()
exclusive.gridX
 the grid index on the x axis, from 0 inclusive to gridSize[0]
exclusive.gridY
 the grid index on the y axis, from 0 inclusive to gridSize[1]
exclusive.public double getCellMean(int dim)
getCellValue(dim, …)
, but subclasses may override with more specific values.
dim
 the dimension for which to get an average translation value,
from 0 inclusive to getTranslationDimensions()
exclusive.public abstract double getCellPrecision()
getCellValue(int, int, int)
.
In particular if isCellValueRatio()
returns true
, then the accuracy is in
units of grid cell size.
This information is used for determining a tolerance threshold in iterative calculation.
public boolean isCellValueRatio()
true
if the translation values in the cells are divided by the cell size.
If true
, then the values returned by getCellValue(…)
,
getCellMean(…)
and interpolateInCell(…)
methods
are the ratio of the translation divided by the distance between grid cells in the requested
dimension (Δx or Δy in the constructor javadoc).true
if the translation values in the cells are divided by the cell size.public boolean equals(Object other)
true
if the given object is a grid containing the same data than this grid.public int hashCode()
Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.