# GlobeControls

class in `3d-tiles-renderer/three`, extends `EnvironmentControls`

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

Camera controls for navigating a globe-shaped tileset. Extends EnvironmentControls with
ellipsoid-aware rotation, globe inertia, and automatic near/far plane adjustment.

Example: Drag to rotate the globe, right drag or shift drag to tilt, and scroll to zoom

```js
import { TilesRenderer, GlobeControls } from '3d-tiles-renderer/three';
import { GeneratedSurfacePlugin, XYZTilesOverlay } from '3d-tiles-renderer/three/plugins';

// scene, camera and renderer are initialized here

const URL = 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}';

const tiles = new TilesRenderer();
tiles.registerPlugin( new GeneratedSurfacePlugin( {
	overlay: new XYZTilesOverlay( { url: URL } ),
	applyOverlayTexture: true,
} ) );
tiles.setCamera( camera );
tiles.group.rotation.x = - Math.PI / 2;
scene.add( tiles.group );

camera.position.set( 0, 0, 1.75e7 );

const controls = new GlobeControls( scene, camera, renderer.domElement );
controls.setEllipsoid( tiles.ellipsoid, tiles.group );
controls.enableDamping = true;

renderer.setAnimationLoop( () => {

	controls.update();
	camera.updateMatrixWorld();
	tiles.setResolutionFromRenderer( camera, renderer );
	tiles.update();
	renderer.render( scene, camera );

} );
```

## Constructor

```js
new GlobeControls( scene?: Object3D, camera?: Camera, domElement?: HTMLElement )
```

- `scene`, `Object3D`, optional, default `null`: The scene to raycast against for surface interaction.
- `camera`, `Camera`, optional, default `null`: The camera to control.
- `domElement`, `HTMLElement`, optional, default `null`: The DOM element to attach pointer events to.

## Properties

### .ellipsoidFrame: Matrix4

readonly

The world matrix of `ellipsoidGroup`, representing the ellipsoid's coordinate frame.

### .ellipsoidFrameInverse: Matrix4

readonly

The inverse of `ellipsoidFrame`.

### .nearMargin: number

default `0.25`

Fraction of the near plane distance added as a buffer.

### .farMargin: number

default `0`

Fraction of the far plane distance added as a buffer.

### .globeInertia: Quaternion

default `new Quaternion()`

Accumulated globe rotation inertia quaternion. Applied each frame when globe inertia is active.

### .globeInertiaFactor: number

default `0`

Magnitude of the current globe rotation inertia. Decays to zero over time.

### .ellipsoid: Ellipsoid

default `WGS84_ELLIPSOID`

The ellipsoid model used for surface interaction and up-direction calculation.

### .ellipsoidGroup: Group

default `new Group()`

The Three.js group whose world matrix defines the ellipsoid's coordinate frame.

## Methods

### .setEllipsoid

```js
.setEllipsoid( ellipsoid?: Ellipsoid, ellipsoidGroup?: Group )
```

Sets the ellipsoid model and its scene group for globe-aware interaction.

- `ellipsoid`, `Ellipsoid`, optional: Ellipsoid to use. Defaults to a WGS84 clone.
- `ellipsoidGroup`, `Group`, optional: Group whose world matrix defines the ellipsoid frame.

### .getVectorToCenter

```js
.getVectorToCenter( target: Vector3 ): Vector3
```

Returns the vector from the camera to the center of the ellipsoid in world space.

- `target`, `Vector3`

### .getDistanceToCenter

```js
.getDistanceToCenter(  ): number
```

Returns the distance from the camera to the center of the ellipsoid.