Class DatumShiftGridFile<C extends javax.measure.Quantity<C>,T extends javax.measure.Quantity<T>>
java.lang.Object
org.apache.sis.referencing.datum.DatumShiftGrid<C,T>
org.apache.sis.internal.referencing.provider.DatumShiftGridFile<C,T>
- Type Parameters:
C
- dimension of the coordinate unit (usuallyAngle
).T
- dimension of the translation unit. UsuallyAngle
, but can also beLength
.
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
DatumShiftGridCompressed
,DatumShiftGridFile.Double
,DatumShiftGridFile.Float
,DatumShiftGridGroup
abstract class DatumShiftGridFile<C extends javax.measure.Quantity<C>,T extends javax.measure.Quantity<T>>
extends DatumShiftGrid<C,T>
A datum shift grid loaded from a file.
The filename is usually a parameter defined in the EPSG database.
This class should not be in public API because it requires implementation to expose internal mechanic:
Subclasses need to give an access to their internal data (not a copy) through the
getData()
and setData(Object[])
methods. We use that for managing the cache, reducing memory usage by
sharing data and for equals(Object)
and hashCode()
implementations.- Since:
- 0.7
- Version:
- 1.1
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static final class
DatumShiftGridFile.Double<C extends javax.measure.Quantity<C>,
T extends javax.measure.Quantity<T>> An implementation ofDatumShiftGridFile
which stores the offset values indouble[]
arrays.(package private) static final class
DatumShiftGridFile.Float<C extends javax.measure.Quantity<C>,
T extends javax.measure.Quantity<T>> An implementation ofDatumShiftGridFile
which stores the offset values infloat[]
arrays. -
Field Summary
FieldsModifier and TypeFieldDescription(package private) double
The best translation accuracy that we can expect from this file.(package private) static final Cache
<Object, DatumShiftGridFile<?, ?>> Cache of grids loaded so far.private final org.opengis.parameter.ParameterDescriptorGroup
The parameter descriptor of the provider that created this grid.private final Path[]
The files from which the grid has been loaded.private final double
Number of cells that the grid would have if it was spanning 360° of longitude, or 0 if no wraparound should be applied.protected final int
Number of cells between the start of adjacent rows in the grid.private static final long
Serial number for inter-operability with different versions.protected DatumShiftGridFile<C,
T>[] The sub-grids, ornull
if none.Fields inherited from class org.apache.sis.referencing.datum.DatumShiftGrid
INTERPOLATED_DIMENSIONS
-
Constructor Summary
ConstructorsModifierConstructorDescription(package private)
DatumShiftGridFile
(javax.measure.Unit<C> coordinateUnit, javax.measure.Unit<T> translationUnit, boolean isCellValueRatio, double x0, double y0, double Δx, double Δy, int nx, int ny, org.opengis.parameter.ParameterDescriptorGroup descriptor, Path... files) Creates a new datum shift grid for the given grid geometry.protected
DatumShiftGridFile
(DatumShiftGridFile<C, T> other) Creates a new datum shift grid with the same grid geometry than the given grid.(package private)
DatumShiftGridFile
(DatumShiftGridFile<C, T> other, AffineTransform2D gridToCRS, int nx, int ny) Creates a new datum shift grid with the same configuration than the given grid, except the size and transform which are set to the given values. -
Method Summary
Modifier and TypeMethodDescription(package private) final <NC extends javax.measure.Quantity<NC>,
NT extends javax.measure.Quantity<NT>>
DatumShiftGridFile<NC, NT> Returnsthis
casted to the given type, after verification that those types are valid.static org.opengis.referencing.operation.MathTransform
createGeodeticTransformation
(Class<? extends AbstractProvider> provider, org.opengis.referencing.operation.MathTransformFactory factory, DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle> grid) Creates a transformation between two geodetic CRS, including the sub-grid transforms.boolean
Returnstrue
if the given object is a grid containing the same data than this grid.double
Suggests a precision for the translation values in this grid.protected abstract Object[]
getData()
Returns the data for each shift dimensions.private int
Returns the number of grids, including this grid and all sub-grids counted recursively.final org.opengis.parameter.ParameterDescriptorGroup
Returns the descriptor specified at construction time.final void
getParameterValues
(Parameters parameters) Sets all parameters for a value of typePath
to the values given to the constructor.int
hashCode()
Returns a hash code value for this datum shift grid.protected void
replaceOutsideGridCoordinates
(double[] gridCoordinates) Invoked when agridX
orgridY
coordinate is outside the range of valid grid coordinates.protected abstract DatumShiftGridFile
<C, T> Returns a new grid with the same geometry than this grid but different data arrays.(package private) final void
setSubGrids
(Collection<DatumShiftGridFile<C, T>> children) Sets the sub-grids that are direct children of this grid.final String
toString()
Returns a string representation of this grid for debugging purpose.private void
toTree
(TreeTable.Node branch) Formats this grid as a tree with its children.protected final DatumShiftGridFile
<C, T> If a grid exists in the cache for the same data, returns a new grid sharing the same data arrays.Methods inherited from class org.apache.sis.referencing.datum.DatumShiftGrid
derivativeInCell, getCellMean, getCellValue, getCoordinateToGrid, getCoordinateUnit, getDomainOfValidity, getDomainOfValidity, getGridSize, getGridSize, getTranslationDimensions, getTranslationUnit, interpolateAt, interpolateInCell, isCellInGrid, isCellValueRatio
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
CACHE
Cache of grids loaded so far. The keys are typicallyPath
s or a tuple of paths. Values are grids stored by hard references until the amount of data exceed 32768 (about 128 kilobytes if the values use thefloat
type), in which case the oldest grids will be replaced by soft references.Memory consumption
The use of soft references instead of weak references is on the assumption that users typically use the same few Coordinate Reference Systems for their work. Consequently, we presume that users will not load a lot of grids and are likely to reuse the already loaded grids. -
descriptor
private final org.opengis.parameter.ParameterDescriptorGroup descriptorThe parameter descriptor of the provider that created this grid. -
files
The files from which the grid has been loaded. This is not used directly by this class (except forequals(Object)
andhashCode()
), but can be used by math transform for setting the parameter values. Shall never be null and never empty. -
scanlineStride
protected final int scanlineStrideNumber of cells between the start of adjacent rows in the grid. This is usuallygetGridSize(0)
, stored as a field for performance reasons. Value could be greater thangetGridSize(0)
if there is some elements to ignore at the end of each row. -
periodX
private final double periodXNumber of cells that the grid would have if it was spanning 360° of longitude, or 0 if no wraparound should be applied. Current implementation rounds to nearest integer on the assumption that we expect an integer number of cells in 360°. This value is used for longitude values that are on the other side of the ±180° meridian compared to the region where the grid is defined.- See Also:
-
accuracy
double accuracyThe best translation accuracy that we can expect from this file. The unit of measurement depends onDatumShiftGrid.isCellValueRatio()
.This field is initialized to zero. It is loader responsibility to assign a value to this field after
DatumShiftGridFile
construction.- See Also:
-
subgrids
protected DatumShiftGridFile<C extends javax.measure.Quantity<C>,T extends javax.measure.Quantity<T>>[] subgridsThe sub-grids, ornull
if none. The domain of validity of each sub-grid should be contained in the domain of validity of this grid. Children do not change the way thisDatumShiftGrid
performs its calculation; this list is used only at the time of buildingMathTransform
tree.Design note: we do not provide sub-grids functionality in theThis field has protected access for usage byDatumShiftGrid
parent class because theMathTransform
tree will depend on assumptions aboutDatumShiftGrid.getCoordinateToGrid()
, in particular that it contains only translations and scales (no rotation, no shear). Those assumptions are enforced by theDatumShiftGridFile
constructor.DatumShiftGridGroup
subclass only. No access to this field should be done except by subclasses.- See Also:
-
-
Constructor Details
-
DatumShiftGridFile
DatumShiftGridFile(javax.measure.Unit<C> coordinateUnit, javax.measure.Unit<T> translationUnit, boolean isCellValueRatio, double x0, double y0, double Δx, double Δy, int nx, int ny, org.opengis.parameter.ParameterDescriptorGroup descriptor, Path... files) throws org.opengis.referencing.operation.NoninvertibleTransformException Creates a new datum shift grid for the given grid geometry. The actual offset values need to be provided by subclasses.- Parameters:
coordinateUnit
- the unit of measurement of input values, before conversion to grid indices bycoordinateToGrid
.translationUnit
- the unit of measurement of output values.isCellValueRatio
-true
if results ofinterpolateInCell(…)
are divided by grid cell size.x0
- longitude in degrees of the center of the cell at grid index (0,0), positive east.y0
- latitude in degrees of the center of the cell at grid index (0,0), positive north.Δx
- increment in x value between cells at index gridX and gridX + 1.Δy
- increment in y value between cells at index gridY and gridY + 1.nx
- number of cells along the x axis in the grid.ny
- number of cells along the y axis in the grid.descriptor
- the parameter descriptor of the provider that created this grid.files
- the file(s) from which the grid has been loaded. This array is not cloned.- Throws:
org.opengis.referencing.operation.NoninvertibleTransformException
-
DatumShiftGridFile
Creates a new datum shift grid with the same grid geometry than the given grid. This is used byDatumShiftGridCompressed
for replacing a grid by another one.- Parameters:
other
- the other datum shift grid from which to copy the grid geometry.
-
DatumShiftGridFile
DatumShiftGridFile(DatumShiftGridFile<C, T> other, AffineTransform2D gridToCRS, int nx, int ny) throws org.opengis.referencing.operation.NoninvertibleTransformExceptionCreates a new datum shift grid with the same configuration than the given grid, except the size and transform which are set to the given values. This is used for creating aDatumShiftGridGroup
containing many grids, using one grid as a template for setting parameter values. Theaccuracy
is initialized to zero and should be updated by the caller.- Parameters:
other
- the other datum shift grid from which to copy parameters.gridToCRS
- conversion from grid indices to "real world" coordinates.nx
- number of cells along the x axis in the grid.ny
- number of cells along the y axis in the grid.- Throws:
org.opengis.referencing.operation.NoninvertibleTransformException
-
-
Method Details
-
setSubGrids
Sets the sub-grids that are direct children of this grid. This method can be invoked only once. -
getGridCount
private int getGridCount()Returns the number of grids, including this grid and all sub-grids counted recursively. This is used for information purpose only.- See Also:
-
toString
Returns a string representation of this grid for debugging purpose. If this grid has children, then it will be formatted as a tree. -
toTree
Formats this grid as a tree with its children. -
castTo
final <NC extends javax.measure.Quantity<NC>,NT extends javax.measure.Quantity<NT>> DatumShiftGridFile<NC,NT> castTo(Class<NC> coordinateType, Class<NT> translationType) -
setData
Returns a new grid with the same geometry than this grid but different data arrays. This method is invoked byuseSharedData()
when it detected that a newly created grid uses the same data than an existing grid. The typical use case is when a filename is different but still reference the same grid (e.g. symbolic link, lower case versus upper case in a case-insensitive file system).- Parameters:
other
- data from anotherDatumShiftGridFile
that we can share.- Returns:
- a new
DatumShiftGridFile
using the given data reference.
-
getData
Returns the data for each shift dimensions. This method is for cache management,equals(Object)
andhashCode()
implementations only and should not be invoked in other context.- Returns:
- a direct (not cloned) reference to the internal data array.
-
equals
Returnstrue
if the given object is a grid containing the same data than this grid. This method compares the data provided bygetData()
.- Overrides:
equals
in classDatumShiftGrid<C extends javax.measure.Quantity<C>,
T extends javax.measure.Quantity<T>> - Parameters:
other
- the other object to compare with this datum shift grid.- Returns:
true
if the given object is non-null, of the same class than thisDatumShiftGrid
and contains the same data.
-
hashCode
public int hashCode()Returns a hash code value for this datum shift grid. The hash code is based on metadata such as filename, but not ongetData()
for performance reason. -
getCellPrecision
public double getCellPrecision()Suggests a precision for the translation values in this grid. This information is used for deciding when to stop iterations in inverse transformations. The default implementation returns the accuracy divided by an arbitrary value.- Specified by:
getCellPrecision
in classDatumShiftGrid<C extends javax.measure.Quantity<C>,
T extends javax.measure.Quantity<T>> - Returns:
- a precision for the translation values in this grid.
-
replaceOutsideGridCoordinates
protected void replaceOutsideGridCoordinates(double[] gridCoordinates) Invoked when agridX
orgridY
coordinate is outside the range of valid grid coordinates. If the coordinate outside the range is a longitude value and if we handle those values as cyclic, brings that coordinate inside the range.- Overrides:
replaceOutsideGridCoordinates
in classDatumShiftGrid<C extends javax.measure.Quantity<C>,
T extends javax.measure.Quantity<T>> - Parameters:
gridCoordinates
- on input, the cell indices of the point which is outside the grid. On output, the cell indices of an equivalent point inside the grid if possible. Coordinate values are modified in-place.- See Also:
-
getParameterDescriptors
public final org.opengis.parameter.ParameterDescriptorGroup getParameterDescriptors()Returns the descriptor specified at construction time.- Specified by:
getParameterDescriptors
in classDatumShiftGrid<C extends javax.measure.Quantity<C>,
T extends javax.measure.Quantity<T>> - Returns:
- a description of the values in this grid.
-
getParameterValues
Sets all parameters for a value of typePath
to the values given to the constructor. Subclasses may override for defining other kinds of parameters too.- Specified by:
getParameterValues
in classDatumShiftGrid<C extends javax.measure.Quantity<C>,
T extends javax.measure.Quantity<T>> - Parameters:
parameters
- the parameter group where to set the values.
-
createGeodeticTransformation
public static org.opengis.referencing.operation.MathTransform createGeodeticTransformation(Class<? extends AbstractProvider> provider, org.opengis.referencing.operation.MathTransformFactory factory, DatumShiftGridFile<javax.measure.quantity.Angle, javax.measure.quantity.Angle> grid) throws org.opengis.util.FactoryExceptionCreates a transformation between two geodetic CRS, including the sub-grid transforms. If the given grid has no sub-grid, then this method is equivalent to a direct call toInterpolatedTransform.createGeodeticTransformation(MathTransformFactory, DatumShiftGrid)
.- Parameters:
provider
- the provider which is creating a transform.factory
- the factory to use for creating the transform.grid
- the grid of datum shifts from source to target datum.- Returns:
- the transformation between geodetic coordinates.
- Throws:
org.opengis.util.FactoryException
- if an error occurred while creating a transform.- See Also:
-