Color Coversion Helper

GitHub Link to Code.

Color conversion utilities for structure visualization.

This module provides utilities for converting between color formats (HEX, RGB, PyMOL) and mixing colors for overlapping features.

class mdxplain.structure_visualization.helper.color_conversion_helper.ColorConversionHelper

Helper class for color format conversions and mixing.

Provides static methods for converting HEX colors to various formats (RGB tuples, PyMOL format) and for mixing multiple colors via RGB averaging. Used by both NGLView and PyMOL visualizations.

Examples

>>> # Convert HEX to RGB
>>> rgb = ColorConversionHelper.hex_to_rgb("#ff0000")
>>> print(rgb)
(255, 0, 0)

>>> # Mix colors
>>> mixed = ColorConversionHelper.mix_hex_colors(["#ff0000", "#0000ff"])
>>> print(mixed)
'#7f007f'

>>> # Convert to PyMOL format
>>> pymol_color = ColorConversionHelper.hex_to_pymol_rgb("#ff0000")
>>> print(pymol_color)
'0xff0000'

static hex_to_rgb(hex_color: str) → tuple

Convert HEX color to RGB tuple.

Parameters

hex_colorstr: HEX color string (e.g., “#ff0000” or “ff0000”)

Returns

tuple: RGB values (r, g, b) as integers (0-255)

Examples

>>> ColorConversionHelper.hex_to_rgb("#ff0000")
(255, 0, 0)
>>> ColorConversionHelper.hex_to_rgb("00ff00")
(0, 255, 0)

Notes

Leading ‘#’ is automatically stripped if present.

static hex_to_pymol_rgb(hex_color: str) → str

Convert HEX color to PyMOL RGB format.

PyMOL uses hexadecimal color format with ‘0x’ prefix instead of ‘#’. This method performs the conversion.

Parameters

hex_colorstr: HEX color string (e.g., “#ff0000” or “ff0000”)

Returns

str: PyMOL RGB format (e.g., “0xff0000”)

Examples

>>> ColorConversionHelper.hex_to_pymol_rgb("#ff0000")
'0xff0000'
>>> ColorConversionHelper.hex_to_pymol_rgb("00ff00")
'0x00ff00'

Notes

Leading ‘#’ is automatically stripped if present before adding PyMOL’s ‘0x’ prefix.

static calculate_average_rgb(rgb_values: List[tuple]) → tuple

Calculate average RGB values from multiple RGB tuples.

Averages RGB components independently using integer division. Used as intermediate step in color mixing.

Parameters

rgb_valuesList[tuple]: List of RGB tuples, each containing (r, g, b) integers

Returns

tuple: Average (r, g, b) values as integers

Examples

>>> rgb_list = [(255, 0, 0), (0, 0, 255)]
>>> ColorConversionHelper.calculate_average_rgb(rgb_list)
(127, 0, 127)

Notes

Uses integer division (//) for averaging, which may cause small rounding differences compared to float averaging.

static mix_hex_colors(hex_colors: List[str]) → str

Calculate RGB average of multiple HEX colors.

Mixes multiple colors by converting to RGB, averaging each component independently, and converting back to HEX. Used for visualizing overlapping features with blended colors.

Parameters

hex_colorsList[str]: List of HEX color strings (e.g., [“#ff0000”, “#0000ff”])

Returns

str: Mixed color as HEX string (#RRGGBB)

Examples

>>> # Mix red and blue to get purple
>>> mixed = ColorConversionHelper.mix_hex_colors(
...     ["#ff0000", "#0000ff"]
... )
>>> print(mixed)
'#7f007f'

>>> # Mix three colors
>>> mixed = ColorConversionHelper.mix_hex_colors(
...     ["#ff0000", "#00ff00", "#0000ff"]
... )

>>> # Empty list returns gray
>>> ColorConversionHelper.mix_hex_colors([])
'#808080'

Notes

Empty list returns neutral gray (#808080)
Integer division may cause small rounding differences
All colors weighted equally in averaging