cesiumjs-materials-shaders
CesiumJS materials and post-processing — Material, Fabric JSON, MaterialAppearance, ImageBasedLighting, PostProcessStage, PostProcessStageLibrary, bloom, depth of field, ambient occlusion, FXAA, tonemapping, BlendingState. Use when defining Fabric materials for entities or primitives, configuring PBR image-based lighting, or adding screen-space post-processing effects.
git clone --depth 1 https://github.com/CesiumGS/cesiumjs-skills /tmp/cesiumjs-materials-shaders && cp -r /tmp/cesiumjs-materials-shaders/skills/cesiumjs-materials-shaders ~/.claude/skills/cesiumjs-materials-shadersSKILL.md
# CesiumJS Materials, Shaders & Post-Processing
Version baseline: CesiumJS 1.142 (June 2026). All imports use ES module style.
## Material System (Fabric JSON)
`Material` defines surface appearance for **Primitives** through a JSON schema called Fabric. Materials compile to GLSL and are consumed by `MaterialAppearance` or `PolylineMaterialAppearance`.
### Built-in Material Types
**Surface:** `Color` (color), `Image` (image, repeat), `DiffuseMap`, `AlphaMap`, `SpecularMap`, `EmissionMap` (image, channel(s), repeat), `BumpMap`, `NormalMap` (image, channel(s), strength, repeat).
**Patterns:** `Grid` (color, cellAlpha, lineCount, lineThickness), `Stripe` (evenColor, oddColor, repeat), `Checkerboard` (lightColor, darkColor, repeat), `Dot` (lightColor, darkColor, repeat).
**Effects:** `Water` (baseWaterColor, normalMap, frequency, animationSpeed), `RimLighting` (color, rimColor, width), `Fade` (fadeInColor, fadeOutColor, maximumDistance).
**Terrain:** `ElevationContour` (color, spacing, width), `ElevationRamp` (image, minimumHeight, maximumHeight).
**Polyline:** `PolylineArrow` (color), `PolylineDash` (color, gapColor, dashLength, dashPattern), `PolylineGlow` (color, glowPower, taperPower), `PolylineOutline` (color, outlineColor, outlineWidth).
### Creating Materials
```js
import { Material, Color, Cartesian2 } from "cesium";
// Shorthand with fromType (preferred for built-in types)
const colorMat = Material.fromType("Color", { color: new Color(1.0, 0.0, 0.0, 0.5) });
// Full Fabric notation
const gridMat = new Material({
fabric: {
type: "Grid",
uniforms: { color: Color.GREEN, cellAlpha: 0.1, lineCount: new Cartesian2(8, 8) },
},
});
// Async loading -- awaits textures before first frame, no flicker
const imageMat = await Material.fromTypeAsync("Image", { image: "./textures/facade.png" });
```
### Custom Fabric with GLSL Source
Use `source` for inline GLSL. Uniforms declared in `uniforms` are available by name in the shader.
```js
import { Material, Color } from "cesium";
const pulseMaterial = new Material({
fabric: {
uniforms: { color: Color.CYAN, speed: 2.0 },
source: `czm_material czm_getMaterial(czm_materialInput materialInput) {
czm_material material = czm_getDefaultMaterial(materialInput);
float pulse = sin(czm_frameNumber * speed * 0.01) * 0.5 + 0.5;
material.diffuse = color.rgb;
material.alpha = color.a * pulse;
return material;
}`,
},
translucent: true,
});
```
### Applying Materials to Primitives
```js
import { Primitive, GeometryInstance, RectangleGeometry, Rectangle,
MaterialAppearance, Material, Color, Cartesian2 } from "cesium";
viewer.scene.primitives.add(new Primitive({
geometryInstances: new GeometryInstance({
geometry: new RectangleGeometry({ rectangle: Rectangle.fromDegrees(-100, 30, -90, 40) }),
}),
appearance: new MaterialAppearance({
material: Material.fromType("Checkerboard", {
lightColor: Color.WHITE, darkColor: Color.BLACK, repeat: new Cartesian2(4, 4),
}),
}),
}));
```
### Compositing Sub-Materials (Fabric `materials` + `components`)
```js
import { Material, Color } from "cesium";
const compositeMat = new Material({ fabric: {
materials: {
gridMaterial: { type: "Grid" },
colorMaterial: { type: "Color", uniforms: { color: Color.BLUE } },
},
components: {
diffuse: "gridMaterial.diffuse + 0.2 * colorMaterial.diffuse",
alpha: "min(gridMaterial.alpha, colorMaterial.alpha)",
},
}});
```
## CustomShader
`CustomShader` injects user GLSL into `Model`, `Cesium3DTileset`, and `VoxelPrimitive` rendering, with access to vertex attributes, feature IDs, and `EXT_structural_metadata`.
**For shader authoring — struct reference, metadata access, feature IDs, voxel subset, 1.139 breaking changes, and seven worked examples — see the `cesiumjs-custom-shader` skill.** This skill owns the `CustomShader` integration surface; the authoring depth lives there.
Minimal example:
```js
import { CustomShader, Model } from "cesium";
const shader = new CustomShader({
fragmentShaderText: `
void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
material.diffuse = vec3(1.0, 0.5, 0.0);
}
`,
});
const model = await Model.fromGltfAsync({ url: "./building.glb", customShader: shader });
viewer.scene.primitives.add(model);
```
## ImageBasedLighting
Controls PBR image-based lighting for `Model` and `Cesium3DTileset`. `imageBasedLightingFactor` (Cartesian2) scales diffuse (x) and specular (y) from 0 to 1. Diffuse comes from `sphericalHarmonicCoefficients` (array of 9 Cartesian3, L0-L2). Specular comes from `specularEnvironmentMaps` (URL to KTX2 cube map).
```js
import { ImageBasedLighting, Cartesian2, Cartesian3 } from "cesium";
const coefficients = [ // 9 Cartesian3 values for L0..L2 bands
new Cartesian3(0.35, 0.35, 0.38), new Cartesian3(0.11, 0.11, 0.11),
new Cartesian3(0.04, 0.04, 0.04), new Cartesian3(-0.08, -0.08, -0.08),
new Cartesian3(-0.02, -0.02, -0.02), new Cartesian3(0.04, 0.04, 0.04),
new Cartesian3(-0.06, -0.06, -0.06), new Cartesian3(0.01, 0.01, 0.01),
new Cartesian3(-0.03, -0.03, -0.03),
];
const ibl = new ImageBasedLighting({
imageBasedLightingFactor: new Cartesian2(1.0, 1.0),
sphericalHarmonicCoefficients: coefficients,
specularEnvironmentMaps: "./environment/specular.ktx2",
});
const model = await Cesium.Model.fromGltfAsync({ url: "./helmet.glb", imageBasedLighting: ibl });
viewer.scene.primitives.add(model);
// Disable: model.imageBasedLighting.imageBasedLightingFactor = new Cartesian2(0.0, 0.0);
```
## Post-Processing
Screen-space pipeline via `viewer.scene.postProcessStages` (`PostProcessStageCollection`). Stages execute in order; each reads `colorTexture` and `depthTexture`.
### Built-in Effects (PostProcessStageLibrary)
`createBlurStage()` (delta, sigma, stepSize), `createDepthOfFieldStage()` (focalDistance, delta, sigma, stepSize), `createEdgeDetectionStage()` (color, length), `createSiCesiumJS 3D Tiles - Cesium3DTileset, MVTDataProvider, styling, metadata, feature picking, voxels, point clouds, I3S, Gaussian splats, clipping planes and polygons. Use when loading 3D Tiles tilesets or Mapbox Vector Tiles as runtime 3D Tiles, styling building/vector features, querying metadata properties, working with voxels or point clouds, or clipping spatial data.
CesiumJS camera control - Camera, flyTo, lookAt, setView, ScreenSpaceCameraController, CameraEventAggregator, flight animation. Use when positioning the camera, creating flyTo animations, constraining user navigation, tracking entities, or converting between screen and world coordinates.
CesiumJS core utilities and networking - Resource, Color, Event, Request, RequestScheduler, error handling, helper functions, feature detection. Use when fetching remote data, managing HTTP requests, working with colors, handling events, debugging errors, or using utility functions like defined, clone, or buildModuleUrl.
CustomShader authoring — vertexShaderText and fragmentShaderText against VertexInput, FragmentInput, FeatureIds, Metadata, czm_modelMaterial. Use when reading EXT_mesh_features or EXT_structural_metadata property textures/tables, vertex displacement, or shading VoxelPrimitive.
CesiumJS entities and data sources - Entity, EntityCollection, DataSource, GeoJsonDataSource, KmlDataSource, CzmlDataSource, Graphics types, Visualizers. Use when adding points, labels, models, polygons, or polylines to the map, loading GeoJSON/KML/CZML/GPX data, or working with the high-level Entity API.
CesiumJS imagery layers - ImageryProvider, ImageryLayer, ImageryLayerCollection, WMS, WMTS, Bing, OpenStreetMap, ArcGIS, Mapbox, tile discard policies. Use when adding or swapping base map layers, configuring imagery providers, layering multiple map sources, or creating split-screen imagery comparisons.
CesiumJS interaction and picking - ScreenSpaceEventHandler, multi-key KeyboardEventModifier input actions, Scene.pick, Scene.drillPick, Scene.pickPosition, mouse and touch events. Use when handling user clicks on the globe, selecting entities or 3D Tiles features, registering modifier-key shortcuts, implementing hover effects, or building drag-based interactions.
CesiumJS models, glTF, and particle effects - Model, EdgeDisplayMode, ModelAnimation, ModelNode, ParticleSystem, emitters, GPM extensions. Use when loading glTF/GLB 3D models, controlling edge rendering, playing model animations, positioning particle effects like fire or smoke, or working with geospatial positioning metadata.