Package com.esri.arcgisruntime.geometry

Class DatumTransformation

java.lang.Object

com.esri.arcgisruntime.geometry.DatumTransformation

Direct Known Subclasses:

GeographicTransformation, HorizontalVerticalTransformation

public abstract class DatumTransformation
extends Object

Represents a function to convert between the coordinate systems. This is the base class for classes used to transform coordinates between spatial references that have different datums. The inverse of the datum transformation, used to transform in the opposite direction, may be accessed by calling getInverse().

A datum transformation has a getName() method, which returns a name suitable for display, such as when displaying a list of available transformations to an end user.

You can get a list of suitable transformations for a given input and output spatial reference by using the TransformationCatalog.getTransformationsBySuitability method. Alternatively, if you know the transformations you require, create a GeographicTransformation from one or more GeographicTransformationSteps. The following example shows a GeographicTransformation created with a single GeographicTransformationStep:

 // 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);
 

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.

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

In order for any Projection Engine files to be found, the data location must be set first using the TransformationCatalog.setProjectionEngineDirectory(String) method.

A datum transformation object is immutable.

Since:

100.2.0

See Also:

GeographicTransformation, GeographicTransformationStep

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object obj)	Indicates whether some other object is "equal to" this DatumTransformation.
SpatialReference	getInputSpatialReference()	Gets the input spatial reference of this datum transformation.
abstract DatumTransformation	getInverse()	Gets the inverse of this datum transformation.
String	getName()	Gets the name of the datum transformation, suitable for display in a user interface.
SpatialReference	getOutputSpatialReference()	Gets the output spatial reference of this datum transformation.
int	hashCode()
boolean	isMissingProjectionEngineFiles()	Indicates if any files needed by the Projection Engine for any of the geographic transformation steps that comprise this transformation are missing from the local file system.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

getName

public String getName()

Gets the name of the datum transformation, suitable for display in a user interface.

If this transformation has more than one step, the name contains the concatenated names of each step's transformation, separated by a plus sign '+'. If the transformation is inverted, the name starts with a tilde (~).

Returns:

the name of the datum transformation

Since:

100.2.0

getInputSpatialReference

public SpatialReference getInputSpatialReference()

Gets the input spatial reference of this datum transformation. This transformation is suitable for transforming geometries whose spatial reference has the same datum as this spatial reference.

Returns:

the input spatial reference

Since:

100.2.0

getOutputSpatialReference

public SpatialReference getOutputSpatialReference()

Gets the output spatial reference of this datum transformation. This transformation is suitable for transforming geometries into a spatial reference that has the same datum as this spatial reference.

Returns:

the output spatial reference

Since:

100.2.0

getInverse

public abstract DatumTransformation getInverse()

Gets the inverse of this datum transformation.

Returns:

the inverse of this datum transformation, or null if the transformation is not invertible

Since:

100.2.0

isMissingProjectionEngineFiles

public boolean isMissingProjectionEngineFiles()

Indicates if any files needed by the Projection Engine for any of the geographic transformation steps that comprise this transformation are missing from the local file system.

If true, this indicates that this transformation is not currently usable; in this case, using the GeometryEngine.project(Geometry, SpatialReference, DatumTransformation) method with this transform will throw an exception. In order for a transform to be usable, two conditions must be satisfied:

• In order for any Projection Engine files to be found, the root directory must have been successfully set before any transforms are used, using TransformationCatalog.setProjectionEngineDirectory(String). For JavaSE, if the default Projection Engine directory is found during Runtime initialization, explicitly setting the location is not required.
• The specific Projection Engine files required by every GeographicTransformationStep in this transform must be found within the Projection Engine directory. Use GeographicTransformationStep.getProjectionEngineFilenames() to find out the filenames required by each individual step in this transformation.

If Projection Engine files are installed at run time, the app may need to be restarted for this value to change.

If false, this transformation can successfully be used. Either this transformation does not require any Projection Engine files (it is equation-based), or the required files are found.

Returns:

true if any required files are missing; false otherwise

Since:

100.2.0

equals

public boolean equals(Object obj)

Indicates whether some other object is "equal to" this DatumTransformation. Returns true if the two DatumTransformations use the same methods of transformation, and operate in the same direction.

Overrides:

equals in class Object

Parameters:

obj - the reference DatumTransformation with which to compare

Returns:

true if this object has the same values as the obj argument; false otherwise

Since:

100.2.0

hashCode

public int hashCode()

Overrides:

hashCode in class Object