Class HorizontalVerticalTransformation
- java.lang.Object
-
- com.esri.arcgisruntime.geometry.DatumTransformation
-
- com.esri.arcgisruntime.geometry.HorizontalVerticalTransformation
-
public final class HorizontalVerticalTransformation extends DatumTransformation
Used to transform coordinates of z-aware geometries between spatial references that have different geographic and/or vertical coordinate systems.A HorizontalVerticalTransformation is an ordered list of
HorizontalVerticalTransformationStep
objects. Each HorizontalVerticalTransformation has an input and an outputSpatialReference
, 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 theGeometryEngine.project(Geometry, SpatialReference, DatumTransformation)
method to transform the coordinates of a specificGeometry
.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 theHorizontalVerticalTransformationStep.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:
GeographicTransformation
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static HorizontalVerticalTransformation
create(HorizontalVerticalTransformationStep horizontalVerticalTransformationStep)
Creates a transformation with the given horizontal-vertical transformation step.static HorizontalVerticalTransformation
create(java.lang.Iterable<HorizontalVerticalTransformationStep> horizontalVerticalTransformationSteps)
Creates a transformation from an iterable of one or more horizontal-vertical transformation steps.HorizontalVerticalTransformation
getInverse()
Gets the inverse of this datum transformation.java.util.List<HorizontalVerticalTransformationStep>
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 Detail
-
create
public static HorizontalVerticalTransformation create(java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException
- if horizontalVerticalTransformationStep is null- Since:
- 100.9.0
-
getSteps
public java.util.List<HorizontalVerticalTransformationStep> 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
public HorizontalVerticalTransformation 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
-
-