Class DatumTransformation

  • Direct Known Subclasses:
    GeographicTransformation

    public abstract class DatumTransformation
    extends Object
    Base class for types that transform coordinates between spatial references that have different datums.

    Get a list of suitable transformations for a given input and output spatial reference using the TransformationCatalog.getTransformationsBySuitability method. Alternatively if you know the transformations you require, create a GeographicTransformation from one or more GeographicTransformationSteps.

     // Create a geometry located in London, UK, with British National Grid spatial reference
     Point britishNationalGridPt = new Point(538985.355, 177329.516, SpatialReference.create(27700));
     // Create a GeographicTransformation with a single step using WKID for OSGB_1936_To_WGS_1984_NGA_7PAR transformation
     GeographicTransformation transform = GeographicTransformation.create(GeographicTransformationStep.create(108336));
     // Project the point to WGS84, using the transformation
     Point wgs84Pt = (Point) GeometryEngine.project(britishNationalGridPt, SpatialReferences.getWgs84(), transform);
     

    To transform coordinates in the opposite direction (from the output spatial reference to the input spatial reference using the same transformation methods, use the getInverse() method.

     // Create a geometry located in London UK, with British National Grid spatial reference
     Point britishNationalGridPt = new Point(538985.355, 177329.516, SpatialReference.create(27700));
    
     // Create a transformation with more than one step
     List<GeographicTransformationStep> steps = new ArrayList<>();
     steps.add(GeographicTransformationStep.create(1196)); // OSGB_1936_To_WGS_1984_2
     steps.add(GeographicTransformationStep.create(1149).getInverse()); // ETRS_1989_To_WGS_1984 inversed
     GeographicTransformation transform = GeographicTransformation.create(steps);
    
     // Project the point to ETRS 1989 geographic spatial reference, using the transformation
     Point etrs89Pt = (Point) GeometryEngine.project(britishNationalGridPt, SpatialReference.create(4258), transform);
     

    The getName() method returns a string intended to be suitable for display, such as when displaying a list of available transformations to an end user.

    Some geographic transformations rely on supporting files to be present in a known location (see TransformationCatalog.getProjectionEngineDirectory). Use isMissingProjectionEngineFiles() to identify transformations for which the supporting files are missing; if true then the transformation cannot be used to project geometries. Use GeographicTransformationStep.getProjectionEngineFilenames to identify which files are missing for each individual step.

    Since:
    100.2.0
    See Also:
    GeographicTransformation, GeographicTransformationStep
    • Method Detail

      • getName

        public String getName()
        Gets the name of the datum transformation, suitable for display in a user interface.

        If this transformation has more than one step, the name contains the concatenated names of each step's transformation, separated by a plus sign '+'. If the transformation is inverted, the name starts with a tilde (~).

        Returns:
        the name of the datum transformation
        Since:
        100.2.0
      • getInputSpatialReference

        public SpatialReference getInputSpatialReference()
        Gets the input spatial reference of this datum transformation. This transformation is suitable for transforming geometries whose spatial reference has the same datum as this spatial reference.
        Returns:
        the input spatial reference
        Since:
        100.2.0
      • getOutputSpatialReference

        public SpatialReference getOutputSpatialReference()
        Gets the output spatial reference of this datum transformation. This transformation is suitable for transforming geometries into a spatial reference that has the same datum as this spatial reference.
        Returns:
        the output spatial reference
        Since:
        100.2.0
      • getInverse

        public abstract DatumTransformation getInverse()
        Gets the inverse of this datum transformation.
        Returns:
        the inverse of this datum transformation, or null if the transformation is not invertible
        Since:
        100.2.0
      • isMissingProjectionEngineFiles

        public boolean isMissingProjectionEngineFiles()
        Indicates if any files needed by the Projection Engine for any of the geographic transformation steps that comprise this transformation are missing from the local file system.

        If true, this indicates that this transformation is not currently usable; in this case, using the GeometryEngine.project(Geometry, SpatialReference, DatumTransformation) method with this transform will throw an exception. In order for a transform to be usable, two conditions must be satisfied:

        If Projection Engine files are installed at run time, the app may need to be restarted for this value to change.

        If false, this transformation can successfully be used. Either this transformation does not require any Projection Engine files (it is equation-based), or the required files are found.

        Returns:
        true if any required files are missing; false otherwise
        Since:
        100.2.0
      • equals

        public boolean equals​(Object obj)
        Indicates whether some other object is "equal to" this DatumTransformation. Returns true if the two DatumTransformations use the same methods of transformation, and operate in the same direction.
        Overrides:
        equals in class Object
        Parameters:
        obj - the reference DatumTransformation with which to compare
        Returns:
        true if this object has the same values as the obj argument; false otherwise
        Since:
        100.2.0
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object