0
# Colormap Visualization
1

2
Create visualizations of colormaps for evaluation, comparison, and presentation. These functions help assess colormap properties and create publication-ready overview plots.
3

4
## Capabilities
5

6
### Individual Colormap Visualization
7

8
Display single colormaps with optional test data and grayscale comparison.
9

10
```python { .api }
11
def view_cmap(
12
    cmap: str | Colormap,
13
    *,
14
    savefig: str | None = None,
15
    show_test: bool = False,
16
    show_grayscale: bool = False
17
) -> None:
18
    """
19
    Shows a simple plot of the provided colormap.
20

21
    Parameters:
22
    - cmap: Colormap name or object to visualize
23
    - savefig: Path to save plot (None to display)
24
    - show_test: Show colormap test data instead of gradient
25
    - show_grayscale: Also show grayscale version of colormap
26

27
    Returns:
28
    None
29
    """
30
```
31

32
#### Usage Examples
33

34
```python
35
import cmasher as cmr
36

37
# Basic colormap visualization
38
cmr.view_cmap('cmr.rainforest')
39

40
# View with grayscale comparison
41
cmr.view_cmap('cmr.iceburn', show_grayscale=True)
42

43
# View with test data pattern
44
cmr.view_cmap('cmr.ocean', show_test=True)
45

46
# Save visualization to file
47
cmr.view_cmap('cmr.wildfire', savefig='wildfire_cmap.png')
48

49
# View all three options together
50
cmr.view_cmap(
51
    'cmr.seasons',
52
    show_test=True,
53
    show_grayscale=True,
54
    savefig='seasons_analysis.png'
55
)
56
```
57

58
### Comprehensive Colormap Overview
59

60
Create overview plots showing multiple colormaps with detailed analysis and comparison features.
61

62
```python { .api }
63
def create_cmap_overview(
64
    cmaps: list | dict | None = None,
65
    *,
66
    savefig: str | None = None,
67
    use_types: bool = True,
68
    sort: str | callable | None = "alphabetical",
69
    show_grayscale: bool = True,
70
    show_info: bool = False,
71
    plot_profile: bool | float = False,
72
    dark_mode: bool = False,
73
    title: str | None = "Colormap Overview",
74
    wscale: float = 1,
75
    hscale: float = 1
76
) -> None:
77
    """
78
    Creates an overview plot containing multiple colormaps.
79

80
    Parameters:
81
    - cmaps: Colormaps to include (None for all CMasher colormaps)
82
    - savefig: Path to save plot (None to display)
83
    - use_types: Categorize colormaps by type
84
    - sort: Sorting method - 'alphabetical', 'lightness', 'perceptual', function, or None
85
    - show_grayscale: Show grayscale versions alongside color versions
86
    - show_info: Show lightness and perceptual statistics
87
    - plot_profile: Plot lightness profiles (True, False, or alpha value)
88
    - dark_mode: Use dark background and light text
89
    - title: Plot title (None for no title)
90
    - wscale, hscale: Scale factors for subplot dimensions
91

92
    Returns:
93
    None
94
    """
95
```
96

97
#### Usage Examples
98

99
```python
100
import cmasher as cmr
101

102
# Basic overview of all CMasher colormaps
103
cmr.create_cmap_overview()
104

105
# Overview of specific colormap types
106
sequential_cmaps = cmr.get_cmap_list('sequential')
107
cmr.create_cmap_overview(
108
    [f'cmr.{name}' for name in sequential_cmaps[:10]],
109
    title="Sequential Colormaps",
110
    savefig='sequential_overview.png'
111
)
112

113
# Detailed analysis with lightness profiles
114
cmr.create_cmap_overview(
115
    show_info=True,
116
    plot_profile=0.3,
117
    sort='perceptual',
118
    title="CMasher Colormaps - Perceptual Analysis"
119
)
120

121
# Dark mode overview
122
cmr.create_cmap_overview(
123
    dark_mode=True,
124
    title="CMasher Colormaps (Dark Mode)",
125
    savefig='cmaps_dark.png'
126
)
127

128
# Custom colormap selection with categorical organization
129
custom_cmaps = {
130
    'Ocean Theme': ['cmr.ocean', 'cmr.tropical', 'cmr.arctic'],
131
    'Fire Theme': ['cmr.ember', 'cmr.torch', 'cmr.wildfire'],
132
    'Nature Theme': ['cmr.jungle', 'cmr.rainforest', 'cmr.savanna']
133
}
134
cmr.create_cmap_overview(
135
    custom_cmaps,
136
    show_grayscale=False,
137
    wscale=1.2,
138
    title="Themed Colormaps"
139
)
140
```
141

142
### Sorting and Organization Options
143

144
```python
145
# Alphabetical sorting (default)
146
cmr.create_cmap_overview(sort='alphabetical')
147

148
# Sort by lightness profile
149
cmr.create_cmap_overview(sort='lightness')
150

151
# Sort by perceptual characteristics
152
cmr.create_cmap_overview(sort='perceptual')
153

154
# Custom sorting function
155
def custom_sort(cmap):
156
    return len(cmap.name)  # Sort by name length
157

158
cmr.create_cmap_overview(sort=custom_sort)
159

160
# No sorting (preserve input order)
161
cmr.create_cmap_overview(sort=None)
162
```
163

164
### Colormap Comparison Workflows
165

166
#### Comparing Colormap Types
167

168
```python
169
import cmasher as cmr
170

171
# Compare all diverging colormaps
172
diverging_names = cmr.get_cmap_list('diverging')
173
cmr.create_cmap_overview(
174
    [f'cmr.{name}' for name in diverging_names],
175
    title="Diverging Colormaps Comparison",
176
    show_info=True,
177
    plot_profile=True,
178
    savefig='diverging_comparison.png'
179
)
180
```
181

182
#### Scientific Publication Figures
183

184
```python
185
import cmasher as cmr
186

187
# Create publication-quality overview
188
cmr.create_cmap_overview(
189
    savefig='cmasher_overview_publication.png',
190
    show_grayscale=True,
191
    show_info=True,
192
    plot_profile=0.25,
193
    sort='perceptual',
194
    title="CMasher: Scientific Colormaps for Data Visualization",
195
    wscale=1.5,
196
    hscale=1.2
197
)
198
```
199

200
#### Colormap Selection Aid
201

202
```python
203
import cmasher as cmr
204

205
# Create focused comparison for selection
206
candidates = ['cmr.rainforest', 'cmr.ocean', 'cmr.tropical', 'cmr.jungle']
207
cmr.create_cmap_overview(
208
    candidates,
209
    show_grayscale=True,
210
    show_info=True,
211
    title="Sequential Colormap Candidates",
212
    use_types=False  # Don't group by type
213
)
214
```
215

216
### Interactive Exploration
217

218
```python
219
import cmasher as cmr
220
import matplotlib.pyplot as plt
221

222
def explore_colormap(cmap_name):
223
    """Interactive colormap exploration."""
224
    print(f"\n=== {cmap_name} ===")
225
    print(f"Type: {cmr.get_cmap_type(cmap_name)}")
226
    
227
    # Show basic view
228
    cmr.view_cmap(cmap_name)
229
    
230
    # Show with test data
231
    cmr.view_cmap(cmap_name, show_test=True)
232
    
233
    # Extract sample colors
234
    colors = cmr.take_cmap_colors(cmap_name, 5, return_fmt='hex')
235
    print(f"Sample colors: {colors}")
236

237
# Explore different colormaps
238
for cmap in ['cmr.rainforest', 'cmr.iceburn', 'cmr.seasons']:
239
    explore_colormap(cmap)
240
```
241

242
### Batch Visualization
243

244
```python
245
import cmasher as cmr
246
import os
247

248
def create_all_cmap_views(output_dir='colormap_views'):
249
    """Create individual visualization for each CMasher colormap."""
250
    os.makedirs(output_dir, exist_ok=True)
251
    
252
    all_cmaps = cmr.get_cmap_list()
253
    for cmap_name in all_cmaps:
254
        filename = f"{output_dir}/{cmap_name}_view.png"
255
        cmr.view_cmap(
256
            f'cmr.{cmap_name}',
257
            show_grayscale=True,
258
            savefig=filename
259
        )
260
        print(f"Created: {filename}")
261

262
# Create all visualizations
263
create_all_cmap_views()
264
```