---
type: Architecture Decision
title: Numeric raster encoding and palettes
description: Keep numeric pixel encoding in Channel and raster colors in Layer presentation.
tags: [rendering, raster, channel, layer, palette]
visibility: public
---

# Rule

A raster is paletteable only when its [Channel](/catalog/channel.md) 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](/presentation/layer.md) 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

1. Decide whether pixels are RGB presentation or encoded numeric values.
2. For numeric pixels, declare codec, range, validity channel, quantity, and
   unit in `value_encoding`.
3. Put the recommended palette in Data Product defaults so the active and
   Original snapshots are copied into each new Layer.
4. Verify palette switching, legend values, provider alpha, and globe zooms
   `4.99`, `5`, `5.5`, `6`, and `6.01`.
5. Add fail-closed render-contract tests and catalog migration tests.