Method GetTransformationsBySuitability

GetTransformationsBySuitability(SpatialReference, SpatialReference)

Gets a list representing the datum transformations suitable for projecting between spatial references without taking into account the area of interest.

Declaration

public static IReadOnlyList<DatumTransformation> GetTransformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference)

Parameters

Type	Name	Description
SpatialReference	inputSpatialReference	The SpatialReference to use as the input.
SpatialReference	outputSpatialReference	The SpatialReference to use as the output.

Returns

Type	Description
System.Collections.Generic.IReadOnlyList<DatumTransformation>	A read-only list containing DatumTransformation elements, 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 read-only list of datum transformation 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 list of HorizontalVerticalTransformation instances. If either spatial reference 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 read-only list is returned. To replicate the former behavior, use the GetTransformation(SpatialReference, SpatialReference, Envelope, Boolean) method instead with `ignoreVertical = true`.

Remarks

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 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 ProjectionEngineFilenames and ProjectionEngineFilenames to determine the dataset required for a specific transformation instance.

Applies to

Platforms and versions

Target	Versions
.NET Standard 2.0	100.3 - 200.5
.NET	100.13 - 200.5
.NET Windows	100.13 - 200.5
.NET Android	200.0 - 200.5
.NET iOS	200.0 - 200.5
.NET Framework	100.2.1 - 200.5
Xamarin.Android	100.2.1 - 100.15
Xamarin.iOS	100.2.1 - 100.15
UWP	100.2.1 - 200.5

GetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope)

Gets a list representing the datum transformations suitable for projecting between spatial references and takes into account the area of interest.

Declaration

public static IReadOnlyList<DatumTransformation> GetTransformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest)

Parameters

Type	Name	Description
SpatialReference	inputSpatialReference	The SpatialReference to use as the input.
SpatialReference	outputSpatialReference	The SpatialReference to use as the output.
Envelope	areaOfInterest	The bounding box of coordinates to be transformed, or `null` to consider the entire world extent. If `areaOfInterest` is `null` or 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 list. If the SpatialReference of `areaOfInterest` differs from `inputSpatialReference`, then `areaOfInterest` is reprojected to `inputSpatialReference`.

Returns

Type	Description
System.Collections.Generic.IReadOnlyList<DatumTransformation>	A read-only list containing DatumTransformation elements, 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 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 spatial reference 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 list is returned. To replicate the former behavior, use the GetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope, Boolean) method instead with `ignoreVertical = true`.

Remarks

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 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 ProjectionEngineFilenames and ProjectionEngineFilenames to determine the dataset required for a specific transformation instance.

Applies to

Platforms and versions

Target	Versions
.NET Standard 2.0	100.3 - 200.5
.NET	100.13 - 200.5
.NET Windows	100.13 - 200.5
.NET Android	200.0 - 200.5
.NET iOS	200.0 - 200.5
.NET Framework	100.2.1 - 200.5
Xamarin.Android	100.2.1 - 100.15
Xamarin.iOS	100.2.1 - 100.15
UWP	100.2.1 - 200.5

GetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope, Boolean)

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.

Declaration

public static IReadOnlyList<DatumTransformation> GetTransformationsBySuitability(SpatialReference inputSpatialReference, SpatialReference outputSpatialReference, Envelope areaOfInterest, bool ignoreVertical)

Parameters

Type	Name	Description
SpatialReference	inputSpatialReference	The SpatialReference to use as the input.
SpatialReference	outputSpatialReference	The SpatialReference to use as the output.
Envelope	areaOfInterest	The bounding box of coordinates to be transformed, or `null` to consider the entire world extent. If `areaOfInterest` is `null` or 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 list. If the SpatialReference of `areaOfInterest` differs from `inputSpatialReference`, then `areaOfInterest` will first be reprojected to `inputSpatialReference`.
System.Boolean	ignoreVertical	`true` if TransformationCatalog should ignore any vertical coordinate systems set on the `inputSpatialReference` or `outputSpatialReference`, and only consider horizontal (geographic) transformations; `false` otherwise.

Returns

Type	Description
System.Collections.Generic.IReadOnlyList<DatumTransformation>	A collection of DatumTransformation objects suitable for the given parameters, ordered by suitability, or an empty collection if no transformation is required.

Remarks

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 100.9.0) behavior of the GetTransformationsBySuitability(SpatialReference, SpatialReference) and GetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope) methods. Calling this method with ignoreVertical = false is equivalent to calling GetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope). Calling this method with ignoreVertical = true is equivalent to GetTransformationsBySuitability(SpatialReference, SpatialReference, Envelope) in releases prior to 100.9.0.

Applies to

Platforms and versions

Target	Versions
.NET Standard 2.0	100.10 - 200.5
.NET	100.13 - 200.5
.NET Windows	100.13 - 200.5
.NET Android	200.0 - 200.5
.NET iOS	200.0 - 200.5
.NET Framework	100.10 - 200.5
Xamarin.Android	100.10 - 100.15
Xamarin.iOS	100.10 - 100.15
UWP	100.10 - 200.5