Allows discovery and management of the transformations used to convert coordinates between different datums. More...
| Header: | #include <TransformationCatalog.h> |
| Since: | Esri::ArcGISRuntime 100.2 |
| Inherits: | Esri::ArcGISRuntime::Object |
Public Functions
| virtual | ~TransformationCatalog() override |
Static Public Members
| Esri::ArcGISRuntime::TransformationCatalog * | instance() |
| QString | projectionEngineDirectory() |
| void | setProjectionEngineDirectory(const QString &projectionEngineDirectory) |
| Esri::ArcGISRuntime::DatumTransformation * | transformation(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference) |
| Esri::ArcGISRuntime::DatumTransformation * | transformation(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference, const Esri::ArcGISRuntime::Envelope &areaOfInterest) |
| Esri::ArcGISRuntime::DatumTransformation * | transformation(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference, const Esri::ArcGISRuntime::Envelope &areaOfInterest, bool ignoreVertical) |
| QList<Esri::ArcGISRuntime::DatumTransformation *> | transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference) |
| QList<Esri::ArcGISRuntime::DatumTransformation *> | transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference, const Esri::ArcGISRuntime::Envelope &areaOfInterest) |
| QList<Esri::ArcGISRuntime::DatumTransformation *> | transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference &inputSpatialReference, const Esri::ArcGISRuntime::SpatialReference &outputSpatialReference, const Esri::ArcGISRuntime::Envelope &areaOfInterest, bool ignoreVertical) |
Detailed Description
The transformation catalog class 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 class also allows you to set the location where Projection Engine data files needed for some transformations are found on local storage. The projectionEngineDirectory property must be set at process startup. Projection Engine data files are available in the downloads area of developers.arcgis.com, under the relevant SDK, in the `Projection Engine Data` section. 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 transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&).
Relevant samples:
- List transformations by suitability: Get a list of suitable transformations for projecting a geometry between two spatial references with different horizontal datums.
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 projectionEngineDirectory to projectionEngineDirectory.
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 to transform between the input and output spatial references, without taking into account an area of interest.
- inputSpatialReference - The spatial reference to use as the input.
- outputSpatialReference - The spatial reference to use as the output.
The default transformation is the one used in cases such as calling GeometryEngine::project(const Esri::ArcGISRuntime::Geometry&, const Esri::ArcGISRuntime::SpatialReference&) without specifying a transformation.
{transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&)}, {Esri::ArcGISRuntime::TransformationCatalog::transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&, bool, QObject*)} {transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&, bool, QObject*)}
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.
- 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.
If areaOfInterest is nullptr 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 assumed.
Otherwise, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns nullptr.
If the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest is reprojected to inputSpatialReference.
{transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&, bool)}
See also Esri::ArcGISRuntime::TransformationCatalog::transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&, bool).
[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 -
trueif TransformationCatalog should ignore any vertical coordinate system set on the inputSpatialReference or outputSpatialReference, and only consider horizontal (geographic) transformations;falseotherwise.
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. If you set ignoreVertical to false, this is equivalent to calling transformation(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&).
If areaOfInterest is nullptr 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 nullptr.
If the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest is reprojected to inputSpatialReference.
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 representing the datum transformations suitable for projecting between spatial references without taking into account an area of interest.
- inputSpatialReference - The spatial reference to use as the input.
- outputSpatialReference - The spatial reference to use as the output.
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 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.
{transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&, bool)}
See also Esri::ArcGISRuntime::TransformationCatalog::transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&, bool).
[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 representing the datum transformations suitable for projecting between spatial references and takes into account the area of interest.
- 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.
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 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.
If areaOfInterest is nullptr 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 SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest is reprojected to inputSpatialReference.
{transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&, bool)}
See also Esri::ArcGISRuntime::TransformationCatalog::transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&, bool).
[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 - 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 -
trueif TransformationCatalog should ignore any vertical coordinate systems set on the inputSpatialReference or outputSpatialReference, and only consider horizontal (geographic) transformations;falseotherwise.
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. If you set ignoreVertical to false, this is equivalent to calling transformationsBySuitability(const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::SpatialReference&, const Esri::ArcGISRuntime::Envelope&).
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 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.
If areaOfInterest is nullptr or Geometry::isEmpty, the returned collection does not take into account an area of interest; instead the entire world extent is effectively assumed. Otherwise, if areaOfInterest does not intersect the area of use of inputSpatialReference, this method returns an empty list.
If the SpatialReference of areaOfInterest differs from inputSpatialReference, then areaOfInterest is reprojected to inputSpatialReference.
This function was introduced in Esri::ArcGISRuntime 100.9.