Transformation | References | ArcGIS Maps SDK for JavaScript

import Transformation from "@arcgis/core/geometry/operators/support/Transformation.js";

Since: ArcGIS Maps SDK for JavaScript 4.31

The Transformation class represents 2D transformations that can be applied to geometries using the affineTransformOperator. All transformations are applied in the spatial reference units of the input geometries.

Constructors

Constructor

Methods

Method	Signature	Class
`calculateErrors`	`calculateErrors(input: Point[], output: Point[]): ErrorResult`
`flipX`	`flipX(x0: number, x1: number): this`
`flipY`	`flipY(y0: number, y1: number): this`
`initializeFromControlPoints`	`initializeFromControlPoints(type: "conformal" \| "general", input: Point[], output: Point[], inverseOut?: Transformation): void`
`isIdentity`	`isIdentity(): boolean`
`rotate`	`rotate(angleInDegrees: number, rotationX?: number, rotationY?: number): this`
`scale`	`scale(x: number, y: number): this`
`setIdentity`	`setIdentity(): void`
`setSwapCoordinates`	`setSwapCoordinates(): this`
`shear`	`shear(proportionX: number, proportionY: number): this`
`shift`	`shift(x: number, y: number): this`

calculateErrors

Method

Signature: calculateErrors (input: Point[], output: Point[]): ErrorResult

Calculates distance errors for a transformation on a given set of the input points to the output points. This method is usually used to calculate errors for the transformation initialized by initializeFromControlPoints().

The length of the input and output arrays must be the same.

Parameters

Parameter	Type	Description	Required
input	`Point[]`	The input points to transform from.
output	`Point[]`	The output points to transform to.

Returns: ErrorResult
Returns an object representing the errors incurred during transformation.

Example

// Calculate the errors for a transformation
const errors = transformation.calculateErrors(inputPoints, outputPoints);
// Example returned object:
// { rms: 0.5, errorsOut: [0.1, 0.2, 0.3, 0.4, 0.5] }

flipX

Method

Signature: flipX (x0: number, x1: number): this

Flips all the x coordinates of geometries on the vertical y-axis (right or left) that is centered between x0 and x1. For example, if x0 is 0 and x1 is 10, all the x coordinates of the geometries will be flipped, or mirrored, on the vertical axis centered at x = 5.

FlipX transformation

Parameters

Parameter	Type	Description	Required
x0	`number`	The x-coordinate of the first geometry.
x1	`number`	The x-coordinate of the second geometry.

Returns: this

Example

// Flip the x-coordinates of a geometry on the vertical axis
const transform = new Transformation();
transform.flipX(0, 10);
const result = affineTransformOperator.execute(polygon, transform);

// Flip the x-coordinates of a geometry on the vertical axis centered at the geometry's center
const centerX = polygon.extent.center.x;
transform.flipX(centerX, centerX);
const result = affineTransformOperator.execute(polygon, transform);

flipY

Method

Signature: flipY (y0: number, y1: number): this

Flips all the y coordinates of geometries on the horizontal x-axis (up or down) that is centered between y0 and y1. For example, if y0 is 0 and y1 is 10, all the y coordinates of the geometries will be flipped, or mirrored, on the horizontal axis centered at y = 5.

FlipY transformation

Parameters

Parameter	Type	Description	Required
y0	`number`	The y-coordinate of the first geometry.
y1	`number`	The y-coordinate of the second geometry.

Returns: this

Example

// Flip the y-coordinates of a geometry on the vertical axis
transformation.flipY(0, 10);
const result = affineTransformOperator.execute(polygon, transform);

// Flip the y-coordinates of a geometry on the horizontal axis centered at the geometry's center
const centerY = polygon.extent.center.y;
transform.flipY(centerY, centerY);
const result = affineTransformOperator.execute(polygon, transform);

initializeFromControlPoints

Method

Signature: initializeFromControlPoints (type: "conformal" | "general", input: Point[], output: Point[], inverseOut?: Transformation): void

Initializes a new transformation from the input and output control points. Uses least squares method to find the best fit transformation. Adding control points allows you to snap lines and polygons to the input and output points on a map.

The length of the input and output arrays must be the same.

Parameters

Parameter Type Description Required

type

"conformal" | "general"

The type of transformation to initialize.

Value	Description
"conformal"	Preserves the angles between curves.
"general"	Preserves lines and parallelisms. Does not preserve angles or lengths.

input

Point[]

The input points to transform from.

output

Point[]

The output points to transform to.

inverseOut

Transformation

The transformation instance that is the inverse of the calculated transformation.

Returns: void

Example

// Initialize a transformation from control points
transformation.initializeFromControlPoints("conformal", inputPoints, outputPoints);

isIdentity

Method

Signature: isIdentity (): boolean

Determines if the transformation is in its default state, which is an identity matrix.

See also

setIdentity()

Returns: boolean
Returns true if the transformation is the default and has not been changed. There will be no change in the geometries when applying the transformation.

rotate

Method

Signature: rotate (angleInDegrees: number, rotationX?: number, rotationY?: number): this

Rotates the geometries by the specified angle in degrees around the point specified by the x and y coordinates. The point can be the center of the geometries or any other point.

Rotate transformation

Parameters

Parameter	Type	Description
angleInDegrees	`number`	The angle to rotate the geometries in degrees.
rotationX	`number`	The x-coordinate of the point to rotate around.
rotationY	`number`	The y-coordinate of the point to rotate around.

Returns: this

Example

// Rotate a geometry
transformation.rotate(90, 0, 0);
const result = affineTransformOperator.execute(polygon, transform);

scale

Method

Signature: scale (x: number, y: number): this

Resizes the geometries by the specified scale factors defined by the x and y coordinates. The coordinates define how much scaling is applied to the geometries in the x and y directions.

Scale transformation

Parameters

Parameter	Type	Description	Required
x	`number`	The x-coordinate that defines the horizontal scale factor.
y	`number`	The y-coordinate that defines the vertical scale factor.

Returns: this

Example

// Scale a geometry
transformation.scale(2, 2);
const result = affineTransformOperator.execute(polygon, transform);

setIdentity

Method

Signature: setIdentity (): void

Use this method to reset the transformation to its default state, which is an identity matrix. This method is useful when reusing the class instance for multiple transformations.

See also

Wikipedia - Identity Matrix

Returns: void

setSwapCoordinates

Method

Signature: setSwapCoordinates (): this

Use this method to swap the x and y coordinate values in the transformation. An example usage is when slicing vertically with the polgonSlicerOperator.findSlicesByArea() method.

Returns: this

shear

Method

Signature: shear (proportionX: number, proportionY: number): this

Shifts a geometry's points by the specified proportion in parallel to the x and y directions, except those points that are along the shear axis, which is a line defined by the x and y coordinates. This transformation preserves lines and parallelisms, however it may distort angles and distances. Applying this transformation will not change a geometry's area.

Shear transformation

Parameters

Parameter	Type	Description	Required
proportionX	`number`	The proportion to shear the geometry in the x direction.
proportionY	`number`	The proportion to shear the geometry in the y direction.

Returns: this

Example

// Shear a geometry
transformation.shear(0.5, 0.5);
const result = affineTransformOperator.execute(polygon, transform);

shift

Method

Signature: shift (x: number, y: number): this

Shifts all the coordinates of the geometries by the distance and direction between the specified x and y coordinates and their current location. This operation does not change the size or shape of the geometries.

Shift transformation

Parameters

Parameter	Type	Description	Required
x	`number`	The x-coordinate to shift by.
y	`number`	The y-coordinate to shift by.

Returns: this

Example

// Shift the coordinates of a geometry
transformation.shift(5, 2);
const result = affineTransformOperator.execute(polygon, transform);

Type definitions

ErrorResult

Type definition

Object returned from the calculateErrors() method.

rms

Property

Type: number

The root mean square (rms) of the 'average' distance error between the specified output points and the transformed input points.

errorsOut

Property

Type: number[]

Contains the errors of the individual distance differences between specific pairs of points.