Styling and band math

Select bands, stretch values, apply colormaps, and derive bands with expressions.

The same TileStyle model serves the Rust API and the example server’s query string. Styles are validated before expensive COG reads and rendering work.

Common recipes

Natural-color RGB from three bands:

bidx=1&bidx=2&bidx=3&rescale=0,3000&rescale=0,3000&rescale=0,3000

Single-band color ramp:

bidx=1&colormap_name=viridis&rescale=0,3000

Percentile stretch:

stretch=percent&pc=2,98

Average downsampling and bilinear reprojection:

resampling=average&reproject=bilinear

Stretch behavior

For non-U8 data, the effective value range is selected in this order:

Explicit rescale=min,max values.
The requested stretch mode.
stretch=stddev&sigma=2.0 when neither is present.

U8 RGB data keeps its 0–255 fast path. Dataset statistics come from embedded STATISTICS_* tags when present; otherwise the highest overview is sampled once and the estimate is memoized.

Arithmetic expressions

expression computes one derived output band. Band references are 1-indexed:

expression=(b5-b4)/(b5+b4)&rescale=-1,1&colormap_name=viridis

This NDVI formula is only correct when band 5 is near-infrared and band 4 is red in the selected COG. The library does not infer spectral roles from band numbers; verify the asset metadata and adjust the references before using the formula. A pre-rendered STAC visual asset is not automatically suitable for this example.

When used in a URL, percent-encode / and +:

curl --output ndvi.png \
  'http://127.0.0.1:8080/tiles/WebMercatorQuad/0/0/0.png?expression=(b5-b4)%2F(b5%2Bb4)&rescale=-1,1&colormap_name=viridis'

The grammar supports finite decimal numbers, parentheses, binary +, -, *, /, and unary -. Multiplication and division bind more tightly than addition and subtraction. Scientific notation is not supported.

expression is mutually exclusive with bidx and color_formula, and it accepts at most one rescale range. Nodata inputs, division by zero, and other non-finite results become transparent pixels. Input is bounded to 4096 bytes, 256 tokens, and 128 nesting levels.

Color formulas

The supported rio-color subset applies operations from left to right:

gamma
sigmoidal
saturation

For example:

color_formula=gamma RGB 1.5

Percent-encode spaces when the formula is placed in a URL query string.