0
# Colormap Creation
1
2
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.
3
4
## Capabilities
5
6
### Base Color Mapping
7
8
Base colormap class that provides core color conversion methods and rendering functionality. All colormap classes inherit from this base class.
9
10
```python { .api }
11
class ColorMap:
12
def __init__(
13
self,
14
vmin: float = 0.0,
15
vmax: float = 1.0,
16
caption: str = "",
17
text_color: str = "black",
18
max_labels: int = 10
19
):
20
"""
21
Base colormap class with core functionality.
22
23
Parameters:
24
- vmin: minimum value for the colormap
25
- vmax: maximum value for the colormap
26
- caption: caption text for the colormap legend
27
- text_color: color for legend text
28
- max_labels: maximum number of legend labels
29
"""
30
31
def __call__(self, x: float) -> str:
32
"""
33
Get hex color string for a given value.
34
35
Parameters:
36
- x: value to map to color
37
38
Returns:
39
str: hex color string "#RRGGBBAA"
40
"""
41
42
def rgba_floats_tuple(self, x: float):
43
"""
44
Abstract method to get RGBA color tuple with float values (0.0-1.0).
45
Must be implemented by subclasses.
46
47
Parameters:
48
- x: value to map to color
49
50
Returns:
51
tuple: (r, g, b, a) with float values between 0.0 and 1.0
52
"""
53
54
def rgba_bytes_tuple(self, x: float):
55
"""
56
Get RGBA color tuple with int values (0-255).
57
58
Parameters:
59
- x: value to map to color
60
61
Returns:
62
tuple: (r, g, b, a) with int values between 0 and 255
63
"""
64
65
def rgb_bytes_tuple(self, x: float):
66
"""
67
Get RGB color tuple with int values (0-255).
68
69
Parameters:
70
- x: value to map to color
71
72
Returns:
73
tuple: (r, g, b) with int values between 0 and 255
74
"""
75
76
def rgb_hex_str(self, x: float) -> str:
77
"""
78
Get RGB hex color string for a given value.
79
80
Parameters:
81
- x: value to map to color
82
83
Returns:
84
str: hex color string "#RRGGBB"
85
"""
86
87
def rgba_hex_str(self, x: float) -> str:
88
"""
89
Get RGBA hex color string for a given value.
90
91
Parameters:
92
- x: value to map to color
93
94
Returns:
95
str: hex color string "#RRGGBBAA"
96
"""
97
98
def render(self, **kwargs):
99
"""
100
Render colormap as HTML element in parent Figure.
101
Must be added to a Figure to render properly.
102
"""
103
104
def _repr_html_(self) -> str:
105
"""
106
Display colormap in Jupyter notebook as SVG.
107
108
Returns:
109
str: SVG representation of the colormap
110
"""
111
```
112
113
### Linear Color Mapping
114
115
Creates smooth color transitions through linear interpolation between specified colors, ideal for continuous data visualization.
116
117
```python { .api }
118
class LinearColormap:
119
def __init__(
120
self,
121
colors,
122
index=None,
123
vmin: float = 0.0,
124
vmax: float = 1.0,
125
caption: str = "",
126
text_color: str = "black",
127
max_labels: int = 10,
128
tick_labels=None
129
):
130
"""
131
Create a linear colormap with smooth color transitions.
132
133
Parameters:
134
- colors: list of colors (hex strings, RGB tuples, or color names)
135
- index: list of float values corresponding to each color
136
- vmin: minimum value for the colormap
137
- vmax: maximum value for the colormap
138
- caption: caption text for the colormap legend
139
- text_color: color for legend text
140
- max_labels: maximum number of legend labels
141
- tick_labels: custom positions for legend ticks
142
"""
143
144
def __call__(self, x: float) -> str:
145
"""
146
Get hex color string for a given value.
147
148
Parameters:
149
- x: value to map to color
150
151
Returns:
152
str: hex color string "#RRGGBBAA"
153
"""
154
155
def rgba_floats_tuple(self, x: float):
156
"""
157
Get RGBA color tuple with float values (0.0-1.0) using linear interpolation.
158
159
Parameters:
160
- x: value to map to color
161
162
Returns:
163
tuple: (r, g, b, a) with float values between 0.0 and 1.0
164
"""
165
166
def scale(self, vmin: float = 0.0, vmax: float = 1.0, max_labels: int = 10):
167
"""
168
Create scaled version of colormap with new min/max values.
169
170
Parameters:
171
- vmin: new minimum value
172
- vmax: new maximum value
173
- max_labels: maximum number of legend labels
174
175
Returns:
176
LinearColormap: scaled colormap instance
177
"""
178
179
def to_step(
180
self,
181
n=None,
182
index=None,
183
data=None,
184
method: str = "linear",
185
quantiles=None,
186
round_method=None,
187
max_labels: int = 10
188
):
189
"""
190
Convert to StepColormap with discrete color bands.
191
192
Parameters:
193
- n: number of color steps
194
- index: custom breakpoints for color steps
195
- data: sample data to adapt colormap to
196
- method: scaling method ('linear', 'log', 'quantiles')
197
- quantiles: explicit quantile breakpoints
198
- round_method: rounding method ('int', 'log10')
199
- max_labels: maximum number of legend labels
200
201
Returns:
202
StepColormap: converted step colormap
203
"""
204
```
205
206
### Step Color Mapping
207
208
Creates discrete color bands with sharp transitions, ideal for categorical data or creating distinct value ranges.
209
210
```python { .api }
211
class StepColormap:
212
def __init__(
213
self,
214
colors,
215
index=None,
216
vmin: float = 0.0,
217
vmax: float = 1.0,
218
caption: str = "",
219
text_color: str = "black",
220
max_labels: int = 10,
221
tick_labels=None
222
):
223
"""
224
Create a step colormap with discrete color bands.
225
226
Parameters:
227
- colors: list of colors (hex strings, RGB tuples, or color names)
228
- index: list of breakpoints for color transitions
229
- vmin: minimum value for the colormap
230
- vmax: maximum value for the colormap
231
- caption: caption text for the colormap legend
232
- text_color: color for legend text
233
- max_labels: maximum number of legend labels
234
- tick_labels: custom positions for legend ticks
235
"""
236
237
def __call__(self, x: float) -> str:
238
"""
239
Get hex color string for a given value (discrete bands).
240
241
Parameters:
242
- x: value to map to color
243
244
Returns:
245
str: hex color string "#RRGGBBAA"
246
"""
247
248
def rgba_floats_tuple(self, x: float):
249
"""
250
Get RGBA color tuple with float values (0.0-1.0) using step/discrete bands.
251
252
Parameters:
253
- x: value to map to color
254
255
Returns:
256
tuple: (r, g, b, a) with float values between 0.0 and 1.0
257
"""
258
259
def to_linear(self, index=None, max_labels: int = 10):
260
"""
261
Convert to LinearColormap with smooth transitions.
262
263
Parameters:
264
- index: values for color interpolation points
265
- max_labels: maximum number of legend labels
266
267
Returns:
268
LinearColormap: converted linear colormap
269
"""
270
271
def scale(self, vmin: float = 0.0, vmax: float = 1.0, max_labels: int = 10):
272
"""
273
Create scaled version of colormap with new min/max values.
274
275
Parameters:
276
- vmin: new minimum value
277
- vmax: new maximum value
278
- max_labels: maximum number of legend labels
279
280
Returns:
281
StepColormap: scaled colormap instance
282
"""
283
```
284
285
### Built-in Colormap Collections
286
287
Pre-defined colormap collections with ColorBrewer schemes for immediate use.
288
289
```python { .api }
290
class _LinearColormaps:
291
"""Collection of built-in linear colormaps."""
292
def _repr_html_(self) -> str: ...
293
# Dynamic attributes for each scheme (e.g., viridis, plasma, etc.)
294
295
class _StepColormaps:
296
"""Collection of built-in step colormaps."""
297
def _repr_html_(self) -> str: ...
298
# Dynamic attributes for each scheme (e.g., viridis, plasma, etc.)
299
300
# Global instances
301
linear: _LinearColormaps
302
step: _StepColormaps
303
```
304
305
## Usage Examples
306
307
### Creating Custom Colormaps
308
309
```python
310
import branca.colormap as cm
311
312
# Linear colormap with custom colors
313
linear_map = cm.LinearColormap(
314
colors=['green', 'yellow', 'red'],
315
vmin=0,
316
vmax=100,
317
caption='Temperature (°C)'
318
)
319
320
# Step colormap with specific breakpoints
321
step_map = cm.StepColormap(
322
colors=['blue', 'cyan', 'yellow', 'red'],
323
index=[0, 25, 50, 75, 100],
324
caption='Risk Level'
325
)
326
327
# Get colors for specific values
328
color_50 = linear_map(50) # Returns hex color for value 50
329
risk_color = step_map(30) # Returns discrete color for value 30
330
```
331
332
### Using Built-in Schemes
333
334
```python
335
import branca.colormap as cm
336
337
# Access pre-defined linear colormaps
338
viridis = cm.linear.viridis.scale(0, 1000)
339
plasma = cm.linear.plasma.scale(-100, 100)
340
341
# Access pre-defined step colormaps
342
viridis_step = cm.step.viridis.scale(0, 10)
343
```
344
345
### Converting Between Types
346
347
```python
348
# Convert linear to step colormap
349
linear_map = cm.LinearColormap(['blue', 'red'], vmin=0, vmax=100)
350
step_version = linear_map.to_step(n=5) # 5 discrete color bands
351
352
# Convert step to linear colormap
353
step_map = cm.StepColormap(['blue', 'green', 'red'])
354
linear_version = step_map.to_linear() # Smooth transitions
355
356
# Data-adaptive scaling
357
import numpy as np
358
data = np.random.normal(50, 15, 1000)
359
adaptive_map = linear_map.to_step(data=data, n=10, method='quantiles')
360
```
361
362
## Type Definitions
363
364
```python { .api }
365
# Color type definitions
366
TypeRGBInts = tuple[int, int, int]
367
TypeRGBFloats = tuple[float, float, float]
368
TypeRGBAInts = tuple[int, int, int, int]
369
TypeRGBAFloats = tuple[float, float, float, float]
370
TypeAnyColorType = TypeRGBInts | TypeRGBFloats | TypeRGBAInts | TypeRGBAFloats | str
371
```