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. Categorical palettes mirror the Rust palette registry; sequential/diverging palettes interpolate using the same stop definitions as the Rust renderer.

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.	`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', '#21918c', '#fde725']

to_hex ¶

to_hex(color: tuple[float, ...] | str) -> 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] (floats) or [0, 255] (ints), or a hex string (returned as-is after normalization).	required

Returns:

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

Raises:

Type	Description
`ValueError`	If the input format is not recognized.

Examples:

>>> import ferrum
>>> ferrum.color.to_hex((1.0, 0.0, 0.0))
'#ff0000'
>>> ferrum.color.to_hex((255, 0, 0))
'#ff0000'

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.

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.

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