Class GeographicTransformation


  • public final class GeographicTransformation
    extends DatumTransformation
    Represents a function used to transform coordinates between two different spatial references that have different datums. The transformation accounts for the difference between the datums of each spatial reference.

    Construct a GeographicTransformation from a single GeographicTransformationStep, or from a list of steps. The output spatial reference of each one step must match the input spatial reference of the following step. Use it to project a Geometry.

     // 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);
     

    Most multi-step transformations between spatial references that are not based on the WGS 1984 datum use WGS 1984 as an intermediate datum. It is common to create a geographic transformation object with two geographic transformation steps: first to transform from the datum of the input spatial reference to WGS 1984, and then from WGS 1984 to the datum of the output spatial reference's datum. There are a limited number of transformations directly between two non-WGS84 datums, such as WKID 4461 (NAD_1983_HARN_To_NAD_1983_NSRS2007_1) that do not need WGS 1984 as an intermediate datum.

     // 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);
     

    You can get a list of all the suitable transformations between a given input and output spatial reference using the TransformationCatalog.getTransformationsBySuitability method.

    GeographicTransformations are immutable. 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. If different steps are required, create a new GeographicTransformation with the required steps.

    Some geographic transformations rely on supporting files to be present in a known location (see TransformationCatalog.getProjectionEngineDirectory). Use DatumTransformation.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.

    See the Spatial references topic in the developer Guide for more information about using transformations.

    Since:
    100.2.0
    See Also:
    GeographicTransformationStep
    • Method Detail

      • create

        public static GeographicTransformation create​(Iterable<GeographicTransformationStep> geographicTransformationSteps)
        Creates a transformation from an iterable of one or more geographic transformation steps.

        Use this factory method to create a GeographicTransformation when all the steps are known in advance. The output spatial reference of each step should match the input spatial reference of the following step. The transformation can be used to project geometries using GeometryEngine.project(Geometry, SpatialReference, DatumTransformation).

         // 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);
         
        Parameters:
        geographicTransformationSteps - an iterable of geographic transformation steps
        Returns:
        a new GeographicTransformation instance comprising the given steps
        Throws:
        IllegalArgumentException - if geographicTransformationSteps is null or empty
        Since:
        100.2.0
      • create

        public static GeographicTransformation create​(GeographicTransformationStep geographicTransformationStep)
        Creates a transformation with the given geographic transformation step.
         // 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);
         

        Use this factory method when a single step transformation is known in advance. The transformation can be used to project geometries using GeometryEngine.project(Geometry, SpatialReference, DatumTransformation).

        Parameters:
        geographicTransformationStep - a geographic transformation step
        Returns:
        a GeographicTransformation instance
        Throws:
        IllegalArgumentException - if geographicTransformationStep is null
        Since:
        100.2.0
      • getSteps

        public List<GeographicTransformationStep> getSteps()
        Gets an unmodifiable list of geographic transformation steps that comprise this GeographicTransformation.

        GeographicTransformations are immutable. 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. If different steps are required, create a new GeographicTransformation with the required steps.

        Returns:
        an unmodifiable list of geographic transformation steps
        Since:
        100.2.0