Class TransformationCatalog


  • public final class TransformationCatalog
    extends Object
    Provides functions for discovering and managing datum transformations, used for projecting geometries where the input and output spatial references have different datums.

    Use the getTransformationsBySuitability(SpatialReference, SpatialReference) and getTransformationsBySuitability(SpatialReference, SpatialReference, Envelope) methods to discover available transformations.

    Some transformations rely on supporting files to be present in a known location. Set this location by calling 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.

     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.
     }
     

    You can also retrieve the default transformation, used when projecting between two given spatial references when a transformation is not explicitly specified, using getTransformation(SpatialReference, SpatialReference).

    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 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​(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 List<DatumTransformation> getTransformationsBySuitability​(SpatialReference inputSpatialReference,
                                                                                SpatialReference outputSpatialReference)
        Gets a complete list of transformations suitable to transform geometries from the given input spatial reference to the given output spatial reference.

        The list is unmodifiable and ordered in descending order by suitability, with the most suitable being first in the list.

        The list may include grid-based transformations, regardless of the presence or absence of the Projection Engine files required for those transformations. Grid-based transformations with missing supporting files cannot be successfully used to transform geometries. Use DatumTransformation.isMissingProjectionEngineFiles to check if supporting files are missing for a specific transformation.

        Parameters:
        inputSpatialReference - the spatial reference to use as the input
        outputSpatialReference - the spatial reference to use as the output
        Returns:
        an unmodifiable list of transformations available to transform between the given spatial references
        Throws:
        IllegalArgumentException - if inputSpatialReference or outputSpatialReference is null
        Since:
        100.2.0
      • getTransformationsBySuitability

        public static List<DatumTransformation> getTransformationsBySuitability​(SpatialReference inputSpatialReference,
                                                                                SpatialReference outputSpatialReference,
                                                                                Envelope extentOfInterest)
        Gets a complete list of transformations available to transform from the given input spatial reference to the given output spatial reference, for the given area of interest.

        The list is unmodifiable and ordered in descending order by suitability, with the most suitable being first in the list. The suitability calculation takes into account the given extent of interest. Alternatively, use the getTransformation(SpatialReference, SpatialReference, Envelope) method to return only the single most suitable transformation for the same input parameters.

        The list may include grid-based transformations, regardless of the presence or absence of the Projection Engine files required for those transformations. Grid-based transformations with missing supporting files cannot be successfully used to transform geometries. Use DatumTransformation.isMissingProjectionEngineFiles to check if supporting files are missing for a specific transformation.

        Parameters:
        inputSpatialReference - the spatial reference to use as the input
        outputSpatialReference - the spatial reference to use as the output
        extentOfInterest - a geographic extent taken into account to determine the suitability of the returned transformations. Will be reprojected to the inputSpatialReference if it has a different spatial reference.
        Returns:
        an unmodifiable list of transformations available to transform between the input and output spatial references. The list will be empty if extentOfInterest lies outside of the horizon of inputSpatialReference.
        Throws:
        IllegalArgumentException - if inputSpatialReference or outputSpatialReference is null
        Since:
        100.2.0
      • getTransformation

        public static DatumTransformation getTransformation​(SpatialReference inputSpatialReference,
                                                            SpatialReference outputSpatialReference)
        Gets the default transformation used to transform from the given input spatial reference to the given output spatial reference.

        The default transformation is used internally when projecting data between the input and output spatial references, and when calling GeometryEngine.project(Geometry, SpatialReference), where a transformation is not specified 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 default transformation for the given parameters, or null if no transformation is required (for example if the two spatial references have the same underlying datum).
        Throws:
        IllegalArgumentException - if inputSpatialReference or outputSpatialReference is null
        Since:
        100.2.0
      • getTransformation

        public static DatumTransformation getTransformation​(SpatialReference inputSpatialReference,
                                                            SpatialReference outputSpatialReference,
                                                            Envelope extentOfInterest)
        Gets the most suitable transformation used to transform from the given input spatial reference to the given output spatial reference, taking in to account the given area of interest.
        Parameters:
        inputSpatialReference - the spatial reference to use as the input
        outputSpatialReference - the spatial reference to use as the output
        extentOfInterest - a geographic area containing coordinates to be transformed, expressed as an envelope. Will be reprojected to the inputSpatialReference if it has a different spatial reference.
        Returns:
        a DatumTransformation instance that represents the best choice given the parameters. Returns null if no transformation is required (for example if the two spatial references have the same underlying datum), or if extentOfInterest lies outside of the horizon of inputSpatialReference.
        Throws:
        IllegalArgumentException - if inputSpatialReference or outputSpatialReference is null
        Since:
        100.2.0