0
# pdf2pic
1

2
pdf2pic is a utility for converting PDF documents to image formats, supporting multiple input sources (file path, buffer, base64) and output formats (image files, base64, buffer). It leverages GraphicsMagick and Ghostscript for reliable PDF processing with configurable output options.
3

4
## Package Information
5

6
- **Package Name**: pdf2pic
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install pdf2pic`
10

11
## Prerequisites
12

13
Before using pdf2pic, you need to install the following system dependencies:
14

15
- **Node.js**: >= 14.x
16
- **GraphicsMagick**: Image processing library
17
- **Ghostscript**: PDF processing library
18

19
## Core Imports
20

21
```typescript
22
import { fromPath, fromBuffer, fromBase64 } from "pdf2pic";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const { fromPath, fromBuffer, fromBase64 } = require("pdf2pic");
29
```
30

31
**TypeScript Types**: All types (`Options`, `Convert`, `WriteImageResponse`, etc.) are automatically available through TypeScript's type inference when using the imported functions. No additional type imports are needed.
32

33
## Basic Usage
34

35
```typescript
36
import { fromPath } from "pdf2pic";
37

38
// Configure conversion options
39
const options = {
40
  density: 100,
41
  saveFilename: "page",
42
  savePath: "./images",
43
  format: "png",
44
  width: 600,
45
  height: 600
46
};
47

48
// Initialize converter from file path
49
const convert = fromPath("/path/to/document.pdf", options);
50

51
// Convert specific page to image file
52
const imageResult = await convert(1, { responseType: "image" });
53
console.log(`Saved: ${imageResult.path}`);
54

55
// Convert page to base64
56
const base64Result = await convert(1, { responseType: "base64" });
57
console.log(`Base64: ${base64Result.base64}`);
58

59
// Bulk convert multiple pages
60
const results = await convert.bulk([1, 2, 3], { responseType: "image" });
61
results.forEach(result => console.log(`Page ${result.page}: ${result.path}`));
62
```
63

64
## Architecture
65

66
pdf2pic is built around several key components:
67

68
- **Initialization Functions**: `fromPath`, `fromBuffer`, `fromBase64` create converters from different input sources
69
- **Convert Interface**: Returned converter object provides both single-page and bulk conversion methods
70
- **Graphics Engine**: Internal GraphicsMagick wrapper handling the actual PDF-to-image conversion
71
- **Response Types**: Three output formats (image files, base64 strings, buffers) with type-safe interfaces
72
- **Configuration System**: Comprehensive options for controlling output quality, dimensions, and formats
73

74
## Capabilities
75

76
### PDF Input Sources
77

78
Three initialization functions for different PDF input types, each returning a Convert interface with identical conversion capabilities.
79

80
```typescript { .api }
81
function fromPath(filePath: string, options?: Options): Convert;
82
function fromBuffer(buffer: Buffer, options?: Options): Convert;
83
function fromBase64(b64string: string, options?: Options): Convert;
84
```
85

86
[PDF Input Sources](./input-sources.md)
87

88
### PDF Conversion
89

90
Core conversion functionality for transforming PDF pages to images with configurable output types and extensive customization options.
91

92
```typescript { .api }
93
interface Convert {
94
  (pages?: number): Promise<WriteImageResponse>;
95
  (pages: number, options: { responseType?: undefined }): Promise<WriteImageResponse>;
96
  (pages: number, options: { responseType: 'image' }): Promise<WriteImageResponse>;
97
  (pages: number, options: { responseType: 'base64' }): Promise<ToBase64Response>;
98
  (pages: number, options: { responseType: 'buffer' }): Promise<BufferResponse>;
99
  
100
  bulk: {
101
    (pages?: number | number[]): Promise<WriteImageResponse[]>;
102
    (pages: number | number[], options: { responseType?: undefined }): Promise<WriteImageResponse[]>;
103
    (pages: number | number[], options: { responseType: 'image' }): Promise<WriteImageResponse[]>;
104
    (pages: number | number[], options: { responseType: 'base64' }): Promise<ToBase64Response[]>;
105
    (pages: number | number[], options: { responseType: 'buffer' }): Promise<BufferResponse[]>;
106
  };
107
  
108
  setOptions(): void;
109
  setGMClass(gmClass: string | boolean): void;
110
}
111
```
112

113
[PDF Conversion](./conversion.md)
114

115
### Configuration Options
116

117
Comprehensive configuration system for controlling output quality, dimensions, file handling, and GraphicsMagick settings.
118

119
```typescript { .api }
120
interface Options {
121
  quality?: number;
122
  format?: string;
123
  width?: number;
124
  height?: number;
125
  preserveAspectRatio?: boolean;
126
  density?: number;
127
  savePath?: string;
128
  saveFilename?: string;
129
  compression?: string;
130
  units?: 'Undefined' | 'PixelsPerInch' | 'PixelsPerCentimeter';
131
}
132
```
133

134
[Configuration Options](./configuration.md)
135

136
## Types
137

138
### Response Types
139

140
```typescript { .api }
141
interface BaseResponse {
142
  size?: string;
143
  page?: number;
144
}
145

146
interface WriteImageResponse extends BaseResponse {
147
  name?: string;
148
  fileSize?: number;
149
  path?: string;
150
}
151

152
interface ToBase64Response extends BaseResponse {
153
  base64?: string;
154
}
155

156
interface BufferResponse extends BaseResponse {
157
  buffer?: Buffer;
158
}
159

160
type ConvertResponse = WriteImageResponse | ToBase64Response | BufferResponse;
161

162
type ResponseType = 'image' | 'base64' | 'buffer';
163

164
interface ConvertOptions {
165
  /** Output format for the conversion result */
166
  responseType: ResponseType;
167
}
168
```
169

170
## Troubleshooting
171

172
### Common Setup Issues
173

174
**GraphicsMagick/Ghostscript not found**: Ensure both GraphicsMagick and Ghostscript are installed and available in your system PATH. On most systems:
175

176
- **macOS**: `brew install graphicsmagick ghostscript`
177
- **Ubuntu/Debian**: `sudo apt-get install graphicsmagick ghostscript`
178
- **Windows**: Download and install from official websites, ensure PATH is updated
179

180
**Permission errors**: Ensure the process has read access to input files and write access to the output directory specified in `savePath`.
181

182
**Memory issues with large PDFs**: Use the `bulk()` method which automatically handles batching, or process pages individually for very large documents.