math module

Reference

Package:: azure-maps-control

Classes

An Affine Transform class generated from a set of reference points.

Enums

AccelerationUnits	Units of measurement for acceleration.
AreaUnits	Units of measurement for areas.
DistanceUnits	Units of measurement for distances.
SpeedUnits	Units of measurement for speed.
TimeUnits	Units of measurement for time.

Functions

boundingBoxToPolygon(BoundingBox)	Takes a BoundingBox and converts it to a polygon.
convertAcceleration(number, string \| AccelerationUnits, string \| AccelerationUnits, number)	Converts an acceleration value from one unit to another. Supported units: milesPerSecondSquared, kilometersPerSecondSquared, metersPerSecondSquared, feetPerSecondSquared yardsPerSecondSquared, kilometersPerHoursSecond, milesPerHourSecond, knotsPerSecond, standardGravity
convertArea(number, string, string, number)	Converts an area value from one unit to another. Supported units: squareMeters, acres, hectares, squareFeet, squareYards, squareMiles, squareKilometers
convertDistance(number, string \| DistanceUnits, string \| DistanceUnits, number)	Converts a distance from one distance units to another. Supported units: miles, nauticalMiles, yards, meters, kilometers, feet
convertSpeed(number, string \| SpeedUnits, string \| SpeedUnits, number)	Converts a speed value from one unit to another. Supported units: kilometersPerHour, milesPerHour, metersPerSecond, feetPerSecond, knots, mach
convertTimespan(number, string \| TimeUnits, string \| TimeUnits, number)	Converts a timespan value from one unit to another. Supported units: ms (milliseconds), hours, minutes, seconds
getAcceleration(number, number, number, string \| SpeedUnits, string \| DistanceUnits, string \| TimeUnits, string \| AccelerationUnits, number)	Calculates an acceleration based on an initial speed, travel distance and timespan. Formula: a = 2(d - vt)/t^2
getAccelerationFromFeatures(Feature<Point, any>, Feature<Point, any>, string, string, string \| SpeedUnits, string \| AccelerationUnits, number)	Calculates an acceleration between two point features that have a timestamp property and optionally a speed property. if speeds are provided, ignore distance between points as the path may not have been straight and calculate: a = (v2 - v1)/(t2 - t1) if speeds not provided or only provided on first point, calculate straight line distance between points and calculate: a = 2(d - vt)/t^2
getAccelerationFromSpeeds(number, number, number, string \| SpeedUnits, string \| TimeUnits, string \| AccelerationUnits, number)	Calculates an acceleration based on an initial speed, final speed and timespan. Formula: a = 2* (v2 - v1)/t
getArea(atlas.data.Geometry \| Feature<atlas.data.Geometry, any> \| Shape, AreaUnits, number)	Calculates the approximate area of a geometry in the specified units
getCardinalSpline(Position[], number, number, boolean)	Calculates an array of positions that form a cardinal spline between the specified array of positions.
getClosestPointOnGeometry(Position \| Point \| Feature<Point, any> \| Shape, atlas.data.Geometry \| Feature<atlas.data.Geometry, any> \| Shape, string \| DistanceUnits, number)	Calculates the closest point on the edge of a geometry to a specified point or position. The returned point feature will have a `distance` property that specifies the distance between the two points in the specified units. If the geometry is a Point, that points position will be used for the result. If the geometry is a MultiPoint, the distances to the individual positions will be used. If the geometry is a Polygon or MultiPolygon, the point closest to any edge will be returned regardless of if the point intersects the geometry or not.
getConvexHull(Position[] \| atlas.data.Geometry \| Feature<atlas.data.Geometry, any> \| FeatureCollection \| GeometryCollection \| atlas.data.Geometry[] \| Array<Feature<atlas.data.Geometry, any> \| Shape> \| Shape)	Calculates a Convex Hull from an array of positions, geometries or features.
getDestination(Position \| Point, number, number, string \| DistanceUnits)	Calculates a destination position based on a starting position, a heading, a distance, and a distance unit type.
getDistanceTo(Position \| Point, Position \| Point, string \| DistanceUnits)	Calculate the distance between two position objects on the surface of the earth using the Haversine formula.
getEarthRadius(string \| DistanceUnits)	Retrieves the radius of the earth in a specific distance unit for WGS84.
getGeodesicPath(LineString \| Position[], number)	Takes an array of positions objects and fills in the space between them with accurately positioned positions to form an approximated Geodesic path.
getGeodesicPaths(LineString \| Position[], number)	Takes an array of positions objects and fills in the space between them with accurately positioned positions to form an approximated Geodesic path broken by antimeridian into multiple sub-paths.
getHeading(Position \| Point, Position \| Point)	Calculates the heading from one position object to another.
getLengthOfPath(LineString \| Position[], string \| DistanceUnits)	Calculates the distance between all position objects in an array.
getPathDenormalizedAtAntimerian(LineString \| Position[])	Denormalizes path on antimeridian, this makes lines with coordinates on the opposite side of the antimeridian to always cross it. Note that the path crossing antimeridian will contain longitude outside of -180 to 180 range. See getPathSplitByAntimeridian when this is not desired.
getPathSplitByAntimeridian(LineString \| Position[])	Split path on antimeridian into multiple paths. See getPathDenormalizedAtAntimerian when this is not desired.
getPixelHeading(Position \| Point, Position \| Point)	Calculates the pixel accurate heading from one position to another based on the Mercator map projection. This heading is visually accurate.
getPointsWithHeadingsAlongPath(LineString \| Position[], number)	Gets an array of evenly spaced points with headings along a path.
getPointWithHeadingAlongPath(LineString \| Position[], number, string \| DistanceUnits)	Gets a point with heading a specified distance along a path.
getPosition(Position \| Point \| Feature<Point, any> \| Shape)	Gets the position of an object that is a position, point, point feature, or circle. If it is a circle, its center coordinate will be returned.
getPositionAlongPath(LineString \| Position[], number, string \| DistanceUnits)	Calculates the position object on a path that is a specified distance away from the start of the path. If the specified distance is longer than the length of the path, the last position of the path will be returned.
getPositions(Position[] \| atlas.data.Geometry \| Feature<atlas.data.Geometry, any> \| FeatureCollection \| GeometryCollection \| atlas.data.Geometry[] \| Array<Feature<atlas.data.Geometry, any> \| Shape> \| Shape)	Retrieves an array of all positions in the provided geometry, feature or array of geometries/features.
getPositionsAlongPath(LineString \| Position[], number)	Gets an array of evenly spaced positions along a path.
getRegularPolygonPath(Position \| Point, number, number, string \| DistanceUnits, number)	Calculates an array of position objects that are an equal distance away from a central point to create a regular polygon.
getRegularPolygonPaths(Position \| Point, number, number, string \| DistanceUnits, number)	Calculates an array of position objects that are an equal distance away from a central point to create a regular polygon broken by antimeridian into multiple sub-paths.
getSpeed(Position \| Point \| Feature<Point, any>, Position \| Point \| Feature<Point, any>, number, string \| TimeUnits, string \| SpeedUnits, number)	Calculates the average speed of travel between two points based on the provided amount of time.
getSpeedFromFeatures(Feature<Point, any>, Feature<Point, any>, string, string \| SpeedUnits, number)	Calculates the average speed of travel between two point features that have a property containing a timestamp. The timestamp can be; A JavaScript Date object A number which represents the number of milliseconds since Jan 1st, 1970. A string which uses one of the following formats: ISO8601 date format (i.e. 2012-04-23T18:25:43.511Z) RFC282 / IETF date syntax (section 3.3) OData Date string (i.e. "/Date(1235764800000)/")
getTimespan(Date \| string \| number, Date \| string \| number, TimeUnits, number)	Calculates the timespan between two dates or timestamps. Timestamps can be; A JavaScript Date object A number which represents the number of milliseconds since Jan 1st, 1970. A string which uses one of the following formats: ISO8601 date format (i.e. 2012-04-23T18:25:43.511Z) RFC282 / IETF date syntax (section 3.3) OData Date string (i.e. "/Date(1235764800000)/")
getTravelDistance(string, number, number, number, string \| TimeUnits, string \| SpeedUnits, string, number)	Calculates the distance traveled for a specified timespan, speed and optionally an acceleration. Formula: d = vt + 0.5a*t^2
interpolate(Position \| Point, Position \| Point, number)	Calculates a position object that is a fractional distance between two position objects.
mercatorPixelsToPositions(Pixel[], number)	Converts an array of global Mercator pixel coordinates into an array of geospatial positions at a specified zoom level. Global pixel coordinates are relative to the top left corner of the map [-180, 90].
mercatorPositionsToPixels(Position[], number)	Converts an array of positions into an array of global Mercator pixel coordinates at a specified zoom level.
normalizeLatitude(number)	Normalizes a latitude value between -90 and 90 degrees.
normalizeLongitude(number)	Normalizes a longitude value between -180 and 180 degrees.
parseTimestamp(Date \| string \| number)	Parses a timestamp into a JavaScript Date object. Timestamps can be; A JavaScript Date object A number which represents the number of milliseconds since Jan 1st, 1970. A string which uses one of the following formats: ISO8601 date format (i.e. 2012-04-23T18:25:43.511Z) RFC282 / IETF date syntax (section 3.3) OData Date string (i.e. "/Date(1235764800000)/")
rotatePositions(Position[], Position \| Point, number)	Takes an array of positions and rotates them around a given position for the specified angle of rotation.
simplify((Position \| Pixel)[], number)	Perform a Douglas-Peucker simplification on an array of positions or pixels.

Function Details

boundingBoxToPolygon(BoundingBox)

Takes a BoundingBox and converts it to a polygon.

function boundingBoxToPolygon(bounds: BoundingBox): Polygon

Parameters

bounds: BoundingBox

The BoundingBox to convert to a Polygon.

Returns

Polygon

A polygon representation of the BoundingBox.

convertAcceleration(number, string | AccelerationUnits, string | AccelerationUnits, number)

Converts an acceleration value from one unit to another. Supported units: milesPerSecondSquared, kilometersPerSecondSquared, metersPerSecondSquared, feetPerSecondSquared yardsPerSecondSquared, kilometersPerHoursSecond, milesPerHourSecond, knotsPerSecond, standardGravity

function convertAcceleration(acceleration: number, fromUnits: string | AccelerationUnits, toUnits: string | AccelerationUnits, decimals?: number): number

Parameters

acceleration: number

The acceleration value to convert.

fromUnits: string | AccelerationUnits

The acceleration units the value is in.

toUnits: string | AccelerationUnits

The acceleration units to convert to.

decimals: number

The number of decimal places to round the result to.

Returns

number

An acceleration value convertered from one unit to another.

convertArea(number, string, string, number)

Converts an area value from one unit to another. Supported units: squareMeters, acres, hectares, squareFeet, squareYards, squareMiles, squareKilometers

function convertArea(area: number, fromUnits: string, toUnits: string, decimals?: number): number

Parameters

area: number

The area value to convert.

fromUnits: string

The area units the value is in.

toUnits: string

The area units to convert to.

decimals: number

The number of decimal places to round the result to.

Returns

number

An area value convertered from one unit to another.

convertDistance(number, string | DistanceUnits, string | DistanceUnits, number)

Converts a distance from one distance units to another. Supported units: miles, nauticalMiles, yards, meters, kilometers, feet

function convertDistance(distance: number, fromUnits: string | DistanceUnits, toUnits: string | DistanceUnits, decimals?: number): number

Parameters

distance: number

A number that represents a distance to convert.

fromUnits: string | DistanceUnits

The distance units the original distance is in.

toUnits: string | DistanceUnits

The desired distance units to convert to.

decimals: number

Specifies the number of decimal places to round the result to. If undefined, no rounding will occur.

Returns

number

A distance in the new units.

convertSpeed(number, string | SpeedUnits, string | SpeedUnits, number)

Converts a speed value from one unit to another. Supported units: kilometersPerHour, milesPerHour, metersPerSecond, feetPerSecond, knots, mach

function convertSpeed(speed: number, fromUnits: string | SpeedUnits, toUnits: string | SpeedUnits, decimals?: number): number

Parameters

speed: number

The speed value to convert.

fromUnits: string | SpeedUnits

The speed units to convert from.

toUnits: string | SpeedUnits

The speed units to convert to.

decimals: number

The number of decimal places to round the result to.

Returns

number

A speed value convertered from one unit to another.

convertTimespan(number, string | TimeUnits, string | TimeUnits, number)

Converts a timespan value from one unit to another. Supported units: ms (milliseconds), hours, minutes, seconds

function convertTimespan(timespan: number, fromUnits: string | TimeUnits, toUnits: string | TimeUnits, decimals?: number): number

Parameters

timespan: number

The time value to convert.

fromUnits: string | TimeUnits

The time units to convert from.

toUnits: string | TimeUnits

The time units to convert to.

decimals: number

The number of decimal places to round the result to.

Returns

number

A time value convertered from one unit to another.

getAcceleration(number, number, number, string | SpeedUnits, string | DistanceUnits, string | TimeUnits, string | AccelerationUnits, number)

Calculates an acceleration based on an initial speed, travel distance and timespan. Formula: a = 2*(d - v*t)/t^2

function getAcceleration(initialSpeed: number, distance: number, timespan: number, speedUnits?: string | SpeedUnits, distanceUnits?: string | DistanceUnits, timeUnits?: string | TimeUnits, accelerationUnits?: string | AccelerationUnits, decimals?: number): number

Parameters

initialSpeed: number

The initial speed.

distance: number

The distance that has been travelled.

timespan: number

The timespan that was travelled.

speedUnits: string | SpeedUnits

The units of the speed information. If not specified m/s are used.

distanceUnits: string | DistanceUnits

The units of the distance information. If not specified meters are used.

timeUnits: string | TimeUnits

The units of the timespan information. If not specified seconds are used.

accelerationUnits: string | AccelerationUnits

The units to return the acceleration value in. If not specified m/s^2 are used.

decimals: number

The number of decimal places to round the result to.

Returns

number

An acceleration based on an initial speed, travel distance and timespan.

getAccelerationFromFeatures(Feature<Point, any>, Feature<Point, any>, string, string, string | SpeedUnits, string | AccelerationUnits, number)

Calculates an acceleration between two point features that have a timestamp property and optionally a speed property. if speeds are provided, ignore distance between points as the path may not have been straight and calculate: a = (v2 - v1)/(t2 - t1) if speeds not provided or only provided on first point, calculate straight line distance between points and calculate: a = 2*(d - v*t)/t^2

function getAccelerationFromFeatures(origin: Feature<Point, any>, destination: Feature<Point, any>, timestampProperty: string, speedProperty?: string, speedUnits?: string | SpeedUnits, accelerationUnits?: string | AccelerationUnits, decimals?: number): number

Parameters

origin: Feature<Point, any>

The initial point in which the acceleration is calculated from.

destination: Feature<Point, any>

The final point in which the acceleration is calculated from.

timestampProperty: string

The name of the property on the features that contains the timestamp information.

speedProperty: string

The name of the property on the features that contains a speed information.

speedUnits: string | SpeedUnits

The units of the speed information. If not specified m/s is used.

accelerationUnits: string | AccelerationUnits

The units to return the acceleration value in. If not specified m/s^2 are used.

decimals: number

The number of decimal places to round the result to.

Returns

number

An acceleration between two point features that have a timestamp property and optionally a speed property. Returns NaN if unable to parse timestamp.

getAccelerationFromSpeeds(number, number, number, string | SpeedUnits, string | TimeUnits, string | AccelerationUnits, number)

Calculates an acceleration based on an initial speed, final speed and timespan. Formula: a = 2* (v2 - v1)/t

function getAccelerationFromSpeeds(initialSpeed: number, finalSpeed: number, timespan: number, speedUnits?: string | SpeedUnits, timeUnits?: string | TimeUnits, accelerationUnits?: string | AccelerationUnits, decimals?: number): number

Parameters

initialSpeed: number

The initial speed.

finalSpeed: number

The final speed.

timespan: number

The timespan that was travelled.

speedUnits: string | SpeedUnits

The units of the speed information. If not specified meters are used.

timeUnits: string | TimeUnits

The units of the timespan information. If not specified seconds are used.

accelerationUnits: string | AccelerationUnits

The units to return the acceleration value in. If not specified m/s^2 are used.

decimals: number

The number of decimal places to round the result to.

Returns

number

An acceleration based on an initial speed, final speed and timespan.

getArea(atlas.data.Geometry | Feature<atlas.data.Geometry, any> | Shape, AreaUnits, number)

Calculates the approximate area of a geometry in the specified units

function getArea(data: atlas.data.Geometry | Feature<atlas.data.Geometry, any> | Shape, areaUnits?: AreaUnits, decimals?: number): number

Parameters

data: Geometry | Feature<Geometry, any> | Shape

areaUnits: AreaUnits

Unit of area measurement. Default is squareMeters.

decimals: number

The number of decimal places to round the result to.

Returns

number

The area of a geometry in the specified units.

getCardinalSpline(Position[], number, number, boolean)

Calculates an array of positions that form a cardinal spline between the specified array of positions.

function getCardinalSpline(positions: Position[], tension?: number, nodeSize?: number, close?: boolean): Position[]

Parameters

positions: Position[]

The array of positions to calculate the spline through.

tension: number

A number that indicates the tightness of the curve. Can be any number, although a value between 0 and 1 is usually used. Default: 0.5

nodeSize: number

Number of nodes to insert between each position. Default: 15

close: boolean

A boolean indicating if the spline should be a closed ring or not. Default: false

Returns

Position[]

An array of positions that form a cardinal spline between the specified array of positions.

getClosestPointOnGeometry(Position | Point | Feature<Point, any> | Shape, atlas.data.Geometry | Feature<atlas.data.Geometry, any> | Shape, string | DistanceUnits, number)

Calculates the closest point on the edge of a geometry to a specified point or position. The returned point feature will have a distance property that specifies the distance between the two points in the specified units. If the geometry is a Point, that points position will be used for the result. If the geometry is a MultiPoint, the distances to the individual positions will be used. If the geometry is a Polygon or MultiPolygon, the point closest to any edge will be returned regardless of if the point intersects the geometry or not.

function getClosestPointOnGeometry(pt: Position | Point | Feature<Point, any> | Shape, geom: atlas.data.Geometry | Feature<atlas.data.Geometry, any> | Shape, units?: string | DistanceUnits, decimals?: number): Feature<Point, { distance: number }>

Parameters

pt: Position | Point | Feature<Point, any> | Shape

The point or position to find the closest point on the edge of the geometry.

geom: Geometry | Feature<Geometry, any> | Shape

The geometry to find the closest point on.

units: string | DistanceUnits

Unit of distance measurement. Default is meters.

decimals: number

The number of decimal places to round the result to.

Returns

Feature<Point, { distance: number }>

getConvexHull(Position[] | atlas.data.Geometry | Feature<atlas.data.Geometry, any> | FeatureCollection | GeometryCollection | atlas.data.Geometry[] | Array<Feature<atlas.data.Geometry, any> | Shape> | Shape)

Calculates a Convex Hull from an array of positions, geometries or features.

function getConvexHull(data: Position[] | atlas.data.Geometry | Feature<atlas.data.Geometry, any> | FeatureCollection | GeometryCollection | atlas.data.Geometry[] | Array<Feature<atlas.data.Geometry, any> | Shape> | Shape): Polygon

Parameters

data: Position[] | Geometry | Feature<Geometry, any> | FeatureCollection | GeometryCollection | Geometry[] | Array<Feature<Geometry, any> | Shape> | Shape

The array of positions, geometries or features to calculate a convex hull for.

Returns

Polygon

A Convex Hull from an array of positions, geometries or features.

getDestination(Position | Point, number, number, string | DistanceUnits)

Calculates a destination position based on a starting position, a heading, a distance, and a distance unit type.

function getDestination(origin: Position | Point, heading: number, distance: number, units?: string | DistanceUnits): Position

Parameters

origin: Position | Point

Position that the destination is relative to.

heading: number

A heading angle between 0 - 360 degrees. 0 - North, 90 - East, 180 - South, 270 - West.

distance: number

Distance that destination is away.

units: string | DistanceUnits

Unit of distance measurement. Default is meters.

Returns

Position

A position that is the specified distance away from the origin.

getDistanceTo(Position | Point, Position | Point, string | DistanceUnits)

Calculate the distance between two position objects on the surface of the earth using the Haversine formula.

function getDistanceTo(origin: Position | Point, destination: Position | Point, units?: string | DistanceUnits): number

Parameters

origin: Position | Point

First position to calculate distance between.

destination: Position | Point

Second position to calculate distance between.

units: string | DistanceUnits

Unit of distance measurement. Default is meters.

Returns

number

The shortest distance between two positions in the specified units.

getEarthRadius(string | DistanceUnits)

Retrieves the radius of the earth in a specific distance unit for WGS84.

function getEarthRadius(units?: string | DistanceUnits): number

Parameters

units: string | DistanceUnits

Unit of distance measurement. Default: meters

Returns

number

A number that represents the radius of the earth in a specific distance unit.

getGeodesicPath(LineString | Position[], number)

Takes an array of positions objects and fills in the space between them with accurately positioned positions to form an approximated Geodesic path.

function getGeodesicPath(path: LineString | Position[], nodeSize?: number): Position[]

Parameters

path: LineString | Position[]

Array of position objects that form a path to fill in.

nodeSize: number

Number of nodes to insert between each position. Default: 15

Returns

Position[]

An array of position objects that form a geodesic paths, geodesic path crossing antimeridian will contain longitude outside of -180 to 180 range. See getGeodesicPaths() when this is undesired.

getGeodesicPaths(LineString | Position[], number)

Takes an array of positions objects and fills in the space between them with accurately positioned positions to form an approximated Geodesic path broken by antimeridian into multiple sub-paths.

function getGeodesicPaths(path: LineString | Position[], nodeSize?: number): Position[][]

Parameters

path: LineString | Position[]

Array of position objects that form a path to fill in.

nodeSize: number

Number of nodes to insert between each position. Default: 15

Returns

Position[][]

An array of paths that form geodesic paths, Comparing to getGeodesicPath, sub-paths will always contain longitude in -180 to 180 range

getHeading(Position | Point, Position | Point)

Calculates the heading from one position object to another.

function getHeading(origin: Position | Point, destination: Position | Point): number

Parameters

origin: Position | Point

Point of origin.

destination: Position | Point

Destination to calculate relative heading to.

Returns

number

A heading in degrees between 0 and 360. 0 degrees points due North.

getLengthOfPath(LineString | Position[], string | DistanceUnits)

Calculates the distance between all position objects in an array.

function getLengthOfPath(path: LineString | Position[], units?: string | DistanceUnits): number

Parameters

path: LineString | Position[]

The array of position objects that make up the path to calculate the length of.

units: string | DistanceUnits

Unit of distance measurement. Default: meters

Returns

number

The distance between all positions in between all position objects in an array on the surface of a earth in the specified units.

getPathDenormalizedAtAntimerian(LineString | Position[])

Denormalizes path on antimeridian, this makes lines with coordinates on the opposite side of the antimeridian to always cross it. Note that the path crossing antimeridian will contain longitude outside of -180 to 180 range. See getPathSplitByAntimeridian when this is not desired.

function getPathDenormalizedAtAntimerian(path: LineString | Position[]): Position[]

Parameters

path: LineString | Position[]

Array of position objects or linestring to denormalize

Returns

Position[]

A denormalized array of position objects, path crossing antimeridian will contain longitude outside of -180 to 180 range.

getPathSplitByAntimeridian(LineString | Position[])

Split path on antimeridian into multiple paths. See getPathDenormalizedAtAntimerian when this is not desired.

function getPathSplitByAntimeridian(path: LineString | Position[]): Position[][]

Parameters

path: LineString | Position[]

Array of position objects or linestring to split

Returns

Position[][]

A path split into multiple paths by antimeridian.

getPixelHeading(Position | Point, Position | Point)

Calculates the pixel accurate heading from one position to another based on the Mercator map projection. This heading is visually accurate.

function getPixelHeading(origin: Position | Point, destination: Position | Point): number

Parameters

origin: Position | Point

destination: Position | Point

Returns

number

getPointsWithHeadingsAlongPath(LineString | Position[], number)

Gets an array of evenly spaced points with headings along a path.

function getPointsWithHeadingsAlongPath(path: LineString | Position[], numPoints: number): Array<Feature<Point, { heading: number }>>

Parameters

path: LineString | Position[]

The path to get the positions from.

numPoints: number

The number of points to get.

Returns

Array<Feature<Point, { heading: number }>>

An array of evenly spaced points with headings along a path.

getPointWithHeadingAlongPath(LineString | Position[], number, string | DistanceUnits)

Gets a point with heading a specified distance along a path.

function getPointWithHeadingAlongPath(path: LineString | Position[], distance: number, units?: string | DistanceUnits): Feature<Point, { heading: number }>

Parameters

path: LineString | Position[]

The path to get the point from.

distance: number

The distance along the path to get the point at.

units: string | DistanceUnits

The distance units.

Returns

Feature<Point, { heading: number }>

A point with heading a specified distance along a path.

getPosition(Position | Point | Feature<Point, any> | Shape)

Gets the position of an object that is a position, point, point feature, or circle. If it is a circle, its center coordinate will be returned.

function getPosition(data: Position | Point | Feature<Point, any> | Shape): Position

Parameters

data: Position | Point | Feature<Point, any> | Shape

The data object to extract the position from.

Returns

Position

The position of an object that is a position, point, or point feature. Returns null if invalid data passed in.

getPositionAlongPath(LineString | Position[], number, string | DistanceUnits)

Calculates the position object on a path that is a specified distance away from the start of the path. If the specified distance is longer than the length of the path, the last position of the path will be returned.

function getPositionAlongPath(path: LineString | Position[], distance: number, units?: string | DistanceUnits): Position

Parameters

path: LineString | Position[]

A polyline or array of position coordinates that form a path.

distance: number

The distance along the path (from the start) to calculate the position for.

units: string | DistanceUnits

Unit of distance measurement. Default is meters.

Returns

Position

A position object that is the specified distance away from the start of the path when following the path.

getPositions(Position[] | atlas.data.Geometry | Feature<atlas.data.Geometry, any> | FeatureCollection | GeometryCollection | atlas.data.Geometry[] | Array<Feature<atlas.data.Geometry, any> | Shape> | Shape)

Retrieves an array of all positions in the provided geometry, feature or array of geometries/features.

function getPositions(data: Position[] | atlas.data.Geometry | Feature<atlas.data.Geometry, any> | FeatureCollection | GeometryCollection | atlas.data.Geometry[] | Array<Feature<atlas.data.Geometry, any> | Shape> | Shape): Position[]

Parameters

data: Position[] | Geometry | Feature<Geometry, any> | FeatureCollection | GeometryCollection | Geometry[] | Array<Feature<Geometry, any> | Shape> | Shape

The geometries or features to retrieve the positions from.

Returns

Position[]

An array of all positions in the provided geometry, feature or array of geometries/features.

getPositionsAlongPath(LineString | Position[], number)

Gets an array of evenly spaced positions along a path.

function getPositionsAlongPath(path: LineString | Position[], numPositions: number): Position[]

Parameters

path: LineString | Position[]

The path to get the positions from.

numPositions: number

The number of positions to get.

Returns

Position[]

An array of evenly spaced positions along a path.

getRegularPolygonPath(Position | Point, number, number, string | DistanceUnits, number)

Calculates an array of position objects that are an equal distance away from a central point to create a regular polygon.

function getRegularPolygonPath(origin: Position | Point, radius: number, numberOfPositions: number, units?: string | DistanceUnits, offset?: number): Position[]

Parameters

origin: Position | Point

Center of the regular polygon.

radius: number

Radius of the regular polygon.

numberOfPositions: number

Number of positions the polygon should have.

units: string | DistanceUnits

Unit of distance measurement. Default is meters.

offset: number

An offset to rotate the polygon. When 0 the first position will align with North.

Returns

Position[]

An array of position objects that form a regular polygon.

getRegularPolygonPaths(Position | Point, number, number, string | DistanceUnits, number)

Calculates an array of position objects that are an equal distance away from a central point to create a regular polygon broken by antimeridian into multiple sub-paths.

function getRegularPolygonPaths(origin: Position | Point, radius: number, numberOfPositions: number, units?: string | DistanceUnits, offset?: number): Position[][]

Parameters

origin: Position | Point

Center of the regular polygon.

radius: number

Radius of the regular polygon.

numberOfPositions: number

Number of positions the polygon should have.

units: string | DistanceUnits

Unit of distance measurement. Default is meters.

offset: number

An offset to rotate the polygon. When 0 the first position will align with North.

Returns

Position[][]

An array of paths that form a regular polygon. Comparing to getRegularPolygonPath, sub-paths will always contain longitude in -180 to 180 range

getSpeed(Position | Point | Feature<Point, any>, Position | Point | Feature<Point, any>, number, string | TimeUnits, string | SpeedUnits, number)

Calculates the average speed of travel between two points based on the provided amount of time.

function getSpeed(origin: Position | Point | Feature<Point, any>, destination: Position | Point | Feature<Point, any>, timespan: number, timeUnits?: string | TimeUnits, speedUnits?: string | SpeedUnits, decimals?: number): number

Parameters

origin: Position | Point | Feature<Point, any>

The initial point in which the speed is calculated from.

destination: Position | Point | Feature<Point, any>

The final point in which the speed is calculated from.

timespan: number

timeUnits: string | TimeUnits

The units of the time value. If not specified seconds are used.

speedUnits: string | SpeedUnits

The units to return the speed value in. If not specified m/s are used.

decimals: number

The number of decimal places to round the result to.

Returns

number

The average speed of travel between two points based on the provided amount of time.

getSpeedFromFeatures(Feature<Point, any>, Feature<Point, any>, string, string | SpeedUnits, number)

Calculates the average speed of travel between two point features that have a property containing a timestamp. The timestamp can be;

A JavaScript Date object
A number which represents the number of milliseconds since Jan 1st, 1970.
A string which uses one of the following formats:
- ISO8601 date format (i.e. 2012-04-23T18:25:43.511Z)
- RFC282 / IETF date syntax (section 3.3)
- OData Date string (i.e. "/Date(1235764800000)/")

function getSpeedFromFeatures(origin: Feature<Point, any>, destination: Feature<Point, any>, timestampProperty: string, speedUnits?: string | SpeedUnits, decimals?: number): number

Parameters

origin: Feature<Point, any>

The initial point in which the speed is calculated from.

destination: Feature<Point, any>

The final point in which the speed is calculated from.

timestampProperty: string

The name of the property on the features which has the timestamp information.

speedUnits: string | SpeedUnits

The units to return the speed value in. If not specified m/s are used.

decimals: number

The number of decimal places to round the result to.

Returns

number

The speed in the specified units or NaN if valid timestamps are not found.

getTimespan(Date | string | number, Date | string | number, TimeUnits, number)

Calculates the timespan between two dates or timestamps. Timestamps can be;

A JavaScript Date object
A number which represents the number of milliseconds since Jan 1st, 1970.
A string which uses one of the following formats:
- ISO8601 date format (i.e. 2012-04-23T18:25:43.511Z)
- RFC282 / IETF date syntax (section 3.3)
- OData Date string (i.e. "/Date(1235764800000)/")

function getTimespan(startTime: Date | string | number, endTime: Date | string | number, units?: TimeUnits, decimals?: number): number

Parameters

startTime: Date | string | number

The start date or time.

endTime: Date | string | number

The end date or time.

units: TimeUnits

The units to return the time value in. If not specified seconds are used.

decimals: number

Returns

number

A timespan between two dates or timestamps. Returns NaN if unable to parse timestamps.

getTravelDistance(string, number, number, number, string | TimeUnits, string | SpeedUnits, string, number)

Calculates the distance traveled for a specified timespan, speed and optionally an acceleration. Formula: d = vt + 0.5a*t^2

function getTravelDistance(distanceUnits: string, timespan: number, speed: number, acceleration?: number, timeUnits?: string | TimeUnits, speedUnits?: string | SpeedUnits, accelerationUnits?: string, decimals?: number): number

Parameters

distanceUnits: string

The distance units in which to return the distance in.

timespan: number

The timespan to calculate the distance for.

speed: number

The initial or constant speed.

acceleration: number

Optional. An acceleration which increases the speed over time.

timeUnits: string | TimeUnits

The units of the timespan. If not specified seconds are used.

speedUnits: string | SpeedUnits

The units of the speed value. If not specified m/s are used.

accelerationUnits: string

Optional. The units of the acceleration value. If not specified m/s^2 are used.

decimals: number

The number of decimal places to round the result to.

Returns

number

The distance traveled for a specified timespan, speed and optionally an acceleration.

interpolate(Position | Point, Position | Point, number)

Calculates a position object that is a fractional distance between two position objects.

function interpolate(origin: Position | Point, destination: Position | Point, fraction?: number): Position

Parameters

origin: Position | Point

First position to calculate mid-point between.

destination: Position | Point

Second position to calculate mid-point between.

fraction: number

The fractional parameter to calculate a mid-point for. Default 0.5.

Returns

Position

A position that lies a fraction of the distance between two position objects, relative to the first position object.

mercatorPixelsToPositions(Pixel[], number)

Converts an array of global Mercator pixel coordinates into an array of geospatial positions at a specified zoom level. Global pixel coordinates are relative to the top left corner of the map [-180, 90].

function mercatorPixelsToPositions(pixels: Pixel[], zoom: number): Position[]

Parameters

pixels: Pixel[]

Array of pixel coordinates.

zoom: number

Zoom level.

Returns

Position[]

An array of positions.

mercatorPositionsToPixels(Position[], number)

Converts an array of positions into an array of global Mercator pixel coordinates at a specified zoom level.

function mercatorPositionsToPixels(positions: Position[], zoom: number): Pixel[]

Parameters

positions: Position[]

Array of positions.

zoom: number

Zoom level.

Returns

Pixel[]

Array of global Mercator pixels.

normalizeLatitude(number)

Normalizes a latitude value between -90 and 90 degrees.

function normalizeLatitude(lat: number): number

Parameters

lat: number

The latitude value to normalize.

Returns

number

normalizeLongitude(number)

Normalizes a longitude value between -180 and 180 degrees.

function normalizeLongitude(lng: number): number

Parameters

lng: number

The longitude value to normalize.

Returns

number

parseTimestamp(Date | string | number)

Parses a timestamp into a JavaScript Date object. Timestamps can be;

A JavaScript Date object
A number which represents the number of milliseconds since Jan 1st, 1970.
A string which uses one of the following formats:
- ISO8601 date format (i.e. 2012-04-23T18:25:43.511Z)
- RFC282 / IETF date syntax (section 3.3)
- OData Date string (i.e. "/Date(1235764800000)/")

function parseTimestamp(timestamp: Date | string | number): Date

Parameters

timestamp: Date | string | number

The timestamp value to parse.

Returns

Date

A Date object that represents the timestamp or null if the timestamp could not be parsed.

rotatePositions(Position[], Position | Point, number)

Takes an array of positions and rotates them around a given position for the specified angle of rotation.

function rotatePositions(positions: Position[], origin: Position | Point, angle: number): Position[]

Parameters

positions: Position[]

An array of positions to be rotated.

origin: Position | Point

The position to rotate the positions around.

angle: number

The amount to rotate the array of positions in degrees clockwise.

Returns

Position[]

simplify((Position | Pixel)[], number)

Perform a Douglas-Peucker simplification on an array of positions or pixels.

function simplify(points: (Position | Pixel)[], tolerance: number): (Position | Pixel)[]

Parameters

points: (Position | Pixel)[]

The position or pixel points to simplify.

tolerance: number

A tolerance to use in the simplification.

Returns

(Position | Pixel)[]

A new array of the simplified set of points.