ControlPointsGeoreference | API Reference | ArcGIS Maps SDK for JavaScript 4.31

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 Watch for changes topic.

Show inherited properties

Hide inherited properties

Type	Summary	Class
ControlPoint []	An array of two, three, or four controlPoints positions the media element.	ControlPointsGeoreference
String	The name of the class.	Accessor
Number	Defines the size of the element displayed, typically the element's height in pixels.	ControlPointsGeoreference
String	For ControlPointsGeoreference the type is always "control-points".	ControlPointsGeoreference
Number	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

Return Type	Summary	Class
	Adds one or more handles which are to be tied to the lifecycle of the object.	Accessor
Boolean	Returns true if a named group of handles exist.	Accessor
	Removes a group of handles owned by the object.	Accessor
Point	Converts the given sourcePoint to a mapPoint.	ControlPointsGeoreference
SourcePoint	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 }