Class HorizontalVerticalTransformation
A HorizontalVerticalTransformation is an ordered list of HorizontalVerticalTransformationStep
objects.
Each HorizontalVerticalTransformation has an input and an output SpatialReference
, and this
HorizontalVerticalTransformation object can be used to convert coordinates between the horizontal (geographic)
and vertical datums of these spatial references using the series of steps it contains. Use the
GeometryEngine.project(Geometry, SpatialReference, DatumTransformation)
method to transform the coordinates
of a specific Geometry
.
A horizontal transformation step is not needed when the input and output spatial references have the same
underlying geographic coordinate systems. A vertical transformation is not needed if both datums (for
ellipsoidal heights) or vertical datums (for gravity-related heights) are the same. To transform coordinates
only between different horizontal (geographic) coordinate systems, you can use a GeographicTransformation
instead.
The inverse of this transformation, used to transform in the opposite direction, is returned from the
DatumTransformation.getInverse()
method.
A HorizontalVerticalTransformation can be constructed from a single HorizontalVerticalTransformationStep
object, or from a number of transformation step objects that are chained together.
You can get a list of suitable transformations for a given input and output spatial reference using one of the
methods on the TransformationCatalog
class.
Some transformations require that certain Projection Engine data files be present on the local file system,
and vertical transformation steps are especially likely to use such files, which can be very large in size.
The DatumTransformation.isMissingProjectionEngineFiles()
property indicates whether any of the files are
missing. The complete list of necessary files for each specific step is available using the
HorizontalVerticalTransformationStep.getProjectionEngineFilenames()
property.
See the "Spatial references" topic in the Developer Guide for more information about using transformations.
This example creates a horizontal-vertical transformation from multiple steps, checks that Projection Engine data is available, and then projects a point geometry using the transformation:
// Create a 3D geometry located in the Pacific, with WGS 1984 geographic coordinate system and EGM2008_Geoid
// vertical coordinate system
Point inputPt = new Point(165.0, -20, 40, SpatialReference.create(4326, 3855));
// Create a horizontal-vertical transformation using more than one step
List<HorizontalVerticalTransformationStep> steps = new ArrayList<>();
// Inverse of transform WGS_1984_To_WGS_1984_EGM2008_2.5x2.5_Height
steps.add(HorizontalVerticalTransformationStep.create(110019).getInverse());
// Transform WGS_1984_(ITRF08)_To_NAD_1983_PA11
steps.add(HorizontalVerticalTransformationStep.create(108365));
HorizontalVerticalTransformation transform = HorizontalVerticalTransformation.create(steps);
// Only project the geometry if the required projection engine files are available
if (!transform.isMissingProjectionEngineFiles()) {
// Project the point to NAD 1983 PA11 geographic spatial reference and NAD 1983 PA11 vertical coordinate system,
// using the transformation created above
SpatialReference outputSr = SpatialReference.create(6322, 115762);
Point projectedPt = (Point) GeometryEngine.project(inputPt, outputSr, transform);
}
- Since:
- 100.9.0
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptioncreate
(HorizontalVerticalTransformationStep horizontalVerticalTransformationStep) Creates a transformation with the given horizontal-vertical transformation step.create
(Iterable<HorizontalVerticalTransformationStep> horizontalVerticalTransformationSteps) Creates a transformation from an iterable of one or more horizontal-vertical transformation steps.Gets the inverse of this datum transformation.getSteps()
Gets an unmodifiable list of horizontal-vertical transformation steps that comprise this HorizontalVerticalTransformation.Methods inherited from class com.esri.arcgisruntime.geometry.DatumTransformation
equals, getInputSpatialReference, getName, getOutputSpatialReference, hashCode, isMissingProjectionEngineFiles
-
Method Details
-
create
public static HorizontalVerticalTransformation create(Iterable<HorizontalVerticalTransformationStep> horizontalVerticalTransformationSteps) Creates a transformation from an iterable of one or more horizontal-vertical transformation steps.Use this factory method to create a HorizontalVerticalTransformation when all the steps are known in advance. The output spatial reference of each step should match the input spatial reference of the following step. The transformation can be used to project geometries using
GeometryEngine.project(Geometry, SpatialReference, DatumTransformation)
.// Create a 3D geometry located in the Pacific, with WGS 1984 geographic coordinate system and EGM2008_Geoid // vertical coordinate system Point inputPt = new Point(165.0, -20, 40, SpatialReference.create(4326, 3855)); // Create a horizontal-vertical transformation using more than one step List<HorizontalVerticalTransformationStep> steps = new ArrayList<>(); // Inverse of transform WGS_1984_To_WGS_1984_EGM2008_2.5x2.5_Height steps.add(HorizontalVerticalTransformationStep.create(110019).getInverse()); // Transform WGS_1984_(ITRF08)_To_NAD_1983_PA11 steps.add(HorizontalVerticalTransformationStep.create(108365)); HorizontalVerticalTransformation transform = HorizontalVerticalTransformation.create(steps); // Check required projection engine files are available if (!transform.isMissingProjectionEngineFiles()) { // Project the point to NAD 1983 PA11 geographic spatial reference and NAD 1983 PA11 vertical coordinate system, // using the transformation created above SpatialReference outputSr = SpatialReference.create(6322, 115762); Point projectedPt = (Point) GeometryEngine.project(inputPt, outputSr, transform); }
- Parameters:
horizontalVerticalTransformationSteps
- an iterable of geographic transformation steps- Returns:
- a new HorizontalVerticalTransformation instance comprising the given steps
- Throws:
IllegalArgumentException
- if horizontalVerticalTransformationSteps is null or empty- Since:
- 100.9.0
-
create
public static HorizontalVerticalTransformation create(HorizontalVerticalTransformationStep horizontalVerticalTransformationStep) Creates a transformation with the given horizontal-vertical transformation step.Use this factory method when a single step transformation is known in advance. The transformation can be used to project geometries using
GeometryEngine.project(Geometry, SpatialReference, DatumTransformation)
.// Create a 3D geometry located in New Zealand, with WGS 1984 geographic coordinate system and // NZVD2009_height vertical coordinate system Point inputPt = new Point(170.55336, -45.813178, 668, SpatialReference.create(4326, 4440)); // Create a horizontal-vertical transformation using a single step equation-based transformation // NZVD2009_To_Dunedin_Bluff_1960_1 HorizontalVerticalTransformation transform = HorizontalVerticalTransformation.create( HorizontalVerticalTransformationStep.create(4453)); // Project the point to WGS84 geographic spatial reference and Dunedin_Bluff_1960_height // vertical coordinate system, using the transformation created above SpatialReference outputSr = SpatialReference.create(4326, 4458); Point projectedPt = (Point) GeometryEngine.project(inputPt, outputSr, transform);
- Parameters:
horizontalVerticalTransformationStep
- a geographic transformation step- Returns:
- a HorizontalVerticalTransformation instance
- Throws:
IllegalArgumentException
- if horizontalVerticalTransformationStep is null- Since:
- 100.9.0
-
getSteps
Gets an unmodifiable list of horizontal-vertical transformation steps that comprise this HorizontalVerticalTransformation.HorizontalVerticalTransformation are immutable. To transform coordinates in the opposite direction (from the
output spatial reference
to theinput spatial reference
) using the same transformation methods, use thegetInverse()
method. If different steps are required, create a new HorizontalVerticalTransformation with the required steps.- Returns:
- an unmodifiable list of horizontal-vertical transformation steps
- Since:
- 100.9.0
-
getInverse
Description copied from class:DatumTransformation
Gets the inverse of this datum transformation.- Specified by:
getInverse
in classDatumTransformation
- Returns:
- the inverse of this datum transformation, or null if the transformation is not invertible
-