docsby gkjohnson

Ellipsoid

Represents a triaxial ellipsoid defined by three semi-axis radii. Used to model planet-scale surfaces such as the Earth (see WGS84_ELLIPSOID). All geographic coordinates use latitude and longitude in radians.

On this page

Properties

isEllipsoid: boolean

Flag indicating that this is an ellipsoid surface.

name: string

Optional name for this ellipsoid instance.

radius: Vector3

Semi-axis radii of the ellipsoid.

Methods

constructor

new Ellipsoid(
	// Semi-axis radius along the X axis.
	x: number = 1,

	// Semi-axis radius along the Y axis.
	y: number = 1,

	// Semi-axis radius along the Z axis.
	z: number = 1
)

intersectRay

intersectRay( ray: Ray, target: Vector3 ): Vector3 | null

Returns the point where the given ray intersects the ellipsoid surface, or null if no intersection exists. Writes the result into target.

getEastNorthUpFrame

getEastNorthUpFrame(
	// Latitude in radians.
	lat: number,

	// Longitude in radians.
	lon: number,

	// Height above the ellipsoid surface in meters.
	height: number,
	target: Matrix4
): Matrix4

Returns a Matrix4 representing the East-North-Up (ENU) frame at the given geographic position: X points east, Y points north, Z points up. Writes the result into target.

getOrientedEastNorthUpFrame

getOrientedEastNorthUpFrame(
	// Latitude in radians.
	lat: number,

	// Longitude in radians.
	lon: number,

	// Height above the ellipsoid surface in meters.
	height: number,

	// Azimuth in radians, measured from true north towards east.
	az: number,

	// Elevation in radians, measured from the horizon upward.
	el: number,

	// Roll in radians around the north axis.
	roll: number,
	target: Matrix4
): Matrix4

Returns a Matrix4 representing the ENU frame at the given position, rotated by the given azimuth, elevation, and roll. Equivalent to getObjectFrame with ENU_FRAME.

getObjectFrame

getObjectFrame(
	// Latitude in radians.
	lat: number,

	// Longitude in radians.
	lon: number,

	// Height above the ellipsoid surface in meters.
	height: number,

	// Azimuth in radians, measured from true north towards east.
	az: number,

	// Elevation in radians, measured from the horizon upward.
	el: number,

	// Roll in radians around the north axis.
	roll: number,
	target: Matrix4,
	frame: Frames = OBJECT_FRAME
): Matrix4

Returns a Matrix4 representing a frame at the given geographic position, rotated by the given azimuth, elevation, and roll, and adjusted to match the three.js frame convention. OBJECT_FRAME orients with "+Y" up and "+Z" forward; CAMERA_FRAME orients with "+Y" up and "-Z" forward; ENU_FRAME returns the raw ENU-relative rotation.

getCartographicFromObjectFrame

getCartographicFromObjectFrame(
	matrix: Matrix4,
	target: Object,
	frame: Frames = OBJECT_FRAME
): Object

Extracts geographic position and orientation (lat, lon, height, azimuth, elevation, roll) from the given object/camera frame matrix. The inverse of getObjectFrame. Writes the result into target and returns it.

getEastNorthUpAxes

getEastNorthUpAxes(
	// Latitude in radians.
	lat: number,

	// Longitude in radians.
	lon: number,
	vecEast: Vector3,
	vecNorth: Vector3,
	vecUp: Vector3,
	point?: Vector3
): void

Fills in the east, north, and up unit vectors for the ENU frame at the given latitude and longitude. Optionally writes the surface position into point.

getCartographicToPosition

getCartographicToPosition(
	// Latitude in radians.
	lat: number,

	// Longitude in radians.
	lon: number,

	// Height above the ellipsoid surface in meters.
	height: number,
	target: Vector3
): Vector3

Converts geographic coordinates to a 3D Cartesian position on the ellipsoid surface (plus the given height offset). Writes the result into target and returns it.

getPositionToCartographic

getPositionToCartographic( pos: Vector3, target: Object ): Object

Converts a 3D Cartesian position to geographic coordinates (lat, lon, height). Writes the result into target and returns it.

getCartographicToNormal

getCartographicToNormal(
	// Latitude in radians.
	lat: number,

	// Longitude in radians.
	lon: number,
	target: Vector3
): Vector3

Returns the surface normal of the ellipsoid at the given latitude and longitude. Writes the result into target and returns it.

getPositionToNormal

getPositionToNormal( pos: Vector3, target: Vector3 ): Vector3

Returns the surface normal of the ellipsoid at the given 3D Cartesian position. Writes the result into target and returns it.

getPositionToSurfacePoint

getPositionToSurfacePoint(
	pos: Vector3,
	target: Vector3
): Vector3 | null

Projects the given 3D position onto the ellipsoid surface along the geodetic normal. Returns null if the position is at or near the center. Writes the result into target.

calculateHorizonDistance

calculateHorizonDistance(
	// Latitude in degrees.
	latitude: number,

	// Height above the ellipsoid surface in meters.
	elevation: number
): number

Returns the geometric distance to the horizon from the given latitude and elevation above the ellipsoid surface.

calculateEffectiveRadius

calculateEffectiveRadius(
	// Latitude in degrees.
	latitude: number
): number

Returns the prime vertical radius of curvature (distance from the center of the ellipsoid to the surface along the normal) at the given latitude.

getPositionElevation

getPositionElevation( pos: Vector3 ): number

Returns the height of the given 3D position above (or below) the ellipsoid surface.

closestPointToRayEstimate

closestPointToRayEstimate( ray: Ray, target: Vector3 ): Vector3

Returns an estimate of the closest point on the ellipsoid surface to the given ray. Returns the exact surface intersection point if the ray intersects the ellipsoid.

copy

copy( source: Ellipsoid ): this

Copies the radius from the given ellipsoid into this one.

clone

clone(): Ellipsoid

Returns a new Ellipsoid with the same radius as this one.