Class GeographicTransformation
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 Summary
Modifier and TypeMethodDescriptionstatic GeographicTransformation
create
(GeographicTransformationStep geographicTransformationStep) Creates a transformation with the given geographic transformation step.static GeographicTransformation
create
(Iterable<GeographicTransformationStep> geographicTransformationSteps) Creates a transformation from an iterable of one or more geographic transformation steps.Gets the inverse of this datum transformation.getSteps()
Gets an unmodifiable list of geographic transformation steps that comprise this GeographicTransformation.Methods inherited from class com.esri.arcgisruntime.geometry.DatumTransformation
equals, getInputSpatialReference, getName, getOutputSpatialReference, hashCode, isMissingProjectionEngineFiles
-
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
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 theinput spatial reference)
using the same transformation methods, use thegetInverse()
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
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
-