Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.geometry

Class GeographicTransformation

java.lang.Object
com.esri.arcgisruntime.geometry.DatumTransformation
com.esri.arcgisruntime.geometry.GeographicTransformation
public final class GeographicTransformation extends DatumTransformation
Represents a function used to transform coordinates of geometries between spatial references that have two different geographic coordinate systems. The transformation accounts for the difference between the datums of each spatial reference.

Each geographic transformation has an input and an output spatial reference. The transformation operates on the horizontal (geographic) datums in each spatial reference.

The inverse of the geographic transformation, if any, can be used to transform in the opposite direction. 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 GeographicTransformation with the required steps.

A geographic transformation can be constructed from a single geographic transformation step object, or from a list of geographic transformation steps objects that are chained together. For multiple steps, the output spatial reference of each one step must match the input spatial reference of the following step.

Most transformations between spatial references that do not share the WGS 1984 datum use WGS 1984 as an intermediate datum. Thus, it is common to create a geographic transformation object with two geographic transformation steps: first to transform from the datum in the input spatial reference to WGS 1984 and then from WGS 1984 to the output spatial reference's datum. There are a limited number of direct transformations between two non-WGS84 datums, such as WKID 4461, which is NAD_1983_HARN_To_NAD_1983_NSRS2007_1. These do not need WGS 1984 as an intermediate datum.

In most cases, however, you do not need to construct your own GeographicTransformation. You can get a list of suitable transformations for a given input and output spatial reference using methods of the TransformationCatalog class.

A geographic transformation object is immutable.

Following is an example that creates a geographic transformation from a single GeographicTransformationStep. and then uses GeometryEngine.project(Geometry, SpatialReference, DatumTransformation) to project the geometry (a Point) to WGS84. 

 // Create a geometry located in London, UK, with British National Grid spatial reference
 Point britishNationalGridPt = new Point(538985.355, 177329.516, SpatialReference.create(27700));
 // Create a GeographicTransformation with a single step using WKID for OSGB_1936_To_WGS_1984_NGA_7PAR transformation
 GeographicTransformation transform = GeographicTransformation.create(GeographicTransformationStep.create(108336));
 // Project the point to WGS84, using the transformation
 Point wgs84Pt = (Point) GeometryEngine.project(britishNationalGridPt, SpatialReferences.getWgs84(), transform);

The next example creates a geographic transformation from multiple steps and then projects the geometry (a Point) to ETRS 1989: 

 // Create a geometry located in London UK, with British National Grid spatial reference
 Point britishNationalGridPt = new Point(538985.355, 177329.516, SpatialReference.create(27700));

 // Create a transformation with more than one step
 List<GeographicTransformationStep> steps = new ArrayList<>();
 steps.add(GeographicTransformationStep.create(1196)); // OSGB_1936_To_WGS_1984_2
 steps.add(GeographicTransformationStep.create(1149).getInverse()); // ETRS_1989_To_WGS_1984 inversed
 GeographicTransformation transform = GeographicTransformation.create(steps);

 // Project the point to ETRS 1989 geographic spatial reference, using the transformation
 Point etrs89Pt = (Point) GeometryEngine.project(britishNationalGridPt, SpatialReference.create(4258), transform);

Some geographic transformations require that certain Projection Engine data files be present on the local file system. Call DatumTransformation.isMissingProjectionEngineFiles() to determine if any of the files are missing; if true, then the transformation cannot be used to project geometries. The complete list of necessary files is available by calling the GeographicTransformationStep.getProjectionEngineFilenames() on each geographic transformation step.

See the "Spatial references" topic in the Developer Guide for more information about using transformations.

Since:
100.2.0
See Also:

  • Method Details

    • create

      public static GeographicTransformation create(Iterable<GeographicTransformationStep> geographicTransformationSteps)
      Creates a transformation from an iterable of one or more geographic transformation steps.

      Use this factory method to create a GeographicTransformation 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 geometry located in London UK, with British National Grid spatial reference
 Point britishNationalGridPt = new Point(538985.355, 177329.516, SpatialReference.create(27700));

 // Create a transformation with more than one step
 List<GeographicTransformationStep> steps = new ArrayList<>();
 steps.add(GeographicTransformationStep.create(1196)); // OSGB_1936_To_WGS_1984_2
 steps.add(GeographicTransformationStep.create(1149).getInverse()); // ETRS_1989_To_WGS_1984 inversed
 GeographicTransformation transform = GeographicTransformation.create(steps);

 // Project the point to ETRS 1989 geographic spatial reference, using the transformation
 Point etrs89Pt = (Point) GeometryEngine.project(britishNationalGridPt, SpatialReference.create(4258), transform);
      Parameters:
      geographicTransformationSteps - an iterable of geographic transformation steps
      Returns:
      a new GeographicTransformation instance comprising the given steps
      Throws:
      IllegalArgumentException - if geographicTransformationSteps is null or empty
      Since:
      100.2.0

    • create

      public static GeographicTransformation create(GeographicTransformationStep geographicTransformationStep)
      Creates a transformation with the given geographic transformation step. 
       // Create a geometry located in London, UK, with British National Grid spatial reference
 Point britishNationalGridPt = new Point(538985.355, 177329.516, SpatialReference.create(27700));
 // Create a GeographicTransformation with a single step using WKID for OSGB_1936_To_WGS_1984_NGA_7PAR transformation
 GeographicTransformation transform = GeographicTransformation.create(GeographicTransformationStep.create(108336));
 // Project the point to WGS84, using the transformation
 Point wgs84Pt = (Point) GeometryEngine.project(britishNationalGridPt, SpatialReferences.getWgs84(), transform);

      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).

      Parameters:
      geographicTransformationStep - a geographic transformation step
      Returns:
      a GeographicTransformation instance
      Throws:
      IllegalArgumentException - if geographicTransformationStep is null
      Since:
      100.2.0

    • getSteps

      public List<GeographicTransformationStep> getSteps()
      Gets an unmodifiable list of geographic transformation steps that comprise this GeographicTransformation.

      GeographicTransformations 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 GeographicTransformation with the required steps.

      Returns:
      an unmodifiable list of geographic transformation steps
      Since:
      100.2.0

    • getInverse

      public GeographicTransformation getInverse()
      Description copied from class: DatumTransformation
      Gets the inverse of this datum transformation.
      Specified by:
      getInverse in class DatumTransformation
      Returns:
      the inverse of this datum transformation, or null if the transformation is not invertible