getTransformationsBySuitability static method

List<DatumTransformation> getTransformationsBySuitability({
  1. required SpatialReference inputSpatialReference,
  2. required SpatialReference outputSpatialReference,
  3. Envelope? areaOfInterest,
  4. bool ignoreVertical = false,
})

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

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.

If areaOfInterest is null 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.

Parameters:

  • 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.
  • ignoreVertical — True if TransformationCatalog should ignore any vertical coordinate systems set on the inputSpatialReference or outputSpatialReference, and only consider horizontal (geographic) transformations; false otherwise.

Return Value: A collection of DatumTransformation objects suitable for the given parameters, ordered by suitability, or an empty collection if no transformation is required.

Implementation

static List<DatumTransformation> getTransformationsBySuitability({
  required SpatialReference inputSpatialReference,
  required SpatialReference outputSpatialReference,
  Envelope? areaOfInterest,
  bool ignoreVertical = false,
}) {
  _initializeArcGISEnvironmentIfNeeded();
  final arrayHandle = _withThrowingErrorHandler((errorHandler) {
    return runtimecore
        .RT_TransformationCatalog_getTransformationsBySuitabilityWithAreaOfInterestAndIgnoreVertical(
      inputSpatialReference._handle,
      outputSpatialReference._handle,
      areaOfInterest?._handle ?? ffi.nullptr,
      ignoreVertical,
      errorHandler,
    );
  });
  return arrayHandle.toList();
}