/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 { Viewer, ImageryLayer, OpenStreetMapImageryProvider } from "cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

const viewer = new Viewer("cesiumContainer", {
  baseLayer: new ImageryLayer(new OpenStreetMapImageryProvider({
    url: "https://tile.openstreetmap.org/",
    maximumLevel: 18,
  })),
  baseLayerPicker: false,
});

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

Use Cesium ion defaults (`Terrain.fromWorldTerrain`, `ImageryLayer.fromWorldImagery`, `createOsmBuildingsAsync`, Google Photorealistic 3D Tiles) only when the target runtime has the required ion or Google entitlement. For public/no-token examples, choose explicit public providers and URL-backed 3D Tiles.

Framing Loaded Content (Critical)

**After adding a tileset, model, or data source, you must explicitly frame it.** A `Viewer` constructed with default options starts the camera at a fixed view of Earth. It does NOT auto-zoom to primitives you add. Forgetting this is the most common cause of "I see only gray surface" or "the asset is a speck in the corner" failures.

const tileset = await Cesium3DTileset.fromUrl(url);
viewer.scene.primitives.add(tileset);

// Pick ONE of:
await viewer.zoomTo(tileset);                 // instant fit to bounding sphere
await viewer.flyTo(tileset, { duration: 0 }); // animated; duration 0 = instant

`viewer.zoomTo` / `viewer.flyTo` accept `Entity`, `Entity[]`, `EntityCollection`, `DataSource`, `ImageryLayer`, `Cesium3DTileset`, `VoxelPrimitive`, `Model`, or `TimeDynamicPointCloud`. They use the target's bounding sphere, which works for tilesets with arbitrary local coordinate systems where computing an ECEF camera position by hand will miss the asset entirely.

When you do need an explicit camera position (e.g., to satisfy a heading/pitch specification), still use `viewer.zoomTo(target, headingPitchRange)` so the range is derived from the bounding sphere rather than guessed:

import { HeadingPitchRange, Math as CesiumMath } from "cesium";

await viewer.zoomTo(tileset, new HeadingPitchRange(
  CesiumMath.toRadians(45),   // heading
  CesiumMath.toRadians(-30),  // pitch
  /* range omitted -> auto-fit */
));

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);
await viewer.zoomTo(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 per geometry instance | | `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 |

Pair `requestRenderMode: true` with `scene3DOnly: true` for low-power / dashboard apps; both are commonly required together when the scenario calls for GPU savings.

#