0
# CMasher
1

2
Scientific colormaps for making accessible, informative and "cmashing" plots. CMasher provides a comprehensive collection of perceptually uniform sequential, diverging, and cyclic colormaps designed for data visualization, along with utilities for colormap manipulation and integration with matplotlib.
3

4
## Package Information
5

6
- **Package Name**: cmasher
7
- **Language**: Python
8
- **Installation**: `pip install cmasher`
9

10
## Core Imports
11

12
```python
13
import cmasher as cmr
14
```
15

16
For direct access to colormaps:
17

18
```python
19
import cmasher.cm as cmrcm
20
```
21

22
For utility functions:
23

24
```python
25
from cmasher import (
26
    take_cmap_colors, view_cmap, get_cmap_type, 
27
    create_cmap_overview, combine_cmaps
28
)
29
```
30

31
## Basic Usage
32

33
```python
34
import cmasher as cmr
35
import matplotlib.pyplot as plt
36
import numpy as np
37

38
# Basic plotting with CMasher colormap
39
data = np.random.rand(10, 10)
40
plt.imshow(data, cmap='cmr.rainforest')
41
plt.colorbar()
42
plt.show()
43

44
# Extract colors from a colormap
45
colors = cmr.take_cmap_colors('cmr.ocean', 5, return_fmt='hex')
46
print(colors)  # ['#000000', '#1B4F72', '#0E8474', '#A4C639', '#FFFFFF']
47

48
# View a colormap
49
cmr.view_cmap('cmr.iceburn', show_grayscale=True)
50

51
# Get colormap type
52
print(cmr.get_cmap_type('cmr.iceburn'))  # 'diverging'
53
```
54

55
## Architecture
56

57
CMasher is organized around several key components:
58

59
- **Colormap Collections**: Pre-defined scientific colormaps organized by type (sequential, diverging, cyclic)
60
- **Colormap Utilities**: Functions for manipulating, combining, and analyzing colormaps
61
- **Integration Tools**: Utilities for exporting colormaps to other applications (Tableau, R)
62
- **CLI Interface**: Command-line tools for colormap management and visualization
63
- **Type System**: Comprehensive colormap classification and validation
64

65
## Capabilities
66

67
### Colormap Collections
68

69
Access to 53 scientifically designed colormaps organized by type: sequential (37), diverging (12), and cyclic (4). All colormaps are perceptually uniform and color-vision deficiency friendly.
70

71
```python { .api }
72
# Sequential colormaps
73
cmrcm.rainforest  # ListedColormap
74
cmrcm.ocean       # ListedColormap
75
cmrcm.amber       # ListedColormap
76

77
# Diverging colormaps  
78
cmrcm.iceburn     # ListedColormap
79
cmrcm.fusion      # ListedColormap
80
cmrcm.wildfire    # ListedColormap
81

82
# Cyclic colormaps
83
cmrcm.seasons     # ListedColormap
84
cmrcm.infinity    # ListedColormap
85

86
# Colormap dictionaries
87
cmrcm.cmap_d      # dict[str, ListedColormap] - all colormaps
88
cmrcm.cmap_cd     # dict[str, dict[str, ListedColormap]] - by type
89
```
90

91
[Colormap Collections](./colormap-collections.md)
92

93
### Color Extraction and Analysis
94

95
Extract colors from colormaps and analyze their properties for data visualization workflows.
96

97
```python { .api }
98
def take_cmap_colors(
99
    cmap: str | Colormap,
100
    N: int | None,
101
    *,
102
    cmap_range: tuple[float, float] = (0, 1),
103
    return_fmt: str = "float"
104
) -> list[tuple[float, float, float]] | list[tuple[int, int, int]] | list[str]: ...
105

106
def get_cmap_type(cmap: str | Colormap) -> str: ...
107

108
def get_cmap_list(cmap_type: str = "all") -> list[str]: ...
109
```
110

111
[Color Extraction and Analysis](./color-analysis.md)
112

113
### Colormap Visualization
114

115
Create visualizations of colormaps for evaluation and presentation.
116

117
```python { .api }
118
def view_cmap(
119
    cmap: str | Colormap,
120
    *,
121
    savefig: str | None = None,
122
    show_test: bool = False,
123
    show_grayscale: bool = False
124
) -> None: ...
125

126
def create_cmap_overview(
127
    cmaps: list[str | Colormap] | dict[str, list[Colormap]] | None = None,
128
    *,
129
    savefig: str | os.PathLike[str] | None = None,
130
    use_types: bool = True,
131
    sort: str | Callable | None = "alphabetical",
132
    show_grayscale: bool = True,
133
    show_info: bool = False,
134
    plot_profile: bool | float = False,
135
    dark_mode: bool = False,
136
    title: str | None = "Colormap Overview",
137
    wscale: float = 1,
138
    hscale: float = 1
139
) -> None: ...
140
```
141

142
[Colormap Visualization](./visualization.md)
143

144
### Colormap Manipulation
145

146
Combine and modify colormaps to create custom color schemes.
147

148
```python { .api }
149
def combine_cmaps(
150
    *cmaps: Colormap | str,
151
    nodes: list[float] | np.ndarray | None = None,
152
    n_rgb_levels: int = 256,
153
    combined_cmap_name: str = "combined_cmap"
154
) -> LinearSegmentedColormap: ...
155

156
def get_sub_cmap(
157
    cmap: str | Colormap,
158
    start: float,
159
    stop: float,
160
    *,
161
    N: int | None = None
162
) -> ListedColormap: ...
163
```
164

165
[Colormap Manipulation](./manipulation.md)
166

167
### Colormap Registration and Import
168

169
Register custom colormaps and import colormap data from various formats.
170

171
```python { .api }
172
def register_cmap(name: str, data: list[tuple[float, float, float]] | list[tuple[int, int, int]] | list[str]) -> None: ...
173

174
def import_cmaps(
175
    cmap_path: str | os.PathLike[str],
176
    *,
177
    _skip_registration: bool = False
178
) -> None: ...
179

180
def create_cmap_mod(
181
    cmap: str,
182
    *,
183
    save_dir: str | os.PathLike[str] = ".",
184
    _copy_name: str | None = None
185
) -> str: ...
186
```
187

188
[Colormap Registration](./registration.md)
189

190
### Application Integration
191

192
Export colormaps to external applications and set up matplotlib integration features.
193

194
```python { .api }
195
def update_tableau_pref_file(dirname: str | os.PathLike[str] = ".") -> None: ...
196

197
def set_cmap_legend_entry(artist: Artist, label: str) -> None: ...
198

199
def get_bibtex() -> None: ...
200
```
201

202
[Application Integration](./integration.md)
203

204
### Command Line Interface
205

206
CLI tools for colormap management, visualization, and color extraction accessible via the `cmr` command.
207

208
```bash { .api }
209
cmr bibtex                    # Print BibTeX citation
210
cmr cmlist [--type TYPE]      # List available colormaps
211
cmr cmtype CMAP               # Show colormap type
212
cmr cmcolors CMAP N [OPTIONS] # Extract colors from colormap
213
cmr cmview CMAP [OPTIONS]     # View colormap
214
cmr mkcmod CMAP [CMAPS...]    # Create standalone modules
215
```
216

217
[CLI Tools](./cli-tools.md)
218

219
## Types
220

221
```python { .api }
222
import os
223
from collections.abc import Callable
224
from matplotlib.colors import Colormap, ListedColormap, LinearSegmentedColormap
225
from matplotlib.artist import Artist
226
from typing import Union, TypeAlias
227
import numpy as np
228

229
# Core type aliases
230
CMAP = Union[str, Colormap]
231
RGB = list[tuple[float, float, float]]
232
RED: TypeAlias = float
233
GREEN: TypeAlias = float
234
BLUE: TypeAlias = float
235

236
# Colormap collections
237
cmap_d: dict[str, ListedColormap]  # All colormaps by name
238
cmap_cd: dict[str, dict[str, ListedColormap]]  # Categorized colormaps
239
# cmap_cd contains: "sequential", "diverging", "cyclic", "qualitative", "misc"
240

241
# Package metadata
242
__version__: str
243
__author__: str
244
```