0
# CLI Tools
1

2
Command-line interface tools for colormap management, visualization, and color extraction. The `cmr` command provides convenient access to CMasher functionality from the terminal.
3

4
## Installation and Access
5

6
The CLI is automatically available after installing CMasher:
7

8
```bash
9
pip install cmasher
10
```
11

12
Access via the `cmr` command:
13

14
```bash
15
cmr --help
16
```
17

18
## Capabilities
19

20
### Basic Information Commands
21

22
#### Get CMasher Version
23

24
```bash { .api }
25
cmr --version
26
# Output: CMasher v1.9.2
27
```
28

29
#### Print BibTeX Citation
30

31
```bash { .api }
32
cmr bibtex
33
```
34

35
Prints the complete BibTeX entry for citing CMasher in scientific publications.
36

37
#### List Available Colormaps
38

39
```bash { .api }
40
cmr cmlist [--type TYPE]
41

42
# Options:
43
# --type: Filter by colormap type
44
#   all (default), s/seq/sequential, d/div/diverging, c/cyc/cyclic
45
```
46

47
##### Usage Examples
48

49
```bash
50
# List all colormaps
51
cmr cmlist
52

53
# List only sequential colormaps
54
cmr cmlist --type sequential
55
cmr cmlist --type seq
56
cmr cmlist --type s
57

58
# List diverging colormaps
59
cmr cmlist --type diverging
60
cmr cmlist --type div
61
cmr cmlist --type d
62

63
# List cyclic colormaps
64
cmr cmlist --type cyclic
65
cmr cmlist --type cyc
66
cmr cmlist --type c
67
```
68

69
### Colormap Analysis Commands
70

71
#### Get Colormap Type
72

73
```bash { .api }
74
cmr cmtype CMAP
75

76
# Parameters:
77
# CMAP: Colormap name or object path (e.g., 'cmr.rainforest' or 'a.b:c.d')
78
```
79

80
##### Usage Examples
81

82
```bash
83
# Check CMasher colormap types
84
cmr cmtype cmr.rainforest    # Output: sequential
85
cmr cmtype cmr.iceburn       # Output: diverging
86
cmr cmtype cmr.seasons       # Output: cyclic
87

88
# Check matplotlib colormap types
89
cmr cmtype viridis           # Output: sequential
90
cmr cmtype coolwarm          # Output: diverging
91
```
92

93
### Color Extraction Commands
94

95
#### Extract Specific Number of Colors
96

97
```bash { .api }
98
cmr cmcolors CMAP N [OPTIONS]
99

100
# Parameters:
101
# CMAP: Colormap name
102
# N: Number of colors to extract
103

104
# Options:
105
# --range LOWER UPPER: Normalized range to extract from (default: 0 1)
106
# --fmt FORMAT: Output format (default: float)
107
#   float/norm, int/8bit, str/hex
108
```
109

110
##### Usage Examples
111

112
```bash
113
# Extract 5 colors as normalized RGB
114
cmr cmcolors cmr.rainforest 5
115
# Output:
116
# 0.00000000 0.00000000 0.00000000
117
# 0.22612359 0.12458403 0.56299728
118
# 0.05482105 0.51583525 0.45667819
119
# 0.70961598 0.72286398 0.08347276
120
# 1.00000000 1.00000000 1.00000000
121

122
# Extract colors as hex strings
123
cmr cmcolors cmr.ocean 3 --fmt hex
124
# Output:
125
# #000000
126
# #0E8474
127
# #FFFFFF
128

129
# Extract colors as 8-bit RGB
130
cmr cmcolors cmr.iceburn 4 --fmt int
131
# Output:
132
# 0 0 0
133
# 58 32 144
134
# 181 184 21
135
# 255 255 255
136

137
# Extract from specific range
138
cmr cmcolors cmr.wildfire 5 --range 0.2 0.8 --fmt hex
139
# Output: colors from 20% to 80% of the colormap
140

141
# Extract with different range and format
142
cmr cmcolors cmr.tropical 10 --range 0.1 0.9 --fmt int
143
```
144

145
#### Get Full RGB Table
146

147
```bash { .api }
148
cmr rgbtable CMAP [OPTIONS]
149

150
# Parameters:
151
# CMAP: Colormap name
152

153
# Options:
154
# --range LOWER UPPER: Normalized range (default: 0 1)
155
# --fmt FORMAT: Output format (default: float)
156
#   float/norm, int/8bit, str/hex
157
```
158

159
##### Usage Examples
160

161
```bash
162
# Get complete RGB table
163
cmr rgbtable cmr.rainforest
164

165
# Get RGB table as hex values
166
cmr rgbtable cmr.ocean --fmt hex
167

168
# Get subset of colormap as 8-bit RGB
169
cmr rgbtable cmr.iceburn --range 0.3 0.7 --fmt int
170

171
# Get full RGB table with all colors as integers
172
cmr rgbtable cmr.wildfire --fmt int
173

174
# Extract specific range for analysis
175
cmr rgbtable cmr.seasons --range 0.25 0.75 --fmt float
176
```
177

178
### Visualization Commands
179

180
#### View Single Colormap
181

182
```bash { .api }
183
cmr cmview CMAP [OPTIONS]
184

185
# Parameters:
186
# CMAP: Colormap name
187

188
# Options:
189
# --save [PATH]: Save plot to file (PNG if no path given)
190
# --test: Show colormap test pattern instead of gradient
191
# --gs/--grayscale: Show grayscale version alongside
192
```
193

194
##### Usage Examples
195

196
```bash
197
# Basic colormap view
198
cmr cmview cmr.rainforest
199

200
# View with grayscale comparison
201
cmr cmview cmr.iceburn --grayscale
202

203
# View with test pattern
204
cmr cmview cmr.ocean --test
205

206
# Save visualization
207
cmr cmview cmr.wildfire --save
208
cmr cmview cmr.seasons --save colormap_seasons.png
209

210
# Combined options
211
cmr cmview cmr.tropical --test --grayscale --save tropical_analysis.png
212
```
213

214
### Module Generation Commands
215

216
#### Create Standalone Modules
217

218
```bash { .api }
219
cmr mkcmod CMAP [CMAP ...] [OPTIONS]
220

221
# Parameters:
222
# CMAP: One or more CMasher colormap names
223

224
# Options:
225
# -d/--dir DIR: Output directory (default: current directory)
226
```
227

228
##### Usage Examples
229

230
```bash
231
# Create module for single colormap
232
cmr mkcmod rainforest
233

234
# Create modules for multiple colormaps
235
cmr mkcmod iceburn wildfire ocean
236

237
# Create modules in specific directory
238
mkdir colormap_modules
239
cmr mkcmod rainforest iceburn --dir colormap_modules
240

241
# Create modules for all sequential colormaps
242
cmr mkcmod amber amethyst apple arctic bubblegum chroma cosmic --dir sequential_modules
243
```
244

245
### Application Integration Commands
246

247
#### Tableau Integration
248

249
```bash { .api }
250
cmr app_usage tableau [OPTIONS]
251

252
# Options:
253
# -d/--dir DIR: Directory for Tableau preferences file (default: current)
254
```
255

256
##### Usage Examples
257

258
```bash
259
# Update Tableau preferences in current directory
260
cmr app_usage tableau
261

262
# Update in specific directory
263
cmr app_usage tableau --dir ~/Documents/My\ Tableau\ Repository/Preferences
264

265
# Update in Tableau's default location (adjust path for your system)
266
cmr app_usage tableau --dir "/c/Users/username/Documents/My Tableau Repository/Preferences"
267
```
268

269
#### Language Usage Information
270

271
```bash { .api }
272
cmr lang_usage r
273
```
274

275
Displays URL to documentation for using CMasher colormaps in R.
276

277
## Advanced Usage Patterns
278

279
### Batch Operations
280

281
```bash
282
# Create visualization for all diverging colormaps
283
for cmap in $(cmr cmlist --type diverging); do
284
    cmr cmview cmr.$cmap --save ${cmap}_view.png
285
done
286

287
# Extract color palettes for web design
288
mkdir web_colors
289
for cmap in rainforest ocean ember iceburn; do
290
    cmr cmcolors cmr.$cmap 8 --fmt hex > web_colors/${cmap}_palette.txt
291
done
292

293
# Generate standalone modules for distribution
294
mkdir cmasher_modules
295
cmr cmlist --type sequential | head -5 | xargs cmr mkcmod --dir cmasher_modules
296
```
297

298
### Pipeline Integration
299

300
```bash
301
# Use in data processing pipeline
302
COLORMAP_TYPE=$(cmr cmtype cmr.rainforest)
303
echo "Using $COLORMAP_TYPE colormap for data visualization"
304

305
# Extract colors for external plotting tool
306
cmr cmcolors cmr.ocean 256 --fmt hex > ocean_colormap.hex
307

308
# Integrate with other tools
309
cmr rgbtable cmr.iceburn --fmt int | python process_colors.py
310
```
311

312
### Configuration and Environment
313

314
```bash
315
# Set environment variable for additional colormap packages
316
export CMR_CMAP_PKGS="colorcet:cmocean"
317

318
# Use with custom colormap packages
319
cmr cmtype colorcet.fire  # If colorcet is installed
320

321
# Object path syntax for custom colormaps
322
cmr cmtype mypackage.colormaps:custom_cmap
323
```
324

325
### Output Redirection and Processing
326

327
```bash
328
# Save colormap list to file
329
cmr cmlist > available_colormaps.txt
330

331
# Create color lookup table
332
cmr cmcolors cmr.rainforest 100 --fmt hex > rainforest_lut.txt
333

334
# Extract specific color ranges
335
cmr cmcolors cmr.iceburn 20 --range 0.0 0.5 --fmt int > iceburn_cool.rgb
336
cmr cmcolors cmr.iceburn 20 --range 0.5 1.0 --fmt int > iceburn_warm.rgb
337

338
# Process multiple colormaps
339
echo "rainforest ocean ember" | xargs -n1 -I{} cmr cmcolors cmr.{} 5 --fmt hex
340
```
341

342
### Help and Documentation
343

344
```bash
345
# Get general help
346
cmr --help
347

348
# Get help for specific commands
349
cmr cmcolors --help
350
cmr cmview --help
351
cmr app_usage --help
352

353
# Get help for subcommands
354
cmr app_usage tableau --help
355
cmr lang_usage --help
356
```
357

358
### Error Handling
359

360
The CLI provides informative error messages:
361

362
```bash
363
# Invalid colormap name
364
cmr cmtype invalid_colormap
365
# Output: Requested 'CMAP' ('invalid_colormap') cannot be found!
366

367
# Invalid command
368
cmr invalidcommand
369
# Shows help with available commands
370

371
# Missing required arguments
372
cmr cmcolors
373
# Shows usage information for cmcolors command
374
```
375

376
### Integration with Scripts
377

378
```python
379
#!/usr/bin/env python3
380
import subprocess
381
import json
382

383
def get_cmasher_info(cmap_name):
384
    """Get colormap information using CLI."""
385
    
386
    # Get colormap type
387
    result = subprocess.run(['cmr', 'cmtype', f'cmr.{cmap_name}'], 
388
                          capture_output=True, text=True)
389
    cmap_type = result.stdout.strip()
390
    
391
    # Get color palette
392
    result = subprocess.run(['cmr', 'cmcolors', f'cmr.{cmap_name}', '10', '--fmt', 'hex'],
393
                          capture_output=True, text=True)
394
    colors = result.stdout.strip().split('\n')
395
    
396
    return {
397
        'name': cmap_name,
398
        'type': cmap_type,
399
        'palette': colors
400
    }
401

402
# Example usage
403
info = get_cmasher_info('rainforest')
404
print(json.dumps(info, indent=2))
405
```