The transformation catalog class provides a mechanism for discovering available DatumTransformation
objects.
You can retrieve the default transformation used internally 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,
using getTransformation(SpatialReference, SpatialReference)
. To discover available transformations,
use the getTransformationsBySuitability(SpatialReference, SpatialReference)
or
getTransformationsBySuitability(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 property
must be set at process startup.
If the default Projection Engine directory is found during API initialization, explicitly setting the
location is not required.
Projection Engine data files are available in the
downloads area of developers.arcgis.com (requires
login).
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:
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.
}
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 String
Gets the path of the directory containing Projection Engine files on the local file system, where supporting files for grid-based 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 grid-based transformations are located.
-
Method Details
-
getProjectionEngineDirectory
Gets the path of the directory containing Projection Engine files on the local file system, where supporting files for grid-based transformations are located.If the default Projection Engine directory (<application directory>/resources/pedata) is found during API 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
Sets the path of the directory containing Projection Engine files on the local file system, where supporting files for grid-based transformations are located.If the default Projection Engine directory (<application directory>/resources/pedata) is found during API initialization, calling this method is not required in order to use grid-based transformations. However, you can call this method in order to use a non-default Projection Engine directory.
This property should only be set upon process startup - a suitable point could be after license or license keys, but before any use of maps, map views, scene views, or any other functionality that may involve geometry or projection functionality.
Projection Engine data files are available in the downloads area of developers.arcgis.com (requires login).
- 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 (PE) dataset to function correctly. If this API cannot locate these datasets, the transformation is not usable, and
DatumTransformation.isMissingProjectionEngineFiles()
is true. The list may include transformations like this. To use such transformations, ensuregetProjectionEngineDirectory()
is set correctly, and that the required dataset is available within that location. UseGeographicTransformationStep.getProjectionEngineFilenames()
andHorizontalVerticalTransformationStep.getProjectionEngineFilenames()
to determine the dataset required for a specific transformation instance.- 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 gravity-related 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 (PE) dataset to function correctly. If this API cannot locate these datasets, the transformation is not usable, and
DatumTransformation.isMissingProjectionEngineFiles()
is true. The list may include transformations like this. To use such transformations, ensuregetProjectionEngineDirectory()
is set correctly, and that the required dataset is available within that location. UseGeographicTransformationStep.getProjectionEngineFilenames()
andHorizontalVerticalTransformationStep.getProjectionEngineFilenames()
to determine the dataset required for a specific transformation instance.- 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 gravity-related 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 gravity-related 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 (PE) dataset to function correctly. If this API cannot locate these datasets, the transformation is not usable, and
DatumTransformation.isMissingProjectionEngineFiles()
is true. The list may include transformations like this. To use such transformations, ensuregetProjectionEngineDirectory()
is set correctly, and that the required dataset is available within that location. UseGeographicTransformationStep.getProjectionEngineFilenames()
andHorizontalVerticalTransformationStep.getProjectionEngineFilenames()
to determine the dataset required for a specific transformation instance.- 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
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
-