0
# Color Management
1

2
Comprehensive color management system with built-in colormaps, custom color generation algorithms, and styling utilities for enhanced CAD visualization. The system supports both automatic color assignment and manual color specification with transparency control.
3

4
## Capabilities
5

6
### ColorMap Factory Class
7

8
Factory class providing access to built-in colormaps with customizable transparency and ordering.
9

10
```python { .api }
11
class ColorMap:
12
    """
13
    Factory class for creating colormap instances with built-in matplotlib-style colormaps.
14
    All methods return colormap objects that can be used directly with show() functions.
15
    """
16
    
17
    @staticmethod
18
    def accent(alpha=1.0, reverse=False):
19
        """Accent colormap - 8 qualitative colors"""
20
    
21
    @staticmethod  
22
    def dark2(alpha=1.0, reverse=False):
23
        """Dark2 colormap - 8 qualitative colors with darker tones"""
24
        
25
    @staticmethod
26
    def paired(alpha=1.0, reverse=False):
27
        """Paired colormap - 12 colors in paired combinations"""
28
        
29
    @staticmethod
30
    def pastel1(alpha=1.0, reverse=False):
31
        """Pastel1 colormap - 9 soft pastel colors"""
32
        
33
    @staticmethod  
34
    def pastel2(alpha=1.0, reverse=False):
35
        """Pastel2 colormap - 8 soft pastel colors"""
36
        
37
    @staticmethod
38
    def set1(alpha=1.0, reverse=False):
39
        """Set1 colormap - 9 distinct qualitative colors"""
40
        
41
    @staticmethod
42
    def set2(alpha=1.0, reverse=False):
43
        """Set2 colormap - 8 distinct qualitative colors"""
44
        
45
    @staticmethod
46
    def set3(alpha=1.0, reverse=False):
47
        """Set3 colormap - 12 soft qualitative colors"""
48
        
49
    @staticmethod
50
    def tab10(alpha=1.0, reverse=False):
51
        """Tab10 colormap - 10 distinct colors (matplotlib default)"""
52
        
53
    @staticmethod
54
    def tab20(alpha=1.0, reverse=False):
55
        """Tab20 colormap - 20 distinct colors"""
56
        
57
    @staticmethod
58
    def tab20b(alpha=1.0, reverse=False):
59
        """Tab20b colormap - 20 colors in groups of 4"""
60
        
61
    @staticmethod
62
    def tab20c(alpha=1.0, reverse=False):
63
        """Tab20c colormap - 20 colors with varied lightness"""
64
        
65
    @staticmethod
66
    def golden_ratio(colormap="hsv", alpha=1.0, reverse=False):
67
        """
68
        Golden ratio colormap using aesthetically pleasing color distribution.
69
        
70
        Parameters:
71
            colormap (str): Base colormap ("hsv" or "mpl:name")
72
            alpha (float): Transparency 0-1 (default: 1.0)
73
            reverse (bool): Reverse color order (default: False)
74
        """
75
        
76
    @staticmethod
77
    def seeded(seed_value=42, colormap="hsv", alpha=1.0, **params):
78
        """
79
        Seeded random colormap for reproducible color sequences.
80
        
81
        Parameters:
82
            seed_value (int): Random seed for reproducibility (default: 42)
83
            colormap (str): Base colormap ("hsv", "rgb", or "mpl:name")
84
            alpha (float): Transparency 0-1 (default: 1.0)
85
            **params: Additional parameters for specific colormaps
86
        """
87
        
88
    @staticmethod  
89
    def segmented(length=10, colormap="hsv", alpha=1.0, reverse=False):
90
        """
91
        Segmented colormap with fixed number of evenly distributed colors.
92
        
93
        Parameters:
94
            length (int): Number of colors to generate (default: 10)
95
            colormap (str): Base colormap ("hsv" or "mpl:name")
96
            alpha (float): Transparency 0-1 (default: 1.0)  
97
            reverse (bool): Reverse color order (default: False)
98
        """
99
        
100
    @staticmethod
101
    def listed(length=10, colormap="mpl:plasma", colors=None, alpha=1.0, reverse=False):
102
        """
103
        Listed colormap from matplotlib or custom color list.
104
        
105
        Parameters:
106
            length (int): Number of colors to extract (default: 10)
107
            colormap (str): Matplotlib colormap name with "mpl:" prefix
108
            colors (list, optional): Custom color list instead of matplotlib
109
            alpha (float): Transparency 0-1 (default: 1.0)
110
            reverse (bool): Reverse color order (default: False)
111
        """
112
```
113

114
**Usage Examples:**
115

116
```python
117
from ocp_vscode import show, ColorMap
118

119
# Use built-in colormaps
120
objects = [create_part(i) for i in range(8)]
121
show(*objects, colors=ColorMap.tab10())
122

123
# With transparency
124
show(*objects, colors=ColorMap.set1(alpha=0.7))
125

126
# Reversed order
127
show(*objects, colors=ColorMap.accent(reverse=True))
128

129
# Golden ratio distribution (aesthetically pleasing)
130
show(*objects, colors=ColorMap.golden_ratio())
131

132
# Reproducible random colors
133
show(*objects, colors=ColorMap.seeded(seed_value=12345))
134

135
# Fixed number of evenly distributed colors
136
show(*objects, colors=ColorMap.segmented(length=6, colormap="hsv"))
137
```
138

139
### Base ColorMap Classes
140

141
Foundation classes for implementing custom colormap behavior.
142

143
```python { .api }
144
class BaseColorMap:
145
    """
146
    Abstract base class for all colormap implementations.
147
    Provides iteration protocol and state management.
148
    """
149
    
150
    def __init__(self):
151
        """Initialize colormap with index=0 and alpha=1.0"""
152
        
153
    def __iter__(self):
154
        """Make colormap iterable"""
155
        
156
    def __next__(self):
157
        """Get next color - must be implemented by subclasses"""
158
        
159
    def reset(self):
160
        """Reset colormap to first color"""
161

162
class ListedColorMap(BaseColorMap):
163
    """
164
    Colormap based on a fixed list of colors that cycles when exhausted.
165
    """
166
    
167
    def __init__(self, colors, alpha=1.0, reverse=False):
168
        """
169
        Parameters:
170
            colors (list): List of color tuples or web color names
171
            alpha (float): Transparency 0-1 (default: 1.0)  
172
            reverse (bool): Reverse color order (default: False)
173
        """
174

175
class SegmentedColorMap(BaseColorMap):
176
    """
177
    Colormap that generates colors by sampling a continuous color space.
178
    """
179
    
180
    def __init__(self, length, mapper, alpha=1.0, reverse=False, **params):
181
        """
182
        Parameters:
183
            length (int): Total number of colors before cycling
184
            mapper (function): Function that converts 0-1 values to RGB
185
            alpha (float): Transparency 0-1 (default: 1.0)
186
            reverse (bool): Reverse color order (default: False)
187
            **params: Parameters passed to mapper function
188
        """
189

190
class GoldenRatioColormap(BaseColorMap):
191
    """
192
    Colormap using golden ratio for aesthetically pleasing color distribution.
193
    """
194
    
195
    def __init__(self, mapper, alpha=1.0, reverse=False, **params):
196
        """
197
        Parameters:
198
            mapper (function): Function that converts 0-1 values to RGB
199
            alpha (float): Transparency 0-1 (default: 1.0)
200
            reverse (bool): Reverse color order (default: False)
201
            **params: Parameters passed to mapper function
202
        """
203

204
class SeededColormap(BaseColorMap):
205
    """
206
    Colormap with seeded random generation for reproducible results.  
207
    """
208
    
209
    def __init__(self, seed_value, mapper, alpha=1.0, no_param=False, **params):
210
        """
211
        Parameters:
212
            seed_value (int): Random seed for reproducibility
213
            mapper (function): Function that generates colors
214
            alpha (float): Transparency 0-1 (default: 1.0)
215
            no_param (bool): Mapper doesn't use 0-1 parameter (default: False)
216
            **params: Parameters passed to mapper function
217
        """
218
```
219

220
### Global Colormap Management
221

222
Functions for managing a global colormap that automatically applies to display functions.
223

224
```python { .api }
225
def set_colormap(colormap):
226
    """
227
    Set global colormap used automatically by show() and show_object().
228
    
229
    Parameters:
230
        colormap (BaseColorMap): Colormap instance to use globally
231
    """
232

233
def get_colormap():
234
    """
235
    Get current global colormap.
236
    
237
    Returns:
238
        BaseColorMap or None: Current global colormap, reset to beginning
239
    """
240

241
def unset_colormap():
242
    """
243
    Clear global colormap. Objects will use explicit colors or defaults.
244
    """
245
```
246

247
**Usage Examples:**
248

249
```python
250
from ocp_vscode import set_colormap, get_colormap, unset_colormap, show, ColorMap
251

252
# Set global colormap
253
set_colormap(ColorMap.tab20())
254

255
# All subsequent show() calls will use this colormap automatically
256
show(object1)  # Gets first color from tab20
257
show(object2)  # Gets second color from tab20  
258

259
# Multiple objects get sequential colors
260
objects = [obj1, obj2, obj3, obj4]
261
show(*objects)  # Each object gets next color from colormap
262

263
# Check current colormap
264
current = get_colormap()
265
if current:
266
    print("Using global colormap")
267

268
# Clear global colormap  
269
unset_colormap()
270
show(object5)  # Uses default color
271
```
272

273
### Color Utility Functions
274

275
Utility functions for color conversion and manipulation.
276

277
```python { .api }
278
def web_to_rgb(name):
279
    """
280
    Convert web color name to RGB tuple.
281
    
282
    Parameters:
283
        name (str): Web color name (e.g., "red", "steelblue", "darkgreen")
284
        
285
    Returns:
286
        tuple: RGB values as floats 0-1 (r, g, b)
287
        
288
    Examples:
289
        web_to_rgb("red") -> (1.0, 0.0, 0.0)
290
        web_to_rgb("steelblue") -> (0.27, 0.51, 0.71)
291
    """
292
```
293

294
**Usage Examples:**
295

296
```python
297
from ocp_vscode import web_to_rgb, show
298

299
# Convert web colors to RGB
300
red_rgb = web_to_rgb("red")
301
blue_rgb = web_to_rgb("steelblue")
302
green_rgb = web_to_rgb("forestgreen")
303

304
# Use in show() calls
305
colors = [red_rgb, blue_rgb, green_rgb]
306
show(obj1, obj2, obj3, colors=colors)
307

308
# Mix web colors and RGB tuples
309
mixed_colors = [
310
    "red",                    # Web color name
311
    (0.0, 1.0, 0.0),         # RGB tuple  
312
    web_to_rgb("purple"),     # Converted web color
313
    (0.2, 0.4, 0.8, 0.7)     # RGBA tuple with alpha
314
]
315
show(*objects, colors=mixed_colors)
316
```
317

318
### Advanced Colormap Creation
319

320
Creating custom colormaps for specialized visualization needs.
321

322
```python
323
from ocp_vscode import BaseColorMap, set_colormap
324
from colorsys import hsv_to_rgb
325
import random
326

327
# Custom colormap based on temperature
328
class TemperatureColorMap(BaseColorMap):
329
    def __init__(self, min_temp=0, max_temp=100, alpha=1.0):
330
        super().__init__()
331
        self.min_temp = min_temp
332
        self.max_temp = max_temp
333
        self.alpha = alpha
334
        self.temperatures = []
335
        
336
    def add_temperature(self, temp):
337
        self.temperatures.append(temp)
338
        
339
    def __next__(self):
340
        if self.index >= len(self.temperatures):
341
            # Generate random temperature for demo
342
            temp = random.uniform(self.min_temp, self.max_temp)
343
        else:
344
            temp = self.temperatures[self.index]
345
            
346
        # Map temperature to color (blue=cold, red=hot)
347
        normalized = (temp - self.min_temp) / (self.max_temp - self.min_temp)
348
        hue = 0.7 - (normalized * 0.7)  # Blue to red
349
        r, g, b = hsv_to_rgb(hue, 1.0, 1.0)
350
        
351
        self.index += 1
352
        return (r, g, b, self.alpha)
353

354
# Usage
355
temp_map = TemperatureColorMap(0, 200)
356
temp_map.add_temperature(25)   # Room temperature - blue-ish
357
temp_map.add_temperature(150)  # Hot - red-ish
358
set_colormap(temp_map)
359

360
show(*heat_analysis_objects)
361
```
362

363
### Color Format Support
364

365
The system supports multiple color formats for maximum flexibility:
366

367
```python
368
from ocp_vscode import show, ColorMap
369

370
# RGB tuples (0-1 range)
371
colors_01 = [(1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)]
372

373
# RGB tuples (0-255 range) - automatically converted  
374
colors_255 = [(255, 0, 0), (0, 255, 0), (0, 0, 255)]
375

376
# RGBA tuples with alpha
377
colors_rgba = [(1.0, 0.0, 0.0, 0.8), (0.0, 1.0, 0.0, 0.6)]
378

379
# Web color names
380
colors_web = ["red", "green", "blue", "purple", "orange"]
381

382
# Hex color strings  
383
colors_hex = ["#FF0000", "#00FF00", "#0000FF"]
384

385
# Mixed formats
386
colors_mixed = [
387
    "red",                # Web name
388
    (0.0, 1.0, 0.0),     # RGB tuple
389
    "#0000FF",           # Hex string  
390
    (1.0, 1.0, 0.0, 0.5) # RGBA tuple
391
]
392

393
# All formats work with show()
394
show(*objects, colors=colors_mixed)
395

396
# ColorMap instances also work
397
show(*objects, colors=ColorMap.tab10())
398
```