### Complete example: PersonViewPlugin with terrain, photo, and 3D-tiles layers

Source: https://navara.world/docs/three/tutorial/interior-explore

Complete setup for a third-person character exploration scene using @navaramap/three. It creates a DefaultPlugin, a ThreeView with shadow and background color, and a PersonViewPlugin configured with a Soldier model, movement speeds, camera settings, and start position. It then adds a photoreal scene, terrain, raster photo, and 3D-tiles building layer before starting the person view.

```typescript
import ThreeView, { Color } from "@navaramap/three";
import {
  DefaultPlugin,
  type DefaultDescriptions,
} from "@navaramap/three-default-plugin";
import { PersonViewPlugin } from "@navaramap/three-plugins";


const plugin = new DefaultPlugin();
const view = new ThreeView<DefaultDescriptions>({
  shadow: true,
  backgroundColor: new Color().setStyle("#475668"),
});


const startLat = 35.6341630282;
const startLng = 139.7420527162;
const startHeight = 59.05;
const startHeading = 288;


const personView = new PersonViewPlugin({
  character: {
    modelUrl: "/Soldier.glb",
    animation: {
      idleClip: "Idle",
      walkClip: "Walk",
      dashClip: "Run",
      speed: 1.0,
      crossfadeDuration: 0.3,
    },
    modelRotationOffset: { x: Math.PI / 2, y: 0, z: 0 },
    modelScale: 1,
    castShadow: true,
    receiveShadow: true,
  },
  moveSpeed: 5,
  altSpeed: 5,
  rotationSpeed: 2,
  cameraDistance: 8,
  cameraPitch: 3.4,
  cameraLerpSpeed: 4,
  minAlt: -1000,
  maxAlt: 5000,
  startLat,
  startLng,
  startHeight,
  startHeading,
  allowCameraControl: true,
});


view.addPlugin(plugin);
view.addPlugin(personView);
await view.init();


view.atmosphere.date.setHours(8);
view.toneMappingExposure = 10;


const layers = plugin.addDefaultPhotorealScene();
layers.sun.update({
  sun: { castShadow: true, shadowFar: 1000, shadowLambda: 1 },
});


const terrainSource = view.addSource({
  type: "quantized-mesh",
  url: "https://terrain.reearth.land/cesium-mesh/ellipsoid/{z}/{x}/{y}.terrain",
  requestVertexNormals: true,
  maxZoom: 18,
});
view.addLayer({
  type: "terrain",
  source: terrainSource,
  terrain: {
    castShadow: true,
    receiveShadow: true,
    skirt: false,
  },
});


const photoSource = view.addSource({
  type: "raster-tile",
  // Credit:
  // - Geospatial Information Authority of Japan Tiles - Latest Nationwide Photo (Seamless)
  //   https://maps.gsi.go.jp/development/ichiran.html
  url: "https://cyberjapandata.gsi.go.jp/xyz/seamlessphoto/{z}/{x}/{y}.jpg",
  maxZoom: 18,
});
view.addLayer({
  type: "raster",
  source: photoSource,
});


const buildingSource = view.addSource({
  type: "3d-tiles",
  // Credit:
  // - [UC23-11] Advanced Area Management Using Storytelling GIS - MLIT PLATEAU
  //   https://www.geospatial.jp/ckan/dataset/plateau-uc23-11
  url: "https://cms.plateau.reearth.io/assets/c1/28f9ff-e9d0-44df-b092-88ac7ebdfa42/tngw_4gaiku/tileset.json",
});
view.addLayer({
  type: "3d-tiles",
  source: buildingSource,
  model: {
    show: true,
    castShadow: true,
    receiveShadow: true,
  },
});


personView.start();
```

--------------------------------

### Usage example: register and start plugins

Source: https://navara.world/docs/three_plugins/about

Shows the standard plugin lifecycle: create instances, register with view.addPlugin() before view.init(), then use plugin-specific methods after initialization.

```javascript
import ThreeView from "@navaramap/three";
import { DefaultPlugin } from "@navaramap/three-default-plugin";
import { PersonViewPlugin, OverlayPlugin } from "@navaramap/three-plugins";


const view = new ThreeView({ container, animation: true });


const defaultPlugin = new DefaultPlugin();
const personView = new PersonViewPlugin({
  character: {
    modelUrl: "/glTF/bird/scene.gltf",
    animation: {
      idleClip: "Gliding",
      dashClip: "Flapping",
      speed: 1.0,
      crossfadeDuration: 0.3,
    },
  },
});
const overlay = new OverlayPlugin({ maxDistance: 100_000 });


view.addPlugin(defaultPlugin);
view.addPlugin(personView);
view.addPlugin(overlay);


await view.init();


personView.start();
```

--------------------------------

### start()

Source: https://navara.world/docs/three_plugins/personviewplugin

Starts the person view, loading the model and taking over camera control.

```APIDOC
## start()

### Description
Loads the GLTF model (when configured), takes over the camera and starts reading the movement keys. Must be called after `view.init()` completes. Calling it again after `stop()` resumes from wherever the character was left.

### Method
start

### Signature
`start(): void`

### Returns
- **void** - No return value.
```

--------------------------------

### Install with npm

Source: https://navara.world/docs/three/introduction/install

Use npm to install @navaramap/three, @navaramap/three-default-plugin, three, and postprocessing. This installs the core package and its peer dependencies, plus the default plugin for built-in descriptors.

```bash
npm install @navaramap/three @navaramap/three-default-plugin three postprocessing
```

--------------------------------

### Complete code for basic visualization with ThreeView

Source: https://navara.world/docs/three/tutorial/basic-visualization

Complete example for the basic visualization tutorial. It initializes ThreeView with the DefaultPlugin and TileJsonPlugin, adds an ambient light, loads a raster-tile basemap from the given TileJSON URL, and sets the camera to Tokyo. Use this as a starting point for a minimal map application.

```typescript
import ThreeView from "@navaramap/three";
import { DefaultPlugin, type DefaultDescriptions } from "@navaramap/three-default-plugin";
import { TileJsonPlugin } from "@navaramap/three-plugins";


const plugin = new DefaultPlugin();
const view = new ThreeView<DefaultDescriptions>({});
view.addPlugin(plugin);


const tilejson = new TileJsonPlugin();
view.addPlugin(tilejson);


await view.init();


view.addLight({
  ambient: {},
});


const basemapSource = await tilejson.addSource({
  type: "raster-tile",
  url: "https://papers.reearth.land/styles/protomaps-light/tilejson.json",
});
view.addLayer({
  type: "raster",
  source: basemapSource,
});


view.setCamera({
  lng: 139.7671,
  lat: 35.6812,
  height: 1000,
  heading: 0, // -180 to 180
  pitch: -30, // -180 to 0
  roll: 0, // -180 to 180
});
```

--------------------------------

### Recommended photorealistic scene setup using DefaultPlugin and addDefaultPhotorealScene

Source: https://navara.world/docs/three_default_descs/light-desc/about

Registers all light descriptors via DefaultPlugin from @navaramap/three-default-plugin, initializes the view, and adds a photorealistic scene (including SunLight and SkyLightProbe). Then adds an additional ambient light. Requires installing and importing DefaultPlugin.

```typescript
import { DefaultPlugin } from "@navaramap/three-default-plugin";

const plugin = new DefaultPlugin();
view.addPlugin(plugin);
await view.init();

// Set up a photorealistic scene at once (includes SunLight + SkyLightProbe, etc.)
const layers = plugin.addDefaultPhotorealScene();

// Add additional ambient light as needed
view.addLight<AmbientLightDesc>({
  ambient: { intensity: 0.3 }
});
```

--------------------------------

### Complete realistic atmosphere example with ThreeView and DefaultPlugin

Source: https://navara.world/docs/three/tutorial/realistic-atmosphere

Complete example for a realistic atmosphere with photoreal terrain, 3D Tiles buildings, clouds, rain, and SSR. It sets up a DefaultPlugin, adds raster and terrain layers, enables shadows and tone mapping, adds rain and rainDrop effects, and configures the camera and atmosphere date. Use this as a starting point for a full scene with weather and lighting.

```typescript
import ThreeView, { Color } from "@navaramap/three";
import { type CloudsEffectDesc, type RainDropEffectDesc, type RainMeshDesc, type SnowMeshDesc, type SSREffectDesc, ToneMappingMode } from "@navaramap/three-default-descs";
import { DefaultPlugin, type DefaultDescriptions } from "@navaramap/three-default-plugin";


const plugin = new DefaultPlugin();
const view = new ThreeView<DefaultDescriptions>({
  shadow: true,
  animation: true,
});
view.addPlugin(plugin);
await view.init();


const layers = plugin.addDefaultPhotorealScene();


layers.aerialPerspective.update({
  aerialPerspective: {
    irradiance: true,
  },
});


view.lit = false;


const photoSource = view.addSource({
  // Credit:
  // - Geospatial Information Authority of Japan Tiles - Latest Nationwide Photo (Seamless)
  //   https://maps.gsi.go.jp/development/ichiran.html
  type: "raster-tile",
  url: "https://cyberjapandata.gsi.go.jp/xyz/seamlessphoto/{z}/{x}/{y}.jpg",
  maxZoom: 18,
});
view.addLayer({
  type: "raster",
  source: photoSource,
});


const terrainSource = view.addSource({
  type: "quantized-mesh",
  url: "https://terrain.reearth.land/cesium-mesh/ellipsoid/{z}/{x}/{y}.terrain",
  requestVertexNormals: true,
  requestWaterMask: true,
  maxZoom: 18,
});
view.addLayer({
  type: "terrain",
  source: terrainSource,
  terrain: {
    castShadow: true,
    receiveShadow: true,
  },
});


layers.sun.update({ sun: { castShadow: true } });


layers.toneMapping.update({ toneMapping: { mode: ToneMappingMode.AGX } });
view.toneMappingExposure = 6;


const clouds = view.addEffect<CloudsEffectDesc>({
  clouds: {
    qualityPreset: "high",
    lightShafts: true,
  },
});


clouds.update({ clouds: { shadows: true } });


view.addMesh<RainMeshDesc>({
  rain: {
    particleCount: 5000,
    speed: 0.0015,
    opacity: 1.0,
    width: 3,
    height: 60.0,
    areaWidth: 500,
    areaHeight: 1000,
    maxHeight: 10000,
  },
});


view.addEffect<RainDropEffectDesc>({
  rainDrop: {
    opacity: 0.8,
    dropGridSize: 12,
    dropDensity: 0.7,
    dropSizeFactor: 0.018,
  },
});


const plateauSource = view.addSource({
  // Credit:
  // - 3D City Model (Project PLATEAU) Chuo Ward (FY2023) - MLIT PLATEAU
  //   https://www.geospatial.jp/ckan/dataset/plateau-13102-chuo-ku-2023
  type: "3d-tiles",
  url: "https://assets.cms.plateau.reearth.io/assets/4c/f2436a-e2be-40e2-83da-f1781f36e1b/13102_chuo-ku_pref_2023_citygml_1_op_bldg_3dtiles_13102_chuo-ku_lod2_no_texture/tileset.json",
});
view.addLayer({
  type: "3d-tiles",
  source: plateauSource,
  model: {
    show: true,
    color: new Color().setStyle("#ffffff"),
    metalness: 0,
    roughness: 0.5,
    castShadow: true,
    receiveShadow: true,
  },
});


view.addEffect<SSREffectDesc>({
  ssr: {
  },
});


view.atmosphere.date = new Date("2026-01-01T16:15:00+09:00");
view.toneMappingExposure = 12;


view.setCamera({ lng: 139.88, lat: 35.42, height: 2800, heading: 250, pitch: -16, roll: 0 });
```

--------------------------------

### featureEnter event example

Source: https://navara.world/docs/three/api/threeview-events

Example of logging the properties of the feature that the pointer started hovering.

```javascript
view.on("featureEnter", (info) => {
  console.log("Entered feature:", info.properties);
});
```

--------------------------------

### Usage Example

Source: https://navara.world/docs/three_default_descs/mesh-desc/sky-mesh-desc

Example of registering and adding a SkyMeshDesc to a ThreeView instance.

```APIDOC
## Usage Example

```typescript
import ThreeView from "@navaramap/three";
import { SkyMeshDesc } from "@navaramap/three-default-descs";

const view = new ThreeView();
view.registerMesh("sky", SkyMeshDesc);
await view.init();

// Add a SkyMeshDesc
const skyDesc = view.addMesh<SkyMeshDesc>({
  sky: {
    visible: true,
    sun: true,
    moon: true,
    moonScale: 1.2,
    moonIntensity: 0.9,
    sunAngularRadius: 0.004675,
  },
});
```

```

--------------------------------

### resize event example

Source: https://navara.world/docs/three/api/threeview-events

Example of registering a resize listener that logs the new window dimensions.

```javascript
view.on("resize", (width, height) => {
  console.log(`Window resized: ${width}x${height}`);
});
```

--------------------------------

### Usage Example

Source: https://navara.world/docs/three_default_descs/mesh-desc/smooth-line-mesh-desc

Example of registering and adding a SmoothLineMeshDesc to a ThreeView instance.

```APIDOC
## Usage Example

### Description
Example of registering and adding a SmoothLineMeshDesc to a ThreeView instance.

### Code
```javascript
import ThreeView from "@navaramap/three";
import { SmoothLineMeshDesc } from "@navaramap/three-default-descs";

const view = new ThreeView();
view.registerMesh("smoothLines", SmoothLineMeshDesc);
await view.init();

// Add a SmoothLineMeshDesc
const smoothLineDesc = view.addMesh<SmoothLineMeshDesc>({
  smoothLines: {
    tension: 0.5,
    segments: 10,
    lineWidth: 3,
    // color omitted in example
    showPoints: true,
    pointSize: 5,
    // pointColor omitted in example
    points: [
      { lng: 139.7671, lat: 35.6812, height: 100 },
      { lng: 139.7700, lat: 35.6850, height: 150 },
      { lng: 139.7750, lat: 35.6900, height: 100 },
    ],
  },
});
```
```

--------------------------------

### Install with npm

Source: https://navara.world/docs/three_default_descs/about

Install the package using npm. Requires @navaramap/three, three, and postprocessing as peer dependencies.

```bash
npm install @navaramap/three-default-descs
```

--------------------------------

### SkyMeshDesc sun property example

Source: https://navara.world/docs/three_default_descs/mesh-desc/sky-mesh-desc

Example showing how to enable the sun display by setting sun to true.

```json
{
  sky: {
    sun: true,
  }
}
```

--------------------------------

### Install TileJsonPlugin with npm

Source: https://navara.world/docs/three/tutorial/basic-visualization

Install the @navaramap/three-plugins package using npm. Required for the TileJsonPlugin used in this tutorial.

```bash
npm install @navaramap/three-plugins
```

--------------------------------

### Install with pnpm

Source: https://navara.world/docs/three_default_descs/about

Install the package using pnpm. Requires @navaramap/three, three, and postprocessing as peer dependencies.

```bash
pnpm add @navaramap/three-default-descs
```

--------------------------------

### Install with yarn

Source: https://navara.world/docs/three_default_descs/about

Install the package using yarn. Requires @navaramap/three, three, and postprocessing as peer dependencies.

```bash
yarn add @navaramap/three-default-descs
```

--------------------------------

### Complete code for GeoJSON display with terrain and basemap

Source: https://navara.world/docs/three/tutorial/basic-visualization

Complete example that initializes a ThreeView with default plugin and TileJsonPlugin, adds a terrain layer, a raster basemap, a GeoJSON polygon layer, and sets the camera to view the area. Use this as a full working setup for displaying GeoJSON data.

```javascript
import ThreeView, { Color } from "@navaramap/three";
import { DefaultPlugin, type DefaultDescriptions } from "@navaramap/three-default-plugin";
import { TileJsonPlugin } from "@navaramap/three-plugins";


const plugin = new DefaultPlugin();
const view = new ThreeView<DefaultDescriptions>({ shadow: true });
view.addPlugin(plugin);


const tilejson = new TileJsonPlugin();
view.addPlugin(tilejson);


await view.init();


view.addLight({
  sun: {},
});
view.atmosphere.date = new Date("2026-07-16T01:00:00Z");


const terrainSource = view.addSource({
  type: "quantized-mesh",
  url: "https://terrain.reearth.land/cesium-mesh/ellipsoid/{z}/{x}/{y}.terrain",
  requestVertexNormals: true,
  maxZoom: 18,
});
view.addLayer({
  type: "terrain",
  source: terrainSource,
  terrain: {
    castShadow: true,
    receiveShadow: true,
  },
});


const basemapSource = await tilejson.addSource({
  type: "raster-tile",
  url: "https://papers.reearth.land/styles/protomaps-light/tilejson.json",
});
view.addLayer({
  type: "raster",
  source: basemapSource,
});


const geojsonSource = view.addSource({
  type: "geojson",
  data: {
    type: "Feature",
    properties: { name: "Area" },
    geometry: {
      type: "Polygon",
      coordinates: [
        [
          [138.7, 35.425],
          [138.7, 35.4],
          [138.745, 35.4],
          [138.745, 35.425],
          [138.7, 35.425],
        ],
      ],
    },
  },
});
view.addLayer({
  type: "vector",
  source: geojsonSource,
  polygon: {
    color: new Color().setHex(0xff3b30),
    opacity: 0.75,
    transparent: true,
  },
});


view.setCamera({
  lng: 138.75,
  lat: 35.5,
  height: 6000,
  heading: 185, // -180 to 180
  pitch: -26, // -180 to 0
  roll: 0, // -180 to 180
});
```

--------------------------------

### Install with pnpm

Source: https://navara.world/docs/three/introduction/install

Use pnpm to install the same packages as the npm command. This is an alternative package manager command.

```bash
pnpm add @navaramap/three @navaramap/three-default-plugin three postprocessing
```

--------------------------------

### start() - enter person view

Source: https://navara.world/docs/three_plugins/personviewplugin

Loads the GLTF model (when configured), takes over the camera and starts reading the movement keys. Must be called after view.init() completes. Calling it again after stop() resumes from wherever the character was left, rather than returning to the configured start position.

```typescript
start(): void
```

--------------------------------

### forceUpdate() example

Source: https://navara.world/docs/three/api/threeview-functions

Example usage of forceUpdate. It manually triggers a re-render of the scene.

```javascript
view.forceUpdate();
```

--------------------------------

### Install TileJsonPlugin with pnpm

Source: https://navara.world/docs/three/tutorial/basic-visualization

Install the @navaramap/three-plugins package using pnpm. Required for the TileJsonPlugin used in this tutorial.

```bash
pnpm add @navaramap/three-plugins
```

--------------------------------

### Install TileJsonPlugin with yarn

Source: https://navara.world/docs/three/tutorial/basic-visualization

Install the @navaramap/three-plugins package using yarn. Required for the TileJsonPlugin used in this tutorial.

```bash
yarn add @navaramap/three-plugins
```

--------------------------------

### Install with yarn

Source: https://navara.world/docs/three/introduction/install

Use yarn to install the same packages as the npm command. This is an alternative package manager command.

```bash
yarn add @navaramap/three @navaramap/three-default-plugin three postprocessing
```

--------------------------------

### SkyMeshDesc moon property example

Source: https://navara.world/docs/three_default_descs/mesh-desc/sky-mesh-desc

Example showing how to enable the moon display by setting moon to true.

```json
{
  sky: {
    moon: true,
  }
}
```

--------------------------------

### memoryStats() example

Source: https://navara.world/docs/three/api/threeview-functions

Example usage of memoryStats() to log memory usage in MB. Checks for undefined before accessing properties.

```javascript
const stats = view.memoryStats();
if (stats) {
  const MB = 1024 * 1024;
  console.log(`WASM buffers: ${(stats.bufferTotalBytes / MB).toFixed(1)} MB`);
  console.log(`GPU estimate: ${(stats.gpuBytesEst / MB).toFixed(1)} MB`);
  console.log(`evicted: ${stats.evictedCount}, sse x${stats.sseMultiplier}`);
}

```

--------------------------------

### start

Source: https://navara.world/docs/three/api/navara_three_api

Gets the geodetic coordinates of the start point.

```APIDOC
## get start(): LatLngHeight

### Description
Gets the geodetic coordinates of the start point.

### Syntax
```
get start(): LatLngHeight
```

### Returns
Geodetic coordinates of the start point
```

--------------------------------

### Start the plugin with personView.start()

Source: https://navara.world/docs/three/tutorial/interior-explore

Starts the plugin, loading the GLTF model and beginning the per-frame loop that drives the character and camera. After this call, the character responds to keyboard input and the camera follows it.

```javascript
personView.start();
```

--------------------------------

### Set up the basic scene with ThreeView and plugins

Source: https://navara.world/docs/three/tutorial/interior-explore

Initialize the ThreeView with shadow enabled and a background color, then add the DefaultPlugin. These must be done before adding the PersonViewPlugin.

```javascript
import ThreeView, { Color } from "@navaramap/three";
import {
  DefaultPlugin,
  type DefaultDescriptions,
} from "@navaramap/three-default-plugin";
import { PersonViewPlugin } from "@navaramap/three-plugins";


const plugin = new DefaultPlugin();
const view = new ThreeView<DefaultDescriptions>({
  shadow: true,
  backgroundColor: new Color().setStyle("#475668"),
});
view.addPlugin(plugin);
```

--------------------------------

### startHeading

Source: https://navara.world/docs/three/api/navara_three_api

Gets the azimuth at the start point (degrees).

```APIDOC
## get startHeading(): number

### Description
Gets the azimuth at the start point (degrees).

### Syntax
```
get startHeading(): number
```

### Returns
Azimuth at the start point (degrees)

### Example
```
const geodesic = new EllipsoidGeodesic(start, end);
console.log(`Start heading: ${geodesic.startHeading}°`);
```
```

--------------------------------

### handle.ref.add(config) example

Source: https://navara.world/docs/three_default_descs/mesh-desc/instanced-gltf-model-mesh-desc

Adds a new instance and returns its index. Capacity grows automatically on the non-skinned path.

```javascript
const index = handle.ref.add({
  position: { x: 100, y: 0, z: 0 },
  scale: { x: 2, y: 2, z: 2 },
});
```

--------------------------------

### distance

Source: https://navara.world/docs/three/api/navara_three_api

Gets the geodesic distance between the start and end points (meters).

```APIDOC
## get distance(): number

### Description
Gets the geodesic distance between the start and end points (meters).

### Syntax
```
get distance(): number
```

### Returns
Geodesic distance (meters)

### Example
```
const geodesic = new EllipsoidGeodesic(start, end);
console.log(`Distance: ${geodesic.distance} m`); // Distance: 401747.8... m
```
```

--------------------------------

### registerLight() example

Source: https://navara.world/docs/three/api/threeview-functions

Example usage of registerLight. It defines a custom light descriptor class and registers it with the name 'customLight'.

```javascript
class CustomLightDesc extends LightDesc {
  onCreate() {
    // Custom implementation
  }
}


view.registerLight("customLight", CustomLightDesc);
```

--------------------------------

### Get sun elevation example

Source: https://navara.world/docs/three/api/atmosphere

Gets the sun elevation at the camera's geographic position and logs a message if the elevation is negative, indicating the sun has set.

```javascript
const elevation = view.atmosphere.getSunElevation(view.camera.positionGeographic);
if (elevation < 0) {
  console.log("The sun has set.");
}
```

--------------------------------

### getHeightFromEllipsoid example

Source: https://navara.world/docs/three/api/navara_three_api

Gets the height above the ellipsoid for a given ECEF point using getHeightFromEllipsoid. The example uses a sample position and logs the resulting height in meters.

```typescript
import { getHeightFromEllipsoid } from "@navaramap/three-api";
import { Vector3 } from "three";


const position = new Vector3(-3946416, 3364068, 3702654);
const height = getHeightFromEllipsoid(position);
console.log(`Height: ${height} m`);
```

--------------------------------

### Complete terrain visualization example

Source: https://navara.world/docs/three/tutorial/basic-visualization

Complete example combining all steps: initializes the view with shadow mapping, adds the default and TileJson plugins, sets a sun light and date, adds terrain and raster basemap layers, and positions the camera at Mount Fuji.

```javascript
import ThreeView from "@navaramap/three";
import { DefaultPlugin, type DefaultDescriptions } from "@navaramap/three-default-plugin";
import { TileJsonPlugin } from "@navaramap/three-plugins";


const plugin = new DefaultPlugin();
const view = new ThreeView<DefaultDescriptions>({ shadow: true });
view.addPlugin(plugin);


const tilejson = new TileJsonPlugin();
view.addPlugin(tilejson);


await view.init();


view.addLight({
  sun: {},
});
view.atmosphere.date = new Date("2026-07-16T01:00:00Z");


const terrainSource = view.addSource({
  type: "quantized-mesh",
  url: "https://terrain.reearth.land/cesium-mesh/ellipsoid/{z}/{x}/{y}.terrain",
  requestVertexNormals: true,
  maxZoom: 18,
});
view.addLayer({
  type: "terrain",
  source: terrainSource,
  terrain: {
    castShadow: true,
    receiveShadow: true,
  },
});


const basemapSource = await tilejson.addSource({
  type: "raster-tile",
  url: "https://papers.reearth.land/styles/protomaps-light/tilejson.json",
});
view.addLayer({
  type: "raster",
  source: basemapSource,
});


view.setCamera({
  lng: 138.75,
  lat: 35.5,
  height: 6000,
  heading: 185, // -180 to 180
  pitch: -26, // -180 to 0
  roll: 0, // -180 to 180
});
```

--------------------------------

### Get solar time example

Source: https://navara.world/docs/three/api/atmosphere

Gets the local solar time at longitude 139.69 degrees (Tokyo) for the current date. The result is in hours, e.g., 6.3 means 06:18.

```javascript
const hours = view.atmosphere.getSolarTime({ lng: 139.69 });
```

--------------------------------

### Create and set colors with Color.setRGB(), setHex(), setStyle()

Source: https://navara.world/docs/three/api/color

Shows how to create Color instances and set them using setRGB(), setHex(), and setStyle(). The constructor takes no arguments; colors are set via method chaining.

```javascript
import { Color } from "@navaramap/three";


// Set by RGB values (each component is 0.0-1.0)
const red = new Color().setRGB(1.0, 0.0, 0.0);


// Set by hexadecimal
const green = new Color().setHex(0x00ff00);


// Set by CSS color string
const blue = new Color().setStyle("#0000ff");
```

--------------------------------

### SphereMeshDesc thetaStart property example

Source: https://navara.world/docs/three_default_descs/mesh-desc/sphere-mesh-desc

Sets the vertical starting angle in radians. The default value is 0.

```json
{
  sphere: {
    thetaStart: Math.PI / 6,
  }
}
```

--------------------------------

### init() Example

Source: https://navara.world/docs/three/api/threeview-functions

Initializes the view and adds a raster layer after `init()`. The example creates a `ThreeView`, calls `init()`, adds a raster-tile source, and adds a raster layer.

```typescript
const view = new ThreeView();
await view.init();


// Add layers after init()
const osm = view.addSource({
  type: "raster-tile",
  url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
  maxZoom: 19,
});


view.addLayer({ type: "raster", source: osm });
```

--------------------------------

### SphereMeshDesc phiStart property example

Source: https://navara.world/docs/three_default_descs/mesh-desc/sphere-mesh-desc

Sets the horizontal starting angle in radians. The default value is 0.

```json
{
  sphere: {
    phiStart: Math.PI / 4,
  }
}
```

--------------------------------

### coneTracingFadeStart example

Source: https://navara.world/docs/three_default_descs/effect-desc/ssr-effect-desc

Sets the ratio at which reflection fading begins. Default is 0.9.

```json
{
  ssr: {
    coneTracingFadeStart: 0.5,
  }
}
```

--------------------------------

### EllipsoidGeodesic interpolateDistance signature

Source: https://navara.world/docs/three/api/navara_three_api

Declares the method signature for getting the point at a specified distance along the geodesic. The distance is in meters from the start point.

```typescript
interpolateDistance(distance: number): LatLngHeight
```

--------------------------------

### opacity example

Source: https://navara.world/docs/three/material/billboard-material

Sets transparent to true and opacity to 0.5 for 50% opacity.

```json
{
  billboard: {
    transparent: true,
    opacity: 0.5 // 50% opacity
  }
}
```

--------------------------------

### srcColor property example

Source: https://navara.world/docs/three_default_descs/mesh-desc/arcline-mesh-desc

Sets the color of the arc line's starting point using a Color instance. The default is new Color().setHex(0xffffff).

```javascript
import { Color } from "@navaramap/three";


{
  arcLines: {
    srcColor: new Color().setHex(0xff0000),
  }
}
```

--------------------------------

### Plugin lifecycle example with DefaultPlugin

Source: https://navara.world/docs/three/introduction/about-plugin

Shows the correct order: create plugin, register with view.addPlugin() before view.init(), then await view.init() to trigger plugin init, and finally use plugin methods. Calling addPlugin() after init() results in an error.

```javascript
import ThreeView from "@navaramap/three";
import { DefaultPlugin } from "@navaramap/three-default-plugin";


// 1. Create a plugin instance
const plugin = new DefaultPlugin();


// 2. Register the plugin before view.init()
const view = new ThreeView({});
view.addPlugin(plugin);


// 3. Plugin's init() is automatically called within init()
await view.init();


// 4. After initialization, plugin methods are available
const layers = plugin.addDefaultPhotorealScene();
```

--------------------------------

### jitter example

Source: https://navara.world/docs/three_default_descs/effect-desc/ssr-effect-desc

Offsets each ray's start along its own stride to trade banding for noise. Only meaningful with cone tracing enabled; set to 0 when useConeTracing is false.

```json
{
  ssr: {
    jitter: 0.5,
  }
}
```

--------------------------------

### Get moon direction example

Source: https://navara.world/docs/three/api/atmosphere

Retrieves the moon direction vector and logs its x, y, z components to the console. The returned vector is a clone, so modifying it does not affect the internal state.

```javascript
const moonDir = view.atmosphere.getMoonDirection();
console.log("Moon direction:", moonDir.x, moonDir.y, moonDir.z);
```

--------------------------------

### Get sun direction example

Source: https://navara.world/docs/three/api/atmosphere

Retrieves the sun direction vector and logs its x, y, z components to the console. The returned vector is a clone, so modifying it does not affect the internal state.

```javascript
const sunDir = view.atmosphere.getSunDirection();
console.log("Sun direction:", sunDir.x, sunDir.y, sunDir.z);
```

--------------------------------

### Basic usage example for SkyLightProbeDesc with DefaultPlugin

Source: https://navara.world/docs/three_default_descs/light-desc/sky-light-probe-desc

Shows how to set up a ThreeView with DefaultPlugin and add a default photoreal scene, then update the SkyLightProbeDesc with a specified intensity.

```javascript
import ThreeView from "@navaramap/three";
import { SkyLightProbeDesc } from "@navaramap/three-default-descs";
import { DefaultPlugin } from "@navaramap/three-default-plugin";


const view = new ThreeView();
const plugin = new DefaultPlugin();
view.addPlugin(plugin);
await view.init();


// Add default photorealistic objects
const defaultLayers = plugin.addDefaultPhotorealScene();


// The sky light probe automatically follows the sun's position
defaultLayers.skyLightProbe.update({
  skyLightProbe: {
    intensity: 1.0
  }
});
```

--------------------------------

### getAnimationDetails(name) - Get animation details

Source: https://navara.world/docs/three_default_descs/mesh-desc/gltf-model-desc

Fetches detailed information for a specific animation by name. The example logs an object containing properties such as name, duration, tracks, isLooping, and timeScale.

```javascript
const details = modelDesc.ref.getAnimationDetails("Walk");
console.log(details);
// { name: "Walk", duration: 2.5, tracks: 45, isLooping: true, timeScale: 1.0 }

```

--------------------------------

### Basic 3D Tiles tileset example

Source: https://navara.world/docs/three/layer/3d-tiles-layer

Creates a 3D Tiles source from a URL and adds a layer with model appearance settings. The layer type is `"3d-tiles"` and the source is the returned tileset object. The model options include `show`, `color`, `metalness`, and `roughness`.

```javascript
import ThreeView, { Color } from "@navaramap/three";


const view = new ThreeView(/* options */);
await view.init();


const tileset = view.addSource({
  type: "3d-tiles",
  url: "https://example.com/tileset.json",
});


view.addLayer({
  type: "3d-tiles",
  source: tileset,
  model: { show: true, color: new Color().setHex(0xffffff), metalness: 0.1, roughness: 0.1 },
});
```

--------------------------------

### Configure and add PersonViewPlugin with character and camera settings

Source: https://navara.world/docs/three/tutorial/interior-explore

Set up the character model, animation clips, movement speeds, camera distance and pitch, altitude limits, and starting position. Add the plugin to the view before initializing. Adjust atmosphere and lighting after init.

```javascript
const startLat = 35.6341630282;
const startLng = 139.7420527162;
const startHeight = 59.05;
const startHeading = 288;


const personView = new PersonViewPlugin({
  character: {
    modelUrl: "/Soldier.glb",
    animation: {
      idleClip: "Idle",
      walkClip: "Walk",
      dashClip: "Run",
      speed: 1.0,
      crossfadeDuration: 0.3,
    },
    modelRotationOffset: { x: Math.PI / 2, y: 0, z: 0 },
    modelScale: 1,
    castShadow: true,
    receiveShadow: true,
  },
  moveSpeed: 5,
  altSpeed: 5,
  rotationSpeed: 2,
  cameraDistance: 8,
  cameraPitch: 3.4,
  cameraLerpSpeed: 4,
  minAlt: -1000,
  maxAlt: 5000,
  startLat,
  startLng,
  startHeight,
  startHeading,
  allowCameraControl: true,
});


view.addPlugin(personView);
await view.init();


view.atmosphere.date.setHours(8);
view.toneMappingExposure = 10;


const layers = plugin.addDefaultPhotorealScene();
layers.sun.update({
  sun: { castShadow: true, shadowFar: 1000, shadowLambda: 1 },
});
```

--------------------------------

### async init(): Promise<void>

Source: https://navara.world/docs/three/api/threeview-functions

Initializes the 3D engine and WASM modules, and starts the main rendering loop. Must be called before using the view.

```APIDOC
## async init(): Promise<void>

### Description
Initializes the 3D engine and WASM modules, and starts the main rendering loop. You must call this method before using the view.

### Method
init

### Syntax
```
async init(): Promise<void>
```

### Returns
- **Promise<void>** - Resolves when initialization is complete.

### Example
```
const view = new ThreeView();
await view.init();

// Add layers after init()
const osm = view.addSource({
  type: "raster-tile",
  url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
  maxZoom: 19,
});

view.addLayer({ type: "raster", source: osm });
```
```

--------------------------------

### Calculate geodesic distance and azimuth with EllipsoidGeodesic

Source: https://navara.world/docs/three/introduction/what-is-navara-three-api

Calculates the distance and azimuth along the Earth's surface between two points. The example creates an EllipsoidGeodesic instance with Tokyo and Osaka, then logs the distance in kilometers and the start heading in degrees.

```javascript
import { EllipsoidGeodesic } from "@navaramap/three";


const geodesic = new EllipsoidGeodesic(tokyo, osaka);
console.log(`Distance: ${geodesic.distance / 1000} km`);
console.log(`Azimuth: ${geodesic.startHeading}°`);
```

--------------------------------

### Set up ENU local coordinate system with eastNorthUpToFixedFrame

Source: https://navara.world/docs/three/introduction/what-is-navara-three-api

Sets up a local coordinate system (East-North-Up) with a specific point on the Earth as the origin. The example gets the transformation matrix for Tokyo and applies it to a mesh to correctly place it on the ground surface.

```javascript
import { eastNorthUpToFixedFrame, geodeticToVector3 } from "@navaramap/three";


// Get the ENU coordinate system transformation matrix with Tokyo as the origin
const origin = geodeticToVector3(tokyoLle);
const enuMatrix = eastNorthUpToFixedFrame(origin);


// Apply to a mesh to correctly place it on the ground surface
mesh.matrix.copy(enuMatrix);
```

--------------------------------

### Plugin Providing a High-Level API: setupScene Method

Source: https://navara.world/docs/three/core/plugin

Extends the basic plugin by adding a setupScene method that adds meshes, lights, and effects after initialization. The usage example shows calling setupScene after adding the plugin and initializing the view.

```typescript
import ThreeView, { Plugin, type ViewContext, type MeshHandle, type LightHandle } from "@navaramap/three";
import {
  SkyMeshDesc,
  SunLightDesc,
  AmbientLightDesc,
  ToneMappingEffectDesc,
  FXAAEffectDesc,
} from "@navaramap/three-default-descs";


class MyScenePlugin extends Plugin<ThreeView, ViewContext> {
  private view?: ThreeView;


  async init(view: ThreeView, _ctx: ViewContext) {
    this.view = view;


    view.registerMesh("sky", SkyMeshDesc);
    view.registerLight("sun", SunLightDesc);
    view.registerLight("ambient", AmbientLightDesc);
    view.registerEffect("toneMapping", ToneMappingEffectDesc);
    view.registerEffect("fxaa", FXAAEffectDesc);
  }


  /** Add basic lighting and effects to the scene */
  setupScene(): {
    sky: MeshHandle<SkyMeshDesc>;
    sun: LightHandle<SunLightDesc>;
  } {
    if (!this.view) throw new Error("Plugin is not initialized");


    const sky = this.view.addMesh<SkyMeshDesc>({ sky: {} });
    const sun = this.view.addLight<SunLightDesc>({
      sun: { intensity: 1.0, castShadow: true },
    });
    this.view.addLight({ ambient: { intensity: 0.3 } });
    this.view.addEffect({ toneMapping: {} });
    this.view.addEffect({ fxaa: {} });


    return { sky, sun };
  }
}
```

```typescript
const plugin = new MyScenePlugin();
const view = new ThreeView({});
view.addPlugin(plugin);
await view.init();


// Call plugin methods after initialization
const { sky, sun } = plugin.setupScene();
```

--------------------------------

### getAnimationAvailable() - Get available animation clips

Source: https://navara.world/docs/three_default_descs/mesh-desc/gltf-model-desc

Retrieves an array of available animation clip names. The returned array is logged to the console, showing example values ["Walk", "Run", "Jump"].

```javascript
const clips = modelDesc.ref.getAnimationAvailable();
console.log(clips); // ["Walk", "Run", "Jump"]

```

--------------------------------

### addPlugin() example

Source: https://navara.world/docs/three/api/threeview-functions

Shows how to register plugins before initializing the view. `addPlugin()` can be chained, and `init()` must be awaited after all plugins are added.

```typescript
const view = new ThreeView({});
view.addPlugin(pluginA).addPlugin(pluginB);
await view.init();
```

--------------------------------

### Basic Setup: Add DefaultPlugin to ThreeView

Source: https://navara.world/docs/three_default_plugin/about

Basic setup for using the DefaultPlugin. Import ThreeView and DefaultPlugin, create instances, add the plugin before init(), and initialize the view with a canvas element. This registers all default mesh, effect, and light descriptors.

```javascript
import ThreeView from "@navaramap/three";
import { DefaultPlugin } from "@navaramap/three-default-plugin";


const plugin = new DefaultPlugin();
const view = new ThreeView();


// Add plugin before init()
view.addPlugin(plugin);
await view.init({ canvas: document.getElementById("canvas") });
```

--------------------------------

### DefaultPlugin usage example

Source: https://navara.world/docs/three/introduction/about-plugin

Demonstrates using DefaultPlugin to register all default descriptors, then adding mesh, light, and effect objects after initialization.

```javascript
import ThreeView from "@navaramap/three";
import { DefaultPlugin } from "@navaramap/three-default-plugin";


const plugin = new DefaultPlugin();
const view = new ThreeView({});
view.addPlugin(plugin);
await view.init();


// All default descriptors are now available
view.addMesh({ sky: {} });
view.addLight({ sun: { intensity: 1.0 } });
view.addEffect({ toneMapping: {} });
```

--------------------------------

### resolveStartHeight(source)

Source: https://navara.world/docs/three_plugins/personviewplugin

Resolves the start height by sampling the terrain at the start position.

```APIDOC
## resolveStartHeight(source)

### Description
Pins `startHeight` to the terrain surface at the start position, sampled from the source's most detailed data via `ThreeView.sampleTerrainMostDetailed`. Call it before `start()`.

### Method
resolveStartHeight

### Signature
`resolveStartHeight(source: string | Source): Promise<number | undefined>`

### Parameters
- **source** (string | Source) - Required - The terrain source (registered quantized-mesh or raster-dem source).

### Returns
- **Promise<number | undefined>** - The height used, including the collision's `groundOffset`, or `undefined` when the source has no data at the start position.

### Example
```js
// terrain is a registered quantized-mesh or raster-dem source
await personView.resolveStartHeight(terrain);
personView.start();
```
```

--------------------------------

### Configure camera options examples

Source: https://navara.world/docs/three/api/camera

Shows three separate ways to configure view.camera.options: disabling all interactive controls, tuning inertia durations, and restricting the zoom range. Each assignment updates only the specified fields.

```javascript
// Disable all interactive controls (e.g. for programmatic camera only)
view.camera.options = {
  enableSpin: false,
  enableZoom: false,
  enableTilt: false,
};


// Tune inertia feel
view.camera.options = {
  spinDuration: 1000,
  zoomDuration: 50,
  translateDuration: 800,
};


// Restrict zoom range for a fixed-altitude application
view.camera.options = {
  minimumZoomDistance: 500,
  maximumZoomDistance: 5_000_000,
};
```

--------------------------------

### SkyMeshDesc moonIntensity property example

Source: https://navara.world/docs/three_default_descs/mesh-desc/sky-mesh-desc

Example showing how to set the moon brightness to 0.8.

```json
{
  sky: {
    moonIntensity: 0.8,
  }
}
```

--------------------------------

### sizeInMeters example

Source: https://navara.world/docs/three/material/billboard-material

Sets sizeInMeters to true, specifying the size in meters.

```json
{
  billboard: {
    sizeInMeters: true
  }
}
```

--------------------------------

### SkyMeshDesc moonScale property example

Source: https://navara.world/docs/three_default_descs/mesh-desc/sky-mesh-desc

Example showing how to set the moon scale to 1.5.

```json
{
  sky: {
    moonScale: 1.5,
  }
}
```

--------------------------------

### featureLeave event example

Source: https://navara.world/docs/three/api/threeview-events

Example of logging the properties of the feature that the pointer stopped hovering.

```javascript
view.on("featureLeave", (info) => {
  console.log("Left feature:", info.properties);
});
```

--------------------------------

### Full TubeMeshDesc usage example

Source: https://navara.world/docs/three_default_descs/mesh-desc/tube-mesh-desc

Shows how to import, register, and add a TubeMeshDesc to a ThreeView with all properties set.

```javascript
import ThreeView, { Color } from "@navaramap/three";
import { TubeMeshDesc } from "@navaramap/three-default-descs";


const view = new ThreeView();
view.registerMesh("tube", TubeMeshDesc);
await view.init();


// Add a TubeMeshDesc
const tubeDesc = view.addMesh<TubeMeshDesc>({
  tube: {
    points: [
      { x: 0, y: 0, z: 1000 },
      { x: 100, y: 50, z: 1100 },
      { x: 200, y: -50, z: 1000 },
      { x: 300, y: 0, z: 1000 },
    ],
    radius: 10,
    tubularSegments: 128,
    radialSegments: 16,
    color: new Color().setHex(0xff8800),
    tension: 0.5,
  },
});
```

--------------------------------

### EllipsoidGeodesic start getter signature

Source: https://navara.world/docs/three/api/navara_three_api

Declares the getter signature for the geodetic coordinates of the start point.

```typescript
get start(): LatLngHeight
```

--------------------------------

### Add an instance with handle.ref.add(config)

Source: https://navara.world/docs/three_default_descs/mesh-desc/instanced-sphere-mesh-desc

Adds a new instance to the instanced mesh. The method returns the index of the added instance. The example sets position, radius, and color for the new instance.

```javascript
const index = handle.ref.add({
  position: { x: 100, y: 0, z: 0 },
  radius: 20,
  color: new Color().setHex(0xffff00),
});

```

--------------------------------

### dispose() Example

Source: https://navara.world/docs/three/api/threeview-functions

Disposes the view on component unmount. The example shows a comment and a call to `view.dispose()`.

```typescript
// Cleanup on component unmount
view.dispose();
```

--------------------------------

### deleteEffectById() Example

Source: https://navara.world/docs/three/api/threeview-functions

Deletes an effect by its ID. The example passes the handle's ID to `deleteEffectById()`.

```typescript
view.deleteEffectById(handle.id);
```

--------------------------------

### deleteLightById() Example

Source: https://navara.world/docs/three/api/threeview-functions

Deletes a light by its ID. The example passes the handle's ID to `deleteLightById()`.

```typescript
view.deleteLightById(handle.id);
```

--------------------------------

### debugCSMHelper example

Source: https://navara.world/docs/three_default_descs/light-desc/sun-light-desc

Toggles debug visualization of shadow cascades. Default is `false`.

```json
{
  sun: {
    debugCSMHelper: false,
  }
}
```

--------------------------------

### init() Syntax

Source: https://navara.world/docs/three/api/threeview-functions

Initializes the 3D engine and WASM modules, and starts the main rendering loop. Must be called before using the view. Returns a `Promise<void>` that resolves when initialization is complete.

```typescript
async init(): Promise<void>
```

--------------------------------

### deleteMeshById() Example

Source: https://navara.world/docs/three/api/threeview-functions

Deletes a mesh by its ID. The example passes the handle's ID to `deleteMeshById()`.

```typescript
view.deleteMeshById(handle.id);
```