Class TransformationCatalog
- java.lang.Object
-
- com.esri.arcgisruntime.geometry.TransformationCatalog
-
public final class TransformationCatalog extends java.lang.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 java.lang.String
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.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 java.util.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 java.util.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 java.util.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(java.lang.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 Detail
-
getProjectionEngineDirectory
public static java.lang.String 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.On Android, the Projection Engine directory is not set by default; you must call
setProjectionEngineDirectory(String)
in order to use any grid-based 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(java.lang.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.On Android, the Projection Engine directory is not set by default; you must call this method in order to use any grid-based 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 grid-based transformations. However, you can call this method in order to use a non-default 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 java.util.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 grid-based transformations, even if the required datasets cannot be located by the Runtime. Such grid-based 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 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:
java.lang.IllegalArgumentException
- if inputSpatialReference or outputSpatialReference is null- Since:
- 100.2.0
-
getTransformationsBySuitability
public static java.util.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 grid-based transformations, even if the required datasets cannot be located by the Runtime. Such grid-based 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 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:
java.lang.IllegalArgumentException
- if inputSpatialReference or outputSpatialReference is null- Since:
- 100.2.0
-
getTransformationsBySuitability
public static java.util.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 dataset (stored in files) to function correctly. For details on such datasets, see
GeographicTransformationStep.getProjectionEngineFilenames()
. The list may include grid-based transformations, even if the required datasets cannot be located by the Runtime. Such grid-based 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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException
- if inputSpatialReference or outputSpatialReference is null- Since:
- 100.9.0
- Calling this method with
-
-