ArcGIS Runtime SDK for iOS: AGSTransformationCatalog Class Reference
ArcGIS Runtime SDK for iOS  100.15
List of all members | Class Methods
AGSTransformationCatalog Class Reference

Description

Allows discovery and management of the transformations used to convert coordinates between different datums.

The transformation catalog class provides a mechanism for discovering available AGSDatumTransformation objects. You can retrieve the default transformation used internally by the ArcGIS Runtime 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 (AGSTransformationCatalog) property must be set before using any geometry classes.

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 transformationForInputSpatialReference:outputSpatialReference:areaOfInterest: (AGSTransformationCatalog).

Since
100.2
Inheritance diagram for AGSTransformationCatalog:
AGSObject

Class Methods

(nullable NSURL *) + projectionEngineDirectory
 
(BOOL) + setProjectionEngineDirectory:error:
 
(nullable AGSDatumTransformation *) + transformationForInputSpatialReference:outputSpatialReference:
 
(nullable AGSDatumTransformation *) + transformationForInputSpatialReference:outputSpatialReference:areaOfInterest:
 
(nullable AGSDatumTransformation *) + transformationForInputSpatialReference:outputSpatialReference:areaOfInterest:ignoreVertical:
 
(NSArray< AGSDatumTransformation * > *) + transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:
 
(NSArray< AGSDatumTransformation * > *) + transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:areaOfInterest:
 
(NSArray< AGSDatumTransformation * > *) + transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:areaOfInterest:ignoreVertical:
 

Method Documentation

◆ projectionEngineDirectory

+ (nullable NSURL *) projectionEngineDirectory

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

Since
100.2

◆ setProjectionEngineDirectory:error:

+ (BOOL) setProjectionEngineDirectory: (nullable NSURL *)  directory
error: (NSError **)  error 

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

Note
This method should be called immediately upon application startup before any other API method calls.
Since
100.2

◆ transformationForInputSpatialReference:outputSpatialReference:

+ (nullable AGSDatumTransformation *) transformationForInputSpatialReference: (AGSSpatialReference *)  inputSpatialReference
outputSpatialReference: (AGSSpatialReference *)  outputSpatialReference 

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

The default transformation is the one used in cases such as calling projectGeometry:toSpatialReference: (AGSGeometryEngine) without specifying a transformation.

Parameters
inputSpatialReferenceThe spatial reference to use as the input.
outputSpatialReferenceThe spatial reference to use as the output.
Returns
An AGSDatumTransformation instance that represents the best choice given the parameters. Always returns a usable transformation where AGSDatumTransformation::missingProjectionEngineFiles is NO. Returns nil if no usable transformation is available for the given input parameters, or if no transformation is required. Prior to version 100.9, this method returned an AGSGeographicTransformation. From version 100.9 onwards, if both AGSTransformationCatalog::inputSpatialReference and AGSTransformationCatalog::outputSpatialReference have a vertical coordinate system, this method returns an AGSHorizontalVerticalTransformation instance. If either AGSSpatialReference does not have a vertical coordinate system, an AGSGeographicTransformation is returned. To replicate the former behavior, use the transformationForInputSpatialReference:outputSpatialReference:areaOfInterest:ignoreVertical: method, passing in YES for ignoreVertical.
See also
+ transformationForInputSpatialReference:outputSpatialReference:areaOfInterest:
Since
100.2

◆ transformationForInputSpatialReference:outputSpatialReference:areaOfInterest:

+ (nullable AGSDatumTransformation *) transformationForInputSpatialReference: (AGSSpatialReference *)  inputSpatialReference
outputSpatialReference: (AGSSpatialReference *)  outputSpatialReference
areaOfInterest: (nullable AGSEnvelope *)  areaOfInterest 

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

Parameters
inputSpatialReferenceThe spatial reference to use as the input.
outputSpatialReferenceThe spatial reference to use as the output.
areaOfInterestThe bounding box of coordinates to be transformed, or nil to consider the entire world extent.
Returns
An AGSDatumTransformation instance that represents the best choice given the parameters. Always returns a usable transformation where AGSDatumTransformation::missingProjectionEngineFiles is NO. Returns nil if no usable transformation is available for the given input parameters, or if no transformation is required. Prior to version 100.9, this method returned an AGSGeographicTransformation. From version 100.9 onwards, if both AGSTransformationCatalog::inputSpatialReference and AGSTransformationCatalog::outputSpatialReference have a vertical coordinate system, this method returns an AGSHorizontalVerticalTransformation instance. If either AGSSpatialReference does not have a vertical coordinate system, an AGSGeographicTransformation is returned. To replicate the former behavior, use the transformationForInputSpatialReference:outputSpatialReference:areaOfInterest:ignoreVertical: method, passing in YES for ignoreVertical.
Since
100.2

◆ transformationForInputSpatialReference:outputSpatialReference:areaOfInterest:ignoreVertical:

+ (nullable AGSDatumTransformation *) transformationForInputSpatialReference: (AGSSpatialReference *)  inputSpatialReference
outputSpatialReference: (AGSSpatialReference *)  outputSpatialReference
areaOfInterest: (nullable AGSEnvelope *)  areaOfInterest
ignoreVertical: (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.

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 100.9.0) behavior of the transformationForInputSpatialReference:outputSpatialReference: and transformationForInputSpatialReference:outputSpatialReference:areaOfInterest: methods:

  • Calling this method, passing in NO for ignoreVertical is equivalent to calling transformationForInputSpatialReference:outputSpatialReference:areaOfInterest:
  • Calling this method, passing in YES for ignoreVertical is equivalent to calling transformationForInputSpatialReference:outputSpatialReference:areaOfInterest: in releases prior to 100.9.0
    Parameters
    inputSpatialReferenceThe spatial reference to use as the input.
    outputSpatialReferenceThe spatial reference to use as the output.
    areaOfInterestThe bounding box of coordinates to be transformed, or nil to consider the entire world extent.
    ignoreVerticalYES if AGSTransformationCatalog should ignore any vertical coordinate system set on the AGSTransformationCatalog::inputSpatialReference or AGSTransformationCatalog::outputSpatialReference, and only consider horizontal (geographic) transformations; NO otherwise.
    Returns
    An AGSDatumTransformation instance that represents the best choice given the parameters. Always returns a usable transformation where AGSDatumTransformation::missingProjectionEngineFiles is NO. The specific type returned depends on the given value of the ignoreVertical parameter. Returns nil if no transformation is required for the given input parameters, or if no usable transformation is available.
    Since
    100.9

◆ transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:

+ (NSArray<AGSDatumTransformation*> *) transformationsBySuitabilityWithInputSpatialReference: (AGSSpatialReference *)  inputSpatialReference
outputSpatialReference: (AGSSpatialReference *)  outputSpatialReference 

Returns a list representing the datum transformations suitable 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, and ArcGIS Runtime must be able to locate these datasets. If the datasets cannot be located, the transformation is not currently usable, and AGSDatumTransformation::missingProjectionEngineFiles is YES. 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 AGSGeographicTransformationStep::projectionEngineFilenames and AGSHorizontalVerticalTransformationStep::projectionEngineFilenames to determine the dataset required for a specific transformation instance.

Parameters
inputSpatialReferenceThe spatial reference to use as the input.
outputSpatialReferenceThe spatial reference to use as the output.
Returns
An NSArray containing AGSDatumTransformation objects, each suitable for transforming between the given input and output spatial references. Prior to version 100.9, this method only considered geographic coordinate systems, and the returned array of AGSDatumTransformation objects were of the subtype AGSGeographicTransformation. 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 AGSTransformationCatalog::inputSpatialReference and AGSTransformationCatalog::outputSpatialReference have a vertical coordinate system, this method returns an AGSHorizontalVerticalTransformation instance. If either AGSSpatialReference does not have a vertical coordinate system, an AGSGeographicTransformation 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 transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:areaOfInterest:ignoreVertical: method, passing in YES for ignoreVertical.
Since
100.2

◆ transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:areaOfInterest:

+ (NSArray<AGSDatumTransformation*> *) transformationsBySuitabilityWithInputSpatialReference: (AGSSpatialReference *)  inputSpatialReference
outputSpatialReference: (AGSSpatialReference *)  outputSpatialReference
areaOfInterest: (nullable AGSEnvelope *)  areaOfInterest 

Returns a list representing the datum transformations suitable 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. 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, and ArcGIS Runtime must be able to locate these datasets. If the datasets cannot be located, the transformation is not currently usable, and AGSDatumTransformation::missingProjectionEngineFiles is YES. 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 AGSGeographicTransformationStep::projectionEngineFilenames and AGSHorizontalVerticalTransformationStep::projectionEngineFilenames to determine the dataset required for a specific transformation instance.

Parameters
inputSpatialReferenceThe spatial reference to use as the input.
outputSpatialReferenceThe spatial reference to use as the output.
areaOfInterestThe bounding box of coordinates to be transformed, or nil to consider the entire world extent.
Returns
An NSArray containing AGSDatumTransformation objects, each suitable for transforming between the given input and output spatial references, taking in to account the given area of interest. Prior to version 100.9, this method only considered geographic coordinate systems, and the returned array of AGSDatumTransformation objects were of the subtype AGSGeographicTransformation. 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 AGSTransformationCatalog::inputSpatialReference and AGSTransformationCatalog::outputSpatialReference have a vertical coordinate system, this method returns an AGSHorizontalVerticalTransformation instance. If either SpatialReference does not have a vertical coordinate system, an AGSGeographicTransformation 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 transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:areaOfInterest:ignoreVertical: method instead, passing in YES for ignoreVertical.
Since
100.2

◆ transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:areaOfInterest:ignoreVertical:

+ (NSArray<AGSDatumTransformation *> *) transformationsBySuitabilityWithInputSpatialReference: (AGSSpatialReference *)  inputSpatialReference
outputSpatialReference: (AGSSpatialReference *)  outputSpatialReference
areaOfInterest: (nullable AGSEnvelope *)  areaOfInterest
ignoreVertical: (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.

The array 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 100.9.0) behavior of the transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference: and transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:areaOfInterest: methods: Calling this method, passing in NO for ignoreVertical is equivalent to calling transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:areaOfInterest:. Calling this method, passing in YES for ignoreVertical is equivalent to calling transformationsBySuitabilityWithInputSpatialReference:outputSpatialReference:areaOfInterest: in releases prior to 100.9.0.

Some transformations require a supporting Projection Engine (PE) dataset to function correctly, and ArcGIS Runtime must be able to locate these datasets. If the datasets cannot be located, the transformation is not currently usable, and AGSDatumTransformation::missingProjectionEngineFiles is YES. 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 AGSGeographicTransformationStep::projectionEngineFilenames and AGSHorizontalVerticalTransformationStep::projectionEngineFilenames to determine the dataset required for a specific transformation instance.

Parameters
inputSpatialReferenceThe spatial reference to use as the input.
outputSpatialReferenceThe spatial reference to use as the output.
areaOfInterestThe bounding box of coordinates to be transformed, or nil to consider the entire world extent.
ignoreVerticalYES if AGSTransformationCatalog should ignore any vertical coordinate systems set on the AGSTransformationCatalog::inputSpatialReference or AGSTransformationCatalog::outputSpatialReference, and only consider horizontal (geographic) transformations; NO otherwise.
Returns
An array of AGSDatumTransformation objects suitable for the given parameters, ordered by suitability, or an empty array if no transformation is required.
Since
100.9