Rule
A raster is paletteable only when its Channel declares a validated, presentation-neutral value_encoding. The contract records the pixel codec, numeric range, validity or NoData channel, quantity, and unit. It does not contain colors.
The Layer owns rasterScalarPalette, including optional per-stop opacity, plus overall opacity and resampling. A Data Product may provide a recommended palette for newly created Layers, but changing that default must not recolor existing maps.
When a provider-backed Layer is created, its resolved initial palette is also copied to rasterScalarOriginalPalette. A multi-channel add carries distinct snapshots in rasterScalarOriginalPalettes, keyed by immutable Channel export key, until the resulting Layers resolve their own binding. The palette picker exposes the applicable immutable snapshot as Original; later choices replace only rasterScalarPalette. Layers created before these fields use their semantic quantity default as the compatibility snapshot on the first change.
Supported path
Encoded r8-linear and rg16-linear tile pyramids use the shared scalar palette controls, legend, and Mapbox raster-color path. Provider alpha remains authoritative for transparent NoData pixels. Invalid or incomplete encoding is fail-closed rather than guessed from image contents.
The shared picker may offer continuous ramps and solid-color ramps. A solid ramp keeps one hue while interpolating from its light tint to its saturated color across the numeric domain. Palette stops remain opaque; provider alpha alone makes NoData pixels transparent.
Boundary
RGB and true-color imagery is presentation data, not a scalar field. It remains an ordinary raster unless the provider supplies an explicit numeric encoding contract. Never place a palette or provider-specific color stops in Channel endpoint configuration.
Checklist for a new raster integration
unit in value_encoding.
Original snapshots are copied into each new Layer.
4.99, 5, 5.5, 6, and 6.01.
- Decide whether pixels are RGB presentation or encoded numeric values.
- For numeric pixels, declare codec, range, validity channel, quantity, and
- Put the recommended palette in Data Product defaults so the active and
- Verify palette switching, legend values, provider alpha, and globe zooms
- Add fail-closed render-contract tests and catalog migration tests.