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), or a hex string (returned as-is after normalization).	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.	`"unit"`

Returns:

Type	Description
`str`	Hex string like `"#1f77b4"`.

Raises:

Type	Description
`ValueError`	If the input format is not recognized, or 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'

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