TransformationCatalog QML Type

  • Esri.ArcGISRuntime
  • TransformationCatalog
  • Allows discovery and management of the transformations used to convert coordinates between different datums. More...

    Import Statement: import Esri.ArcGISRuntime
    Since: Esri.ArcGISRuntime 100.2
    Inherits:

    Object

    Properties

    Signals

    Methods

    • DatumTransformation transformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference)
    • DatumTransformation transformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest)
    • DatumTransformation transformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest, bool ignoreVertical)
    • list<DatumTransformation> transformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference)
    • list<DatumTransformation> transformationsBySuitabilityWithAreaOfInterest(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest)
    • list<DatumTransformation> transformationsBySuitabilityWithAreaOfInterestAndIgnoreVertical(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest, bool ignoreVertical)

    Detailed Description

    The transformation catalog type 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.

    This type also lets you set the location where Projection Engine data files needed for some transformations are found on local storage. The projectionEngineDirectory property must be set before using any geometry types.

    Default transformations

    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 TransformationCatalog.transformationsBySuitabilityWithAreaOfInterest.

    See also TransformationCatalog::transformationsBySuitabilityWithAreaOfInterest.

    Property Documentation

    projectionEngineDirectory : string

    The location where Projection Engine data files are found on the local file system.


    Signal Documentation

    projectionEngineDirectoryChanged()

    Emitted when the projectionEngineDirectory property changes.

    Note: The corresponding handler is onProjectionEngineDirectoryChanged.


    Method Documentation

    DatumTransformation transformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference)

    Returns the best usable (default) transformation to transform between the input and output spatial references, without taking into account an area of interest.

    Returns a DatumTransformation instance that represents the best choice given the parameters. Always returns a usable transformation where DatumTransformation::missingProjectionEngineFiles is false. Returns null if no usable transformation is available for the given input parameters, or if no transformation is required.

    The default transformation is the one used in cases such as when calling GeometryEngine::project without specifying a transformation.

    Prior to version 100.9, this method returned a GeographicTransformation.

    From version 100.9 and onward, 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 TransformationCatalog.transformation(inputSpatialReference, outputSpatialReference, areaOfInterest, ignoreVertical) method instead with `ignoreVertical = true`.

    See also TransformationCatalog::transformationsBySuitabilityWithAreaOfInterest.


    DatumTransformation transformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest)

    Returns the best usable transformation to transform between the input and output spatial references, taking into account the area of interest, if specified.

    Returns A DatumTransformation instance that represents the best choice given the parameters. Always returns a usable transformation where DatumTransformation::missingProjectionEngineFiles is false. Returns null if no usable transformation is available for the given input parameters, or if no transformation is required.

    • 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 if Geometry::empty 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. Otherwise, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns null.

    If the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest is reprojected to inputSpatialReference.

    Prior to version 100.9, this method returned a GeographicTransformation.

    From version 100.9 and onward, 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 TransformationCatalog.transformation(inputSpatialReference, outputSpatialReference, areaOfInterest, ignoreVertical) method instead, with `ignoreVertical = true`.


    [since Esri.ArcGISRuntime 100.9] DatumTransformation transformation(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest, bool ignoreVertical)

    Returns the best usable 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.

    • 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 Geometry::empty 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. Otherwise, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns null. If the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest is 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.

    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 Esri.ArcGISRuntime 100.9) behavior of TransformationCatalog.transformation(inputSpatialReference, outputSpatialReference) and TransformationCatalog.transformation(inputSpatialReference, outputSpatialReference, areaOfInterest) methods.

    Returns a DatumTransformation instance that represents the best choice given the parameters. Always returns a usable transformation where DatumTransformation::missingProjectionEngineFiles is false. The specific type returned depends on the given value of the ignoreVertical parameter.

    Calling this method with `ignoreVertical = false` is equivalent to calling transformation with area of interest. In releases prior to Esri.ArcGISRuntime 100.9, calling this method with `ignoreVertical = true` is equivalent to calling transformation with area of interest.

    Calling this method with `ignoreVertical = true` is equivalent to calling transformationsBySuitability(SpatialReference, SpatialReference, Envelope) in releases prior to Esri::ArcGISRuntime 100.9

    This method was introduced in Esri.ArcGISRuntime 100.9.


    list<DatumTransformation> transformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference)

    Returns a list containing DatumTransformation objects, each suitable for transforming between the given input and output spatial references.

    The transformation is the one used in cases such as calling GeometryEngine::project without specifying a transformation.

    The list is 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 currently usable, and DatumTransformation::missingProjectionEngineFiles is true. The list may include transformations like this. To use such transformations, ensure TransformationCatalog::projectionEngineDirectory is set correctly, and that the required dataset is available within that location. Use GeographicTransformationStep::projectionEngineFilenames and HorizontalVerticalTransformationStep::projectionEngineFilenames to determine the dataset required for a specific transformation instance.

    Prior to version 100.9, this method only considered geographic coordinate systems, and the returned list of DatumTransformation objects were of the subclass 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 TransformationCatalog.transformation(inputSpatialReference, outputSpatialReference, areaOfInterest, ignoreVertical) method instead with `ignoreVertical = true`.

    See also TransformationCatalog::transformationsBySuitabilityWithAreaOfInterest.


    list<DatumTransformation> transformationsBySuitabilityWithAreaOfInterest(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest)

    Returns a list containing DatumTransformation objects, each for projecting between spatial references and taking into account the area of interest.

    The list is 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.

    • inputSpatialReference - The SpatialReference to use as the input.
    • outputSpatialReference - The SpatialReference 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 Geometry::empty 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. Otherwise, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns an empty collection. If the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest is reprojected to inputSpatialReference.

    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::missingProjectionEngineFiles is true. The list may include transformations like this. To use such transformations, ensure TransformationCatalog::projectionEngineDirectory is set correctly, and that the required dataset is available within that location. Use GeographicTransformationStep::projectionEngineFilenames and HorizontalVerticalTransformationStep::projectionEngineFilenames to determine the dataset required for a specific transformation instance.

    Prior to version 100.9, this method only considered geographic coordinate systems, and the returned list 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 TransformationCatalog.transformation(inputSpatialReference, outputSpatialReference, areaOfInterest, ignoreVertical) method instead with `ignoreVertical = true`.


    [since Esri.ArcGISRuntime 100.9] list<DatumTransformation> transformationsBySuitabilityWithAreaOfInterestAndIgnoreVertical(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest, bool ignoreVertical)

    Returns a collection of transformations suitable for projecting between the input and output spatial references, taking into account the area of interest, if specified. Optionally checks for suitable vertical transformations.

    • 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 Geometry::empty 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. Otherwise, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns an empty collection. If the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest is reprojected to inputSpatialReference.
    • ignoreVertical - true if TransformationCatalog should ignore any vertical coordinate systems set on the inputSpatialReference or outputSpatialReference, and only consider horizontal (geographic) transformations; false otherwise.

    The collection is 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.

    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 collection 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 Esri.ArcGISRuntime 100.9) behavior of the TransformationCatalog.transformationsBySuitability and TransformationCatalog.transformationsBySuitabilityWithAreaOfInterest methods.

    Calling this method with `ignoreVertical = false` is equivalent to calling TransformationCatalog.transformationsBySuitabilityWithAreaOfInterest.

    In releases prior to Esri.ArcGISRuntime 100.9, calling this method with `ignoreVertical = true` is equivalent to calling TransformationCatalog.transformationsBySuitabilityWithAreaOfInterest.

    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::missingProjectionEngineFiles is true. The list may include transformations like this. To use such transformations, ensure that TransformationCatalog::projectionEngineDirectory is set correctly, and that the required dataset is available within that location. Use GeographicTransformationStep::projectionEngineFilenames and HorizontalVerticalTransformationStep::projectionEngineFilenames to determine the dataset required for a specific transformation instance.

    This method was introduced in Esri.ArcGISRuntime 100.9.


    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.