# Cesiumjs Terrain Environment

> CesiumJS terrain, globe, and environment - TerrainProvider, Globe, sampleTerrain, atmosphere, sky, fog, lighting, shadows, panoramas. Use when configuring terrain providers, querying terrain heights, customizing atmosphere or sky rendering, adding panoramas, or adjusting scene lighting and shadows.

- **Type:** Skill
- **Install:** `agentstack add skill-cesiumgs-cesiumjs-skills-cesiumjs-terrain-environment`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CesiumGS](https://agentstack.voostack.com/s/cesiumgs)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [CesiumGS](https://github.com/CesiumGS)
- **Source:** https://github.com/CesiumGS/cesiumjs-skills/tree/main/skills/cesiumjs-terrain-environment

## Install

```sh
agentstack add skill-cesiumgs-cesiumjs-skills-cesiumjs-terrain-environment
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CesiumJS Terrain, Globe & Environment

Version baseline: CesiumJS v1.142 | ES module imports (`import { ... } from "cesium";`)

## Terrain Providers

Terrain is served through `TerrainProvider` implementations. Use async factory methods
(`fromIonAssetId`, `fromUrl`), not the constructor directly.

### Cesium Ion World Terrain

```js
import { Viewer, Terrain } from "cesium";

const viewer = new Viewer("cesiumContainer", {
  terrain: Terrain.fromWorldTerrain({
    requestVertexNormals: true, // smoother lighting
    requestWaterMask: true,     // ocean water effect
  }),
});
```

### CesiumTerrainProvider from Ion Asset / URL

```js
import { CesiumTerrainProvider } from "cesium";

// By Ion asset ID (e.g. 3956 = Arctic DEM)
const tp = await CesiumTerrainProvider.fromIonAssetId(3956, {
  requestVertexNormals: true,
});
viewer.scene.globe.terrainProvider = tp;

// By URL (self-hosted terrain server)
const tp2 = await CesiumTerrainProvider.fromUrl(
  "https://my-server.example.com/terrain",
  { requestVertexNormals: true },
);
```

### EllipsoidTerrainProvider (Flat Globe)

```js
import { EllipsoidTerrainProvider } from "cesium";
// Flat ellipsoid -- no terrain data, useful for 2D/Columbus or testing
viewer.scene.globe.terrainProvider = new EllipsoidTerrainProvider();
```

### CustomHeightmapTerrainProvider (Procedural)

```js
import { CustomHeightmapTerrainProvider } from "cesium";

viewer.scene.globe.terrainProvider = new CustomHeightmapTerrainProvider({
  width: 32,
  height: 32,
  callback: function (x, y, level) {
    const buf = new Float32Array(32 * 32);
    for (let r = 0; r 0)
fog.screenSpaceErrorFactor = 2.0;
fog.minimumBrightness = 0.03;   // prevents completely black fog
```

## Sun and Moon

```js
viewer.scene.sun = new Cesium.Sun();
viewer.scene.sun.show = true;
viewer.scene.moon.show = true; // follows real lunar ephemeris
```

## Lighting

`scene.light` controls the scene light source. Default is `SunLight` (follows clock).

```js
import { SunLight, DirectionalLight, Cartesian3, Color } from "cesium";

// SunLight -- follows the Sun position based on scene clock
viewer.scene.light = new SunLight({ color: Color.WHITE, intensity: 2.0 });

// DirectionalLight -- fixed direction for studio-style lighting
viewer.scene.light = new DirectionalLight({
  direction: new Cartesian3(0.2, -0.5, -0.8), // must be non-zero
  color: Color.WHITE,
  intensity: 1.5,
});

viewer.scene.globe.enableLighting = true; // required for light to affect terrain
```

`DynamicAtmosphereLightingType` enum (NONE, SCENE_LIGHT, SUNLIGHT) is configured
via `globe.enableLighting`, `globe.dynamicAtmosphereLighting`, and
`globe.dynamicAtmosphereLightingFromSun` flags.

## Shadows

Cascaded shadow maps from the scene light source.

```js
viewer.shadows = true;
const sm = viewer.shadowMap;
sm.maximumDistance = 5000.0; // cascade range (meters)
sm.softShadows = true;      // PCF for softer edges
sm.darkness = 0.3;           // 0 = invisible, 1 = black
sm.fadingEnabled = true;     // fade near horizon

viewer.scene.globe.shadows = Cesium.ShadowMode.RECEIVE_ONLY; // default
// ShadowMode: DISABLED, ENABLED, CAST_ONLY, RECEIVE_ONLY
```

## Panoramas (v1.139+)

360-degree imagery at a scene location. Two formats: equirectangular and cube map.

### EquirectangularPanorama

```js
import {
  EquirectangularPanorama, Cartesian3,
  HeadingPitchRoll, Transforms, Math as CesiumMath,
} from "cesium";

const position = Cartesian3.fromDegrees(-75.17, 39.95, 100.0);
const hpr = new HeadingPitchRoll(CesiumMath.toRadians(45), 0, 0);
const transform = Transforms.headingPitchRollToFixedFrame(position, hpr);

viewer.scene.primitives.add(new EquirectangularPanorama({
  transform,
  image: "path/to/equirectangular-360.jpg",
  radius: 100000.0,
}));
```

### CubeMapPanorama

```js
import { CubeMapPanorama, Cartesian3, Transforms, Matrix3, Matrix4 } from "cesium";

const pos = Cartesian3.fromDegrees(-122.42, 37.77, 10.0);
const northDown = Transforms.localFrameToFixedFrameGenerator("north", "down");
const xform = Matrix4.getMatrix3(northDown(pos), new Matrix3());

viewer.scene.primitives.add(new CubeMapPanorama({
  sources: {
    positiveX: "px.jpg", negativeX: "nx.jpg",
    positiveY: "py.jpg", negativeY: "ny.jpg",
    positiveZ: "pz.jpg", negativeZ: "nz.jpg",
  },
  transform: xform,
}));
```

### GoogleStreetViewCubeMapPanoramaProvider

```js
import { GoogleStreetViewCubeMapPanoramaProvider, Cartographic } from "cesium";

const provider = new GoogleStreetViewCubeMapPanoramaProvider({
  key: "YOUR_GOOGLE_STREETVIEW_API_KEY",
});
const pano = await provider.loadPanorama({
  cartographic: Cartographic.fromDegrees(-122.42, 37.77, 0),
});
viewer.scene.primitives.add(pano);
```

## Terrain Provider Events

```js
viewer.scene.globe.terrainProviderChanged.addEventListener((newProvider) => {
  console.log("Terrain changed:", newProvider.constructor.name);
});
```

## Performance Tips

1. **Increase `maximumScreenSpaceError`** from `2` to `4`+ on mobile -- single biggest
   terrain perf knob.
2. **Keep fog enabled** (default) -- culls distant tiles, reducing draw calls.
3. **Avoid per-frame `verticalExaggeration` changes** -- forces terrain tile reloads.
4. **Set `requestVertexNormals: true` only when lighting is enabled** -- doubles tile size.
5. **Skip `requestWaterMask`** (default false) when `showWaterEffect` is off.
6. **Prefer `sampleTerrain` over `sampleTerrainMostDetailed`** when approximate heights
   suffice -- resolves faster with fewer tile requests.
7. **Batch terrain sampling** -- pass all positions in one array to share tile loads.
8. **Tune `tileCacheSize`** -- increase for zoom-heavy workflows, decrease for memory.
9. **Disable `showGroundAtmosphere`** on non-Earth ellipsoids to avoid artifacts.
10. **Keep `depthTestAgainstTerrain = false`** (default) to avoid z-fighting with
    labels and billboards near the surface.

## Quick Reference

| Class / Function | Purpose |
|---|---|
| `CesiumTerrainProvider.fromIonAssetId(id, opts)` | Ion terrain asset |
| `CesiumTerrainProvider.fromUrl(url, opts)` | Self-hosted terrain |
| `EllipsoidTerrainProvider` | Flat ellipsoid (no terrain) |
| `CustomHeightmapTerrainProvider` | Procedural/callback terrain |
| `ArcGISTiledElevationTerrainProvider` | ArcGIS elevation service |
| `sampleTerrain(provider, level, positions)` | Heights at fixed LOD |
| `sampleTerrainMostDetailed(provider, positions)` | Heights at max LOD |
| `Globe` | Surface rendering, terrain, atmosphere |
| `GlobeTranslucency` | See-through globe for underground views |
| `createElevationBandMaterial` | Color surface by elevation |
| `SkyAtmosphere` | Atmospheric limb glow |
| `SkyBox` / `SkyBox.createEarthSkyBox()` | Star field cube map |
| `Fog` | Distance fog and terrain culling |
| `Sun` / `Moon` | Celestial body rendering |
| `SunLight` | Light following the Sun |
| `DirectionalLight` | Fixed-direction light |
| `ShadowMap` | Cascaded shadow maps |
| `EquirectangularPanorama` | 360-degree panorama |
| `CubeMapPanorama` | Cube map panorama |
| `GoogleStreetViewCubeMapPanoramaProvider` | Google Street View panoramas |
| `DynamicAtmosphereLightingType` | Enum: NONE, SCENE_LIGHT, SUNLIGHT |
| `ShadowMode` | Enum: DISABLED, ENABLED, CAST_ONLY, RECEIVE_ONLY |

## See Also

- **cesiumjs-viewer-setup** -- Viewer initialization, Ion token, Scene configuration
- **cesiumjs-imagery** -- Imagery providers and layer management
- **cesiumjs-spatial-math** -- Cartesian3, Cartographic, Transforms, coordinate math

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CesiumGS](https://github.com/CesiumGS)
- **Source:** [CesiumGS/cesiumjs-skills](https://github.com/CesiumGS/cesiumjs-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cesiumgs-cesiumjs-skills-cesiumjs-terrain-environment
- Seller: https://agentstack.voostack.com/s/cesiumgs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.