Skip to content

flixopt.color_processing

Simplified color handling for visualization.

This module provides clean color processing that transforms various input formats into a label-to-color mapping dictionary, without needing to know about the plotting engine.

Attributes

ColorType module-attribute 

ColorType = str | list[str] | dict[str, str]

Flexible color specification type supporting multiple input formats for visualization.

Color specifications can take several forms to accommodate different use cases:

Named colorscales (str): - Standard colorscales: 'turbo', 'plasma', 'cividis', 'tab10', 'Set1' - Energy-focused: 'portland' (custom flixopt colorscale for energy systems) - Backend-specific maps available in Plotly and Matplotlib

Color Lists (list[str]): - Explicit color sequences: ['red', 'blue', 'green', 'orange'] - HEX codes: ['#FF0000', '#0000FF', '#00FF00', '#FFA500'] - Mixed formats: ['red', '#0000FF', 'green', 'orange']

Label-to-Color Mapping (dict[str, str]): - Explicit associations: {'Wind': 'skyblue', 'Solar': 'gold', 'Gas': 'brown'} - Ensures consistent colors across different plots and datasets - Ideal for energy system components with semantic meaning

Examples:

# Named colorscale
colors = 'turbo'  # Automatic color generation

# Explicit color list
colors = ['red', 'blue', 'green', '#FFD700']

# Component-specific mapping
colors = {
    'Wind_Turbine': 'skyblue',
    'Solar_Panel': 'gold',
    'Natural_Gas': 'brown',
    'Battery': 'green',
    'Electric_Load': 'darkred'
}
Color Format Support
  • Named Colors: 'red', 'blue', 'forestgreen', 'darkorange'
  • HEX Codes: '#FF0000', '#0000FF', '#228B22', '#FF8C00'
  • RGB Tuples: (255, 0, 0), (0, 0, 255) [Matplotlib only]
  • RGBA: 'rgba(255,0,0,0.8)' [Plotly only]
References
  • HTML Color Names: https://htmlcolorcodes.com/color-names/
  • Matplotlib colorscales: https://matplotlib.org/stable/tutorials/colors/colorscales.html
  • Plotly Built-in Colorscales: https://plotly.com/python/builtin-colorscales/

Functions

color_to_rgba 

color_to_rgba(color: str | None, alpha: float = 1.0) -> str

Convert any valid color to RGBA string format.

Handles hex colors (with or without #), named colors, and rgb/rgba strings.

Parameters:

Name Type Description Default
color str | None

Color in any valid format (hex '#FF0000' or 'FF0000', named 'red', rgb 'rgb(255,0,0)', rgba 'rgba(255,0,0,1)').

 required
alpha float

Alpha/opacity value between 0.0 and 1.0.

 1.0

Returns:

Type Description
str

Color in RGBA format 'rgba(R, G, B, A)'.

Examples:

>>> color_to_rgba('#FF0000')
'rgba(255, 0, 0, 1.0)'
>>> color_to_rgba('FF0000')
'rgba(255, 0, 0, 1.0)'
>>> color_to_rgba('red', 0.5)
'rgba(255, 0, 0, 0.5)'
>>> color_to_rgba('forestgreen', 0.4)
'rgba(34, 139, 34, 0.4)'
>>> color_to_rgba(None)
'rgba(200, 200, 200, 1.0)'

process_colors 

process_colors(colors: None | str | list[str] | dict[str, str], labels: list[str], default_colorscale: str = 'turbo') -> dict[str, str]

Process color input and return a label-to-color mapping.

This function takes flexible color input and always returns a dictionary mapping each label to a specific color string. The plotting engine can then use this mapping as needed.

Parameters:

Name Type Description Default
colors None | str | list[str] | dict[str, str]

Color specification in one of four formats: - None: Use the default colorscale - str: Name of a colorscale (e.g., 'turbo', 'plasma', 'Set1', 'portland') - list[str]: List of color strings (hex, named colors, etc.) - dict[str, str]: Direct label-to-color mapping

 required
labels list[str]

List of labels that need colors assigned

 required
default_colorscale str

Fallback colorscale name if requested scale not found

 'turbo'

Returns:

Type Description
dict[str, str]

Dictionary mapping each label to a color string

Examples:

>>> # Using None - applies default colorscale
>>> process_colors(None, ['A', 'B', 'C'])
{'A': '#0d0887', 'B': '#7e03a8', 'C': '#cc4778'}

>>> # Using a colorscale name
>>> process_colors('plasma', ['A', 'B', 'C'])
{'A': '#0d0887', 'B': '#7e03a8', 'C': '#cc4778'}

>>> # Using a list of colors
>>> process_colors(['red', 'blue', 'green'], ['A', 'B', 'C'])
{'A': 'red', 'B': 'blue', 'C': 'green'}

>>> # Using a pre-made mapping
>>> process_colors({'A': 'red', 'B': 'blue'}, ['A', 'B', 'C'])
{'A': 'red', 'B': 'blue', 'C': '#0d0887'}  # C gets color from default scale