imageToWorld

AMD: require(["esri/layers/orientedImagery/transformations/imageToWorld"], (imageToWorld) => { /* code goes here */ });
ESM: import * as imageToWorld from "@arcgis/core/layers/orientedImagery/transformations/imageToWorld.js";
Object: esri/layers/orientedImagery/transformations/imageToWorld
Since: ArcGIS Maps SDK for JavaScript 4.31
beta

Provides the utility function to convert image coordinates to geographic coordinates. This function is currently utilized in the Oriented Imagery widget to extract geographic world locations in the map-image location tool and for constructing the current footprint generated for the images displayed in the oriented imagery widget.

Method Overview

Name Return Type Summary Object
Promise<(Point|Point[])>

Transforms image coordinates in pixels to a point or an array of points specifying the corresponding geographic world coordinates.

imageToWorld

Method Details

imageToWorld

Method
imageToWorld(pixelOrPixels, properties, updateElevationProps){Promise<(Point|Point[])>}

Transforms image coordinates in pixels to a point or an array of points specifying the corresponding geographic world coordinates. The function supports both single points and collections of points.

Parameters

A single Pixel object or an ArrayOrCollection<Pixel> representing the image coordinates in x and y (in rows and columns) to be transformed. Here (0, 0) corresponds to the center of the upper left pixel.

An object containing the properties required for the transformation, such as camera location, rotation matrix, and image dimensions.

updateElevationProps UpdateElevationProps

An object containing the properties required for correcting the elevation of the output point, resulting in a more accurate z-value. This is an optional parameter.

Returns
Type Description
Promise<(Point|Point[])> A Point object if a single pixel is provided, or an array of Point objects if a collection of pixels is provided.
Example
const pixel = {
   x: 2601.062988,
   y: 1297.00708,
   };

const properties: {
   affineTransformations: [2015.5, 1, 0, 1511.5, 0, -1],
   averageElevation: 0,
   cameraLocation: new Point({
     x: -13045995.27,
     y: 4036379.178,
     z: 1.549999952,
     spatialReference: SpatialReference.WebMercator,
   }),
   cameraPitch: 90,
   cameraRoll: 0,
   farDistance: 30,
   horizontalFieldOfView: 65.47045135,
   imageHeight: 3024,
   imageWidth: 4032,
   rotationMatrix: [
     -0.6710996455056446, 4.539564596921633e-17, -0.7413671599161904,
     -0.7413671599161904, -4.1093001638870556e-17, 0.6710996455056446,
      0, 1, 6.123233995736766e-17
    ],
   verticalFieldOfView: 46.39718246,
},

const gorundLocation = imageToWorld(pixel, properties);
console.log(imageLocation);

Type Definitions

ImageToWorldProperties

Type Definition
ImageToWorldProperties

Represents the properties required for transforming image coordinates to world coordinates. For more information on the properties, please refer to the Oriented Imagery table.

Properties
averageElevation Number

The height of the ground at the camera’s location (specified by cameraLocation), determined by subtracting the camera’s height from the absolute z-coordinate of the location. This value can be adjusted as needed. The elevation value should have the same units as that of the cameraLocation's patial reference system (SRS).

cameraPitch Number

The camera orientation of the second rotation around the x-axis of the camera. The value is in degrees. The direction of measurement for heading is in positive counterclockwise direction. The CameraPitch is zero degrees when the camera is facing straight down to the ground. The valid range of CameraPitch values is from 0 through 180 degrees. CameraPitch is 180 degrees for a camera facing straight up, and 90 degrees for a camera facing horizontally.

cameraRoll Number

The camera orientation of the final rotation around the z-axis of the camera in the positive clockwise direction. The value is in degrees. Valid values range from -90 to 90.

farDistance Number

The farthest usable distance of the imagery from the camera position. This value determines the far plane of the visible frustum. The intersection of the frustum far plane with the ground defines the footprint, which is used to determine whether an image is returned when you click the map. The unit is meters. Values must be greater than zero.

affineTransformations Number[]

A fixed length array of 6 numbers corresponding to the camera affine values A0, A1, A2, B0, B1, B2. The coefficient of the affine transformation establishes a relationship between the sensor space and image space. The direction is from ground to image. A0, A1, and A2 represent the translation in x direction, while B0, B1, and B2 represent the translation in y direction. Please refer to the Oriented Imagery table for more information on the afffine values.

cameraLocation Point

A Point representing the camera location in world coordinates where the image was captured.

focalLength Number

The focal length of the camera lens. The unit can be microns, millimeters, or pixels. This parameter is used if ImageWidth and ImageHeight are not provided.

principalOffsetPoint Number[]
optional

A fixed length array of 2 numbers specifying the x-coordinate and y-coordinate of the principal point of the autocollimation. The units must be the same as the unit used for FocalLength. The default value is [0,0]. This is an optional parameter.

radialDistortionCoefficients Number[]
optional

The radial distortion is specified as an array of three numbers, indicating [K1,K2,K3] coefficient values. The coupling unit is the same as the unit specified for FocalLength. The default value is [0,0,0]. This is an optional parameter.

rotationMatrix Number[]

The row-wise sorted rotation matrix that defines the transformation from image space to map space, specified as an array of nine floating-point values.

tangentialDistortionCoefficients Number[]
optional

The tangential distortion is specified as an array of three numbers, indicating [P1,P2] coefficient values. The coupling unit is the same as the unit used for FocalLength. The default value is [0,0]. This is an optional parameter.

horizontalFieldOfView Number

The camera’s field-of-view in a horizontal direction. The unit is degrees. The valid values range from 0 through 360.

verticalFieldOfView Number

The camera’s field-of-view in the vertical direction. The unit is degrees. The valid values range from 0 through 180.

imageHeight Number

Height of the image used for world to image transformation, in pixels. This parameter is used if the focal length is not provided.

imageWidth Number

image used for world to image transformation, in pixels. This parameter is used if the focal length is not provided.

PixelLocation

Type Definition
PixelLocation

Represents the pixel location in image space, where (0, 0) corresponds to the center of the upper left pixel.

Properties
x Number

The row the pixel location.

y Number

The column the pixel location.

UpdateElevationProps

Type Definition
UpdateElevationProps

Represents the properties required for updating the elevation of the output point. Users can either provide values from an elevationSampler or constantElevation.

Properties
elevationSampler ElevationSampler

A cache of elevation values created from an elevation service used for synchronously querying elevation information for geometries. For more information on creating an elevation sampler, please refer ElevationSampler. The elevation value should have the same units as that of the cameraLocation's spatial reference system (SRS).

constantElevation Number

The constant ground elevation value. The elevation value should have the same units as that of the cameraLocation's spatial reference system (SRS).

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