Color Mapping Module

Color mapping functions and custom colormaps for terrain visualization.

This module provides functions for mapping elevation and slope data to colors using matplotlib colormaps, including custom perceptually uniform colormaps optimized for terrain visualization.

Custom Colormaps

michigan - Michigan Natural Landscape Colormap

Perceptually uniform progression through Michigan’s natural features:

  • Great Lakes (deep blue) → Northern forests (evergreen) → Upland meadows → Sand dunes (tan)

  • Desaturated ~35% for subtle, sun-bleached appearance

  • Works well as base layer in dual colormaps

Example:

from src.terrain.color_mapping import elevation_colormap

colors = elevation_colormap(
    dem_data,
    cmap_name='michigan',
    gamma=1.0
)
boreal_mako - Boreal-Mako Winter Forest Colormap

Perceptually uniform winter forest palette with purple ribbon for edge effect:

  • Dark boreal green (cool, blue-tinted forest)

  • Blue → purple ribbon → cyan → white

  • Monotonically increasing luminance (like viridis/mako)

  • Used in Combined Render: Full-Featured Example for sledding score visualization

Access via the global boreal_mako_cmap variable:

from src.terrain.color_mapping import boreal_mako_cmap

# Use directly with matplotlib
import matplotlib.pyplot as plt
plt.imshow(data, cmap=boreal_mako_cmap)

# Or use by name
colors = elevation_colormap(data, cmap_name='boreal_mako')
src.terrain.color_mapping._build_boreal_mako_cmap(purple_position=0.6, purple_width=1.0)[source]

Build the boreal_mako colormap.

Winter forest palette with optional darkened purple ribbon: - Mixed-forest green (warm, Great Lakes hardwood-conifer tone) - Transition to blue - Purple ribbon at configurable position (or omitted if None) - Back to blue, then cyan, then white

Parameters:

  • purple_position – Position of purple ribbon (0.0-1.0), default 0.6. Set to None to omit the purple band entirely.

  • purple_width – Width of the purple band as a proportion of the maximum width (0.0-1.0, default 1.0). Maximum width is 5% of the colormap range. Values near 0 produce a hairline band, 1.0 produces the widest band.

Uses the same method as mako: sample key colors and interpolate.

Build boreal_mako colormap with configurable purple ribbon position.

Purple position parameter:

  • Controls where the purple ribbon appears (0.0-1.0)

  • Default: 0.6 (creates edge effect for scores near upper range)

  • Used for visual emphasis in score visualizations

Example:

from src.terrain.color_mapping import _build_boreal_mako_cmap

# Custom purple position
custom_cmap = _build_boreal_mako_cmap(purple_position=0.7)

Color Mapping Functions

src.terrain.color_mapping.elevation_colormap(dem_data, cmap_name='viridis', min_elev=None, max_elev=None, gamma=1.0)[source]

Create a colormap based on elevation values.

Maps elevation data to colors using a matplotlib colormap. Low elevations map to the start of the colormap, high elevations to the end.

Parameters:

  • dem_data – 2D numpy array of elevation values

  • cmap_name – Matplotlib colormap name (default: ‘viridis’)

  • min_elev – Minimum elevation for normalization (default: use data min)

  • max_elev – Maximum elevation for normalization (default: use data max)

  • gamma – Gamma correction exponent (default: 1.0 = no correction). Values < 1.0 brighten midtones, values > 1.0 darken midtones. Common values: 0.5 = brighten, 2.2 = darken (sRGB gamma)

Returns:

Array of RGB colors with shape (height, width, 3) as uint8

Map elevation or score data to RGB colors using matplotlib colormaps.

Example:

from src.terrain.color_mapping import elevation_colormap

# Basic usage
colors = elevation_colormap(dem_data, cmap_name='viridis')

# With custom range and gamma correction
colors = elevation_colormap(
    dem_data,
    cmap_name='michigan',
    min_elev=0,      # Override auto-min
    max_elev=500,    # Override auto-max
    gamma=1.2        # Brighten mid-tones
)

# Using custom colormaps
colors = elevation_colormap(dem_data, cmap_name='boreal_mako')

Supported colormaps:

  • Standard matplotlib: viridis, plasma, inferno, magma, cividis, terrain, gist_earth, turbo

  • Custom: michigan, boreal_mako

src.terrain.color_mapping.slope_colormap(slopes, cmap_name='terrain', min_slope=0, max_slope=45)[source]

Create a simple colormap based solely on terrain slopes.

Parameters:

  • slopes – Array of slope values in degrees

  • cmap_name – Matplotlib colormap name (default: ‘terrain’)

  • min_slope – Minimum slope value for normalization (default: 0)

  • max_slope – Maximum slope value for normalization (default: 45)

Returns:

Array of RGBA colors with shape (*slopes.shape, 4)

Map slope data to RGB colors.

Example:

from src.terrain.color_mapping import slope_colormap

# Calculate slopes (example)
dy, dx = np.gradient(dem_data)
slopes = np.degrees(np.arctan(np.sqrt(dx**2 + dy**2)))

# Color by slope
colors = slope_colormap(
    slopes,
    cmap_name='terrain',
    min_slope=0,
    max_slope=45
)