0
# Color Utilities
1

2
Comprehensive color manipulation and conversion utilities supporting multiple color formats including CSS colors, RGBA, HSL, and specialized rendering formats for map styling.
3

4
## Capabilities
5

6
### Color Class
7

8
Main color manipulation class providing parsing, conversion, and arithmetic operations.
9

10
```typescript { .api }
11
/**
12
 * Main color class for parsing and manipulating colors
13
 * @param r - Red component (0-1)
14
 * @param g - Green component (0-1)  
15
 * @param b - Blue component (0-1)
16
 * @param a - Alpha component (0-1, default: 1)
17
 */
18
class Color {
19
  constructor(r: number, g: number, b: number, a?: number);
20
  
21
  /** Red component (0-1) */
22
  readonly r: number;
23
  /** Green component (0-1) */
24
  readonly g: number;
25
  /** Blue component (0-1) */
26
  readonly b: number;
27
  /** Alpha component (0-1) */
28
  readonly a: number;
29

30
  /**
31
   * Parses a CSS color string into a Color instance
32
   * @param input - CSS color string (hex, rgb, rgba, hsl, hsla, named colors)
33
   * @returns Color instance or undefined if parsing fails
34
   */
35
  static parse(input: string): Color | undefined;
36

37
  /**
38
   * Converts color to RGBA string representation
39
   * @returns RGBA string format "rgba(r, g, b, a)"
40
   */
41
  toString(): string;
42

43
  /**
44
   * Creates a deep copy of the color
45
   * @returns New Color instance with same values
46
   */
47
  clone(): Color;
48

49
  // Predefined color constants
50
  static readonly black: Color;
51
  static readonly white: Color;
52
  static readonly transparent: Color;
53
  static readonly red: Color;
54
  static readonly blue: Color;
55
}
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
import { Color } from "@mapbox/mapbox-gl-style-spec";
62

63
// Create colors from components
64
const red = new Color(1, 0, 0, 1);
65
const semiTransparent = new Color(0.5, 0.5, 0.5, 0.8);
66

67
// Parse CSS color strings
68
const parsed1 = Color.parse('#ff0000');        // Hex
69
const parsed2 = Color.parse('rgb(255, 0, 0)'); // RGB
70
const parsed3 = Color.parse('rgba(255, 0, 0, 0.5)'); // RGBA
71
const parsed4 = Color.parse('hsl(0, 100%, 50%)');    // HSL
72
const parsed5 = Color.parse('red');                  // Named color
73

74
// Use predefined colors
75
const black = Color.black;
76
const white = Color.white;
77
const transparent = Color.transparent;
78

79
// Convert to string
80
console.log(red.toString()); // "rgba(255, 0, 0, 1)"
81

82
// Clone colors
83
const redCopy = red.clone();
84
```
85

86
### Render Color Classes
87

88
Specialized color classes for different rendering contexts with alpha channel handling.
89

90
```typescript { .api }
91
/**
92
 * Abstract base class for renderable colors
93
 */
94
abstract class RenderColor {
95
  readonly r: number;
96
  readonly g: number;
97
  readonly b: number;
98
  readonly a: number;
99

100
  constructor(r: number, g: number, b: number, a: number);
101
  
102
  /**
103
   * Converts to array representation for rendering
104
   * @returns RGBA array [r, g, b, a]
105
   */
106
  abstract toArray(): [number, number, number, number];
107
}
108

109
/**
110
 * Color with non-premultiplied alpha for standard rendering
111
 */
112
class NonPremultipliedRenderColor extends RenderColor {
113
  /**
114
   * @param lut - Lookup table for color transformation (can be null)
115
   * @param r - Red component (0-1)
116
   * @param g - Green component (0-1)
117
   * @param b - Blue component (0-1) 
118
   * @param a - Alpha component (0-1)
119
   */
120
  constructor(lut: LUT | null, r: number, g: number, b: number, a: number);
121
  
122
  toArray(): [number, number, number, number];
123
}
124

125
/**
126
 * Color with premultiplied alpha for optimized rendering
127
 */
128
class PremultipliedRenderColor extends RenderColor {
129
  /**
130
   * @param lut - Lookup table for color transformation (can be null)
131
   * @param r - Red component (0-1)
132
   * @param g - Green component (0-1)
133
   * @param b - Blue component (0-1)
134
   * @param a - Alpha component (0-1)
135
   */
136
  constructor(lut: LUT | null, r: number, g: number, b: number, a: number);
137
  
138
  toArray(): [number, number, number, number];
139
}
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
import { NonPremultipliedRenderColor, PremultipliedRenderColor } from "@mapbox/mapbox-gl-style-spec";
146

147
// Standard rendering color (no LUT)
148
const standardColor = new NonPremultipliedRenderColor(null, 1, 0, 0, 0.5);
149
console.log(standardColor.toArray()); // [1, 0, 0, 0.5]
150

151
// Optimized rendering color with premultiplied alpha (no LUT)
152
const premultColor = new PremultipliedRenderColor(null, 0.5, 0, 0, 0.5);
153
console.log(premultColor.toArray()); // [0.5, 0, 0, 0.5]
154
```
155

156
## Color Format Support
157

158
### Supported Input Formats
159

160
The Color.parse() method supports a wide range of CSS color formats:
161

162
```typescript { .api }
163
// Hex formats
164
Color.parse('#ff0000');     // 6-digit hex
165
Color.parse('#f00');        // 3-digit hex
166
Color.parse('#ff0000ff');   // 8-digit hex with alpha
167
Color.parse('#f00f');       // 4-digit hex with alpha
168

169
// RGB/RGBA formats
170
Color.parse('rgb(255, 0, 0)');
171
Color.parse('rgba(255, 0, 0, 0.5)');
172
Color.parse('rgb(100%, 0%, 0%)');      // Percentage values
173
Color.parse('rgba(100%, 0%, 0%, 50%)');
174

175
// HSL/HSLA formats
176
Color.parse('hsl(0, 100%, 50%)');
177
Color.parse('hsla(0, 100%, 50%, 0.5)');
178

179
// Named colors
180
Color.parse('red');
181
Color.parse('blue');
182
Color.parse('transparent');
183
Color.parse('aliceblue');
184
```
185

186
**Usage Examples:**
187

188
```typescript
189
import { Color } from "@mapbox/mapbox-gl-style-spec";
190

191
// Parse various formats
192
const colors = [
193
  Color.parse('#3388ff'),
194
  Color.parse('rgb(51, 136, 255)'),
195
  Color.parse('hsl(215, 100%, 60%)'),
196
  Color.parse('cornflowerblue')
197
].filter(Boolean); // Remove any failed parses
198

199
// Convert all to consistent format
200
colors.forEach(color => {
201
  console.log(color.toString()); // All output as rgba() strings
202
});
203
```
204

205
### Color Space Operations
206

207
While the core Color class focuses on RGBA, the package includes utilities for color space conversions and interpolations:
208

209
```typescript { .api }
210
// Color interpolation utilities (from util/interpolate.ts)
211
interface ColorInterpolationUtilities {
212
  /** Interpolate between colors in RGB space */
213
  interpolateRGB(from: Color, to: Color, t: number): Color;
214
  
215
  /** Interpolate between colors in HSL space */
216
  interpolateHSL(from: Color, to: Color, t: number): Color;
217
  
218
  /** Interpolate between colors in LAB space */
219
  interpolateLAB(from: Color, to: Color, t: number): Color;
220
}
221
```
222

223
## Integration with Style Properties
224

225
### Color Property Values
226

227
Colors integrate seamlessly with style property specifications:
228

229
```typescript { .api }
230
type ColorSpecification = string;
231

232
// Usage in layer properties
233
interface LayerPaintProperties {
234
  'background-color'?: ColorSpecification;
235
  'fill-color'?: PropertyValueSpecification<ColorSpecification>;
236
  'line-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
237
  'text-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
238
  'icon-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
239
}
240
```
241

242
**Usage Examples:**
243

244
```typescript
245
// Static colors in layer properties
246
const layer = {
247
  id: 'buildings',
248
  type: 'fill',
249
  paint: {
250
    'fill-color': '#ff0000',           // Hex
251
    'fill-outline-color': 'rgba(0,0,0,0.5)', // RGBA
252
  }
253
};
254

255
// Dynamic colors with expressions
256
const dynamicLayer = {
257
  id: 'population',
258
  type: 'fill', 
259
  paint: {
260
    'fill-color': [
261
      'interpolate',
262
      ['linear'],
263
      ['get', 'population'],
264
      0, '#ffffcc',
265
      1000, '#c2e699', 
266
      5000, '#78c679',
267
      10000, '#238443'
268
    ]
269
  }
270
};
271
```
272

273
## Types
274

275
```typescript { .api }
276
interface ColorComponents {
277
  r: number; // Red (0-1)
278
  g: number; // Green (0-1)
279
  b: number; // Blue (0-1)
280
  a: number; // Alpha (0-1)
281
}
282

283
type ColorSpecification = string;
284

285
type LUT = any; // Lookup table for color transformations
286

287
interface ColorParseResult {
288
  success: boolean;
289
  color?: Color;
290
  error?: string;
291
}
292
```