Package com.esri.arcgisruntime.geometry

Class 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 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:
    GeographicTransformation

    • Method Detail

      • 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

        public 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 the input spatial reference) using the same transformation methods, use the getInverse() 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