0
# Colour Notation Systems
1

2
Colour notation systems including Munsell Color System, hexadecimal color codes, CSS color names, and conversions between different color representation formats.
3

4
## Capabilities
5

6
### Munsell Color System
7

8
The Munsell Color System provides a standardized way to describe colors using hue, value (lightness), and chroma (saturation) dimensions.
9

10
```python { .api }
11
def munsell_value(Y: ArrayLike, method: str = "ASTM D1535", **kwargs) -> NDArray:
12
    """
13
    Calculate Munsell value from relative luminance.
14
    
15
    Parameters:
16
    - Y: relative luminance values (0-100 scale)
17
    - method: computation method
18
        - "ASTM D1535" (default): ASTM D1535-08e1 method
19
        - "Priest 1920": Priest, Gibson, and McNicholas (1920)
20
        - "Munsell 1933": Munsell, Sloan, and Godlove (1933)
21
        - "Moon 1943": Moon and Spencer (1943)
22
        - "Saunderson 1944": Saunderson and Milner (1944)
23
        - "Ladd 1955": Ladd and Pinney (1955)
24
        - "McCamy 1987": McCamy (1987)
25
    
26
    Returns:
27
    Munsell value (lightness) on 0-10 scale
28
    """
29

30
def munsell_colour_to_xyY(specification: str) -> NDArray:
31
    """
32
    Convert Munsell color specification to CIE xyY chromaticity coordinates.
33
    
34
    Parameters:
35
    - specification: Munsell specification string (e.g., "N 5/", "5R 5/14")
36
    
37
    Returns:
38
    CIE xyY chromaticity coordinates as ndarray shape (3,)
39
    """
40

41
def xyY_to_munsell_colour(xyY: ArrayLike) -> str:
42
    """
43
    Convert CIE xyY chromaticity coordinates to Munsell color specification.
44
    
45
    Parameters:
46
    - xyY: CIE xyY chromaticity coordinates
47
    
48
    Returns:
49
    Munsell specification string
50
    """
51

52
# Method collection for Munsell value computation
53
MUNSELL_VALUE_METHODS: Dict[str, Callable]
54
```
55

56
### Hexadecimal Color Codes
57

58
Functions for converting between RGB color values and hexadecimal color codes.
59

60
```python { .api }
61
def RGB_to_HEX(RGB: ArrayLike) -> str:
62
    """
63
    Convert RGB color values to hexadecimal color code.
64
    
65
    Parameters:
66
    - RGB: RGB color values in 0-1 range as ndarray shape (3,)
67
    
68
    Returns:
69
    Hexadecimal color code string (e.g., "#FF5733")
70
    """
71

72
def HEX_to_RGB(HEX: str) -> NDArray:
73
    """
74
    Convert hexadecimal color code to RGB color values.
75
    
76
    Parameters:
77
    - HEX: hexadecimal color code string (e.g., "#FF5733" or "FF5733")
78
    
79
    Returns:
80
    RGB color values in 0-1 range as ndarray shape (3,)
81
    """
82
```
83

84
### CSS Color Names
85

86
CSS Color Module Level 3 color name support for web-compatible color specifications.
87

88
```python { .api }
89
def keyword_to_RGB_CSSColor3(keyword: str) -> NDArray:
90
    """
91
    Convert CSS Color Module Level 3 color keyword to RGB values.
92
    
93
    Parameters:
94
    - keyword: CSS color keyword (e.g., "red", "blue", "darkslategray")
95
    
96
    Returns:
97
    RGB color values in 0-1 range as ndarray shape (3,)
98
    """
99
```
100

101
### Color Datasets
102

103
Predefined color collections for reference and lookup operations.
104

105
```python { .api }
106
# Munsell color datasets
107
MUNSELL_COLOURS_ALL: Dict[str, NDArray]  # Complete Munsell color collection
108
MUNSELL_COLOURS_1929: Dict[str, NDArray]  # Munsell 1929 colors
109
MUNSELL_COLOURS_REAL: Dict[str, NDArray]  # Real Munsell colors subset
110
MUNSELL_COLOURS: Dict[str, NDArray]  # Standard Munsell colors (alias for REAL)
111

112
# CSS color datasets  
113
CSS_COLOR_3_BASIC: Dict[str, NDArray]  # 16 basic CSS colors
114
CSS_COLOR_3_EXTENDED: Dict[str, NDArray]  # Extended CSS color keywords
115
CSS_COLOR_3: Dict[str, NDArray]  # Complete CSS Color 3 specification
116
```
117

118
## Usage Examples
119

120
### Munsell Color System
121

122
```python
123
import colour
124
import numpy as np
125

126
# Calculate Munsell value from luminance
127
Y = 18.0  # 18% reflectance
128
munsell_value = colour.munsell_value(Y, method="ASTM D1535")
129
print(f"Munsell value: {munsell_value:.2f}")
130

131
# Convert Munsell specification to xyY
132
munsell_spec = "5R 5/14"  # 5 Red, value 5, chroma 14
133
xyY = colour.munsell_colour_to_xyY(munsell_spec)
134
print(f"xyY coordinates: {xyY}")
135

136
# Convert xyY back to Munsell
137
recovered_spec = colour.xyY_to_munsell_colour(xyY)
138
print(f"Recovered Munsell: {recovered_spec}")
139
```
140

141
### Hexadecimal Colors
142

143
```python
144
import colour
145
import numpy as np
146

147
# Convert RGB to hexadecimal
148
RGB = np.array([1.0, 0.341, 0.2])  # Orange color
149
hex_code = colour.RGB_to_HEX(RGB)
150
print(f"Hex code: {hex_code}")  # #FF5733
151

152
# Convert hexadecimal to RGB
153
RGB_recovered = colour.HEX_to_RGB("#FF5733")
154
print(f"RGB values: {RGB_recovered}")
155
```
156

157
### CSS Color Keywords
158

159
```python
160
import colour
161

162
# Convert CSS color names to RGB
163
red_rgb = colour.keyword_to_RGB_CSSColor3("red")
164
blue_rgb = colour.keyword_to_RGB_CSSColor3("blue")
165
custom_rgb = colour.keyword_to_RGB_CSSColor3("darkslategray")
166

167
print(f"Red RGB: {red_rgb}")
168
print(f"Blue RGB: {blue_rgb}")
169
print(f"Dark Slate Gray RGB: {custom_rgb}")
170
```
171

172
### Working with Color Datasets
173

174
```python
175
import colour
176

177
# Access Munsell color data
178
munsell_colors = colour.MUNSELL_COLOURS
179
print(f"Available Munsell colors: {len(munsell_colors)}")
180

181
# Access specific Munsell color
182
if "5R 5/14" in munsell_colors:
183
    xyY = munsell_colors["5R 5/14"] 
184
    print(f"5R 5/14 xyY: {xyY}")
185

186
# Access CSS colors
187
css_colors = colour.CSS_COLOR_3
188
print(f"Available CSS colors: {len(css_colors)}")
189
print(f"CSS red: {css_colors['red']}")
190
```
191

192
## Types
193

194
```python { .api }
195
from colour.hints import ArrayLike, NDArray, Dict, Callable
196
from typing import Dict, Callable
197

198
# Type definitions for color datasets
199
ColorDataset = Dict[str, NDArray]
200
MethodCollection = Dict[str, Callable]
201
```
202

203
## Imports
204

205
```python
206
# Munsell system
207
from colour.notation import (
208
    munsell_value, munsell_colour_to_xyY, xyY_to_munsell_colour,
209
    MUNSELL_VALUE_METHODS, MUNSELL_COLOURS, MUNSELL_COLOURS_ALL
210
)
211

212
# Hexadecimal colors
213
from colour.notation import RGB_to_HEX, HEX_to_RGB
214

215
# CSS colors
216
from colour.notation import keyword_to_RGB_CSSColor3, CSS_COLOR_3
217

218
# Alternative imports from main package
219
from colour import (
220
    munsell_value, munsell_colour_to_xyY, xyY_to_munsell_colour,
221
    RGB_to_HEX, HEX_to_RGB, keyword_to_RGB_CSSColor3
222
)
223
```