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 above-cited 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 sis-referencing
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 two-dimensional 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 two-dimensional 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 two-dimensional, 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 pre-allocated 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.