Basic Usage Guide

This guide covers the fundamental usage patterns for chromo-map, from basic color creation to working with gradients and swatches.

Getting Started

First, install chromo-map:

pip install chromo-map

Then import the main classes:

from chromo_map import Color, Gradient, Swatch

Creating Colors

Colors can be created from various input formats:

From Hex Strings

# Standard 6-digit hex
red = Color('#ff0000')
blue = Color('#0066cc')

# Short 3-digit hex (automatically expanded)
green = Color('#0f0')  # Becomes #00ff00

From Named Colors

# CSS/HTML color names
red = Color('red')
blue = Color('cornflowerblue')
green = Color('forestgreen')

From RGB Tuples

# Integer RGB (0-255)
red = Color((255, 0, 0))
blue = Color((0, 102, 204))

# Normalized RGB (0.0-1.0)
green = Color((0.0, 1.0, 0.0))

From RGBA (with transparency)

# With alpha channel
semi_transparent_red = Color((255, 0, 0, 0.5))
transparent_blue = Color('#0066cc80')  # Hex with alpha

Working with Color Properties

Once you have a Color object, you can access various properties:

color = Color('#ff6b35')  # Orange color

# Basic properties
print(f"Hex: {color.hex}")           # #ff6b35
print(f"RGB: {color.rgb}")           # (255, 107, 53)
print(f"RGBA: {color.rgba}")         # (255, 107, 53, 1.0)

# Color space conversions
print(f"HSV: {color.hsv}")           # (16.83, 0.79, 1.0)
print(f"HSL: {color.hsl}")           # (16.83, 1.0, 0.60)

# Individual components
print(f"Hue: {color.hue}")           # 16.83 degrees
print(f"Saturation: {color.saturation}")  # 0.79
print(f"Value: {color.value}")       # 1.0

Color Manipulation

Colors can be modified in various ways:

Adjust Components

original = Color('#ff6b35')

# Adjust hue (shift around color wheel)
shifted = original.adjust_hue(30)     # Shift 30 degrees

# Adjust saturation (color intensity)
more_saturated = original.adjust_saturation(0.2)   # +20%
less_saturated = original.adjust_saturation(-0.3)  # -30%

# Adjust brightness/value
brighter = original.adjust_brightness(0.2)   # +20%
darker = original.adjust_brightness(-0.2)    # -20%

# Adjust lightness (HSL)
lighter = original.adjust_lightness(0.1)     # +10%

Color Relationships

base = Color('#3498db')  # Blue

# Get complementary color (opposite on color wheel)
complement = base.complementary()

# Get analogous colors (adjacent on color wheel)
analogous = base.analogous(count=3)  # Returns list of 3 colors

Creating Gradients

Gradients represent sequences of colors with smooth transitions:

From Color Lists

# Simple two-color gradient
red_to_blue = Gradient(['red', 'blue'], 10)

# Multi-color gradient
rainbow = Gradient(['red', 'orange', 'yellow', 'green', 'blue'], 20)

# Using Color objects
colors = [Color('#ff0000'), Color('#00ff00'), Color('#0000ff')]
custom_gradient = Gradient(colors, 15)

From Existing Colormaps

# From matplotlib colormaps
viridis = Gradient.from_mpl('viridis', 100)
plasma = Gradient.from_mpl('plasma', 50)

# From the catalog
from chromo_map import get_gradient
cool_gradient = get_gradient('cool')

Working with Gradients

Gradients behave like sequences and support many list-like operations:

Accessing Colors

gradient = Gradient(['red', 'blue'], 10)

# Get individual colors
first_color = gradient[0]         # First color
last_color = gradient[-1]        # Last color
middle_color = gradient[5]       # Middle color

# Get slices
first_half = gradient[:5]        # First 5 colors
subset = gradient[2:8]           # Colors 2-7

Gradient Operations

original = Gradient(['red', 'blue'], 10)

# Reverse the gradient
reversed_grad = original.reverse()

# Resample to different length
longer = original.resample(20)      # 20 colors instead of 10
shorter = original.resample(5)      # 5 colors instead of 10

# Adjust properties of all colors
brighter = original.adjust_brightness(0.2)
more_saturated = original.adjust_saturation(0.3)

Creating Swatches

Swatches organize multiple gradients for comparison and display:

# Create multiple gradients
gradients = [
    Gradient(['red', 'pink'], 10),
    Gradient(['blue', 'lightblue'], 10),
    Gradient(['green', 'lightgreen'], 10),
    Gradient(['purple', 'lavender'], 10)
]

# Create swatch
swatch = Swatch(gradients, ncols=2)  # Display in 2 columns

Working in Jupyter Notebooks

chromo-map provides rich visual representations in Jupyter notebooks:

Color Display

# Colors show as colored squares with hover info
color = Color('#ff6b35')
color  # Displays as colored square

Gradient Display

# Gradients show as horizontal color bars
gradient = Gradient(['red', 'blue'], 20)
gradient  # Displays as smooth color transition

Swatch Display

# Swatches show as organized grids
swatch = Swatch([
    Gradient(['red', 'white'], 10),
    Gradient(['blue', 'white'], 10)
])
swatch  # Displays as grid of gradients

Common Patterns

Creating Theme Colors

# Define a base brand color
brand_color = Color('#3498db')

# Create variations for different UI elements
primary = brand_color
secondary = brand_color.adjust_saturation(-0.3)
accent = brand_color.complementary()
light = brand_color.adjust_lightness(0.3)
dark = brand_color.adjust_lightness(-0.3)

Generating Color Scales

# Create a monochromatic scale
base = Color('#e74c3c')
scale = Gradient([
    base.adjust_lightness(0.4),   # Very light
    base.adjust_lightness(0.2),   # Light
    base,                         # Base
    base.adjust_lightness(-0.2),  # Dark
    base.adjust_lightness(-0.4)   # Very dark
], 20)

Data Visualization Setup

import matplotlib.pyplot as plt
from chromo_map import get_gradient

# Get a perceptually uniform colormap
gradient = get_gradient('viridis')

# Use with matplotlib
plt.imshow(data, cmap=gradient.to_mpl())
plt.colorbar()

Matplotlib Compatibility

The Gradient class is fully compatible with matplotlib colormaps, allowing you to use any chromo-map gradient as a drop-in replacement. This gives you access to professional color schemes from Plotly and Palettable that aren’t available in matplotlib.

Using Plotly Colors in Matplotlib

import matplotlib.pyplot as plt
import numpy as np
from chromo_map import cmaps

# Get the Plotly qualitative palette (10 colors)
plotly_colors = cmaps.plotly_by_type['qualitative']['Plotly']

# Create sample data for area plot
x = np.linspace(0, 10, 100)
data = np.array([np.sin(x + i) + i*0.3 for i in range(len(plotly_colors))])

# Create area plot using each color from the Plotly palette
fig, ax = plt.subplots(figsize=(10, 6))
for i, series in enumerate(data):
    ax.fill_between(x, i*0.2, series + i*0.2,
                   color=plotly_colors[i].hex,
                   alpha=0.7, label=f'Series {i+1}')

ax.set_title('Area Plot Using Plotly Color Palette')
ax.legend(bbox_to_anchor=(1.05, 1), loc='upper left')
plt.tight_layout()

Enhanced Color Manipulation

# Create a lightened version of the same palette
lightened_colors = plotly_colors.adjust_saturation(.75)

# Create another plot with the modified colors
fig, ax = plt.subplots(figsize=(10, 6))
for i, series in enumerate(data):
    ax.fill_between(x, i*0.2, series + i*0.2,
                   color=lightened_colors[i].hex,
                   alpha=0.7, label=f'Light Series {i+1}')

ax.set_title('Same Plot with Lightened Plotly Colors')
ax.legend(bbox_to_anchor=(1.05, 1), loc='upper left')
plt.tight_layout()

This demonstrates the key advantage of chromo-map: access to professional color palettes with enhanced manipulation capabilities while maintaining full matplotlib compatibility.

Next Steps

This covers the fundamental usage patterns. The API is designed to be intuitive and follows Python conventions, making it easy to integrate into existing workflows.