ferrum.color¶

Programmatic access to ferrum's color palettes — categorical, sequential, and diverging.

Programmatic access to ferrum's color palettes.

Provides functions to retrieve hex color arrays from named categorical, sequential, and diverging palettes. The Rust palette registry (crates/ferrum-core/src/render/palette.rs + crates/ferrum-core/src/render/color/continuous.rs) is the single source of truth: this module consumes it through the ferrum._core accessors (list_palettes, palette_kind, palette_colors, palette_sample) rather than re-declaring hex tables. Continuous palettes are sampled from the same interpolator the renderer uses, so color.palette("viridis") returns the colors that actually render.

palette ¶

palette(name: str, n: int | None = None) -> list[str]

Return hex colors from a named palette.

Parameters:

Name	Type	Description	Default
`name`	`str`	Palette name (e.g., "tableau10", "okabe_ito", "viridis").	required
`n`	`int`	Number of colors. For categorical palettes, wraps cyclically if n exceeds the palette length. For continuous palettes, interpolates n evenly-spaced colors (render-truth samples).	`None`

Returns:

Type	Description
`list[str]`	Hex color strings (e.g., `["#1f77b4", ...]`).

Raises:

Type	Description
`ValueError`	If name is not a recognized palette.

Examples:

>>> import ferrum
>>> ferrum.color.palette("tableau10")[:3]
['#4c78a8', '#f58e18', '#e45756']
>>> ferrum.color.palette("viridis", n=3)
['#440154', '#20908c', '#fde725']

to_hex ¶

to_hex(color: tuple[float, ...] | str, *, scale: Literal['unit', 'byte'] | None = None) -> str

Convert a color to a hex string.

Parameters:

Name	Type	Description	Default
`color`	`tuple or str`	An RGB tuple with values in [0, 1] (unit) or [0, 255] (byte) — only the first 3 components are read, so a 4^th (alpha) component is silently ignored — or a color string: a CSS named color (e.g. `"steelblue"`), hex (`#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa`), or a functional `rgb()`/`rgba()` form. String input is validated and normalized by ferrum's single Rust color parser (`parse_color`), so this function accepts the exact vocabulary every other ferrum color boundary accepts, alpha included.	required
`scale`	`('unit', 'byte')`	Explicit interpretation of an RGB tuple's component range. `"unit"` treats components as floats in `[0, 1]`; `"byte"` treats them as integers in `[0, 255]`. When `None` (default) the range is inferred: any component greater than 1 forces byte interpretation; otherwise unit interpretation is used. This makes integer-valued floats (`1.0`) and integers (`1`) behave identically. Ignored for string input.	`"unit"`

Returns:

Type	Description
`str`	Normalized hex string. For string input: `"#rrggbb"`, or `"#rrggbbaa"` when the parsed color carried alpha (e.g. an `rgba()` or 4/8-digit hex input). For tuple input: always `"#rrggbb"` — a 4^th tuple component is not alpha-encoded into the output (see the `color` parameter above).

Raises:

Type Description

ValueError

If a string input is not a recognized CSS color name, hex literal, or rgb()/rgba() form (the message names the accepted forms); if the string is a paint-clearing sentinel ("none"/"transparent", trimmed and case-insensitive) — those spellings clear paint at the mark/selection boundaries (MarkBase.__init__, selection.py) and have no hex form here, so the message says that instead of the generic accepted-forms text, which would be self-contradicting for "transparent" (a real CSS Color 4 keyword); if a tuple input's format is not recognized; or if scale is not one of "unit", "byte", or None.

Examples:

>>> import ferrum
>>> ferrum.color.to_hex((1.0, 0.0, 0.0))
'#ff0000'
>>> ferrum.color.to_hex((255, 0, 0))
'#ff0000'
>>> ferrum.color.to_hex((128, 128, 128), scale="byte")
'#808080'
>>> ferrum.color.to_hex("steelblue")
'#4682b4'
>>> ferrum.color.to_hex("rgb(70, 130, 180)")
'#4682b4'

sequential ¶

sequential(name: str, n: int = 256) -> list[str]

Return n interpolated colors from a sequential palette.

Parameters:

Name	Type	Description	Default
`name`	`str`	Sequential palette name (e.g., "viridis", "plasma", "magma", "inferno", "cividis", "blues", "cool_blue", "warm_ochre", "night_blue", "electric_lime", "signal_blue", "ember_orange").	required
`n`	`int`	Number of interpolated colors.	`256`

Returns:

Type	Description
`list[str]`	Hex color strings (render-truth samples).

Raises:

Type	Description
`ValueError`	If name is not a recognized sequential palette.

Examples:

>>> import ferrum
>>> colors = ferrum.color.sequential("viridis", n=5)
>>> len(colors)
5

diverging ¶

diverging(name: str, n: int = 11) -> list[str]

Return n colors from a diverging palette, centered.

Parameters:

Name	Type	Description	Default
`name`	`str`	Diverging palette name (e.g., "rdbu", "blue_to_red", "cyan_to_amber", "blue_to_violet").	required
`n`	`int`	Number of colors (odd recommended for a distinct center point).	`11`

Returns:

Type	Description
`list[str]`	Hex color strings (render-truth samples).

Raises:

Type	Description
`ValueError`	If name is not a recognized diverging palette.

Examples:

>>> import ferrum
>>> colors = ferrum.color.diverging("rdbu", n=5)
>>> len(colors)
5