tessl/pypi-branca
A library to generate HTML + JS pages, spun off from folium and based on Jinja2
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
colormap.mddocs/
Colormap Creation
Comprehensive colormap functionality for data visualization, providing linear and step-based color interpolation, built-in ColorBrewer schemes, and flexible scaling options. Supports both continuous and discrete color mapping with automatic legend generation.
Capabilities
Base Color Mapping
Base colormap class that provides core color conversion methods and rendering functionality. All colormap classes inherit from this base class.
class ColorMap:
def __init__(
self,
vmin: float = 0.0,
vmax: float = 1.0,
caption: str = "",
text_color: str = "black",
max_labels: int = 10
):
"""
Base colormap class with core functionality.
Parameters:
- vmin: minimum value for the colormap
- vmax: maximum value for the colormap
- caption: caption text for the colormap legend
- text_color: color for legend text
- max_labels: maximum number of legend labels
"""
def __call__(self, x: float) -> str:
"""
Get hex color string for a given value.
Parameters:
- x: value to map to color
Returns:
str: hex color string "#RRGGBBAA"
"""
def rgba_floats_tuple(self, x: float):
"""
Abstract method to get RGBA color tuple with float values (0.0-1.0).
Must be implemented by subclasses.
Parameters:
- x: value to map to color
Returns:
tuple: (r, g, b, a) with float values between 0.0 and 1.0
"""
def rgba_bytes_tuple(self, x: float):
"""
Get RGBA color tuple with int values (0-255).
Parameters:
- x: value to map to color
Returns:
tuple: (r, g, b, a) with int values between 0 and 255
"""
def rgb_bytes_tuple(self, x: float):
"""
Get RGB color tuple with int values (0-255).
Parameters:
- x: value to map to color
Returns:
tuple: (r, g, b) with int values between 0 and 255
"""
def rgb_hex_str(self, x: float) -> str:
"""
Get RGB hex color string for a given value.
Parameters:
- x: value to map to color
Returns:
str: hex color string "#RRGGBB"
"""
def rgba_hex_str(self, x: float) -> str:
"""
Get RGBA hex color string for a given value.
Parameters:
- x: value to map to color
Returns:
str: hex color string "#RRGGBBAA"
"""
def render(self, **kwargs):
"""
Render colormap as HTML element in parent Figure.
Must be added to a Figure to render properly.
"""
def _repr_html_(self) -> str:
"""
Display colormap in Jupyter notebook as SVG.
Returns:
str: SVG representation of the colormap
"""Linear Color Mapping
Creates smooth color transitions through linear interpolation between specified colors, ideal for continuous data visualization.
class LinearColormap:
def __init__(
self,
colors,
index=None,
vmin: float = 0.0,
vmax: float = 1.0,
caption: str = "",
text_color: str = "black",
max_labels: int = 10,
tick_labels=None
):
"""
Create a linear colormap with smooth color transitions.
Parameters:
- colors: list of colors (hex strings, RGB tuples, or color names)
- index: list of float values corresponding to each color
- vmin: minimum value for the colormap
- vmax: maximum value for the colormap
- caption: caption text for the colormap legend
- text_color: color for legend text
- max_labels: maximum number of legend labels
- tick_labels: custom positions for legend ticks
"""
def __call__(self, x: float) -> str:
"""
Get hex color string for a given value.
Parameters:
- x: value to map to color
Returns:
str: hex color string "#RRGGBBAA"
"""
def rgba_floats_tuple(self, x: float):
"""
Get RGBA color tuple with float values (0.0-1.0) using linear interpolation.
Parameters:
- x: value to map to color
Returns:
tuple: (r, g, b, a) with float values between 0.0 and 1.0
"""
def scale(self, vmin: float = 0.0, vmax: float = 1.0, max_labels: int = 10):
"""
Create scaled version of colormap with new min/max values.
Parameters:
- vmin: new minimum value
- vmax: new maximum value
- max_labels: maximum number of legend labels
Returns:
LinearColormap: scaled colormap instance
"""
def to_step(
self,
n=None,
index=None,
data=None,
method: str = "linear",
quantiles=None,
round_method=None,
max_labels: int = 10
):
"""
Convert to StepColormap with discrete color bands.
Parameters:
- n: number of color steps
- index: custom breakpoints for color steps
- data: sample data to adapt colormap to
- method: scaling method ('linear', 'log', 'quantiles')
- quantiles: explicit quantile breakpoints
- round_method: rounding method ('int', 'log10')
- max_labels: maximum number of legend labels
Returns:
StepColormap: converted step colormap
"""Step Color Mapping
Creates discrete color bands with sharp transitions, ideal for categorical data or creating distinct value ranges.
class StepColormap:
def __init__(
self,
colors,
index=None,
vmin: float = 0.0,
vmax: float = 1.0,
caption: str = "",
text_color: str = "black",
max_labels: int = 10,
tick_labels=None
):
"""
Create a step colormap with discrete color bands.
Parameters:
- colors: list of colors (hex strings, RGB tuples, or color names)
- index: list of breakpoints for color transitions
- vmin: minimum value for the colormap
- vmax: maximum value for the colormap
- caption: caption text for the colormap legend
- text_color: color for legend text
- max_labels: maximum number of legend labels
- tick_labels: custom positions for legend ticks
"""
def __call__(self, x: float) -> str:
"""
Get hex color string for a given value (discrete bands).
Parameters:
- x: value to map to color
Returns:
str: hex color string "#RRGGBBAA"
"""
def rgba_floats_tuple(self, x: float):
"""
Get RGBA color tuple with float values (0.0-1.0) using step/discrete bands.
Parameters:
- x: value to map to color
Returns:
tuple: (r, g, b, a) with float values between 0.0 and 1.0
"""
def to_linear(self, index=None, max_labels: int = 10):
"""
Convert to LinearColormap with smooth transitions.
Parameters:
- index: values for color interpolation points
- max_labels: maximum number of legend labels
Returns:
LinearColormap: converted linear colormap
"""
def scale(self, vmin: float = 0.0, vmax: float = 1.0, max_labels: int = 10):
"""
Create scaled version of colormap with new min/max values.
Parameters:
- vmin: new minimum value
- vmax: new maximum value
- max_labels: maximum number of legend labels
Returns:
StepColormap: scaled colormap instance
"""Built-in Colormap Collections
Pre-defined colormap collections with ColorBrewer schemes for immediate use.
class _LinearColormaps:
"""Collection of built-in linear colormaps."""
def _repr_html_(self) -> str: ...
# Dynamic attributes for each scheme (e.g., viridis, plasma, etc.)
class _StepColormaps:
"""Collection of built-in step colormaps."""
def _repr_html_(self) -> str: ...
# Dynamic attributes for each scheme (e.g., viridis, plasma, etc.)
# Global instances
linear: _LinearColormaps
step: _StepColormapsUsage Examples
Creating Custom Colormaps
import branca.colormap as cm
# Linear colormap with custom colors
linear_map = cm.LinearColormap(
colors=['green', 'yellow', 'red'],
vmin=0,
vmax=100,
caption='Temperature (°C)'
)
# Step colormap with specific breakpoints
step_map = cm.StepColormap(
colors=['blue', 'cyan', 'yellow', 'red'],
index=[0, 25, 50, 75, 100],
caption='Risk Level'
)
# Get colors for specific values
color_50 = linear_map(50) # Returns hex color for value 50
risk_color = step_map(30) # Returns discrete color for value 30Using Built-in Schemes
import branca.colormap as cm
# Access pre-defined linear colormaps
viridis = cm.linear.viridis.scale(0, 1000)
plasma = cm.linear.plasma.scale(-100, 100)
# Access pre-defined step colormaps
viridis_step = cm.step.viridis.scale(0, 10)Converting Between Types
# Convert linear to step colormap
linear_map = cm.LinearColormap(['blue', 'red'], vmin=0, vmax=100)
step_version = linear_map.to_step(n=5) # 5 discrete color bands
# Convert step to linear colormap
step_map = cm.StepColormap(['blue', 'green', 'red'])
linear_version = step_map.to_linear() # Smooth transitions
# Data-adaptive scaling
import numpy as np
data = np.random.normal(50, 15, 1000)
adaptive_map = linear_map.to_step(data=data, n=10, method='quantiles')Type Definitions
# Color type definitions
TypeRGBInts = tuple[int, int, int]
TypeRGBFloats = tuple[float, float, float]
TypeRGBAInts = tuple[int, int, int, int]
TypeRGBAFloats = tuple[float, float, float, float]
TypeAnyColorType = TypeRGBInts | TypeRGBFloats | TypeRGBAInts | TypeRGBAFloats | strInstall with Tessl CLI
npx tessl i tessl/pypi-branca