Color Encoding

Loading…

Rendering

Mesh: Taxi.glb

Color encodingSpansAtlas

Code

Choose Spans or Atlas on the same mesh. colorEncoding: "atlas" stores glyph/color pairs as Private Use Area (PUA) code points in a COLR/CPAL color font: one text node per output layer, without color spans.

The text identifies palette slots; @font-palette-values maps those slots to colors. Palette swaps can recolor the text without rebuilding the font. Live scenes load the font and manage its CSS automatically; unsupported output falls back to spans.

The palette: atlasPalette

scene.setOptions({ atlasPalette: ["#172554", "#2563eb", "#93c5fd", "#ffffff"] });

Omit this option to derive and pool a palette automatically. Supply an ordered array of #rrggbb colors for repeatable slot assignments; stay within the chosen atlas’s slot limit.

Choosing an atlas: fontAtlas

import { createGlyphScene, GLYPH_FONT_ATLAS_ASCII } from "glyphcss";
const scene = createGlyphScene(host, {
  camera, colorEncoding: "atlas", fontAtlas: GLYPH_FONT_ATLAS_ASCII,
});

Atlas	Glyphs	Palette slots
GLYPH_FONT_ATLAS (default)	212; ASCII plus selected Unicode ramps/edges	30
GLYPH_FONT_ATLAS_ASCII	94; printable ASCII excluding space	68
GLYPH_FONT_ATLAS_BRAILLE_DOTS	256 braille patterns as rectangular dots in a 1 × 1.6 cell (used by @glyphcss/fluid); set font-size and line-height to the cell height	30

fontAtlas is fixed at scene creation. React/Vue expose the same prop; custom elements take it as a JavaScript property. Space remains ordinary U+0020. A glyph outside the selected atlas triggers span fallback.

Make an atlas from your own font

This requires a local source build. There is no public live-scene API for registering a custom font payload; passing a new GlyphFontAtlas object alone falls back to spans.

1. In packages/glyphcss/assets/glyph-atlas/build-atlas.py, change SRC to your font’s absolute path. The script reads face 0; choose a font you can redistribute.
2. Keep its glyph enumeration and PUA mapping. The universal build requires every enumerated glyph, using the vendored fallback fonts for missing outlines.
3. From the repository root, regenerate the artifacts and rebuild the package:

python3 -m venv .venv-atlas
.venv-atlas/bin/python -m pip install fonttools brotli
.venv-atlas/bin/python packages/glyphcss/assets/glyph-atlas/build-atlas.py
.venv-atlas/bin/python packages/glyphcss/assets/glyph-atlas/build-atlas.py ascii
pnpm install
pnpm --filter glyphcss build

The script writes atlas.json (metadata) and atlas-font.json (WOFF2 payload); the ASCII invocation writes their ascii- counterparts. Your local package’s shipped atlas objects then use the rebuilt fonts. Changing the page’s CSS font alone cannot change the atlas outlines.

Fallback and text handling

• Missing font/browser support, uncovered glyphs, or unusable cell colors select spans for the whole output.
• Braille character mode is outside both atlases. Halfblock/quadrant, active weight ramps, semantic output, and disabled colors bypass atlas encoding.
• A glyph-triggered fallback stays latched until setOptions touches colorEncoding, atlasPalette, mode, or charMode.
• Browser find-in-page cannot match PUA text. Decode it before copying; raw copy otherwise retains private code points.

import { decodeGlyphAtlasText, glyphAtlasForFamily } from "glyphcss";
const atlas = glyphAtlasForFamily(scene.output.style.fontFamily);
const text = decodeGlyphAtlasText(scene.output.textContent ?? "", atlas);

Static and compiled output

compileScene and GlyphSceneStatic require an explicit atlasPalette and embedder-supplied CSS for atlas output. Use the same atlas for compilation, font CSS, and palette CSS:

const css = await loadGlyphAtlasFontFaceCss(atlas)
  + buildGlyphAtlasFontPaletteValuesCss("--brand", palette, atlas)
  + `.glyph-output{font-family:"${atlas.family}";font-palette:--brand}`;

Both helpers are exported from glyphcss; the loader rejects unavailable payloads. Frame-roll, interactive, and field-synth static exporters do not carry atlas options. Atlas removes span overhead; it does not reduce grid cells. See performance.