0
# Configuration Options
1

2
pdf2pic provides extensive configuration options for controlling output quality, dimensions, file handling, and graphics processing behavior.
3

4
## Capabilities
5

6
### Options Interface
7

8
Complete configuration interface for customizing PDF to image conversion behavior.
9

10
```typescript { .api }
11
interface Options {
12
  /** Image quality (0-100), where 0 is default quality */
13
  quality?: number;
14
  
15
  /** Output image format (png, jpg, jpeg, tiff, bmp, etc.) */
16
  format?: string;
17
  
18
  /** Output image width in pixels */
19
  width?: number;
20
  
21
  /** Output image height in pixels */
22
  height?: number;
23
  
24
  /** Whether to preserve original aspect ratio during resize */
25
  preserveAspectRatio?: boolean;
26
  
27
  /** Image resolution/DPI for conversion */
28
  density?: number;
29
  
30
  /** Directory path where image files will be saved */
31
  savePath?: string;
32
  
33
  /** Base filename for generated image files */
34
  saveFilename?: string;
35
  
36
  /** Compression algorithm for image output */
37
  compression?: string;
38
  
39
  /** Units for density measurement */
40
  units?: 'Undefined' | 'PixelsPerInch' | 'PixelsPerCentimeter';
41
}
42
```
43

44
### Default Values
45

46
pdf2pic ships with sensible defaults that work for most use cases:
47

48
```typescript { .api }
49
const defaultOptions: Options = {
50
  quality: 0,                    // Default quality (system default)
51
  format: 'png',                 // PNG format for best quality
52
  width: 768,                    // Standard web width
53
  height: 512,                   // Proportional height
54
  density: 72,                   // Standard screen resolution
55
  preserveAspectRatio: false,    // Force exact dimensions
56
  savePath: './',                // Current directory
57
  saveFilename: 'untitled',      // Generic filename
58
  compression: 'jpeg',           // JPEG compression algorithm
59
  units: 'PixelsPerInch'         // Standard DPI units
60
};
61
```
62

63
## Configuration Details
64

65
### Image Quality
66

67
Controls the output image quality and compression level.
68

69
```typescript { .api }
70
quality?: number; // 0-100, where 0 uses system default
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
import { fromPath } from "pdf2pic";
77

78
// Maximum quality (larger file sizes)
79
const highQuality = fromPath("/path/to/document.pdf", {
80
  quality: 100,
81
  format: "jpg"
82
});
83

84
// Balanced quality for web use
85
const webQuality = fromPath("/path/to/document.pdf", {
86
  quality: 85,
87
  format: "jpg"
88
});
89

90
// Use system default quality
91
const defaultQuality = fromPath("/path/to/document.pdf", {
92
  quality: 0, // or omit this property
93
  format: "png"
94
});
95
```
96

97
### Image Format
98

99
Specifies the output image format. Supports all formats available in GraphicsMagick/ImageMagick.
100

101
```typescript { .api }
102
format?: string; // Common: 'png', 'jpg', 'jpeg', 'tiff', 'bmp', 'gif', 'webp'
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
import { fromPath } from "pdf2pic";
109

110
// PNG for documents with text (lossless)
111
const pngConvert = fromPath("/path/to/document.pdf", {
112
  format: "png",
113
  quality: 100
114
});
115

116
// JPEG for photos/images (smaller files)
117
const jpgConvert = fromPath("/path/to/document.pdf", {
118
  format: "jpg",
119
  quality: 90
120
});
121

122
// WebP for modern web browsers
123
const webpConvert = fromPath("/path/to/document.pdf", {
124
  format: "webp",
125
  quality: 80
126
});
127

128
// TIFF for archival/print purposes
129
const tiffConvert = fromPath("/path/to/document.pdf", {
130
  format: "tiff",
131
  compression: "lzw"
132
});
133
```
134

135
### Dimensions and Scaling
136

137
Control output image dimensions and scaling behavior.
138

139
```typescript { .api }
140
width?: number;                  // Output width in pixels
141
height?: number;                 // Output height in pixels  
142
preserveAspectRatio?: boolean;   // Maintain original proportions
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { fromPath } from "pdf2pic";
149

150
// Fixed dimensions (may distort if aspect ratio differs)
151
const fixedSize = fromPath("/path/to/document.pdf", {
152
  width: 800,
153
  height: 600,
154
  preserveAspectRatio: false
155
});
156

157
// Preserve aspect ratio (fit within bounds)
158
const proportional = fromPath("/path/to/document.pdf", {
159
  width: 800,
160
  height: 600,
161
  preserveAspectRatio: true
162
});
163

164
// Specify only width (height calculated automatically)
165
const widthOnly = fromPath("/path/to/document.pdf", {
166
  width: 1200,
167
  preserveAspectRatio: true
168
});
169

170
// High resolution for print
171
const printRes = fromPath("/path/to/document.pdf", {
172
  width: 2400,
173
  height: 3200,
174
  density: 300,
175
  preserveAspectRatio: true
176
});
177
```
178

179
### Resolution and Quality
180

181
Control image resolution and processing quality settings.
182

183
```typescript { .api }
184
density?: number;    // DPI/PPI resolution
185
units?: 'Undefined' | 'PixelsPerInch' | 'PixelsPerCentimeter';
186
```
187

188
**Usage Examples:**
189

190
```typescript
191
import { fromPath } from "pdf2pic";
192

193
// Screen resolution (72 DPI)
194
const screenRes = fromPath("/path/to/document.pdf", {
195
  density: 72,
196
  units: "PixelsPerInch"
197
});
198

199
// Print resolution (300 DPI)
200
const printRes = fromPath("/path/to/document.pdf", {
201
  density: 300,
202
  units: "PixelsPerInch",
203
  width: 2480,  // A4 width at 300 DPI
204
  height: 3508  // A4 height at 300 DPI
205
});
206

207
// High quality scanning (600 DPI)
208
const scanRes = fromPath("/path/to/document.pdf", {
209
  density: 600,
210
  units: "PixelsPerInch"
211
});
212

213
// Metric units
214
const metricRes = fromPath("/path/to/document.pdf", {
215
  density: 118,  // ~300 DPI in cm
216
  units: "PixelsPerCentimeter"
217
});
218
```
219

220
### File Handling
221

222
Configure where and how image files are saved.
223

224
```typescript { .api }
225
savePath?: string;      // Directory for output files
226
saveFilename?: string;  // Base filename for output files
227
```
228

229
**Usage Examples:**
230

231
```typescript
232
import { fromPath } from "pdf2pic";
233

234
// Organize by date
235
const dateOrganized = fromPath("/path/to/document.pdf", {
236
  savePath: "./images/2023-12-01",
237
  saveFilename: "document_page"
238
});
239
// Generates: ./images/2023-12-01/document_page.1.png
240

241
// Project-specific naming
242
const projectFiles = fromPath("/path/to/report.pdf", {
243
  savePath: "./project/assets",
244
  saveFilename: "quarterly_report"
245
});
246
// Generates: ./project/assets/quarterly_report.1.png
247

248
// Absolute paths
249
const absolutePath = fromPath("/path/to/document.pdf", {
250
  savePath: "/var/www/uploads/images",
251
  saveFilename: "user_document"
252
});
253

254
// Nested directories (ensure they exist)
255
import fs from "fs";
256
fs.mkdirSync("./output/thumbnails", { recursive: true });
257
const nested = fromPath("/path/to/document.pdf", {
258
  savePath: "./output/thumbnails",
259
  saveFilename: "thumb"
260
});
261
```
262

263
### Compression Settings
264

265
Control image compression algorithms and quality trade-offs.
266

267
```typescript { .api }
268
compression?: string;  // Compression algorithm ('jpeg', 'lzw', 'zip', etc.)
269
```
270

271
**Usage Examples:**
272

273
```typescript
274
import { fromPath } from "pdf2pic";
275

276
// JPEG compression (good for photos)
277
const jpegComp = fromPath("/path/to/document.pdf", {
278
  format: "jpg",
279
  compression: "jpeg",
280
  quality: 85
281
});
282

283
// LZW compression for TIFF (lossless)
284
const lzwComp = fromPath("/path/to/document.pdf", {
285
  format: "tiff",
286
  compression: "lzw"
287
});
288

289
// ZIP compression for PNG-like formats
290
const zipComp = fromPath("/path/to/document.pdf", {
291
  format: "png",
292
  compression: "zip"
293
});
294

295
// No compression (larger files, faster processing)
296
const noComp = fromPath("/path/to/document.pdf", {
297
  format: "bmp",
298
  compression: "none"
299
});
300
```
301

302
## Configuration Patterns
303

304
### Profile-Based Configuration
305

306
Create reusable configuration profiles for different use cases:
307

308
```typescript
309
import { fromPath, Options } from "pdf2pic";
310

311
// Predefined profiles
312
const profiles = {
313
  thumbnail: {
314
    width: 150,
315
    height: 200,
316
    format: "jpg",
317
    quality: 75,
318
    density: 72
319
  } as Options,
320
  
321
  web: {
322
    width: 800,
323
    height: 1000,
324
    format: "webp",
325
    quality: 85,
326
    density: 96,
327
    preserveAspectRatio: true
328
  } as Options,
329
  
330
  print: {
331
    width: 2480,
332
    height: 3508,
333
    format: "tiff",
334
    density: 300,
335
    compression: "lzw",
336
    preserveAspectRatio: true
337
  } as Options,
338
  
339
  archive: {
340
    format: "png",
341
    quality: 100,
342
    density: 600,
343
    compression: "zip"
344
  } as Options
345
};
346

347
// Use profiles
348
const thumbConvert = fromPath("/path/to/document.pdf", profiles.thumbnail);
349
const webConvert = fromPath("/path/to/document.pdf", profiles.web);
350
```
351

352
### Dynamic Configuration
353

354
Modify configuration based on content or requirements:
355

356
```typescript
357
import { fromPath } from "pdf2pic";
358
import fs from "fs";
359

360
const pdfPath = "/path/to/document.pdf";
361
const pdfStats = fs.statSync(pdfPath);
362

363
// Adjust quality based on file size
364
const options = {
365
  format: "jpg",
366
  width: 800,
367
  quality: pdfStats.size > 10_000_000 ? 70 : 90, // Lower quality for large files
368
  density: pdfStats.size > 50_000_000 ? 150 : 300 // Lower DPI for very large files
369
};
370

371
const convert = fromPath(pdfPath, options);
372
```
373

374
### Validation and Error Handling
375

376
```typescript
377
import { fromPath } from "pdf2pic";
378

379
function createConverter(pdfPath: string, userOptions: Partial<Options>) {
380
  // Validate and sanitize options
381
  const options: Options = {
382
    ...userOptions,
383
    width: Math.max(100, Math.min(4000, userOptions.width || 800)),
384
    height: Math.max(100, Math.min(4000, userOptions.height || 600)),
385
    quality: Math.max(0, Math.min(100, userOptions.quality || 85)),
386
    density: Math.max(72, Math.min(600, userOptions.density || 150))
387
  };
388
  
389
  // Ensure save directory exists
390
  if (options.savePath && !fs.existsSync(options.savePath)) {
391
    fs.mkdirSync(options.savePath, { recursive: true });
392
  }
393
  
394
  return fromPath(pdfPath, options);
395
}
396
```