ControlPointsGeoreference

AMD: require(["esri/layers/support/ControlPointsGeoreference"], (ControlPointsGeoreference) => { /* code goes here */ });
ESM: import ControlPointsGeoreference from "@arcgis/core/layers/support/ControlPointsGeoreference.js";
Class: esri/layers/support/ControlPointsGeoreference
Inheritance: ControlPointsGeoreferenceAccessor
Since: ArcGIS Maps SDK for JavaScript 4.25

ControlPointsGeoreference is used to set the geographic location of the ImageElement or VideoElement referenced in the MediaLayer using the controlPoints, width, and height parameters. The element is positioned, scaled, and rotated with two controlPoints. Additionally, it will be skewed with three controlPoints. With four controlPoints, a perspective transformation is applied to the element.

// the spatial reference for the MediaLayer, North American Datum 1927
const spatialReference = new SpatialReference({ wkid: 4267 });

// create an array of four control points composed of a sourcePoint, a point
// on the image element in pixels, and a mapPoint which is the location of the
// sourcePoint in map space
const swCorner = {
    sourcePoint: { x: 80, y: 1732 },
    mapPoint: new Point({ x: -107.875, y: 37.875, spatialReference })
};

const nwCorner = {
    sourcePoint: { x: 75, y: 102 },
    mapPoint: new Point({ x: -107.875, y: 38, spatialReference })
};

const neCorner = {
   sourcePoint: { x: 1353, y: 99 },
   mapPoint: new Point({ x: -107.75, y: 38, spatialReference })
};

const seCorner = {
   sourcePoint: { x: 1361, y: 1721 },
   mapPoint: new Point({ x: -107.75, y: 37.875, spatialReference })
};

const controlPoints = [swCorner, nwCorner, neCorner, seCorner];

// georeference for the imageElement using the control points,
// image width, and image height
const georeference = new ControlPointsGeoreference({ controlPoints, width: 1991, height: 2500 });

const imageElement = new ImageElement({
    image: "https://jsapi.maps.arcgis.com/sharing/rest/content/items/1a3df04e7d734535a3a6a09dfec5a6b2/data",
    georeference
});

// create a MediaLayer using the georeferenced ImageElement
const mediaLayer = new MediaLayer({
    source: [imageElement],
    title: "Geologic Map of the Telluride Quadrangle, Southwestern Colorado",
    copyright: "Wilbur S Burbank and Robert G. Luedke, 1966",
    opacity: 0.5,
    spatialReference
});

Known Limitations

  • ControlPointsGeoreference is not currently supported in 3D SceneViews.
See also

Constructors

ControlPointsGeoreference

Constructor
new ControlPointsGeoreference(properties)
Parameter
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class

An array of two, three, or four controlPoints positions the media element.

ControlPointsGeoreference

The name of the class.

Accessor

Defines the size of the element displayed, typically the element's height in pixels.

ControlPointsGeoreference
For ControlPointsGeoreference the type is always "control-points". ControlPointsGeoreference

Defines the size of the element displayed, typically the element's width in pixels.

ControlPointsGeoreference

Property Details

controlPoints

Property
controlPoints ControlPoint[]

An array of two, three, or four controlPoints positions the media element. The element is positioned, scaled, and rotated with two controlPoints. Additionally, it will be skewed with three controlPoints. With four controlPoints, a perspective transformation is applied to the element.

Default Value:null
Example
const swCorner = {
    sourcePoint: { x: 80, y: 1732 },
    mapPoint: new Point({ x: -107.875, y: 37.875, spatialReference })
};

const neCorner = {
   sourcePoint: { x: 1353, y: 99 },
   mapPoint: new Point({ x: -107.75, y: 38, spatialReference })
};

const controlPoints = [swCorner, neCorner];

declaredClass

Inherited
Property
declaredClass Stringreadonly
Inherited from Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

height

Property
height Number

Defines the size of the element displayed, typically the element's height in pixels. This property is used alongside controlPoints and width to position the element.

Default Value:0

type

Property
type String

For ControlPointsGeoreference the type is always "control-points".

width

Property
width Number

Defines the size of the element displayed, typically the element's width in pixels. This property is used alongside controlPoints and height to position the element.

Default Value:0

Method Overview

Show inherited methods Hide inherited methods
Name Return Type Summary Class

Adds one or more handles which are to be tied to the lifecycle of the object.

Accessor

Returns true if a named group of handles exist.

Accessor

Removes a group of handles owned by the object.

Accessor

Converts the given sourcePoint to a mapPoint.

ControlPointsGeoreference

Converts the given mapPoint to a sourcePoint.

ControlPointsGeoreference

Method Details

addHandles

Inherited
Method
addHandles(handleOrHandles, groupKey)
Inherited from Accessor

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();
Parameters
handleOrHandles WatchHandle|WatchHandle[]

Handles marked for removal once the object is destroyed.

groupKey *
optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

hasHandles

Inherited
Method
hasHandles(groupKey){Boolean}
Inherited from Accessor

Returns true if a named group of handles exist.

Parameter
groupKey *
optional

A group key.

Returns
Type Description
Boolean Returns true if a named group of handles exist.
Example
// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

removeHandles

Inherited
Method
removeHandles(groupKey)
Inherited from Accessor

Removes a group of handles owned by the object.

Parameter
groupKey *
optional

A group key or an array or collection of group keys to remove.

Example
obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

toMap

Method
toMap(sourcePoint){Point}

Converts the given sourcePoint to a mapPoint. The sourcePoint represents a point in terms of pixels relative to the top-left corner of the element.

Parameter
sourcePoint SourcePoint

The location on the element.

Returns
Type Description
Point The mapPoint corresponding to the given sourcePoint, in the spatial reference found in the mapPoint of the first control point.
Example
const mapPoint = controlPointGeoreference.toMap({x: 100, y: 250})

toSource

Method
toSource(point){SourcePoint}

Converts the given mapPoint to a sourcePoint. The sourcePoint represents a point in terms of pixels relative to the top-left corner of the element.

Parameter
point Point

A point geometry. In the case where the point is not in the same spatial reference as the one in the mapPoint of the first control point, it will be reprojected. Projection engine would need to be loaded to perform the reprojection, otherwise null is returned.

Returns
Type Description
SourcePoint The location on the element corresponding to the given mapPoint.
Example
// North_American_Datum_1927
const spatialReference = new SpatialReference({ wkid: 4267 });
const sourcePoint = controlPointGeoreference.toSource(new Point({ x: -107.875, y: 37.875, spatialReference }))

Type Definitions

ControlPoint

Type Definition
ControlPoint Object

A control point object in the controlPoints array. A control point is composed of a sourcePoint representing a point on the element and of a mapPoint to map the location of the sourcePoint in the map space.

Properties
sourcePoint SourcePoint|null|undefined
optional

The coordinate of the control point in the image coordinate space.

mapPoint Point|null|undefined
optional

The coordinate of the the control point in the map coordinate space.

Example
const controlPoint = {
  sourcePoint: { x: 0, y: 0 },
  mapPoint: new Point({ x: -180, y: 85 })
};

SourcePoint

Type Definition
SourcePoint

An object representing a point on the element. The origin (0, 0) corresponds to the top-left corner of the element.

Properties
x Number

The x coordinate.

y Number

The y coordinate.

Example
const sourcePoint = { x: 80, y: 1732 }

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.