Color tables & band colors¶

Two ways rasters carry colour:

• color_table — a paletted (single-band) raster maps each value to an RGBA colour.
• band_color / get_band_by_color — a multi-band image tags each band with a colour interpretation (red / green / blue …).

Setup¶

In [1]:

%matplotlib inline

import tempfile
from pathlib import Path

import numpy as np

DATA = Path('../../../examples/data')
WORK = Path(tempfile.mkdtemp(prefix='pyramids-t3-'))
DATA.is_dir(), WORK.is_dir()

%matplotlib inline import tempfile from pathlib import Path import numpy as np DATA = Path('../../../examples/data') WORK = Path(tempfile.mkdtemp(prefix='pyramids-t3-')) DATA.is_dir(), WORK.is_dir()

Out[1]:

(True, True)

Read a palette — color_table¶

Returns a table of value → RGBA for a paletted raster.

In [2]:

from pyramids.dataset import Dataset

paletted = Dataset.read_file(DATA / 'geotiff' / 'coello-with-color-table.tif')
ct = paletted.color_table
list(ct.columns), len(ct)

from pyramids.dataset import Dataset paletted = Dataset.read_file(DATA / 'geotiff' / 'coello-with-color-table.tif') ct = paletted.color_table list(ct.columns), len(ct)

2026-07-11 14:41:29 | INFO | pyramids.base.config | Logging is configured.

Out[2]:

(['band', 'values', 'red', 'green', 'blue', 'alpha'], 10)

In [3]:

ct.head()

ct.head()

Out[3]:

	band	values	red	green	blue	alpha
0	1	0	0	0	0	0
1	1	1	112	153	89	255
2	1	2	0	0	0	0
3	1	3	242	238	162	255
4	1	4	0	0	0	0

The paletted raster — band 0 holds the class values that the color table above maps to RGBA.

In [4]:

paletted.plot(band=0, title="Paletted raster (class values)", cmap="tab10")

paletted.plot(band=0, title="Paletted raster (class values)", cmap="tab10")

Out[4]:

<cleopatra.array_glyph.ArrayGlyph at 0x7fb3437c8d70>

Tag band colours — band_color / get_band_by_color¶

Build a 3-band image and label the bands (0-based). get_band_by_color looks a band up by its colour.

In [5]:

from pyramids.dataset.merge import stack_bands

rgb_path = WORK / 'rgb.tif'
stack_bands([DATA / 'acc4000.tif'] * 3, path=rgb_path)
rgb = Dataset.read_file(rgb_path)
rgb.band_color = {0: 'red', 1: 'green', 2: 'blue'}
rgb.band_color, rgb.get_band_by_color('green')

from pyramids.dataset.merge import stack_bands rgb_path = WORK / 'rgb.tif' stack_bands([DATA / 'acc4000.tif'] * 3, path=rgb_path) rgb = Dataset.read_file(rgb_path) rgb.band_color = {0: 'red', 1: 'green', 2: 'blue'} rgb.band_color, rgb.get_band_by_color('green')

Out[5]:

({0: 'red', 1: 'green', 2: 'blue'}, 1)

The 3-band stack just built — plotting band 0 (the red-tagged band) shows the data behind the colour interpretation labels.

In [6]:

rgb.plot(band=0, title="RGB stack — band 0 (red)", cmap="Reds")

rgb.plot(band=0, title="RGB stack — band 0 (red)", cmap="Reds")

Out[6]:

<cleopatra.array_glyph.ArrayGlyph at 0x7fb343754b90>

/home/runner/work/pyramids/pyramids/.pixi/envs/docs/lib/python3.14/site-packages/matplotlib/colors.py:816: RuntimeWarning: overflow encountered in multiply
  xa *= self.N

Notes¶

• color_table also has a setter — assign a DataFrame of value/red/green/blue/alpha to write a palette.
• See also: Visualization (to_image(cmap=...) for ad-hoc colour maps).