# Ellipsoid

class in `3d-tiles-renderer/three`

```js
import { Ellipsoid } from '3d-tiles-renderer/three';
```

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.

## Constructor

```js
new Ellipsoid( x?: number, y?: number, z?: number )
```

- `x`, `number`, optional, default `1`: Semi-axis radius along the X axis.
- `y`, `number`, optional, default `1`: Semi-axis radius along the Y axis.
- `z`, `number`, optional, default `1`: Semi-axis radius along the Z axis.

## 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

### .intersectRay

```js
.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`.

- `ray`, `Ray`
- `target`, `Vector3`

### .getEastNorthUpFrame

```js
.getEastNorthUpFrame( lat: number, lon: number, 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`.

- `lat`, `number`: Latitude in radians.
- `lon`, `number`: Longitude in radians.
- `height`, `number`: Height above the ellipsoid surface in meters.
- `target`, `Matrix4`

### .getOrientedEastNorthUpFrame

```js
.getOrientedEastNorthUpFrame( lat: number, lon: number, height: number, az: number, el: number, 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`.

- `lat`, `number`: Latitude in radians.
- `lon`, `number`: Longitude in radians.
- `height`, `number`: Height above the ellipsoid surface in meters.
- `az`, `number`: Azimuth in radians, measured from true north towards east.
- `el`, `number`: Elevation in radians, measured from the horizon upward.
- `roll`, `number`: Roll in radians around the north axis.
- `target`, `Matrix4`

### .getObjectFrame

```js
.getObjectFrame( lat: number, lon: number, height: number, az: number, el: number, roll: number, target: Matrix4, frame?: Frames ): 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.

- `lat`, `number`: Latitude in radians.
- `lon`, `number`: Longitude in radians.
- `height`, `number`: Height above the ellipsoid surface in meters.
- `az`, `number`: Azimuth in radians, measured from true north towards east.
- `el`, `number`: Elevation in radians, measured from the horizon upward.
- `roll`, `number`: Roll in radians around the north axis.
- `target`, `Matrix4`
- `frame`, `Frames`, optional, default `OBJECT_FRAME`

### .getCartographicFromObjectFrame

```js
.getCartographicFromObjectFrame( matrix: Matrix4, target: Object, frame?: Frames ): 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.

- `matrix`, `Matrix4`
- `target`, `Object`
- `frame`, `Frames`, optional, default `OBJECT_FRAME`

### .getEastNorthUpAxes

```js
.getEastNorthUpAxes( lat: number, lon: number, vecEast: Vector3, vecNorth: Vector3, vecUp: Vector3, point?: Vector3 )
```

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`.

- `lat`, `number`: Latitude in radians.
- `lon`, `number`: Longitude in radians.
- `vecEast`, `Vector3`
- `vecNorth`, `Vector3`
- `vecUp`, `Vector3`
- `point`, `Vector3`, optional

### .getCartographicToPosition

```js
.getCartographicToPosition( lat: number, lon: number, 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.

- `lat`, `number`: Latitude in radians.
- `lon`, `number`: Longitude in radians.
- `height`, `number`: Height above the ellipsoid surface in meters.
- `target`, `Vector3`

### .getPositionToCartographic

```js
.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.

- `pos`, `Vector3`
- `target`, `Object`

### .getCartographicToNormal

```js
.getCartographicToNormal( lat: number, 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.

- `lat`, `number`: Latitude in radians.
- `lon`, `number`: Longitude in radians.
- `target`, `Vector3`

### .getPositionToNormal

```js
.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.

- `pos`, `Vector3`
- `target`, `Vector3`

### .getPositionToSurfacePoint

```js
.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`.

- `pos`, `Vector3`
- `target`, `Vector3`

### .calculateHorizonDistance

```js
.calculateHorizonDistance( latitude: number, elevation: number ): number
```

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

- `latitude`, `number`: Latitude in degrees.
- `elevation`, `number`: Height above the ellipsoid surface in meters.

### .calculateEffectiveRadius

```js
.calculateEffectiveRadius( 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.

- `latitude`, `number`: Latitude in degrees.

### .getPositionElevation

```js
.getPositionElevation( pos: Vector3 ): number
```

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

- `pos`, `Vector3`

### .closestPointToRayEstimate

```js
.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.

- `ray`, `Ray`
- `target`, `Vector3`

### .copy

```js
.copy( source: Ellipsoid ): this
```

Copies the radius from the given ellipsoid into this one.

- `source`, `Ellipsoid`

### .clone

```js
.clone(  ): Ellipsoid
```

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