Package com.esri.arcgisruntime.geometry

Class 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, 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 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: 

    
 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:
    DatumTransformation, GeographicTransformation, GeometryEngine.project(Geometry,SpatialReference,DatumTransformation)

    • 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, call DatumTransformation.isMissingProjectionEngineFiles() on each transformation returned.

        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:
        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, call DatumTransformation.isMissingProjectionEngineFiles() on each transformation returned.

        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:
        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) and getTransformationsBySuitability(SpatialReference, SpatialReference, Envelope) methods:

        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, call DatumTransformation.isMissingProjectionEngineFiles() on each transformation returned.

        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:
        java.lang.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:
        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 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:
        java.lang.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:
        java.lang.IllegalArgumentException - if inputSpatialReference or outputSpatialReference is null
        Since:
        100.9.0