/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.143.

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);

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);

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.activeAnimations.add({
    name: "Walk",                          // glTF animation name
    loop: Cesium.ModelAnimationLoop.REPEAT, // NONE | REPEAT | MIRRORED_REPEAT
    multiplier: 1.0,                       // playback speed (must be > 0)
  });
  anim.start.addEventListener((m, a) => console.log(`Started: ${a.name}`));

  // Or play all animations at once
  model.activeAnimations.addAll({
    loop: Cesium.ModelAnimationLoop.REPEAT,
    multiplier: 0.5,
  });
});

Additional `add` options: `index`, `reverse`, `startTime`, `stopTime`, `delay`, `removeOnStop`, `animationTime` (custom time callback).

Animation Events

animation.start.addEventListener((model, animation) => { });
animation.update.addEventListener((model, animation, time) => { });
animation.stop.addEventListener((model, animation) => { });
// Collection-level
model.activeAnimations.animationAdded.addEventListener((model, anim) => { });

model.activeAnimations.remove(animation); // remove one
model.activeAnimations.removeAll();        // remove all

---

Model Nodes

Override named node transforms for procedural animation (e.g., turret rotation).

model.readyEvent.addEventListener(() => {
  const node = model.getNode("Turret");
  node.matrix = Cesium.Matrix4.fromScale(
    new Cesium.Cartesian3(5.0, 1.0, 1.0), node.matrix
  );
});

Properties: `name` (read-only), `id` (read-only index), `show` (boolean), `matrix` (Matrix4 -- set to `undefined` to restore original and re-enable glTF animations).

---

Coloring, Silhouettes, and Feature Picking

// Tint + silhouette
model.color = Cesium.Color.RED.withAlpha(0.5);
model.colorBlendMode = Cesium.ColorBlendMode.MIX;
model.colorBlendAmount = 0.5;
model.silhouetteColor = Cesi