Class TransformationCatalog
 java.lang.Object

 com.esri.arcgisruntime.geometry.TransformationCatalog

public final class TransformationCatalog extends Object
Allows discovery and management of the transformations used to convert coordinates between different datums.The transformation catalog class provides a mechanism for discovering available
DatumTransformation
objects. You can retrieve the default transformation used internally by Runtime to convert coordinates, and find other available transformations. An area of interest may be taken into account. To retrieve the default transformation, used when projecting between two given spatial references when a transformation is not explicitly specified, usinggetTransformation(SpatialReference, SpatialReference)
. To discover available transformations, use thegetTransformationsBySuitability(SpatialReference, SpatialReference)
orgetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope)
methods.This class also allows you to set the location where Projection Engine data files needed for some transformations are found on local storage. The Projection Engine directory must be set before using any geometry classes. See
setProjectionEngineDirectory(String)
. This method should only be called soon after process startup, before any use of spatial references or transformations. For JavaSE, if the default Projection Engine directory is found during Runtime initialization, explicitly setting the location is not required.The default transformation used when reprojecting geometries is the most suitable available transformation across the area covered by the input and output spatial references. You can sometimes get a more suitable transformation for work within a smaller area by specifying the extent of your specific work area, using
getTransformation(SpatialReference, SpatialReference, Envelope)
.Following is an example that discovers suitable transformations:
See the "Spatial references" topic in the Developer Guide for more information about using transformations.try { TransformationCatalog.setProjectionEngineDirectory(peDataFolder.getAbsolutePath()); // Projection Engine files location was set successfully } catch (ArcGISRuntimeException e) { // If there was an error in setting the projection engine directory, the location may not exist, or if // permissions have not been correctly set, the location cannot be accessed. Transformations that require supporting // files will not be usable. } List<DatumTransformation> transformationsBySuitability = TransformationCatalog.getTransformationsBySuitability(mOriginalGeometry.getSpatialReference(), mArcGISMap.getSpatialReference()); // Display transformations to the user to allow them to choose required transformation for projecting geometries. // For example, get the third transformation from a list of suitable transformations: try { Geometry outputGeom = GeometryEngine.project(mOriginalGeometry, mArcGISMap.getSpatialReference(), transformsBySuitability.get(3)); } catch (ArcGISRuntimeException e) { // If there was an error in setting the projection engine directory (directory cannot be found or is not accessible) // Transformations that require supporting files will not be usable and will throw an exception. }
 Since:
 100.2.0
 See Also:
DatumTransformation
,GeographicTransformation
,GeometryEngine.project(Geometry,SpatialReference,DatumTransformation)


Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static String
getProjectionEngineDirectory()
Gets the path of the directory containing Projection Engine files on the local file system, where supporting files for gridbased transformations are located.static DatumTransformation
getTransformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference)
Returns the default transformation used to transform between the input and output spatial references, without taking into account an area of interest.static DatumTransformation
getTransformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest)
Returns the default transformation used to transform between the input and output spatial references, taking into account the area of interest, if specified.static DatumTransformation
getTransformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest, boolean ignoreVertical)
Returns the default transformation used to transform between the input and output spatial references, taking into account the area of interest, if specified.static List<DatumTransformation>
getTransformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference)
Returns a complete list representing the datum transformations suitable for projection between two spatial references without taking into account an area of interest.static List<DatumTransformation>
getTransformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest)
Returns a complete list representing the datum transformations suitable for projecting between two spatial references and takes into account the area of interest.static List<DatumTransformation>
getTransformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest, boolean ignoreVertical)
Returns a complete list representing the datum transformations suitable for projecting between two spatial references and takes into account the area of interest, optionally checking for suitable vertical transformations.static void
setProjectionEngineDirectory(String projectionEngineDirectory)
Sets the path of the directory containing Projection Engine files on the local file system, where supporting files for gridbased transformations are located.



Method Detail

getProjectionEngineDirectory
public static String getProjectionEngineDirectory()
Gets the path of the directory containing Projection Engine files on the local file system, where supporting files for gridbased transformations are located.On Android, the Projection Engine directory is not set by default; you must call
setProjectionEngineDirectory(String)
in order to use any gridbased transformations.On JavaSE, if the default Projection Engine directory (<application directory>/resources/pedata) is found during Runtime initialization, explicitly setting this location is not required.
This value must not be changed during app run time.
 Returns:
 the directory where the Projection Engine files are located. Default is an empty string.
 Since:
 100.2.0
 See Also:
setProjectionEngineDirectory(String)

setProjectionEngineDirectory
public static void setProjectionEngineDirectory(String projectionEngineDirectory)
Sets the path of the directory containing Projection Engine files on the local file system, where supporting files for gridbased transformations are located.On Android, the Projection Engine directory is not set by default; you must call this method in order to use any gridbased transformations.
On JavaSE, if the default Projection Engine directory (<application directory>/resources/pedata) is found during Runtime initialization, calling this method is not required in order to use gridbased transformations. However, you can call this method in order to use a nondefault Projection Engine directory.
This method should only be called soon after process startup, before any use of spatial references or transformations. A suitable time to call this method is immediately after using
ArcGISRuntimeEnvironment
to license the application. If Projection Engine files are installed to this location during app run time, the app may need to be restarted for them to be found. Parameters:
projectionEngineDirectory
 the path to a directory containing the projection engine files Throws:
ArcGISRuntimeException
 if projectionEngineDirectory is an invalid path, or the directory does not exist, or cannot be accessed Since:
 100.2.0

getTransformationsBySuitability
public static List<DatumTransformation> getTransformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference)
Returns a complete list representing the datum transformations suitable for projection between two spatial references without taking into account an area of interest.The list is unmodifiable and ordered in descending order by suitability, with the most suitable being first in the list.
Some transformations require a supporting Projection Engine dataset (stored in files) to function correctly. For details on such datasets, see
GeographicTransformationStep.getProjectionEngineFilenames()
. The list may include gridbased transformations, even if the required datasets cannot be located by the Runtime. Such gridbased transformations cannot be successfully used to transform geometries. For details on how to check if those datasets are missing, callDatumTransformation.isMissingProjectionEngineFiles()
on each transformation returned. Parameters:
inputSpatialReference
 the spatial reference to use as the inputoutputSpatialReference
 the spatial reference to use as the output Returns:
 A
List
containingDatumTransformation
, each suitable for transforming between the given input and output spatial references.Prior to version 100.9, this method only considered geographic coordinate systems, and the returned array of
DatumTransformation
objects were of the subtypeGeographicTransformation
. A geographic transformation is not required when input and output spatial references have the same underlying geographic coordinate system, in which case an empty list was returned.From version 100.9 onwards, if both
inputSpatialReference
andoutputSpatialReference
have a vertical coordinate system, this method returns aHorizontalVerticalTransformation
instance. If eitherSpatialReference
does not have a vertical coordinate system, aGeographicTransformation
is returned. A geographic transformation is not needed when input and output spatial references have the same underlying geographic (horizontal) coordinate system. A vertical transformation is not needed if both datums (for ellipsoidal heights) or vertical datums (for gravityrelated heights) are the same. If neither type of transformation is needed, an empty collection is returned. To replicate the former behavior, use thegetTransformation(SpatialReference, SpatialReference, Envelope, boolean)
method instead withignoreVertical = true
.  Throws:
IllegalArgumentException
 if inputSpatialReference or outputSpatialReference is null Since:
 100.2.0

getTransformationsBySuitability
public static List<DatumTransformation> getTransformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest)
Returns a complete list representing the datum transformations suitable for projecting between two spatial references and takes into account the area of interest.The list is unmodifiable and ordered in descending order by suitability, with the most suitable being first in the list. The given area of interest can affect the number and order of transformations returned. Alternatively, use the
getTransformation(SpatialReference, SpatialReference, Envelope)
method to return only the single most suitable transformation for the same input parameters.Some transformations require a supporting Projection Engine dataset (stored in files) to function correctly. For details on such datasets, see
GeographicTransformationStep.getProjectionEngineFilenames()
. The list may include gridbased transformations, even if the required datasets cannot be located by the Runtime. Such gridbased transformations cannot be successfully used to transform geometries. For details on how to check if those datasets are missing, callDatumTransformation.isMissingProjectionEngineFiles()
on each transformation returned. Parameters:
inputSpatialReference
 the spatial reference to use as the inputoutputSpatialReference
 the spatial reference to use as the outputareaOfInterest
 the bounding box of coordinates to be transformed, or null to consider the entire world extent. IfareaOfInterest
is null or an empty geometry (Geometry.isEmpty()
is true), the returned transformation does not take into account an area of interest, and the best choice for the entire world extent is effectively assumed. Else, ifareaOfInterest
does not intersect the area of use ofinputSpatialReference
, this method returns null. Else, if theSpatialReference
ofareaOfInterest
differs frominputSpatialReference
, thenareaOfInterest
will first be reprojected toinputSpatialReference
. Returns:
 A
List
containingDatumTransformation
, each suitable for transforming between the given input and output spatial references.Prior to version 100.9, this method only considered geographic coordinate systems, and the returned listof
DatumTransformation
objects were of the subtypeGeographicTransformation
. A geographic transformation is not required when input and output spatial references have the same underlying geographic coordinate system, in which case an empty list was returned.From version 100.9 onwards, if both
inputSpatialReference
andoutputSpatialReference
have a vertical coordinate system, this method returns aHorizontalVerticalTransformation
instance. If eitherSpatialReference
does not have a vertical coordinate system, aGeographicTransformation
is returned. A geographic transformation is not needed when input and output spatial references have the same underlying geographic (horizontal) coordinate system. A vertical transformation is not needed if both datums (for ellipsoidal heights) or vertical datums (for gravityrelated heights) are the same. If neither type of transformation is needed, an empty collection is returned. To replicate the former behavior, use thegetTransformation(SpatialReference, SpatialReference, Envelope, boolean)
method instead withignoreVertical = true
.  Throws:
IllegalArgumentException
 if inputSpatialReference or outputSpatialReference is null Since:
 100.2.0

getTransformationsBySuitability
public static List<DatumTransformation> getTransformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest, boolean ignoreVertical)
Returns a complete list representing the datum transformations suitable for projecting between two spatial references and takes into account the area of interest, optionally checking for suitable vertical transformations.The list is unmodifiable and ordered in descending order by suitability, with the most suitable being first in the list. The given area of interest can affect the number and order of transformations returned. Alternatively, use the
getTransformation(SpatialReference, SpatialReference, Envelope, boolean)
method to return only the single most suitable transformation for the same input parameters.A geographic transformation is not needed when input and output spatial references have the same underlying geographic coordinate system, in which case an empty list is returned. A vertical transformation is not needed if both datums (for ellipsoidal heights) or vertical datums (for gravityrelated heights) are the same. If neither type of transformation is needed, an empty list is returned.
Use this method to determine whether or not any vertical coordinate systems set on the spatial reference parameters should be accounted for in the returned list of transformations. This method can be used to replicate the former (prior to version 100.9.0) behavior of the
getTransformationsBySuitability(SpatialReference, SpatialReference)
andgetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope)
methods: Calling this method with
ignoreVertical == false
is equivalent to callinggetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope)
.  Calling this method with
ignoreVertical == true
is equivalent to callinggetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope)
in releases prior to 100.9.0.
Some transformations require a supporting Projection Engine dataset (stored in files) to function correctly. For details on such datasets, see
GeographicTransformationStep.getProjectionEngineFilenames()
. The list may include gridbased transformations, even if the required datasets cannot be located by the Runtime. Such gridbased transformations cannot be successfully used to transform geometries. For details on how to check if those datasets are missing, callDatumTransformation.isMissingProjectionEngineFiles()
on each transformation returned. Parameters:
inputSpatialReference
 the spatial reference to use as the inputoutputSpatialReference
 the spatial reference to use as the outputareaOfInterest
 the bounding box of coordinates to be transformed, or null to consider the entire world extent. IfareaOfInterest
is null or an empty geometry (Geometry.isEmpty()
is true), the returned transformation does not take into account an area of interest, and the best choice for the entire world extent is effectively assumed. Else, ifareaOfInterest
does not intersect the area of use ofinputSpatialReference
, this method returns null. Else, if theSpatialReference
ofareaOfInterest
differs frominputSpatialReference
, thenareaOfInterest
will first be reprojected toinputSpatialReference
.ignoreVertical
 true ifTransformationCatalog
should ignore any vertical coordinate system set on theinputSpatialReference
oroutputSpatialReference
, and only consider horizontal (geographic) transformations; false otherwise. Returns:
 an unmodifiable list of
DatumTransformation
objects, each suitable for transforming between the given input and output spatial references, taking into account the given area of interest. The list will be empty ifareaOfInterest
lies outside of the horizon ofinputSpatialReference
.  Throws:
IllegalArgumentException
 if inputSpatialReference or outputSpatialReference is null Since:
 100.9.0
 Calling this method with

getTransformation
public static DatumTransformation getTransformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference)
Returns the default transformation used to transform between the input and output spatial references, without taking into account an area of interest.The default transformation is the one used internally in cases such as calling
GeometryEngine.project(Geometry, SpatialReference)
without specifying a transformation as a parameter. Parameters:
inputSpatialReference
 the spatial reference to use as the inputoutputSpatialReference
 the spatial reference to use as the output Returns:
 a DatumTransformation instance that represents the best choice given the parameters. Returns null if no
usable transformation is available for the given input parameters, or if no transformation is required
(for example, if the two spatial references have the same underlying datum).
Prior to version 100.9, this method returned a
GeographicTransformation
.From version 100.9 onwards, if both
inputSpatialReference
andoutputSpatialReference
have a vertical coordinate system, this method returns aHorizontalVerticalTransformation
instance. If eitherSpatialReference
does not have a vertical coordinate system, aGeographicTransformation
is returned. To replicate the former behavior, use thegetTransformation(SpatialReference, SpatialReference, Envelope, boolean)
method withignoreVertical = true
.  Throws:
IllegalArgumentException
 if inputSpatialReference or outputSpatialReference is null Since:
 100.2.0
 See Also:
getTransformation(SpatialReference, SpatialReference, Envelope)

getTransformation
public static DatumTransformation getTransformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest)
Returns the default transformation used to transform between the input and output spatial references, taking into account the area of interest, if specified. Parameters:
inputSpatialReference
 the spatial reference to use as the inputoutputSpatialReference
 the spatial reference to use as the outputareaOfInterest
 the bounding box of coordinates to be transformed, or null to consider the entire world extent. IfareaOfInterest
is null or an empty geometry (Geometry.isEmpty()
is true), the returned transformation does not take into account an area of interest, and the best choice for the entire world extent is effectively assumed. Else, ifareaOfInterest
does not intersect the area of use ofinputSpatialReference
, this method returns null. Else, if theSpatialReference
ofareaOfInterest
differs frominputSpatialReference
, thenareaOfInterest
will first be reprojected toinputSpatialReference
. Returns:
 a DatumTransformation instance that represents the best choice given the parameters. Returns null if no
usable transformation is available for the given input parameters, or if no transformation is required
(for example, if the two spatial references have the same underlying datum).
Prior to version 100.9, this method returned a
GeographicTransformation
.From version 100.9 onwards, if both
inputSpatialReference
andoutputSpatialReference
have a vertical coordinate system, this method returns aHorizontalVerticalTransformation
instance. If eitherSpatialReference
does not have a vertical coordinate system, aGeographicTransformation
is returned. To replicate the former behavior, use thegetTransformation(SpatialReference, SpatialReference, Envelope, boolean)
method withignoreVertical = true
.  Throws:
IllegalArgumentException
 ifinputSpatialReference
oroutputSpatialReference
is null Since:
 100.2.0

getTransformation
public static DatumTransformation getTransformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest, boolean ignoreVertical)
Returns the default transformation used to transform between the input and output spatial references, taking into account the area of interest, if specified. Optionally disregards any vertical transformations.Use this method to determine whether or not any vertical coordinate systems set on the spatial reference parameters should be accounted for in the returned transformation. This method can be used to replicate the former (prior to version 100.9.0) behavior of the
getTransformation(SpatialReference, SpatialReference)
andgetTransformation(SpatialReference, SpatialReference, Envelope)
methods: Calling this method with
ignoreVertical == false
is equivalent to callinggetTransformation(SpatialReference, SpatialReference, Envelope)
.  Calling this method with
ignoreVertical == true
is equivalent to callinggetTransformation(SpatialReference, SpatialReference, Envelope)
in releases prior to 100.9.0.
 Parameters:
inputSpatialReference
 the spatial reference to use as the input.outputSpatialReference
 the spatial reference to use as the output.areaOfInterest
 the bounding box of coordinates to be transformed, or null to consider the entire world extent. IfareaOfInterest
is null or an empty geometry (Geometry.isEmpty()
is true), the returned transformation does not take into account an area of interest, and the best choice for the entire world extent is effectively assumed. Else, ifareaOfInterest
does not intersect the area of use ofinputSpatialReference
, this method returns null. Else, if theSpatialReference
ofareaOfInterest
differs frominputSpatialReference
, thenareaOfInterest
will first be reprojected toinputSpatialReference
.ignoreVertical
 true ifTransformationCatalog
should ignore any vertical coordinate system set on theinputSpatialReference
oroutputSpatialReference
, and only consider horizontal (geographic) transformations; false otherwise. Returns:
 A
DatumTransformation
instance that represents the best choice given the parameters. The specific type returned depends on the given value of theignoreVertical
parameter. Returns null if no transformation is required for the given input parameters, ifareaOfInterest
does not intersect the area of use ofinputSpatialReference
, or if no usable transformation is available.  Throws:
IllegalArgumentException
 if inputSpatialReference or outputSpatialReference is null Since:
 100.9.0
 Calling this method with

