Find Transformations

Description

The findTransformations operation is performed on a geometry service resource. This operation returns a list of applicable geographic transformations you should use when projecting geometries from the input spatial reference to the output spatial reference. The transformations are in JSON format and are returned in order of most applicable to least applicable. Recall that a geographic transformation is not needed when the input and output spatial references have the same underlying geographic coordinate systems. In this case, findTransformations returns an empty list.

Every returned geographic transformation is a forward transformation, meaning that it can be used as-is to project from the input spatial reference to the output spatial reference. In the case where a predefined transformation needs to be applied in the reverse direction, it is returned as a forward composite transformation containing one transformation and a transformForward element with a value of false. See the examples given below.

You can provide arguments to the findTransformations operation as query
parameters defined in the following parameters table:

Description: (Optional) The bounding box of the area of interest specified as a JSON envelope. If provided, the extent of interest is used to return the most applicable geographic transformations for the area. If a spatial reference is not included in the JSON envelope, the inSR is used for the envelope.

numOfResults

Description: (Optional) The number of geographic transformations to return. The default value is 1. If numOfResults has a value of -1, all applicable transformations are returned.

vertical

Note:

This option was added at 10.5.

Description: (Optional) Specifies whether or not to check for vertical transformations. The default value is false. If vertical is set to true, both inSR and outSR must have a vertical coordinate system. A list of hvtransforms will be returned in this case.

Values: true | false

Example usage

Example 1

This example finds the top three transformations that should be used when projecting data from GCS_North_American_1927 (wkid = 4267) to GCS_WGS_1984 (wkid = 4326).

The first two transformations are forward single transformations. The third transformation is a forward composite transformation. It will first apply the transformation 108001 in the forward direction from NAD 27 to NAD 83, and then it will apply 108190 in the reverse direction from NAD 83 to WGS 84. Note that although the second transformation in the composite transformation is applied in the reverse direction, the entire composite transformation is a forward transformation. You could copy and paste the composite transformation, or any transformation returned by findTransformations, into the project operation as-is without having to change the default direction, which is forward.

Example 2

This example performs the reverse of the operation performed in Example 1. This example projects data from GCS_WGS_1984 (wkid = 4326) to GCS_North_American_1927 (wkid = 4267) and retrieves the top three transformations.

Notice that the first two transformations are composite transformations containing a single transformation with the transformForward element set to false. The reason for this is that findTransformations always returns forward transformations. The transformation with wkid = 15851 is the best transformation for this situation, but if you use it directly, it must be used in the reverse direction. The composite transformation with one transformation is a forward transformation.

Example 3

This example shows how to find the top two transformations for projecting data from North_America_Equidistant_Conic, a projected coordinate system with NAD 83 as its underlying geographic coordinate system, to World_Mercator, a projected coordinate system with WGS 84 as its underlying geographic coordinate system.

Example 4

This example shows how to find the top horizontal/vertical transformation when projecting data from GCS_ETRS_1989 (WKID = 4258) and vertical coordinate system ETRS_1989 (WKID = 115701) to GCS_North_American_1983 (WKID = 4269) and vertical coordinate system NAD_1983 (WKID = 115702). Notice that since Vertical is set to true, the result is an array of hvTransforms rather than a geoTransforms.