Class: GeoCircle

Defined in: src/sdk/geo/GeoCircle.ts:10

A circle on Earth's surface, defined as the set of points on the Earth's surface equidistant (as measured geodetically) from a central point.

Constructors

Constructor

new GeoCircle(center, radius): GeoCircle

Defined in: src/sdk/geo/GeoCircle.ts:29

Constructor.

Parameters

Parameter	Type	Description
center	ReadonlyFloat64Array	The center of the new small circle, represented as a position vector in the standard geographic cartesian reference system.
radius	number	The radius of the new small circle in great-arc radians.

Returns

GeoCircle

Properties

ANGULAR_TOLERANCE

readonly static ANGULAR_TOLERANCE: 1e-7 = 1e-7

Defined in: src/sdk/geo/GeoCircle.ts:11

Accessors

center

Get Signature

get center(): ReadonlyFloat64Array

Defined in: src/sdk/geo/GeoCircle.ts:37

The center of this circle.

Returns

ReadonlyFloat64Array

---

radius

Get Signature

get radius(): number

Defined in: src/sdk/geo/GeoCircle.ts:45

The radius of this circle, in great-arc radians.

Returns

number

Methods

angleAlong()

angleAlong(start, end, tolerance, equalityTolerance): number

Defined in: src/sdk/geo/GeoCircle.ts:248

Gets the angular distance along an arc between two points that lie on this circle. The arc extends from the first point to the second in a counterclockwise direction when viewed from above the center of the circle.

Parameters

Parameter	Type	Default value	Description
start	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	undefined	A point on this circle which marks the beginning of an arc.
end	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	undefined	A point on this circle which marks the end of an arc.
tolerance	number	GeoCircle.ANGULAR_TOLERANCE	The error tolerance, in great-arc radians, when checking if start and end lie on this circle. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.
equalityTolerance	number	0	The angular tolerance for considering the start and end points to be equal, in radians. If the absolute (direction-agnostic) angular distance between the start and end points is less than or equal to this value, then the zero will be returned. Defaults to 0.

Returns

number

the angular width of the arc between the two points, in radians.

Throws

Error if either point does not lie on this circle.

---

angularWidth()

angularWidth(length): number

Defined in: src/sdk/geo/GeoCircle.ts:72

Calculates the central angle which subtends an arc along this circle of given length.

Parameters

Parameter	Type	Description
length	number	An arc length, in great-arc radians.

Returns

number

The central angle which subtends an arc along this circle of the given length, in radians.

---

arcLength()

arcLength(angle): number

Defined in: src/sdk/geo/GeoCircle.ts:63

Calculates the length of an arc along this circle subtended by a central angle.

Parameters

Parameter	Type	Description
angle	number	A central angle, in radians.

Returns

number

The length of the arc subtended by the angle, in great-arc radians.

---

bearingAt()

bearingAt(point, tolerance): number

Defined in: src/sdk/geo/GeoCircle.ts:309

Calculates the true bearing along this circle at a point on the circle.

Parameters

Parameter	Type	Default value	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	undefined	A point on this circle.
tolerance	number	GeoCircle.ANGULAR_TOLERANCE	The error tolerance, in great-arc radians, when checking if point lies on this circle. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.

Returns

number

the bearing along this circle at the point.

Throws

Error if the point does not lie on this circle.

---

closest()

Call Signature

closest(point, out): Float64Array

Defined in: src/sdk/geo/GeoCircle.ts:159

Finds the closest point on this circle to a specified point. In other words, projects the specified point onto this circle. If the specified point is equidistant from all points on this circle (i.e. it is coincident with or antipodal to this circle's center), NaN will be written to all fields of the result.

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	A point, represented as either a position vector or lat/long coordinates.
out	Float64Array	A Float64Array object to which to write the result.

Returns

Float64Array

The closest point on this circle to the specified point.

Call Signature

closest(point, out): GeoPoint

Defined in: src/sdk/geo/GeoCircle.ts:168

Finds the closest point on this circle to a specified point. In other words, projects the specified point onto this circle. If the specified point is equidistant from all points on this circle (i.e. it is coincident with or antipodal to this circle's center), NaN will be written to all fields of the result.

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	A point, represented as either a position vector or lat/long coordinates.
out	GeoPoint	A GeoPoint object to which to write the result.

Returns

GeoPoint

The closest point on this circle to the specified point.

---

distance()

distance(point): number

Defined in: src/sdk/geo/GeoCircle.ts:202

Calculates and returns the great-circle distance from a specified point to the closest point that lies on this circle. In other words, calculates the shortest distance from a point to this circle. The distance is signed, with positive distances representing deviation away from the center of the circle, and negative distances representing deviation toward the center of the circle.

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	A point, represented as either a position vector or lat/long coordinates.

Returns

number

the great circle distance, in great-arc radians, from the point to the closest point on this circle.

---

distanceAlong()

distanceAlong(start, end, tolerance, equalityTolerance): number

Defined in: src/sdk/geo/GeoCircle.ts:292

Gets the distance along an arc between two points that lie on this circle. The arc extends from the first point to the second in a counterclockwise direction when viewed from above the center of the circle.

Parameters

Parameter	Type	Default value	Description
start	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	undefined	A point on this circle which marks the beginning of an arc.
end	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	undefined	A point on this circle which marks the end of an arc.
tolerance	number	GeoCircle.ANGULAR_TOLERANCE	The error tolerance, in great-arc radians, when checking if start and end lie on this circle. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.
equalityTolerance	number	0	The tolerance for considering the start and end points to be equal, in great-arc radians. If the absolute (direction-agnostic) along-arc distance between the start and end points is less than or equal to this value, then the zero will be returned. Defaults to 0.

Returns

number

the length of the arc between the two points, in great-arc radians.

Throws

Error if either point does not lie on this circle.

---

encircles()

encircles(point, inclusive, tolerance): boolean

Defined in: src/sdk/geo/GeoCircle.ts:228

Checks whether a point lies within the boundary defined by this circle. This is equivalent to checking whether the distance of the point from the center of this circle is less than or equal to this circle's radius.

Parameters

Parameter	Type	Default value	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	undefined	A point, represented as either a position vector or lat/long coordinates.
inclusive	boolean	true	Whether points that lie on this circle should pass the check. True by default.
tolerance	number	GeoCircle.ANGULAR_TOLERANCE	The error tolerance, in great-arc radians, of this operation. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.

Returns

boolean

whether the point lies within the boundary defined by this circle.

---

includes()

includes(point, tolerance): boolean

Defined in: src/sdk/geo/GeoCircle.ts:214

Checks whether a point lies on this circle.

Parameters

Parameter	Type	Default value	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	undefined	A point, represented as either a position vector or lat/long coordinates.
tolerance	number	GeoCircle.ANGULAR_TOLERANCE	The error tolerance, in great-arc radians, of this operation. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.

Returns

boolean

whether the point lies on this circle.

---

intersection()

intersection(other, out): number

Defined in: src/sdk/geo/GeoCircle.ts:478

Calculates and returns the set of intersection points between this circle and another one, and writes the results to an array of position vectors.

Parameters

Parameter	Type	Description
other	GeoCircle	The other circle to test for intersections.
out	Float64Array[]	An array in which to store the results. The results will be stored at indexes 0 and 1. If these indexes are empty, then new Float64Array objects will be created and inserted into the array.

Returns

number

The number of solutions written to the out array. Either 0, 1, or 2.

---

intersectionGeoPoint()

intersectionGeoPoint(other, out): number

Defined in: src/sdk/geo/GeoCircle.ts:551

Calculates and returns the set of intersection points between this circle and another one, and writes the results to an array of GeoPoint objects.

Parameters

Parameter	Type	Description
other	GeoCircle	The other circle to test for intersections.
out	GeoPoint[]	An array in which to store the results. The results will be stored at indexes 0 and 1. If these indexes are empty, then new GeoPoint objects will be created and inserted into the array.

Returns

number

The number of solutions written to the out array. Either 0, 1, or 2.

---

isGreatCircle()

isGreatCircle(): boolean

Defined in: src/sdk/geo/GeoCircle.ts:54

Checks whether this circle is a great circle, or equivalently, whether its radius is equal to pi / 2 great-arc radians.

Returns

boolean

Whether this circle is a great circle.

---

numIntersectionPoints()

numIntersectionPoints(other, tolerance): number

Defined in: src/sdk/geo/GeoCircle.ts:570

Calculates and returns the number of intersection points between this circle and another one. Returns NaN if there are an infinite number of intersection points.

Parameters

Parameter	Type	Default value	Description
other	GeoCircle	undefined	The other circle to test for intersections.
tolerance	number	GeoCircle.ANGULAR_TOLERANCE	The error tolerance, in great-arc radians, of this operation. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.

Returns

number

the number of intersection points between this circle and the other one.

---

offsetAngleAlong()

Call Signature

offsetAngleAlong(point, angle, out, tolerance?): Float64Array

Defined in: src/sdk/geo/GeoCircle.ts:375

Offsets a point on this circle by a specified angular distance. The direction of the offset for positive distances is counterclockwise when viewed from above the center of this circle.

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The point to offset.
angle	number	The angular distance by which to offset, in radians.
out	Float64Array	A Float64Array object to which to write the result.
tolerance?	number	The error tolerance, in great-arc radians, when checking if point lies on this circle. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.

Returns

Float64Array

The offset point.

Throws

Error if the point does not lie on this circle.

Call Signature

offsetAngleAlong(point, angle, out, tolerance?): GeoPoint

Defined in: src/sdk/geo/GeoCircle.ts:387

Offsets a point on this circle by a specified angular distance. The direction of the offset for positive distances is counterclockwise when viewed from above the center of this circle.

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The point to offset.
angle	number	The angular distance by which to offset, in radians.
out	GeoPoint	A GeoPoint object to which to write the result.
tolerance?	number	The error tolerance, in great-arc radians, when checking if point lies on this circle. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.

Returns

GeoPoint

The offset point.

Throws

Error if the point does not lie on this circle.

---

offsetDistanceAlong()

Call Signature

offsetDistanceAlong(point, distance, out, tolerance?): Float64Array

Defined in: src/sdk/geo/GeoCircle.ts:340

Offsets a point on this circle by a specified distance. The direction of the offset for positive distances is counterclockwise when viewed from above the center of this circle.

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The point to offset.
distance	number	The distance by which to offset, in great-arc radians.
out	Float64Array	A Float64Array object to which to write the result.
tolerance?	number	The error tolerance, in great-arc radians, when checking if point lies on this circle. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.

Returns

Float64Array

The offset point.

Throws

Error if the point does not lie on this circle.

Call Signature

offsetDistanceAlong(point, distance, out, tolerance?): GeoPoint

Defined in: src/sdk/geo/GeoCircle.ts:352

Offsets a point on this circle by a specified distance. The direction of the offset for positive distances is counterclockwise when viewed from above the center of this circle.

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The point to offset.
distance	number	The distance by which to offset, in great-arc radians.
out	GeoPoint	A GeoPoint object to which to write the result.
tolerance?	number	The error tolerance, in great-arc radians, when checking if point lies on this circle. Defaults to GeoCircle.ANGULAR_TOLERANCE if not specified.

Returns

GeoPoint

The offset point.

Throws

Error if the point does not lie on this circle.

---

reverse()

reverse(): this

Defined in: src/sdk/geo/GeoCircle.ts:129

Reverses the direction of this circle. This sets the center of the circle to its antipode and the radius to its complement with Math.PI.

Returns

this

This circle, after it has been reversed.

---

set()

set(center, radius): this

Defined in: src/sdk/geo/GeoCircle.ts:82

Sets the center and radius of this circle.

Parameters

Parameter	Type	Description
center	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The new center.
radius	number	The new radius in great-arc radians.

Returns

this

this circle, after it has been changed.

---

setAsGreatCircle()

Call Signature

setAsGreatCircle(point1, point2): this

Defined in: src/sdk/geo/GeoCircle.ts:109

Sets this circle to be a great circle which contains two given points. There are two possible great circles that contain any two unique points; these circles differ only by their directionality (equivalently, the sign of their normal vectors). The order of points passed to this method and the right-hand rule determines which of the two is returned.

Parameters

Parameter	Type	Description
point1	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The first point that lies on the great circle.
point2	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The second point that lies on the great circle.

Returns

this

this circle, after it has been changed.

Call Signature

setAsGreatCircle(point, bearing): this

Defined in: src/sdk/geo/GeoCircle.ts:117

Sets this circle to be a great circle defined by a point and bearing offset, equivalent to the path projected from the point with the specified initial bearing (forward azimuth).

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	A point that lies on the great circle.
bearing	number	The initial bearing from the point.

Returns

this

this circle, after it has been changed.

---

createFromPoint()

static createFromPoint(point, radius): GeoCircle

Defined in: src/sdk/geo/GeoCircle.ts:619

Creates a new small circle from a lat/long coordinate pair and radius.

Parameters

Parameter	Type	Description
point	LatLonInterface	The center of the new small circle.
radius	number	The radius of the new small circle, in great-arc radians.

Returns

GeoCircle

a small circle.

---

createGreatCircle()

Call Signature

static createGreatCircle(point1, point2): GeoCircle

Defined in: src/sdk/geo/GeoCircle.ts:632

Creates a new great circle that contains two points. There are two possible great circles that contain any two unique points; these circles differ only by their directionality (equivalently, the sign of their normal vectors). The order of points passed to this method and the right-hand rule determines which of the two is returned.

Parameters

Parameter	Type	Description
point1	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The first point that lies on the new great circle.
point2	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The second point that lies on the new great circle.

Returns

GeoCircle

a great circle.

Call Signature

static createGreatCircle(point, bearing): GeoCircle

Defined in: src/sdk/geo/GeoCircle.ts:633

Creates a new great circle that contains two points. There are two possible great circles that contain any two unique points; these circles differ only by their directionality (equivalently, the sign of their normal vectors). The order of points passed to this method and the right-hand rule determines which of the two is returned.

Parameters

Parameter	Type
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface
bearing	number

Returns

GeoCircle

a great circle.

---

createGreatCircleFromPointBearing()

static createGreatCircleFromPointBearing(point, bearing): GeoCircle

Defined in: src/sdk/geo/GeoCircle.ts:646

Creates a new great circle defined by one point and a bearing offset. The new great circle will be equivalent to the path projected from the point with the specified initial bearing (forward azimuth).

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	A point that lies on the new great circle.
bearing	number	The initial bearing from the point.

Returns

GeoCircle

a great circle.

---

getGreatCircleNormal()

Call Signature

static getGreatCircleNormal(point1, point2, out): Float64Array

Defined in: src/sdk/geo/GeoCircle.ts:659

Calculates a normal vector for a great circle given two points which lie on the circle. The order of points passed to this method and the right-hand rule determines which of the two possible normal vectors for the great circle is returned.

Parameters

Parameter	Type	Description
point1	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The first point that lies on the great circle.
point2	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	The second point that lies on the great circle.
out	Float64Array	The vector to which to write the result.

Returns

Float64Array

the normal vector for the great circle.

Call Signature

static getGreatCircleNormal(point, bearing, out): Float64Array

Defined in: src/sdk/geo/GeoCircle.ts:667

Calculates a normal vector for a great circle given a point and initial bearing.

Parameters

Parameter	Type	Description
point	Readonly<Omit<Float64Array, "set" | "sort" | "copyWithin">> | LatLonInterface	A point that lies on the great circle.
bearing	number	The initial bearing from the point.
out	Float64Array	The vector to which to write the result.

Returns

Float64Array

the normal vector for the great circle.