0
# Vector Graphics
1

2
Comprehensive vector graphics with path construction, shapes, transformations, and painting operations using an HTML5 canvas-like API.
3

4
## Capabilities
5

6
### Graphics State Management
7

8
Methods for saving and restoring graphics state for isolated transformations and styling.
9

10
```javascript { .api }
11
/**
12
 * Save current graphics state
13
 * @returns Document instance for chaining
14
 */
15
save(): PDFDocument;
16

17
/**
18
 * Restore previously saved graphics state
19
 * @returns Document instance for chaining
20
 */
21
restore(): PDFDocument;
22
```
23

24
**Usage Examples:**
25

26
```javascript
27
// Use save/restore for isolated transformations
28
doc.save()
29
   .translate(100, 100)
30
   .rotate(45)
31
   .rect(0, 0, 50, 50)
32
   .fill('red')
33
   .restore();
34

35
// Continue with original coordinate system
36
doc.rect(200, 100, 50, 50)
37
   .fill('blue');
38
```
39

40
### Path Construction
41

42
Low-level path construction methods for creating custom shapes.
43

44
```javascript { .api }
45
/**
46
 * Move to point without drawing
47
 * @param x - X coordinate
48
 * @param y - Y coordinate
49
 * @returns Document instance for chaining
50
 */
51
moveTo(x: number, y: number): PDFDocument;
52

53
/**
54
 * Draw line to point
55
 * @param x - X coordinate
56
 * @param y - Y coordinate
57
 * @returns Document instance for chaining
58
 */
59
lineTo(x: number, y: number): PDFDocument;
60

61
/**
62
 * Draw cubic Bezier curve
63
 * @param cp1x - First control point X
64
 * @param cp1y - First control point Y
65
 * @param cp2x - Second control point X
66
 * @param cp2y - Second control point Y
67
 * @param x - End point X
68
 * @param y - End point Y
69
 * @returns Document instance for chaining
70
 */
71
bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): PDFDocument;
72

73
/**
74
 * Draw quadratic curve
75
 * @param cpx - Control point X
76
 * @param cpy - Control point Y
77
 * @param x - End point X
78
 * @param y - End point Y
79
 * @returns Document instance for chaining
80
 */
81
quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): PDFDocument;
82

83
/**
84
 * Close current path
85
 * @returns Document instance for chaining
86
 */
87
closePath(): PDFDocument;
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
// Draw custom shape with path construction
94
doc.moveTo(100, 100)
95
   .lineTo(200, 150)
96
   .quadraticCurveTo(250, 100, 300, 150)
97
   .lineTo(250, 200)
98
   .closePath()
99
   .fillAndStroke('lightblue', 'navy');
100

101
// Complex curve
102
doc.moveTo(50, 300)
103
   .bezierCurveTo(50, 250, 150, 250, 150, 300)
104
   .bezierCurveTo(150, 350, 50, 350, 50, 300)
105
   .stroke('purple');
106
```
107

108
### Shape Primitives
109

110
High-level methods for creating common geometric shapes.
111

112
```javascript { .api }
113
/**
114
 * Draw rectangle
115
 * @param x - X coordinate
116
 * @param y - Y coordinate
117
 * @param w - Width
118
 * @param h - Height
119
 * @returns Document instance for chaining
120
 */
121
rect(x: number, y: number, w: number, h: number): PDFDocument;
122

123
/**
124
 * Draw rounded rectangle
125
 * @param x - X coordinate
126
 * @param y - Y coordinate
127
 * @param w - Width
128
 * @param h - Height
129
 * @param r - Corner radius
130
 * @returns Document instance for chaining
131
 */
132
roundedRect(x: number, y: number, w: number, h: number, r: number): PDFDocument;
133

134
/**
135
 * Draw ellipse
136
 * @param x - Center X coordinate
137
 * @param y - Center Y coordinate
138
 * @param r1 - Horizontal radius
139
 * @param r2 - Vertical radius (optional, defaults to r1 for circle)
140
 * @returns Document instance for chaining
141
 */
142
ellipse(x: number, y: number, r1: number, r2?: number): PDFDocument;
143

144
/**
145
 * Draw circle
146
 * @param x - Center X coordinate
147
 * @param y - Center Y coordinate
148
 * @param radius - Circle radius
149
 * @returns Document instance for chaining
150
 */
151
circle(x: number, y: number, radius: number): PDFDocument;
152

153
/**
154
 * Draw arc
155
 * @param x - Center X coordinate
156
 * @param y - Center Y coordinate
157
 * @param radius - Arc radius
158
 * @param startAngle - Start angle in radians
159
 * @param endAngle - End angle in radians
160
 * @param anticlockwise - Draw counterclockwise
161
 * @returns Document instance for chaining
162
 */
163
arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): PDFDocument;
164

165
/**
166
 * Draw polygon from points
167
 * @param points - Array of [x, y] coordinate pairs
168
 * @returns Document instance for chaining
169
 */
170
polygon(...points: [number, number][]): PDFDocument;
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
// Basic shapes
177
doc.rect(100, 100, 150, 100)
178
   .fill('lightgreen');
179

180
doc.circle(300, 150, 50)
181
   .stroke('red');
182

183
doc.roundedRect(100, 250, 150, 100, 10)
184
   .fillAndStroke('yellow', 'orange');
185

186
// Ellipse and arc
187
doc.ellipse(400, 150, 60, 40)
188
   .fill('pink');
189

190
doc.arc(200, 400, 50, 0, Math.PI, false)
191
   .stroke('blue');
192

193
// Polygon (triangle)
194
doc.polygon([100, 500], [150, 450], [200, 500])
195
   .fill('purple');
196
```
197

198
### SVG Path Support
199

200
Support for rendering SVG path strings.
201

202
```javascript { .api }
203
/**
204
 * Render SVG path string
205
 * @param path - SVG path data string
206
 * @returns Document instance for chaining
207
 */
208
path(path: string): PDFDocument;
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
// SVG path for complex shape
215
const heartPath = 'M12,21.35l-1.45-1.32C5.4,15.36,2,12.28,2,8.5 C2,5.42,4.42,3,7.5,3c1.74,0,3.41,0.81,4.5,2.09C13.09,3.81,14.76,3,16.5,3 C19.58,3,22,5.42,22,8.5c0,3.78-3.4,6.86-8.55,11.54L12,21.35z';
216

217
doc.save()
218
   .translate(200, 200)
219
   .scale(3)
220
   .path(heartPath)
221
   .fill('red')
222
   .restore();
223
```
224

225
### Line Styling
226

227
Methods for configuring line appearance and stroke properties.
228

229
```javascript { .api }
230
/**
231
 * Set line width
232
 * @param w - Line width in points
233
 * @returns Document instance for chaining
234
 */
235
lineWidth(w: number): PDFDocument;
236

237
/**
238
 * Set line cap style
239
 * @param style - Cap style
240
 * @returns Document instance for chaining
241
 */
242
lineCap(style: 'BUTT' | 'ROUND' | 'SQUARE' | 0 | 1 | 2): PDFDocument;
243

244
/**
245
 * Set line join style
246
 * @param style - Join style
247
 * @returns Document instance for chaining
248
 */
249
lineJoin(style: 'MITER' | 'ROUND' | 'BEVEL' | 0 | 1 | 2): PDFDocument;
250

251
/**
252
 * Set miter limit for sharp joins
253
 * @param limit - Miter limit
254
 * @returns Document instance for chaining
255
 */
256
miterLimit(limit: number): PDFDocument;
257

258
/**
259
 * Set dash pattern
260
 * @param length - Dash length or pattern array
261
 * @param options - Dash options
262
 * @returns Document instance for chaining
263
 */
264
dash(length: number | number[], options?: DashOptions): PDFDocument;
265

266
/**
267
 * Remove dash pattern (solid line)
268
 * @returns Document instance for chaining
269
 */
270
undash(): PDFDocument;
271

272
interface DashOptions {
273
  /** Phase offset for dash pattern */
274
  phase?: number;
275
  /** Space between dashes */
276
  space?: number;
277
}
278
```
279

280
**Usage Examples:**
281

282
```javascript
283
// Different line styles
284
doc.lineWidth(5)
285
   .lineCap('round')
286
   .moveTo(100, 100)
287
   .lineTo(200, 100)
288
   .stroke('blue');
289

290
doc.lineWidth(3)
291
   .dash(5, { space: 3 })
292
   .rect(100, 150, 100, 50)
293
   .stroke('green');
294

295
doc.lineWidth(2)
296
   .dash([10, 5, 2, 5])  // Complex dash pattern
297
   .circle(300, 175, 40)
298
   .stroke('red');
299

300
// Remove dash for solid line
301
doc.undash()
302
   .lineWidth(1)
303
   .rect(100, 250, 100, 50)
304
   .stroke('black');
305
```
306

307
### Painting Operations
308

309
Methods for filling and stroking paths with colors and effects.
310

311
```javascript { .api }
312
/**
313
 * Fill current path
314
 * @param color - Fill color (optional)
315
 * @param rule - Fill rule for complex paths
316
 * @returns Document instance for chaining
317
 */
318
fill(color?: ColorValue, rule?: 'nonzero' | 'evenodd'): PDFDocument;
319

320
/**
321
 * Stroke current path
322
 * @param color - Stroke color (optional)
323
 * @returns Document instance for chaining
324
 */
325
stroke(color?: ColorValue): PDFDocument;
326

327
/**
328
 * Fill and stroke current path
329
 * @param fillColor - Fill color (optional)
330
 * @param strokeColor - Stroke color (optional)
331
 * @param rule - Fill rule
332
 * @returns Document instance for chaining
333
 */
334
fillAndStroke(fillColor?: ColorValue, strokeColor?: ColorValue, rule?: 'nonzero' | 'evenodd'): PDFDocument;
335

336
/**
337
 * Set clipping path
338
 * @param rule - Clipping rule
339
 * @returns Document instance for chaining
340
 */
341
clip(rule?: 'nonzero' | 'evenodd'): PDFDocument;
342

343
type ColorValue = string | [number, number, number] | [number, number, number, number] | Gradient | Pattern;
344
```
345

346
**Usage Examples:**
347

348
```javascript
349
// Different painting operations
350
doc.rect(100, 100, 100, 50)
351
   .fill('lightblue');
352

353
doc.circle(300, 125, 40)
354
   .stroke('red');
355

356
doc.roundedRect(100, 200, 100, 50, 5)
357
   .fillAndStroke('yellow', 'orange');
358

359
// Using clipping
360
doc.save()
361
   .circle(200, 300, 50)
362
   .clip()
363
   .rect(150, 250, 100, 100)
364
   .fill('purple')
365
   .restore();
366
```
367

368
### Coordinate Transformations
369

370
Methods for transforming the coordinate system.
371

372
```javascript { .api }
373
/**
374
 * Apply transformation matrix
375
 * @param m11 - Horizontal scaling
376
 * @param m12 - Horizontal skewing
377
 * @param m21 - Vertical skewing
378
 * @param m22 - Vertical scaling
379
 * @param dx - Horizontal translation
380
 * @param dy - Vertical translation
381
 * @returns Document instance for chaining
382
 */
383
transform(m11: number, m12: number, m21: number, m22: number, dx: number, dy: number): PDFDocument;
384

385
/**
386
 * Translate coordinate system
387
 * @param x - X translation
388
 * @param y - Y translation
389
 * @returns Document instance for chaining
390
 */
391
translate(x: number, y: number): PDFDocument;
392

393
/**
394
 * Rotate coordinate system
395
 * @param angle - Rotation angle in degrees
396
 * @param options - Rotation options
397
 * @returns Document instance for chaining
398
 */
399
rotate(angle: number, options?: RotateOptions): PDFDocument;
400

401
/**
402
 * Scale coordinate system
403
 * @param xFactor - Horizontal scale factor
404
 * @param yFactor - Vertical scale factor (optional, defaults to xFactor)
405
 * @param options - Scale options
406
 * @returns Document instance for chaining
407
 */
408
scale(xFactor: number, yFactor?: number, options?: TransformOptions): PDFDocument;
409

410
interface RotateOptions {
411
  /** Origin point for rotation */
412
  origin?: [number, number];
413
}
414

415
interface TransformOptions {
416
  /** Origin point for transformation */
417
  origin?: [number, number];
418
}
419
```
420

421
**Usage Examples:**
422

423
```javascript
424
// Translation
425
doc.save()
426
   .translate(200, 200)
427
   .rect(0, 0, 50, 50)  // Actually drawn at (200, 200)
428
   .fill('red')
429
   .restore();
430

431
// Rotation
432
doc.save()
433
   .translate(300, 300)
434
   .rotate(45)
435
   .rect(-25, -25, 50, 50)  // Rotated square
436
   .fill('blue')
437
   .restore();
438

439
// Scale
440
doc.save()
441
   .translate(400, 200)
442
   .scale(2, 0.5)  // 2x width, 0.5x height
443
   .rect(0, 0, 50, 50)
444
   .fill('green')
445
   .restore();
446

447
// Complex transformation
448
doc.save()
449
   .transform(1, 0.5, 0, 1, 100, 400)  // Shear transformation
450
   .rect(0, 0, 100, 50)
451
   .fill('purple')
452
   .restore();
453
```
454

455
## Coordinate System
456

457
PDFKit uses a coordinate system where:
458
- Origin (0,0) is at the bottom-left corner of the page
459
- X-axis increases to the right
460
- Y-axis increases upward
461
- Units are in points (1/72 inch)
462
- Page coordinates account for margins automatically
463

464
## Path Winding Rules
465

466
For complex self-intersecting paths, PDFKit supports two fill rules:
467
- **nonzero**: Default rule, fills based on path direction
468
- **evenodd**: Alternates filled/unfilled for overlapping areas
469

470
## Performance Tips
471

472
- Use `save()`/`restore()` instead of manual state tracking
473
- Combine multiple shapes in a single path when possible
474
- Use appropriate line caps and joins for the desired appearance
475
- Consider using `clip()` for masking complex graphics