Utility Functions

The utilities module provides helper functions for color format conversion and manipulation.

Color Format Conversion

chromo_map.rgba_to_tup(rgbstr)[source]

Convert an RGBA string to a tuple.

Return type:

Optional[Tuple[float, float, float, float]]

Convert RGBA values to tuples:

from chromo_map import rgba_to_tup

# Convert rgba string to tuple
rgba_str = "rgba(255, 128, 0, 0.8)"
rgba_tuple = rgba_to_tup(rgba_str)
print(rgba_tuple)  # (255, 128, 0, 0.8)
chromo_map.hexstr_to_tup(hexstr)[source]

Convert a hex string to a tuple.

Return type:

Optional[Tuple[float, float, float, float]]

Convert hex strings to RGB tuples:

from chromo_map import hexstr_to_tup

# Convert hex to RGB tuple
hex_color = "#ff8000"
rgb_tuple = hexstr_to_tup(hex_color)
print(rgb_tuple)  # (255, 128, 0)

# Works with 3-digit hex too
short_hex = "#f80"
rgb_tuple = hexstr_to_tup(short_hex)
print(rgb_tuple)  # (255, 136, 0)
chromo_map.clr_to_tup(clr)[source]

Convert a color to a tuple.

Return type:

Any

Universal color-to-tuple converter:

from chromo_map import clr_to_tup

# Works with various formats
from_hex = clr_to_tup("#ff8000")        # (255, 128, 0)
from_rgba = clr_to_tup("rgba(255, 128, 0, 1)")  # (255, 128, 0, 1)
from_name = clr_to_tup("orange")        # Named color
from_tuple = clr_to_tup((255, 128, 0))  # Pass-through

Format Support

The utility functions support a wide range of color formats:

Hex Formats

  • #RRGGBB (6-digit hex)

  • #RGB (3-digit hex, expanded to 6-digit)

  • With or without the # prefix

RGB/RGBA Formats

  • rgb(r, g, b) string format

  • rgba(r, g, b, a) string format with alpha

  • Tuple formats: (r, g, b) and (r, g, b, a)

Named Colors

  • CSS color names (red, blue, orange, etc.)

  • Matplotlib color names

  • X11 color names

Normalized Formats

  • Floating-point values in range [0, 1]

  • Integer values in range [0, 255]

Conversion Examples

Hex to RGB

from chromo_map import hexstr_to_tup

colors = ["#ff0000", "#00ff00", "#0000ff"]
rgb_colors = [hexstr_to_tup(color) for color in colors]
print(rgb_colors)
# [(255, 0, 0), (0, 255, 0), (0, 0, 255)]

RGBA String Parsing

from chromo_map import rgba_to_tup

rgba_strings = [
    "rgba(255, 0, 0, 1.0)",
    "rgba(0, 255, 0, 0.5)",
    "rgb(0, 0, 255)"  # Also handles rgb format
]

tuples = [rgba_to_tup(rgba) for rgba in rgba_strings]
print(tuples)
# [(255, 0, 0, 1.0), (0, 255, 0, 0.5), (0, 0, 255)]

Universal Conversion

from chromo_map import clr_to_tup

mixed_formats = [
    "#ff0000",              # Hex
    "rgb(0, 255, 0)",       # RGB string
    "blue",                 # Named color
    (255, 255, 0),          # RGB tuple
    (255, 0, 255, 0.8)      # RGBA tuple
]

standardized = [clr_to_tup(color) for color in mixed_formats]

Error Handling

The utility functions include robust error handling:

from chromo_map import clr_to_tup

try:
    # Invalid hex format
    result = clr_to_tup("#invalid")
except ValueError as e:
    print(f"Error: {e}")

try:
    # Invalid RGB values
    result = clr_to_tup("rgb(300, 400, 500)")  # Values > 255
except ValueError as e:
    print(f"Error: {e}")

Integration with Core Classes

These utilities are used internally by the core classes but are also available for direct use:

from chromo_map import Color, clr_to_tup

# Manual conversion
rgb_tuple = clr_to_tup("#ff8000")

# Automatic conversion in Color class
color = Color("#ff8000")  # Uses clr_to_tup internally

# Both produce equivalent results
assert color.rgb == rgb_tuple[:3]  # (ignoring alpha)

Performance Considerations

Caching

The conversion functions use internal caching for named colors to improve performance.

Input Validation

All functions validate input formats and provide clear error messages for invalid inputs.

Memory Efficiency

Functions avoid creating unnecessary intermediate objects for large batch conversions.

Best Practices

Use Universal Converter

When working with mixed input formats, use clr_to_tup() for consistency.

Batch Processing

For converting many colors, consider using list comprehensions or map():

from chromo_map import clr_to_tup

# Efficient batch conversion
hex_colors = ["#ff0000", "#00ff00", "#0000ff"]
rgb_tuples = list(map(clr_to_tup, hex_colors))
Type Consistency

Ensure consistent output types in your applications by choosing the appropriate conversion function.

Extension Points

The utility module is designed to be extensible. You can add custom format support by:

  1. Extending the conversion functions

  2. Adding new format detection logic

  3. Integrating with additional color libraries

This makes chromo-map adaptable to specialized color format requirements in specific domains.