0
# Color Management
1

2
Color handling with support for RGB, CMYK, hex colors, gradients, patterns, and spot colors with comprehensive opacity control.
3

4
## Capabilities
5

6
### Basic Color Control
7

8
Methods for setting fill and stroke colors with opacity support.
9

10
```javascript { .api }
11
/**
12
 * Set fill color
13
 * @param color - Color value in various formats
14
 * @param opacity - Opacity (0.0 to 1.0)
15
 * @returns Document instance for chaining
16
 */
17
fillColor(color: ColorValue, opacity?: number): PDFDocument;
18

19
/**
20
 * Set stroke color
21
 * @param color - Color value in various formats
22
 * @param opacity - Opacity (0.0 to 1.0)
23
 * @returns Document instance for chaining
24
 */
25
strokeColor(color: ColorValue, opacity?: number): PDFDocument;
26

27
type ColorValue = 
28
  | string                              // Hex or named color
29
  | [number, number, number]            // RGB array (0-255)
30
  | [number, number, number, number]    // CMYK array (0-100)
31
  | Gradient                            // Gradient object
32
  | Pattern;                            // Pattern array
33
```
34

35
**Usage Examples:**
36

37
```javascript
38
// Hex colors
39
doc.fillColor('#FF0000')      // Red
40
   .rect(100, 100, 50, 50)
41
   .fill();
42

43
doc.fillColor('#00F')         // Short hex blue
44
   .rect(200, 100, 50, 50)
45
   .fill();
46

47
// RGB colors (0-255)
48
doc.fillColor([255, 165, 0])  // Orange
49
   .rect(300, 100, 50, 50)
50
   .fill();
51

52
// CMYK colors (0-100)
53
doc.fillColor([0, 100, 100, 0])  // Red in CMYK
54
   .rect(400, 100, 50, 50)
55
   .fill();
56

57
// Named colors
58
doc.fillColor('lightblue')
59
   .rect(100, 200, 50, 50)
60
   .fill();
61

62
// With opacity
63
doc.fillColor('red', 0.5)     // 50% transparent red
64
   .rect(200, 200, 50, 50)
65
   .fill();
66
```
67

68
### Opacity Control
69

70
Methods for controlling transparency independently for fill and stroke.
71

72
```javascript { .api }
73
/**
74
 * Set both fill and stroke opacity
75
 * @param opacity - Opacity value (0.0 to 1.0)
76
 * @returns Document instance for chaining
77
 */
78
opacity(opacity: number): PDFDocument;
79

80
/**
81
 * Set fill opacity only
82
 * @param opacity - Fill opacity (0.0 to 1.0)
83
 * @returns Document instance for chaining
84
 */
85
fillOpacity(opacity: number): PDFDocument;
86

87
/**
88
 * Set stroke opacity only
89
 * @param opacity - Stroke opacity (0.0 to 1.0)
90
 * @returns Document instance for chaining
91
 */
92
strokeOpacity(opacity: number): PDFDocument;
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
// Global opacity
99
doc.opacity(0.7)
100
   .fillColor('blue')
101
   .strokeColor('red')
102
   .rect(100, 100, 100, 50)
103
   .fillAndStroke();
104

105
// Independent opacity control
106
doc.fillOpacity(0.3)
107
   .strokeOpacity(1.0)
108
   .fillColor('green')
109
   .strokeColor('black')
110
   .circle(200, 200, 40)
111
   .fillAndStroke();
112
```
113

114
### Linear Gradients
115

116
Create and use linear gradients for sophisticated color effects.
117

118
```javascript { .api }
119
/**
120
 * Create linear gradient
121
 * @param x1 - Start X coordinate
122
 * @param y1 - Start Y coordinate
123
 * @param x2 - End X coordinate
124
 * @param y2 - End Y coordinate
125
 * @returns Gradient object for use with colors
126
 */
127
linearGradient(x1: number, y1: number, x2: number, y2: number): Gradient;
128

129
interface Gradient {
130
  /** Add color stop to gradient */
131
  stop(offset: number, color: ColorValue, opacity?: number): Gradient;
132
}
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
// Simple two-color gradient
139
const gradient1 = doc.linearGradient(100, 100, 200, 100)
140
  .stop(0, 'red')
141
  .stop(1, 'blue');
142

143
doc.rect(100, 100, 100, 50)
144
   .fill(gradient1);
145

146
// Multi-stop gradient
147
const gradient2 = doc.linearGradient(100, 200, 100, 300)
148
  .stop(0, 'yellow')
149
  .stop(0.5, 'orange') 
150
  .stop(1, 'red');
151

152
doc.rect(100, 200, 100, 100)
153
   .fill(gradient2);
154

155
// Diagonal gradient with opacity
156
const gradient3 = doc.linearGradient(250, 100, 350, 200)
157
  .stop(0, 'purple', 1.0)
158
  .stop(1, 'purple', 0.0);  // Fade to transparent
159

160
doc.rect(250, 100, 100, 100)
161
   .fill(gradient3);
162
```
163

164
### Radial Gradients
165

166
Create radial gradients for circular color transitions.
167

168
```javascript { .api }
169
/**
170
 * Create radial gradient
171
 * @param x1 - Inner circle center X
172
 * @param y1 - Inner circle center Y
173
 * @param r1 - Inner circle radius
174
 * @param x2 - Outer circle center X
175
 * @param y2 - Outer circle center Y
176
 * @param r2 - Outer circle radius
177
 * @returns Gradient object for use with colors
178
 */
179
radialGradient(x1: number, y1: number, r1: number, x2: number, y2: number, r2: number): Gradient;
180
```
181

182
**Usage Examples:**
183

184
```javascript
185
// Concentric radial gradient
186
const radial1 = doc.radialGradient(150, 150, 0, 150, 150, 50)
187
  .stop(0, 'white')
188
  .stop(1, 'black');
189

190
doc.circle(150, 150, 50)
191
   .fill(radial1);
192

193
// Offset radial gradient (light source effect)
194
const radial2 = doc.radialGradient(170, 130, 0, 150, 150, 50)
195
  .stop(0, 'yellow')
196
  .stop(0.7, 'orange')
197
  .stop(1, 'red');
198

199
doc.circle(150, 250, 50)
200
   .fill(radial2);
201
```
202

203
### Pattern Support
204

205
Create tiling patterns for complex fills.
206

207
```javascript { .api }
208
/**
209
 * Create tiling pattern
210
 * @param bbox - Pattern bounding box [x, y, width, height]
211
 * @param xStep - Horizontal step between pattern tiles
212
 * @param yStep - Vertical step between pattern tiles
213
 * @param stream - Pattern content stream
214
 * @returns Pattern for use with colors
215
 */
216
pattern(bbox: [number, number, number, number], xStep: number, yStep: number, stream: string): Pattern;
217

218
type Pattern = [PatternObject, ColorValue];
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
// Simple dot pattern
225
const dotPattern = doc.pattern([0, 0, 10, 10], 10, 10, `
226
  2 0 0 2 0 0 cm
227
  0 0 5 5 re
228
  f
229
`);
230

231
doc.rect(100, 100, 100, 100)
232
   .fill([dotPattern, [0, 0, 0]]);  // Black dots
233

234
// Diagonal line pattern
235
const linePattern = doc.pattern([0, 0, 8, 8], 8, 8, `
236
  1 w
237
  0 0 m
238
  8 8 l
239
  S
240
`);
241

242
doc.rect(250, 100, 100, 100)
243
   .fill([linePattern, [100, 0, 0]]);  // Red diagonal lines
244
```
245

246
### Spot Colors
247

248
Define and use spot colors for professional printing.
249

250
```javascript { .api }
251
/**
252
 * Add spot color definition
253
 * @param name - Spot color name
254
 * @param C - Cyan component (0-100)
255
 * @param M - Magenta component (0-100)
256
 * @param Y - Yellow component (0-100)
257
 * @param K - Black component (0-100)
258
 * @returns Document instance for chaining
259
 */
260
addSpotColor(name: string, C: number, M: number, Y: number, K: number): PDFDocument;
261
```
262

263
**Usage Examples:**
264

265
```javascript
266
// Define Pantone-like spot color
267
doc.addSpotColor('PMS186', 0, 100, 91, 0);  // Pantone 186 (red)
268

269
// Use spot color
270
doc.fillColor('PMS186')
271
   .rect(100, 100, 100, 50)
272
   .fill();
273

274
// Spot color with tint
275
doc.fillColor(['PMS186', 0.5])  // 50% tint
276
   .rect(100, 200, 100, 50)
277
   .fill();
278
```
279

280
## Supported Color Formats
281

282
### Named Colors
283

284
PDFKit supports 140+ CSS named colors including:
285

286
```javascript { .api }
287
type NamedColor = 
288
  // Basic colors
289
  | 'black' | 'white' | 'red' | 'green' | 'blue' | 'yellow' | 'cyan' | 'magenta'
290
  // Extended colors
291
  | 'aliceblue' | 'antiquewhite' | 'aqua' | 'aquamarine' | 'azure' | 'beige'
292
  | 'bisque' | 'blanchedalmond' | 'blueviolet' | 'brown' | 'burlywood'
293
  // ... and many more
294
  ;
295
```
296

297
### Hex Color Formats
298

299
```javascript
300
// 6-digit hex
301
doc.fillColor('#FF0000');    // Red
302
doc.fillColor('#00FF00');    // Green
303
doc.fillColor('#0000FF');    // Blue
304

305
// 3-digit hex (expanded automatically)
306
doc.fillColor('#F00');       // Red (#FF0000)
307
doc.fillColor('#0F0');       // Green (#00FF00)
308
doc.fillColor('#00F');       // Blue (#0000FF)
309
```
310

311
### RGB Color Arrays
312

313
```javascript
314
// RGB values 0-255
315
doc.fillColor([255, 0, 0]);     // Red
316
doc.fillColor([0, 255, 0]);     // Green
317
doc.fillColor([0, 0, 255]);     // Blue
318
doc.fillColor([128, 128, 128]); // Gray
319
```
320

321
### CMYK Color Arrays
322

323
```javascript
324
// CMYK values 0-100
325
doc.fillColor([0, 100, 100, 0]);   // Red
326
doc.fillColor([100, 0, 100, 0]);   // Green  
327
doc.fillColor([100, 100, 0, 0]);   // Blue
328
doc.fillColor([0, 0, 0, 50]);      // 50% Gray
329
```
330

331
## Color Space Support
332

333
- **DeviceRGB**: Standard RGB color space
334
- **DeviceCMYK**: CMYK color space for printing
335
- **DeviceGray**: Grayscale color space
336
- **Spot Colors**: Custom spot color spaces
337
- **ICC Profiles**: Custom color profiles (advanced)
338

339
## Color Management Best Practices
340

341
1. **Consistency**: Use the same color space throughout a document
342
2. **Printing**: Use CMYK colors for print-intended documents
343
3. **Web/Screen**: Use RGB colors for screen-only documents
344
4. **Transparency**: Be aware that transparency can affect color appearance
345
5. **Spot Colors**: Use for brand colors or special printing requirements
346
6. **Gradients**: Test gradient rendering at target output resolution