Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.geometry

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 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 Details

    • getProjectionEngineDirectory

      public static 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.

      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

      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 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, ensure getProjectionEngineDirectory() is set correctly, and that the required dataset is available within that location. Use GeographicTransformationStep.getProjectionEngineFilenames() and HorizontalVerticalTransformationStep.getProjectionEngineFilenames() to determine the dataset required for a specific transformation instance.

      Parameters:
      inputSpatialReference - the spatial reference to use as the input
      outputSpatialReference - the spatial reference to use as the output
      Returns:
      A List containing DatumTransformation, 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 subtype GeographicTransformation. 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 and outputSpatialReference have a vertical coordinate system, this method returns a HorizontalVerticalTransformation instance. If either SpatialReference does not have a vertical coordinate system, a GeographicTransformation 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 the getTransformation(SpatialReference, SpatialReference, Envelope, boolean) method instead with ignoreVertical = 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, ensure getProjectionEngineDirectory() is set correctly, and that the required dataset is available within that location. Use GeographicTransformationStep.getProjectionEngineFilenames() and HorizontalVerticalTransformationStep.getProjectionEngineFilenames() to determine the dataset required for a specific transformation instance.

      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. If areaOfInterest 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, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns null. Else, if the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest will first be reprojected to inputSpatialReference.
      Returns:
      A List containing DatumTransformation, 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 subtype GeographicTransformation. 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 and outputSpatialReference have a vertical coordinate system, this method returns a HorizontalVerticalTransformation instance. If either SpatialReference does not have a vertical coordinate system, a GeographicTransformation 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 the getTransformation(SpatialReference, SpatialReference, Envelope, boolean) method instead with ignoreVertical = 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) and getTransformationsBySuitability(SpatialReference, SpatialReference, Envelope) methods:

      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, ensure getProjectionEngineDirectory() is set correctly, and that the required dataset is available within that location. Use GeographicTransformationStep.getProjectionEngineFilenames() and HorizontalVerticalTransformationStep.getProjectionEngineFilenames() to determine the dataset required for a specific transformation instance.

      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. If areaOfInterest 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, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns null. Else, if the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest will first be reprojected to inputSpatialReference.
      ignoreVertical - true if TransformationCatalog should ignore any vertical coordinate system set on the inputSpatialReference or outputSpatialReference, 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 if areaOfInterest lies outside of the horizon of inputSpatialReference.
      Throws:
      IllegalArgumentException - if inputSpatialReference or outputSpatialReference is null
      Since:
      100.9.0

    • 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 input
      outputSpatialReference - 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 and outputSpatialReference have a vertical coordinate system, this method returns a HorizontalVerticalTransformation instance. If either SpatialReference does not have a vertical coordinate system, a GeographicTransformation is returned. To replicate the former behavior, use the getTransformation(SpatialReference, SpatialReference, Envelope, boolean) method with ignoreVertical = 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 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. If areaOfInterest 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, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns null. Else, if the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest will first be reprojected to inputSpatialReference.
      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 and outputSpatialReference have a vertical coordinate system, this method returns a HorizontalVerticalTransformation instance. If either SpatialReference does not have a vertical coordinate system, a GeographicTransformation is returned. To replicate the former behavior, use the getTransformation(SpatialReference, SpatialReference, Envelope, boolean) method with ignoreVertical = true.

      Throws:
      IllegalArgumentException - if inputSpatialReference or outputSpatialReference 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) and getTransformation(SpatialReference, SpatialReference, Envelope) methods:

      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. If areaOfInterest 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, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns null. Else, if the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest will first be reprojected to inputSpatialReference.
      ignoreVertical - true if TransformationCatalog should ignore any vertical coordinate system set on the inputSpatialReference or outputSpatialReference, 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 the ignoreVertical parameter. Returns null if no transformation is required for the given input parameters, if areaOfInterest does not intersect the area of use of inputSpatialReference, or if no usable transformation is available.
      Throws:
      IllegalArgumentException - if inputSpatialReference or outputSpatialReference is null
      Since:
      100.9.0