TransformationCatalog Class

Member Function Documentation

[override virtual] TransformationCatalog::~TransformationCatalog()

Destructor.

[static] Esri::ArcGISRuntime::TransformationCatalog *TransformationCatalog::instance()

Returns the singleton instance of the TransformationCatalog.

Use this method to get a reference to this instance so you can connect its signals to slots.

[static] QString TransformationCatalog::projectionEngineDirectory()

Returns the directory of the Projection Engine files on the local file system.

This property should only be set upon process startup - a suitable point could be after license or license keys, but before any use of maps, maps views, scene views, or any other functionality that may involve geometry or projection functionality.

Projection Engine data files are available in the downloads area of developers.arcgis.com (requires login).

See also setProjectionEngineDirectory.

[static] void TransformationCatalog::setProjectionEngineDirectory(const QString &projectionEngineDirectory)

Sets the location of Projection Engine files on the local file system to projectionEngineDirectory.

This property must be set immediately upon process startup before any other API method calls.

See also projectionEngineDirectory.

[static] Esri::ArcGISRuntime::DatumTransformation *TransformationCatalog::transformation(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference)

Returns the best usable default transformation used 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::isMissingProjectionEngineFiles is false. Returns nullptr 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(const Esri::ArcGISRuntime::Geometry&, const Esri::ArcGISRuntime::SpatialReference&) without specifying a transformation.

• inputSpatialReference - The SpatialReference that transformation is from.
• outputSpatialReference - The SpatialReference that transformation is to.

Prior to version 100.9, this method returned a GeographicTransformation.

Starting with version 100.9, 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'.

{transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&)}

See also Esri::ArcGISRuntime::TransformationCatalog::transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&).

[static] Esri::ArcGISRuntime::DatumTransformation *TransformationCatalog::transformation(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference, const Esri::ArcGISRuntime::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::isMissingProjectionEngineFiles is false. Returns nullptr if no usable transformation is available for the given input parameters, or if no transformation is required.

Geometry mapGeometry = GeometryEngine::project(geometry, map.spatialReference());

• inputSpatialReference - The spatial reference to use as the input.
• outputSpatialReference - The spatial reference to use as the output. is to.
• areaOfInterest - The bounding box of coordinates to be transformed, or nullptr to consider the entire world extent. If areaOfInterest is nullptr or if Geometry::isEmpty, 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 nullptr. If areaOfInterest has a different spatial reference than inputSpatialReference, it is reprojected to inputSpatialReference. If areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns nullptr.

Prior to version 100.9, this method returned a GeographicTransformation.

Starting with version 100.9, 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'.

[static, since Esri::ArcGISRuntime 100.9] Esri::ArcGISRuntime::DatumTransformation *TransformationCatalog::transformation(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference, const Esri::ArcGISRuntime::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 empty to consider the entire world extent.
• 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 the TransformationCatalog::transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&) and TransformationCatalog::transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&) methods:

• Calling this method with 'ignoreVertical = false' is equivalent to calling transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&)
• Calling this method with 'ignoreVertical = true' is equivalent to calling transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&) in releases prior to Esri::ArcGISRuntime 100.9

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

This function was introduced in Esri::ArcGISRuntime 100.9.

[static] QList<Esri::ArcGISRuntime::DatumTransformation *> TransformationCatalog::transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference)

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

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 usable, and DatumTransformation::isMissingProjectionEngineFiles 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.

Starting with version 100.9, 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'.

• inputSpatialReference - The SpatialReference that transformation is from.
• outputSpatialReference - The SpatialReference that transformation is to.

[static] QList<Esri::ArcGISRuntime::DatumTransformation *> TransformationCatalog::transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference, const Esri::ArcGISRuntime::Envelope &areaOfInterest)

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

The list is ordered in descending order by suitability, with the most suitable being first in the list. Note that providing an area of interest may affect the number and order of transformations returned.

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::isMissingProjectionEngineFiles 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.

Starting with version 100.9, 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.

• inputSpatialReference - The spatial reference to use as the input.
• outputSpatialReference - The spatial reference to use as the output.
• areaOfInterest - A geographic extent expressed as an Envelope. If areaOfInterest is null or Geometry::isEmpty, 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 spatial reference of areaOfInterest differs from inputSpatialReference, then areaOfInterest is reprojected to inputSpatialReference.

[static, since Esri::ArcGISRuntime 100.9] QList<Esri::ArcGISRuntime::DatumTransformation *> TransformationCatalog::transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference, const Esri::ArcGISRuntime::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
• outputSpatialReference
• areaOfInterest - The bounding box of coordinates to be transformed, or empty to consider the entire world extent.
• 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 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.

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::isMissingProjectionEngineFiles 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.

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 transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&) and transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&) methods:

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

The returned list may include grid-based transformations, whether or not these datasets can be located by the ArcGIS Maps SDK - see Esri::ArcGISRuntime::DatumTransformation::isMissingProjectionEngineFiles

This function was introduced in Esri::ArcGISRuntime 100.9.