/cesiumjs-models-particles

name: cesiumjs-models-particles
description: "CesiumJS models, glTF, and particle effects - Model, KHR_meshopt_compression, CAD glTF extensions, EdgeDisplayMode, ModelAnimation, ModelNode, ParticleSystem, emitters, GPM extensions. Use when loading compressed or CAD-style glTF/GLB models, controlling edge rendering, playing model animations, positioning particles, or working with geospatial positioning metadata."

CesiumJS Models, glTF & Particle Effects

Version baseline: CesiumJS v1.144.

Quick Reference

| Class | Purpose | |---|---| | `Model` | Low-level glTF/GLB primitive; positioned via `modelMatrix` | | `ModelAnimation` | Active animation instance on a model | | `ModelAnimationCollection` | Collection at `model.activeAnimations` | | `ModelNode` | Named node with modifiable transform | | `ModelFeature` | Per-feature styling/picking for feature-ID models | | `EdgeDisplayMode` | Controls draft glTF edge-visibility rendering on Model/Cesium3DTileset | | `ParticleSystem` | Billboard-based particle manager (fire, smoke, rain) | | `Particle` | Single particle with position, velocity, life | | `ParticleBurst` | Scheduled burst of particles | | `BoxEmitter` / `CircleEmitter` | Emit within box volume / flat disk | | `ConeEmitter` / `SphereEmitter` | Emit from cone tip / within sphere |

The Entity API exposes models through `ModelGraphics` (see cesiumjs-entities). The Primitive API uses `Model.fromGltfAsync` for full control over `modelMatrix`, animations, and node transforms.

---

Loading a glTF/GLB Model

Always use the async factory -- never call the constructor directly.

import { Model, Cartesian3, Transforms, HeadingPitchRoll, Math as CesiumMath } from "cesium";

const model = await Model.fromGltfAsync({ url: "path/to/model.glb" });
viewer.scene.primitives.add(model);

Public Sample Models

CesiumJS ships sample models usable without ion tokens:

https://raw.githubusercontent.com/CesiumGS/cesium/main/Apps/SampleData/models/CesiumAir/Cesium_Air.glb
https://raw.githubusercontent.com/CesiumGS/cesium/main/Apps/SampleData/models/CesiumMan/Cesium_Man.glb
https://raw.githubusercontent.com/CesiumGS/cesium/main/Apps/SampleData/models/CesiumMilkTruck/CesiumMilkTruck.glb

CesiumJS 1.143 decodes `KHR_meshopt_compression` automatically, including the v1 attribute codec and `COLOR` filter. Do not import a decoder or private loader helper. When loading compressed glTF, CAD-style lines/points/edges, or constant-LOD textures, read [REFERENCE.md](REFERENCE.md) for the complete support and authoring matrix. The same loader behavior applies to glTF content inside 3D Tiles.

Positioned Model with Heading

const position = Cartesian3.fromDegrees(-123.074, 44.050, 5000);
const hpr = new HeadingPitchRoll(CesiumMath.toRadians(135), 0, 0);

const model = await Model.fromGltfAsync({
  url: "CesiumAir.glb",
  modelMatrix: Transforms.headingPitchRollToFixedFrame(position, hpr),
  minimumPixelSize: 128,  // never smaller than 128 px on screen
  maximumScale: 20000,    // cap for minimumPixelSize enlargement
  scale: 2.0,             // uniform scale multiplier
});
viewer.scene.primitives.add(model);

> **Visual eval framing:** for model screenshots, the model must be fully inside > the frame and recognizable, not clipped at the bottom edge. Use > `minimumPixelSize` 256-400 for public sample aircraft, add a subtle > `silhouetteColor`/`silhouetteSize`, and place the camera with explicit > coordinates aimed at the known model position. Avoid shallow pitches that put > the model below the frame or rely on `viewer.flyTo(model)`, which is > version-sensitive for `Model` primitives.

Avoiding Distorted Model Appearance

Models can appear stretched or warped when scale is applied non-uniformly or when the orientation matrix is built incorrectly. Common pitfalls:

• **Always use `Transforms.headingPitchRollToFixedFrame` (or the Entity API's `headingPitchRollQuaternion`) for ground-aligned orientation.** Hand-rolled quaternions often invert pitch/roll axes and produce vertically stretched silhouettes.
• **Use `scale` (uniform) for size, not a non-uniform `Matrix4.fromScale`.** A non-uniform scale baked into `modelMatrix` will distort the model. Reserve `Matrix4.fromScale` for per-node tweaks (e.g., stretching a single turret), not the whole model.
• **Pair `minimumPixelSize` with a sensible `maximumScale`.** Without a cap, distant small models can balloon to fill the frame and look elongated when the camera is close.

Key `Model.fromGltfAsync` Options

| Option | Type | Default | |---|---|---| | `url` | `string\|Resource` | required | | `modelMatrix` | `Matrix4` | `IDENTITY` | | `scale` | `number` | `1.0` | | `minimumPixelSize` | `number` | `0.0` | | `maximumScale` | `number` | -- | | `show` | `boolean` | `true` | | `color` / `colorBlendMode` / `colorBlendAmount` | `Color` / `ColorBlendMode` / `number` | -- / `HIGHLIGHT` / `0.5` | | `edgeDisplayMode` | `EdgeDisplayMode` | `SURFACES_ONLY` | | `silhouetteColor` / `silhouetteSize` | `Color` / `number` | `RED` / `0.0` | | `shadows` | `ShadowMode` | `ENABLED` | | `heightReference` | `HeightReference` | `NONE` | | `customShader` | `CustomShader` | -- | | `id` | `any` | -- | | `allowPicking` | `boolean` | `true` |

---

Readiness and Lifecycle

`fromGltfAsync` resolves once glTF JSON is parsed, but WebGL resources may still load. Wait for `readyEvent` before accessing animations, nodes, or `boundingSphere`.

const model = await Model.fromGltfAsync({ url: "robot.glb" });
viewer.scene.primitives.add(model);

model.readyEvent.addEventListener(() => {
  console.log("Bounding sphere:", model.boundingSphere);
});

// Synchronous check
if (model.ready) { const bs = model.boundingSphere; }

---

Animations

Managed through `model.activeAnimations` (`ModelAnimationCollection`).

Play by Name / Play All

model.readyEvent.addEventListener(() => {
  // Single animation
  const anim = model.activeAni