/cesiumjs-viewer-setup

name: cesiumjs-viewer-setup
description: "CesiumJS viewer setup - Viewer, CesiumWidget, widgets, Ion token, Scene configuration, SceneMode, factory helpers, geocoders, platform services. Use when initializing a CesiumJS application, configuring viewer widgets, setting Ion access tokens, creating default terrain or imagery, or bootstrapping a 3D globe."

CesiumJS Viewer & Scene Setup

Reference for bootstrapping CesiumJS applications: Viewer, CesiumWidget, Ion/GoogleMaps/ITwinPlatform configuration, widgets, factory helpers, geocoder services, viewer mixins, Credits, and related enums.

Quick Start

import { Ion, Viewer, Terrain } from "cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

// Always set your Ion token before any other Cesium calls
Ion.defaultAccessToken = "YOUR_CESIUM_ION_ACCESS_TOKEN";

const viewer = new Viewer("cesiumContainer", {
  terrain: Terrain.fromWorldTerrain(),
});

Required HTML: `<div id="cesiumContainer" style="width:100%;height:100vh"></div>`

Ion & Platform Configuration

Cesium Ion

import { Ion } from "cesium";

Ion.defaultAccessToken = "YOUR_TOKEN";  // required for ion assets
Ion.defaultServer = "https://your-ion-server.example.com/"; // optional: self-hosted

IonResource

import { IonResource, Cesium3DTileset } from "cesium";

const resource = await IonResource.fromAssetId(96188);
const tileset = await Cesium3DTileset.fromUrl(resource);
viewer.scene.primitives.add(tileset);

Google Maps Platform

import { GoogleMaps, createGooglePhotorealistic3DTileset, Viewer, IonGeocodeProviderType } from "cesium";

GoogleMaps.defaultApiKey = "YOUR_GOOGLE_MAPS_API_KEY"; // optional: without key, served via ion

const viewer = new Viewer("cesiumContainer", {
  geocoder: IonGeocodeProviderType.GOOGLE, // required with Google 3D Tiles
});

const tileset = await createGooglePhotorealistic3DTileset({
  onlyUsingWithGoogleGeocoder: true,
});
viewer.scene.primitives.add(tileset);

iTwin Platform (experimental)

import { ITwinPlatform, ITwinData } from "cesium";

ITwinPlatform.defaultAccessToken = "YOUR_ITWIN_TOKEN";
const tileset = await ITwinData.createTilesetForIModel(viewer, "imodel-id");

// 1.140+ (#13208): Reality Data of type GaussianSplat3DTiles is now supported
const splats = await ITwinData.createTilesetForRealityDataId(
  iTwinId,
  realityDataId,
  ITwinPlatform.RealityDataType.GaussianSplat3DTiles,
);
viewer.scene.primitives.add(splats);

Viewer Constructor Options

`new Viewer(container, options?)` -- `container` is a DOM element or its string ID.

Widget Toggles

| Option | Default | Purpose | |--------|---------|---------| | `animation` | `true` | Playback controls | | `baseLayerPicker` | `true` | Imagery/terrain switcher | | `fullscreenButton` | `true` | Fullscreen toggle | | `vrButton` | `false` | WebVR toggle | | `geocoder` | `IonGeocodeProviderType.DEFAULT` | Search bar (`false` to hide) | | `homeButton` | `true` | Reset to home view | | `infoBox` | `true` | Entity info popup | | `sceneModePicker` | `true` | 2D/3D/Columbus toggle | | `selectionIndicator` | `true` | Selection reticle | | `timeline` | `true` | Time scrubber | | `navigationHelpButton` | `true` | Mouse/touch help | | `projectionPicker` | `false` | Perspective/ortho toggle |

Scene & Rendering

| Option | Default | Purpose | |--------|---------|---------| | `sceneMode` | `SceneMode.SCENE3D` | Initial scene mode | | `scene3DOnly` | `false` | Lock to 3D, saves GPU memory | | `shadows` | `false` | Shadow casting | | `terrainShadows` | `ShadowMode.RECEIVE_ONLY` | Terrain shadow mode | | `requestRenderMode` | `false` | Render only on changes | | `maximumRenderTimeChange` | `0.0` | Max sim-time delta for render | | `msaaSamples` | `4` | MSAA (1 to disable) | | `orderIndependentTranslucency` | `true` | Translucent ordering | | `mapMode2D` | `MapMode2D.INFINITE_SCROLL` | 2D scroll behavior |

Layers & Terrain

| Option | Default | Purpose | |--------|---------|---------| | `baseLayer` | `ImageryLayer.fromWorldImagery()` | Base imagery (`false` for none; needs `baseLayerPicker: false`) | | `terrain` | none | Async terrain helper (cannot combine with `terrainProvider`) | | `terrainProvider` | `EllipsoidTerrainProvider` | Sync terrain provider | | `globe` | `new Globe()` | `false` for no globe (space scenes) | | `skyBox` | auto (WGS84) | `false` disables sky/sun/moon | | `skyAtmosphere` | auto (WGS84) | `false` disables limb glow |

Minimal Viewer (No Widgets)

import { Viewer, Ion, Terrain } from "cesium";
Ion.defaultAccessToken = "YOUR_TOKEN";

const viewer = new Viewer("cesiumContainer", {
  animation: false, baseLayerPicker: false, fullscreenButton: false,
  geocoder: false, homeButton: false, infoBox: false,
  sceneModePicker: false, selectionIndicator: false,
  timeline: false, navigationHelpButton: false,
  terrain: Terrain.fromWorldTerrain(),
});

CesiumWidget (Lightweight Alternative)

No UI widgets, no Knockout dependency. Suitable for custom UIs or embedding.

import { CesiumWidget, Ion } from "cesium";
Ion.defaultAccessToken = "YOUR_TOKEN";

const widget = new CesiumWidget("cesiumContainer", { shouldAnimate: true });
// Exposes: widget.scene, widget.camera, widget.entities

SceneMode Enum

| Value | Description | |-------|-------------| | `SceneMode.SCENE3D` | Standard 3D globe (default) | | `SceneMode.SCENE2D` | Top-down orthographic map | | `SceneMode.COLUMBUS_VIEW` | 2.5D flat map with height | | `SceneMode.MORPHING` | Transitioning between modes |

import { Viewer, SceneMode } from "cesium";

const viewer = new Viewer("cesiumContainer", { sceneMode: SceneMode.SCENE2D });
viewer.scene.morphTo3D(2.0);          // animated transition
viewer.scene.morphToColumbusView(2.0);

Scene Configuration

const scene = viewer.scene;
scene.globe.depthTestAgainstTerrain = true; // entities interact with terrain
scene.globe.enableLighting = true;