@arcgis/core/layers/orientedImagery/transformations/worldToImage.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * Provides the utility function to convert geographic coordinates to image coordinates.
 * This function is currently utilized in the Oriented Imagery widget to extract image coordinates for the map-image location tool and for constructing the current footprint generated for the images displayed in the oriented imagery widget.
 *
 * @beta
 * @since 4.31
 * @see [OrientedImageryLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/OrientedImageryLayer/)
 * @see [OrientedImageryViewer](https://developers.arcgis.com/javascript/latest/references/core/widgets/OrientedImageryViewer/)
 * @see [Sample - Creating an OrientedImageryLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/orientedImagery/transformations/worldToImage/#creating-an-orientedimagerylayer)
 */
import type Point from "../../../geometry/Point.js";
import type { ReadonlyArrayOrCollection } from "../../../core/Collection.js";
import type { WorldToImageProperties } from "./types.js";
import type { LocationInImageSpace } from "../../../widgets/OrientedImageryViewer/types.js";

/**
 * Transforms a point or an array of points from geographic world coordinates to image space coordinates. The function supports both single points and collections of points.
 *
 * @param pointOrPoints - A single `Point` or an array or collection of points representing the geographic coordinates to be transformed.
 * @param properties - An object containing the properties required for the transformation, such as camera location (selected feature), affineTransformations, rotation matrix, focalLength, imageHeight, imageWidth, horizontalFieldOfView and verticalFieldOfView.
 * @returns A `LocationInImageSpace` which is an object with `x` and `y` properties representing the image coordinates (in rows and columns), where (0, 0) corresponds to the center of the upper left pixel. This function returns a `LocationInImageSpace` object if a single point is provided, or an array of `LocationInImageSpace` objects if a collection of points is provided.
 * @example
 * const point = new Point({
 *    x: -13045967.713,
 *    y: 4036342.97,
 *    z: 0,
 *    spatialReference: SpatialReference.WebMercator,
 * });
 *
 * const properties = {
 *    affineTransformations: [2015.5, 1, 0, 1511.5, 0, -1],
 *    cameraLocation: new Point({
 *      x: -13045995.27,
 *      y: 4036379.178,
 *      z: 1.549999952,
 *      spatialReference: SpatialReference.WebMercator,
 *      }),
 *    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 imageLocation = worldToImage(point, properties);
 *
 * console.log(imageLocation);
 */
export function worldToImage(pointOrPoints: Point | ReadonlyArrayOrCollection<Point>, properties: WorldToImageProperties): LocationInImageSpace | LocationInImageSpace[];