pdf2pic

https://github.com/yakovmeister/pdf2image
Admin
A utility for converting PDF files to image, base64, or buffer formats, supporting conversion from...
Tokens:27,372
Snippets:235
Trust Score:9.2
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Illustrative Example of setOptions() Usage

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/entry-points.md

Shows an example of initializing pdf2pic with options. The `setOptions()` method is called internally during initialization and typically does not require manual invocation.

```typescript
const convert = fromPath('./sample.pdf', {
  width: 1024,
  quality: 90
});
// setOptions() is already called internally
// No need to call manually unless options are modified
```

--------------------------------

### Install pdf2pic

Source: https://github.com/yakovmeister/pdf2image/blob/master/readme.md

Install the pdf2pic library using npm. Ensure you have Node.js version 14.x or higher.

```bash
npm install --save pdf2pic
```

--------------------------------

### Example Usage of BufferResponse

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/types.md

Illustrates how to handle a BufferResponse. Shows logging the result, saving the Buffer directly to a PNG file, and sending the Buffer as an HTTP response.

```typescript
const result = await convert(3, { responseType: 'buffer' });
console.log(result);
// {
//   buffer: <Buffer 89 50 4e 47 0d 0a ...>,
//   size: '768x512',
//   page: 3
// }

// Save to file
fs.writeFileSync('./page3.png', result.buffer);

// Send over HTTP
response.setHeader('Content-Type', 'image/png');
response.end(result.buffer);
```

--------------------------------

### Example Usage of ToBase64Response

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/types.md

Demonstrates how to use the ToBase64Response. Shows how to log the result, embed the Base64 data in an HTML image tag, and convert it to a Buffer for saving to a file.

```typescript
const result = await convert(2, { responseType: 'base64' });
console.log(result);
// {
//   base64: 'iVBORw0KGgoAAAANSUhEUgAA...',
//   size: '768x512',
//   page: 2
// }

// Use in HTML
const html = `<img src="data:image/png;base64,${result.base64}" />`;

// Convert to Buffer and save
const buffer = Buffer.from(result.base64, 'base64');
fs.writeFileSync('./page2.png', buffer);
```

--------------------------------

### Example: Using Convert Type for PDF Conversion

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/types.md

Demonstrates how to use the `convert` function obtained from `fromPath` to convert PDF pages into different response types (image, base64, buffer) and how to use the `bulk` method for multiple pages.

```typescript
import {
  fromPath,
  Options,
  ConvertOptions,
  WriteImageResponse,
  ToBase64Response,
  BufferResponse,
  ResponseType
} from 'pdf2pic';

const options: Options = {
  format: 'png',
  width: 1024,
  height: 768,
  quality: 85,
  savePath: './images'
};

const convert = fromPath('./document.pdf', options);

// Single page with different response types
const imageResponse: WriteImageResponse = await convert(1);
const base64Response: ToBase64Response = await convert(2, { responseType: 'base64' });
const bufferResponse: BufferResponse = await convert(3, { responseType: 'buffer' });

// Multiple pages
const responses: WriteImageResponse[] = await convert.bulk([1, 2, 3]);
```

--------------------------------

### convert.setOptions()

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/entry-points.md

Applies the options that were provided during the initialization of the pdf2pic converter. This method is typically called internally during setup and usually does not require manual invocation.

```APIDOC
## convert.setOptions()

### Description
Apply the options that were provided during initialization.

This method is called automatically during initialization and typically does not need to be called manually. It synchronizes the Graphics instance with the options passed to the factory function.

### Example
```typescript
const convert = fromPath('./sample.pdf', {
  width: 1024,
  quality: 90
});
// setOptions() is already called internally
// No need to call manually unless options are modified
```
```

--------------------------------

### WriteImageResponse Interface Example

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/types.md

Demonstrates the structure of the response object when converting a page to an image file. It includes details like filename, file size, and the full path to the saved image, along with inherited properties like size and page number.

```typescript
export interface WriteImageResponse extends BaseResponse {
  name?: string;
  fileSize?: number;
  path?: string;
}

const result = await convert(1, { responseType: 'image' });
console.log(result);
// {
//   name: 'document.1.png',
//   size: '768x512',
//   fileSize: 234.56,
//   path: './output/document.1.png',
//   page: 1
// }
```

--------------------------------

### AWS Lambda Layer ARNs for GraphicsMagick and Ghostscript

Source: https://github.com/yakovmeister/pdf2image/blob/master/docs/gm-installation.md

Example ARNs for prebuilt community layers for GraphicsMagick and Ghostscript on AWS Lambda.

```bash
arn:aws:lambda:us-east-1:175033217214:layer:graphicsmagick:2
arn:aws:lambda:us-east-1:764866452798:layer:ghostscript:15
```

--------------------------------

### Install GraphicsMagick on macOS

Source: https://github.com/yakovmeister/pdf2image/blob/master/docs/gm-installation.md

Use Homebrew to update package lists and install Ghostscript and GraphicsMagick on macOS.

```bash
brew update
brew install gs graphicsmagick
```

--------------------------------

### Install GraphicsMagick on Debian-based Linux

Source: https://github.com/yakovmeister/pdf2image/blob/master/docs/gm-installation.md

Run these commands to update package lists and install Ghostscript and GraphicsMagick on Debian-based systems.

```bash
sudo apt-get update
sudo apt-get install ghostscript
sudo apt-get install graphicsmagick
```

--------------------------------

### Example Usage of ConvertResponse

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/types.md

Shows a function that handles conversion with a dynamic response type, returning a ConvertResponse. This demonstrates how to use the union type in function signatures.

```typescript
async function handleConversion(responseType: ResponseType): Promise<ConvertResponse> {
  const convert = fromPath('./sample.pdf');
  return convert(1, { responseType });
}
```

--------------------------------

### Initialize Conversion from Base64 String

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/entry-points.md

Use `fromBase64` to convert PDF data provided as a Base64 encoded string. This method is convenient for PDFs received as text. The example shows converting a page to Base64 and then saving it to a file.

```typescript
import { fromBase64 } from 'pdf2pic';
import { readFileSync } from 'fs';

const base64String = readFileSync('./sample.pdf', 'base64');
const convert = fromBase64(base64String, {
  format: 'png',
  width: 600,
  height: 800,
  preserveAspectRatio: true
});

// Convert first page as base64
const result = await convert(1, { responseType: 'base64' });
const base64ImageData = result.base64;

// Write to file
const imageBuffer = Buffer.from(base64ImageData, 'base64');
require('fs').writeFileSync('./output.png', imageBuffer);
```

--------------------------------

### Convert PDF Page to Image from Path

Source: https://github.com/yakovmeister/pdf2image/blob/master/readme.md

Convert a specific page of a PDF file to an image and save it. Requires GraphicsMagick and Ghostscript to be installed.

```javascript
import { fromPath } from "pdf2pic";

const options = {
  density: 100,
  saveFilename: "untitled",
  savePath: "./images",
  format: "png",
  width: 600,
  height: 600
};
const convert = fromPath("/path/to/pdf/sample.pdf", options);
const pageToConvertAsImage = 1;

convert(pageToConvertAsImage, { responseType: "image" })
  .then((resolve) => {
    console.log("Page 1 is now converted as image");

    return resolve;
  });
```

--------------------------------

### v3.x: Get Base64 Response

Source: https://github.com/yakovmeister/pdf2image/blob/master/migration.md

In v3.x, use the `{ responseType: 'base64' }` object to get a base64 response. This applies to `fromPath`, `fromBuffer`, and `fromBase64` functions.

```javascript
const convert = fromPath(filePath, options);
const base64Response = convert(page, { responseType: 'base64' })
```

--------------------------------

### Comprehensive PDF Conversion Error Handling

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/errors.md

Implement a robust try-catch block to handle various potential errors during PDF conversion, including input validation, file access, page number issues, and write permissions. This example demonstrates centralized error management.

```typescript
import { fromPath } from 'pdf2pic';

async function convertPdfSafely(pdfPath: string, pageNumber: number) {
  try {
    // Validate input
    if (!pdfPath || typeof pdfPath !== 'string') {
      throw new Error('PDF path must be a non-empty string');
    }
    
    if (!Number.isInteger(pageNumber) || pageNumber < 1) {
      throw new Error('Page number must be a positive integer');
    }
    
    // Initialize converter
    const convert = fromPath(pdfPath, {
      format: 'png',
      width: 1024,
      height: 768,
      savePath: './output'
    });
    
    // Perform conversion
    const result = await convert(pageNumber, { responseType: 'image' });
    
    console.log(`Successfully converted page ${pageNumber}`);
    console.log(`Saved to: ${result.path}`);
    
    return result;
  } catch (error) {
    // Handle different error types
    if (error.code === 'ENOENT') {
      console.error(`PDF file not found: ${pdfPath}`);
    } else if (error.message.includes('Page number')) {
      console.error(`Invalid page number: ${pageNumber}`);
    } else if (error.code === 'EACCES') {
      console.error(`Permission denied writing to output directory`);
    } else {
      console.error(`Conversion failed: ${error.message}`);
    }
    
    throw error;
  }
}
```

--------------------------------

### Constructor

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Creates a new Graphics instance with default configuration, typically using GraphicsMagick.

```APIDOC
## Constructor

Creates a new Graphics instance with default configuration. Defaults to using GraphicsMagick (not ImageMagick).

**Example:**

```typescript
import { Graphics } from 'pdf2pic';

const gm = new Graphics();
// Now ready to convert PDFs
```
```

--------------------------------

### v2.x: Get Base64 Response

Source: https://github.com/yakovmeister/pdf2image/blob/master/migration.md

In v2.x, a boolean `true` was used to obtain a base64 response. This method is deprecated in v3.x.

```javascript
const convert = fromPath(filePath, options);
const base64Response = convert(page, true);
```

--------------------------------

### Setting Conversion Options

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Demonstrates how to define and apply a comprehensive set of options for image conversion using fromPath. This includes format, quality, dimensions, and save location.

```typescript
import { fromPath, Options } from 'pdf2pic';

const options: Options = {
  quality: 100,
  format: 'jpg',
  width: 1024,
  height: 768,
  density: 150,
  savePath: './output',
  saveFilename: 'page',
  preserveAspectRatio: true,
  compression: 'jpeg',
  units: 'PixelsPerInch'
};

const convert = fromPath('./sample.pdf', options);
```

--------------------------------

### Runtime Option Updates for PDF Conversion

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Demonstrates how to update conversion options at runtime before initiating the conversion process. Requires importing 'fromPath'.

```typescript
import { fromPath } from 'pdf2pic';

const convert = fromPath('./doc.pdf', {
  format: 'png',
  width: 800
});

// Modify implementation (must be before conversion)
convert.setGMClass(true); // Use ImageMagick instead

// Apply changes
convert.setOptions();

const result = await convert(1, { responseType: 'image' });
```

--------------------------------

### fromBase64(b64string, options)

Source: https://github.com/yakovmeister/pdf2image/blob/master/readme.md

Initializes PDF to image conversion by supplying a PDF base64 string.

```APIDOC
## fromBase64(b64string, options)

### Description
Initializes PDF to image conversion by supplying a PDF base64 string.

### Parameters
* `b64string` (string) - The PDF file content as a base64 encoded string.
* `options` (object) - Configuration options for the conversion. See [options](#options).
```

--------------------------------

### Get Current Graphics Options

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Retrieves the current configuration settings of the Graphics object as an Options object. Useful for inspecting or logging current settings.

```typescript
const gm = new Graphics();
gm.setSize(800, 600).setFormat('jpg').setQuality(90);

const options = gm.getOptions();
console.log(options);
// {
//   quality: 90,
//   format: 'jpg',
//   width: 800,
//   height: 600,
//   density: 72,
//   preserveAspectRatio: false,
//   savePath: './',
//   saveFilename: 'untitled',
//   compression: 'jpeg',
//   units: 'PixelsPerInch'
// }
```

--------------------------------

### Configuring Image Dimensions

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Demonstrates setting the width and height for the output image. Explains how `preserveAspectRatio` affects the interpretation of these dimensions.

```typescript
// Standard size
const convert = fromPath('./doc.pdf', { width: 800, height: 600 });

// Square output
const convert = fromPath('./doc.pdf', { width: 512 }); // height will be 512

// Aspect ratio preservation
const convert = fromPath('./doc.pdf', { 
  width: 1024,
  preserveAspectRatio: true
});
```

--------------------------------

### getOptions()

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Retrieves the current configuration settings of the Graphics object as an Options object.

```APIDOC
## getOptions(): Options

### Description
Gets the current configuration as an Options object.

### Returns
- **Options** - An object containing all current settings.

### Example
```typescript
const gm = new Graphics();
gm.setSize(800, 600).setFormat('jpg').setQuality(90);

const options = gm.getOptions();
console.log(options);
// {
//   quality: 90,
//   format: 'jpg',
//   width: 800,
//   height: 600,
//   density: 72,
//   preserveAspectRatio: false,
//   savePath: './',
//   saveFilename: 'untitled',
//   compression: 'jpeg',
//   units: 'PixelsPerInch'
// }
```
```

--------------------------------

### Retry PDF Conversion with Fallback

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/errors.md

Demonstrates how to attempt PDF to image conversion first using a path-based approach and then falling back to a buffer-based approach if the initial attempt fails. This ensures greater reliability for conversion tasks.

```typescript
import { fromPath, fromBuffer } from 'pdf2pic';
import { readFileSync } from 'fs';

async function convertWithFallback(pdfPath: string, pageNumber: number) {
  // Try path-based conversion first
  try {
    const convert = fromPath(pdfPath);
    return await convert(pageNumber, { responseType: 'base64' });
  } catch (error) {
    console.warn(`Path-based conversion failed: ${error.message}`);
    
    // Fall back to buffer-based conversion
    try {
      const buffer = readFileSync(pdfPath);
      const convert = fromBuffer(buffer);
      return await convert(pageNumber, { responseType: 'base64' });
    } catch (fallbackError) {
      console.error(`Buffer-based conversion also failed: ${fallbackError.message}`);
      throw fallbackError;
    }
  }
}
```

--------------------------------

### Instantiate Graphics Class

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Create a new Graphics instance using the default configuration, which typically defaults to GraphicsMagick.

```typescript
import { Graphics } from 'pdf2pic';

const gm = new Graphics();
```

--------------------------------

### Entry Points

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/README.md

Main API functions for initializing and performing PDF to image conversions. Supports conversion from file paths, Buffers, and Base64 strings, with options for single page, bulk conversion, and implementation selection.

```APIDOC
## Entry Points

### Description
Provides the main API functions for initializing and performing PDF to image conversions. Supports conversion from file paths, Buffers, and Base64 strings, with options for single page, bulk conversion, and implementation selection.

### Functions
- `fromPath(filePath, options?)` — Initialize conversion from file path
- `fromBuffer(buffer, options?)` — Initialize conversion from Buffer
- `fromBase64(b64string, options?)` — Initialize conversion from Base64 string
- `convert(page?, options?)` — Convert single page
- `convert.bulk(pages?, options?)` — Convert multiple pages with batching
- `convert.setGMClass(gmClass)` — Switch GraphicsMagick/ImageMagick implementation
- `convert.setOptions()` — Apply configuration

### Response Types
- `WriteImageResponse` — File written to disk with metadata
- `ToBase64Response` — Base64-encoded image string
- `BufferResponse` — Node.js Buffer with image data
```

--------------------------------

### fromBuffer(buffer, options)

Source: https://github.com/yakovmeister/pdf2image/blob/master/readme.md

Initializes PDF to image conversion by supplying a PDF buffer. This function supports converting specific or multiple pages from a buffer.

```APIDOC
## fromBuffer(buffer, options)

### Description
Initializes PDF to image conversion by supplying a PDF buffer.

### Method Signature
`fromBuffer(buffer, options)(page, convertOptions)`

### Parameters
* `buffer` (Buffer) - The PDF file content as a buffer.
* `options` (object) - Configuration options for the conversion. See [options](#options).
* `page` (number) - The page number to convert to an image.
* `convertOptions` (object) - Options specific to the conversion process. See [convertOptions](#convertoptions).

### Method Signature (Bulk Conversion)
`fromBuffer(buffer, options).bulk(pages, convertOptions)`

### Parameters (Bulk Conversion)
* `buffer` (Buffer) - The PDF file content as a buffer.
* `options` (object) - Configuration options for the conversion. See [options](#options).
* `pages` (number or array) - Page numbers to convert. Use `-1` for all pages, an array like `[1,2,3]`, or a single number like `1`.
* `convertOptions` (object) - Options specific to the conversion process. See [convertOptions](#convertoptions).

### Method Signature (Set GM Class)
`fromBuffer(buffer, options).setGMClass(subClass)`

### Description (Set GM Class)
Sets GraphicsMagick's subclass or path. This should be called before `convert()` or `bulk()`.

### Parameters (Set GM Class)
* `buffer` (Buffer) - The PDF file content as a buffer.
* `options` (object) - Configuration options for the conversion. See [options](#options).
* `subClass` (boolean or string) - Set to `true` to use ImageMagick, or supply a valid path to the `gm` binary.
```

--------------------------------

### Build Docker Image

Source: https://github.com/yakovmeister/pdf2image/blob/master/examples/docker/README.md

Builds the Docker image for the pdf2pic-docker application.

```shell
docker build -t pdf2pic-docker .

```

--------------------------------

### Initialize Conversion from PDF Buffer

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/README.md

Initializes the pdf2pic converter using a PDF file read into a Node.js Buffer. Conversion can then proceed for specified pages.

```typescript
import { fromBuffer } from 'pdf2pic';
import { readFileSync } from 'fs';

const pdfBuffer = readFileSync('./sample.pdf');
const convert = fromBuffer(pdfBuffer);
const result = await convert(1);
```

--------------------------------

### fromBase64(b64string, options)(page, convertOptions)

Source: https://github.com/yakovmeister/pdf2image/blob/master/readme.md

Converts a specific page of a PDF, provided as a base64 string, into an image, base64 string, or buffer. The `options` parameter configures the conversion process, while `page` specifies the page number and `convertOptions` determines the output format.

```APIDOC
## fromBase64(b64string, options)(page, convertOptions)

### Description
Converts a specific page of a PDF, provided as a base64 string, into an image, base64 string, or buffer. The `options` parameter configures the conversion process, while `page` specifies the page number and `convertOptions` determines the output format.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters for `options` object:
| option              | default value | description                                                                                                                                                                                                                                                                   |
|---------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| quality             | `0`           | Image compression level. Value depends on `format`, usually from `0` to `100` ([more info](http://www.graphicsmagick.org/GraphicsMagick.html#details-quality))                                                                                                                |
| format              | `'png'`       | Formatted image characteristics / image format ([image characteristics](http://www.graphicsmagick.org/GraphicsMagick.html#details-format), [image format](http://www.graphicsmagick.org/formats.html))                                                                        |
| width               | `768`         | Output width                                                                                                                                                                                                                                                                  |
| height              | `512`         | Output height                                                                                                                                                                                                                                                                 |
| preserveAspectRatio | `false`       | Maintains the aspect ratio of the image. When set to `true` and both `width` and `height` are specified, they are interpreted as the minimum width and minimum height, respectively. If set to `true` with only the `width` specified, the `height` will be automatically determined while preserving the aspect ratio, and vice versa. |
| density             | `72`          | Output DPI (dots per inch) ([more info](http://www.graphicsmagick.org/GraphicsMagick.html#details-density))                                                                                                                                                                   |
| savePath            | `'./'`        | Path where to save the output                                                                                                                                                                                                                                                 |
| saveFilename        | `'untitled'`  | Output filename                                                                                                                                                                                                                                                               |
| compression         | `'jpeg'`      | Compression method ([more info](http://www.graphicsmagick.org/GraphicsMagick.html#details-compress))                                                                                                                                                                          |

### Parameters for `convertOptions` object:
| option       | default value | description | 
|--------------|---------------|-------------|
| responseType | `image`       | Response type of the output. Accepts: `image`, `base64` or `buffer` | 

The parameter can also be a boolean, if `true` then the response type will be `base64` and if `false` then the response type will be `image`. 
This is deprecated and will be removed in the next major version.
```

--------------------------------

### Web/Screen Display Configuration

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Configuration optimized for displaying PDFs on web or screen, prioritizing smaller file sizes and appropriate resolution.

```typescript
const convert = fromPath('./doc.pdf', {
  format: 'png',
  quality: 0,
  width: 800,
  height: 600,
  density: 72,
  compression: 'zip'
});
```

--------------------------------

### Run Docker Container

Source: https://github.com/yakovmeister/pdf2image/blob/master/examples/docker/README.md

Runs the pdf2pic-docker container.

```shell
docker run pdf2pic-docker

```

--------------------------------

### Setting Output Image Format

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Illustrates how to specify the output image format, including common types like PNG, JPEG, and TIFF. The choice of format impacts compression, transparency, and file size.

```typescript
// Save as PNG (default)
const convert = fromPath('./doc.pdf', { format: 'png' });

// Save as JPEG with high quality
const convert = fromPath('./doc.pdf', { 
  format: 'jpg',
  quality: 90
});

// Save as TIFF for archival
const convert = fromPath('./doc.pdf', { format: 'tiff' });
```

--------------------------------

### Configuring Image Quality

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Shows how to set the image compression quality for JPEG and PNG formats. Higher quality values result in better image fidelity but larger file sizes.

```typescript
// High-quality JPEG
const convert = fromPath('./doc.pdf', {
  format: 'jpg',
  quality: 95
});

// Smaller PNG files
const convert = fromPath('./doc.pdf', {
  format: 'png',
  quality: 50
});
```

--------------------------------

### Initialize Conversion from File Path

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/entry-points.md

Use `fromPath` to convert a PDF file located at a given file system path. Specify output format, dimensions, and density. The function returns a Convert function for further processing.

```typescript
import { fromPath } from 'pdf2pic';

const convert = fromPath('./sample.pdf', {
  format: 'png',
  width: 1024,
  height: 768,
  density: 150,
  savePath: './output'
});

// Convert first page and save as image file
const result = await convert(1, { responseType: 'image' });
console.log(result);
// { name: 'untitled.1.png', size: '1024x768', fileSize: 123.45, path: './output/untitled.1.png', page: 1 }

// Convert second page as base64
const base64Result = await convert(2, { responseType: 'base64' });
console.log(base64Result.base64); // iVBORw0KGgoAAAANS...
```

--------------------------------

### fromPath(filePath, options)

Source: https://github.com/yakovmeister/pdf2image/blob/master/readme.md

Initializes PDF to image conversion by supplying a file path. This function can be used to convert a specific page or multiple pages of a PDF to an image format.

```APIDOC
## fromPath(filePath, options)

### Description
Initializes PDF to image conversion by supplying a file path.

### Method Signature
`fromPath(filePath, options)(page, convertOptions)`

### Parameters
* `filePath` (string) - The path to the PDF file.
* `options` (object) - Configuration options for the conversion. See [options](#options).
* `page` (number) - The page number to convert to an image.
* `convertOptions` (object) - Options specific to the conversion process. See [convertOptions](#convertoptions).

### Method Signature (Bulk Conversion)
`fromPath(filePath, options).bulk(pages, convertOptions)`

### Parameters (Bulk Conversion)
* `filePath` (string) - The path to the PDF file.
* `options` (object) - Configuration options for the conversion. See [options](#options).
* `pages` (number or array) - Page numbers to convert. Use `-1` for all pages, an array like `[1,2,3]`, or a single number like `1`.
* `convertOptions` (object) - Options specific to the conversion process. See [convertOptions](#convertoptions).

### Method Signature (Set GM Class)
`fromPath(filePath, options).setGMClass(subClass)`

### Description (Set GM Class)
Sets GraphicsMagick's subclass or path. This should be called before `convert()` or `bulk()`.

### Parameters (Set GM Class)
* `filePath` (string) - The path to the PDF file.
* `options` (object) - Configuration options for the conversion. See [options](#options).
* `subClass` (boolean or string) - Set to `true` to use ImageMagick, or supply a valid path to the `gm` binary.
```

--------------------------------

### Web Thumbnail Configuration

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Configuration for generating small thumbnail images for web use, balancing quality and file size.

```typescript
const convert = fromPath('./doc.pdf', {
  format: 'jpg',
  quality: 85,
  width: 200,
  height: 280,
  density: 100,
  compression: 'jpeg',
  preserveAspectRatio: true
});
```

--------------------------------

### setSize()

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Defines the output image dimensions in pixels. You can specify both width and height, or just the width, with options for aspect ratio preservation.

```APIDOC
## setSize()

### Description
Set the output image dimensions.

### Method Signature
```typescript
setSize(width: number, height?: number): Graphics
```

### Parameters
#### Path Parameters
- **width** (number) - Required - Output width in pixels
- **height** (number) - Optional - Output height in pixels. If omitted and `preserveAspectRatio` is false, defaults to width

### Default
width=768, height=512

### Behavior
If only width is provided and `preserveAspectRatio` is false, height defaults to width. If `preserveAspectRatio` is true, height defaults to undefined (to be calculated). If both width and height are provided and `preserveAspectRatio` is true, they become minimum dimensions.

### Example
```typescript
const gm = new Graphics();
gm.setSize(1024, 768);    // Exact dimensions
gm.setSize(600);          // 600x600 (height = width)

// With aspect ratio preservation
gm.setPreserveAspectRatio(true);
gm.setSize(800);          // Width will be 800, height calculated
gm.setSize(800, 600);     // Both used as min dimensions
```
```

--------------------------------

### Basic PDF to Image Conversion

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/README.md

Initializes conversion from a file path with specified options and converts a single page to an image file. The result object contains the path to the saved image.

```typescript
import { fromPath } from 'pdf2pic';

const convert = fromPath('./sample.pdf', {
  format: 'png',
  width: 1024,
  height: 768,
  density: 150,
  savePath: './output'
});

// Convert single page
const result = await convert(1, { responseType: 'image' });
console.log(result.path); // './output/untitled.1.png'
```

--------------------------------

### Convert Single Page Using Bulk Method

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/entry-points.md

Demonstrates converting a single page using the `convert.bulk()` method, which returns an array containing a single result. Logs the path of the converted page.

```typescript
// Convert single page via bulk (returns array with one element)
const [singlePage] = await convert.bulk(3);
console.log(`Converted: ${singlePage.path}`);
```

--------------------------------

### fromPath

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/entry-points.md

Initializes PDF-to-image conversion from a file path. It returns a Convert function that can be used to process PDF pages into images.

```APIDOC
## fromPath

### Description
Initializes conversion from a file path. This function returns a `Convert` function with the same interface as those returned by `fromBuffer` and `fromBase64`.

### Method
```typescript
function fromPath(filePath: string, options?: Options): Convert
```

### Parameters
#### Path Parameters
- **filePath** (string) - Yes - Absolute or relative path to the PDF file
- **options** (Options) - No - defaultOptions - Configuration options for conversion

### Returns
`Convert` — A conversion function with `bulk`, `setOptions`, and `setGMClass` methods.

### Throws
- `Error` if the file at filePath is not a valid PDF
- `Error` if the specified path does not exist

### Example
```typescript
import { fromPath } from 'pdf2pic';

const convert = fromPath('./sample.pdf', {
  format: 'png',
  width: 1024,
  height: 768,
  density: 150,
  savePath: './output'
});

// Convert first page and save as image file
const result = await convert(1, { responseType: 'image' });
console.log(result);

// Convert second page as base64
const base64Result = await convert(2, { responseType: 'base64' });
console.log(base64Result.base64);
```
```

--------------------------------

### Convert Single Page to Different Response Types

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/entry-points.md

Demonstrates converting the first page of a PDF to an image using default settings, and then converting specific pages to base64, buffer, and image formats.

```typescript
import { fromPath } from 'pdf2pic';

const convert = fromPath('./multi-page.pdf', { 
  savePath: './images',
  format: 'png'
});

// All these are equivalent for first page with default image response
await convert();
await convert(1);
await convert(1, { responseType: 'image' });

// Request specific response types
const base64 = await convert(2, { responseType: 'base64' });
const buffer = await convert(3, { responseType: 'buffer' });
const image = await convert(4, { responseType: 'image' });
```

--------------------------------

### Ensure Output Directory Exists

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/errors.md

Creates the specified output directory, including any necessary parent directories, before saving converted images. This prevents errors related to non-existent output locations.

```typescript
import { mkdirSync } from 'fs';

mkdirSync(outputDir, { recursive: true });
```

--------------------------------

### Balanced Quality/Size Configuration

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Configuration that strikes a balance between image quality and file size, suitable for general-purpose use.

```typescript
const convert = fromPath('./doc.pdf', {
  format: 'jpg',
  quality: 80,
  width: 1024,
  height: 1448,
  density: 150,
  compression: 'jpeg',
  preserveAspectRatio: true
});
```

--------------------------------

### Setting Output Image Height

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Shows how to specify the output image height and its interaction with the width and `preserveAspectRatio` settings. If only width is provided, height defaults to width when aspect ratio is not preserved.

```typescript
// Exact dimensions
const convert = fromPath('./doc.pdf', { width: 800, height: 600 });

// Only width specified, height defaults to width
const convert = fromPath('./doc.pdf', { width: 600 });
// Result: 600x600

// Only height specified with aspect ratio
const convert = fromPath('./doc.pdf', { 
  height: 800,
  preserveAspectRatio: true
});
```

--------------------------------

### fromBuffer

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/entry-points.md

Initializes PDF-to-image conversion from a Node.js Buffer containing PDF data. It returns a Convert function for processing.

```APIDOC
## fromBuffer

### Description
Initializes conversion from a Buffer containing PDF data. This function returns a `Convert` function with the same interface as those returned by `fromPath` and `fromBase64`.

### Method
```typescript
function fromBuffer(buffer: Buffer, options?: Options): Convert
```

### Parameters
#### Path Parameters
- **buffer** (Buffer) - Yes - Node.js Buffer containing PDF data
- **options** (Options) - No - defaultOptions - Configuration options for conversion

### Returns
`Convert` — A conversion function with `bulk`, `setOptions`, and `setGMClass` methods.

### Throws
- `Error` if the buffer does not contain valid PDF data
- `Error` if GraphicsMagick processing fails

### Example
```typescript
import { fromBuffer } from 'pdf2pic';
import { readFileSync } from 'fs';

const pdfBuffer = readFileSync('./sample.pdf');
const convert = fromBuffer(pdfBuffer, {
  format: 'jpg',
  quality: 100,
  width: 800,
  height: 600
});

// Convert all pages with batching
const pages = await convert.bulk(-1, { responseType: 'image' });
console.log(`Converted ${pages.length} pages`);

// Convert specific pages
const selectedPages = await convert.bulk([1, 3, 5], { responseType: 'buffer' });
console.log(`Page 1 buffer size: ${selectedPages[0].buffer.length} bytes`);
```
```

--------------------------------

### fromBase64(b64string, options).bulk(pages, convertOptions)

Source: https://github.com/yakovmeister/pdf2image/blob/master/readme.md

Converts multiple pages of a PDF, provided as a base64 string, into images, base64 strings, or buffers. This function is similar to `fromPath().bulk()`, with the input being a base64 string.

```APIDOC
## fromBase64(b64string, options).bulk(pages, convertOptions)

### Description
Converts multiple pages of a PDF, provided as a base64 string, into images, base64 strings, or buffers. This function is similar to `fromPath().bulk()`, with the input being a base64 string.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters for `options` object:
| option              | default value | description                                                                                                                                                                                                                                                                   |
|---------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| quality             | `0`           | Image compression level. Value depends on `format`, usually from `0` to `100` ([more info](http://www.graphicsmagick.org/GraphicsMagick.html#details-quality))                                                                                                                |
| format              | `'png'`       | Formatted image characteristics / image format ([image characteristics](http://www.graphicsmagick.org/GraphicsMagick.html#details-format), [image format](http://www.graphicsmagick.org/formats.html))                                                                        |
| width               | `768`         | Output width                                                                                                                                                                                                                                                                  |
| height              | `512`         | Output height                                                                                                                                                                                                                                                                 |
| preserveAspectRatio | `false`       | Maintains the aspect ratio of the image. When set to `true` and both `width` and `height` are specified, they are interpreted as the minimum width and minimum height, respectively. If set to `true` with only the `width` specified, the `height` will be automatically determined while preserving the aspect ratio, and vice versa. |
| density             | `72`          | Output DPI (dots per inch) ([more info](http://www.graphicsmagick.org/GraphicsMagick.html#details-density))                                                                                                                                                                   |
| savePath            | `'./'`        | Path where to save the output                                                                                                                                                                                                                                                 |
| saveFilename        | `'untitled'`  | Output filename                                                                                                                                                                                                                                                               |
| compression         | `'jpeg'`      | Compression method ([more info](http://www.graphicsmagick.org/GraphicsMagick.html#details-compress))                                                                                                                                                                          |

### Parameters for `convertOptions` object:
| option       | default value | description | 
|--------------|---------------|-------------|
| responseType | `image`       | Response type of the output. Accepts: `image`, `base64` or `buffer` | 

The parameter can also be a boolean, if `true` then the response type will be `base64` and if `false` then the response type will be `image`. 
This is deprecated and will be removed in the next major version.
```

--------------------------------

### Configure Image Compression Method

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Specify the compression algorithm for output images, such as 'jpeg', 'zip', 'lossless', 'lossy', or 'none'. The availability of options depends on the image format and GraphicsMagick build.

```typescript
// JPEG compression (default)
const convert = fromPath('./doc.pdf', { compression: 'jpeg' });
```

```typescript
// ZIP compression for PNG
const convert = fromPath('./doc.pdf', { 
  format: 'png',
  compression: 'zip'
});
```

```typescript
// Lossless compression
const convert = fromPath('./doc.pdf', { compression: 'lossless' });
```

```typescript
// No compression
const convert = fromPath('./doc.pdf', { compression: 'none' });
```

--------------------------------

### Switching Image Conversion Implementation

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/README.md

Demonstrates how to switch the underlying image conversion library between GraphicsMagick and ImageMagick using `setGMClass(true)`.

```typescript
const convert = fromPath('./sample.pdf');
convert.setGMClass(true);  // Use ImageMagick instead
const result = await convert(1);
```

--------------------------------

### Import Graphics Class

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Import the Graphics class from the pdf2pic library. This is the initial step before creating an instance.

```typescript
import { Graphics } from 'pdf2pic';
```

--------------------------------

### Initialize Conversion from Base64 PDF

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/README.md

Initializes the pdf2pic converter using a Base64 encoded string of a PDF file. Conversion can then proceed for specified pages.

```typescript
import { fromBase64 } from 'pdf2pic';
import { readFileSync } from 'fs';

const base64 = readFileSync('./sample.pdf', 'base64');
const convert = fromBase64(base64);
const result = await convert(1);
```

--------------------------------

### fromBase64

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/entry-points.md

Initializes PDF-to-image conversion from a Base64-encoded PDF string. It returns a Convert function for processing.

```APIDOC
## fromBase64

### Description
Initializes conversion from a Base64-encoded PDF string. This function returns a `Convert` function with the same interface as those returned by `fromPath` and `fromBuffer`.

### Method
```typescript
function fromBase64(b64string: string, options?: Options): Convert
```

### Parameters
#### Path Parameters
- **b64string** (string) - Yes - Base64-encoded PDF data as a string
- **options** (Options) - No - defaultOptions - Configuration options for conversion

### Returns
`Convert` — A conversion function with `bulk`, `setOptions`, and `setGMClass` methods.

### Throws
- `Error` if the base64 string does not decode to valid PDF data
- `Error` if Buffer conversion from base64 fails

### Example
```typescript
import { fromBase64 } from 'pdf2pic';
import { readFileSync } from 'fs';

const base64String = readFileSync('./sample.pdf', 'base64');
const convert = fromBase64(base64String, {
  format: 'png',
  width: 600,
  height: 800,
  preserveAspectRatio: true
});

// Convert first page as base64
const result = await convert(1, { responseType: 'base64' });
const base64ImageData = result.base64;

// Write to file
const imageBuffer = Buffer.from(base64ImageData, 'base64');
require('fs').writeFileSync('./output.png', imageBuffer);
```
```

--------------------------------

### Set Image Compression Quality

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Configure the compression level for output images using `setQuality()`. The effect of this setting varies by image format; for JPEG, higher values mean better quality.

```typescript
const gm = new Graphics();
gm.setQuality(85).setFormat('jpg');
// Will produce high-quality JPEG output
```

--------------------------------

### setFormat()

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Specifies the desired output image format. Supported formats include common types like PNG, JPEG, TIFF, BMP, and GIF.

```APIDOC
## setFormat()

### Description
Set the output image format.

### Method Signature
```typescript
setFormat(format: string): Graphics
```

### Parameters
#### Path Parameters
- **format** (string) - Required - Image format (e.g., 'png', 'jpg', 'jpeg', 'tiff', 'bmp', 'gif')

### Default
'png'

### Example
```typescript
const gm = new Graphics();
gm.setFormat('jpg').setQuality(90);
```
```

--------------------------------

### setQuality()

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Sets the image compression quality for output. The behavior and range of the quality setting can vary depending on the output image format.

```APIDOC
## setQuality()

### Description
Set image compression quality.

### Method Signature
```typescript
setQuality(quality: number): Graphics
```

### Parameters
#### Path Parameters
- **quality** (number) - Required - Compression level (0-100, varies by format). 0 = minimal compression, 100 = maximum

### Default
0

### Note
Behavior depends on the output format. For JPEG, higher values mean better quality. For PNG, the range may differ.

### Example
```typescript
const gm = new Graphics();
gm.setQuality(85).setFormat('jpg');
// Will produce high-quality JPEG output
```
```

--------------------------------

### Generate Output Filename

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Creates the complete filename for saving an image, including the path, base filename, page number, and format. Can optionally include a page number.

```typescript
const gm = new Graphics();
gm.setSavePath('./output').setSaveFilename('doc').setFormat('png');

gm.generateValidFilename();    // './output/doc.png'
gm.generateValidFilename(0);   // './output/doc.1.png'
gm.generateValidFilename(1);   // './output/doc.2.png'
```

--------------------------------

### Convert PDF Page to Image from Base64

Source: https://github.com/yakovmeister/pdf2image/blob/master/readme.md

Initialize PDF to image conversion by supplying a PDF as a base64 encoded string.

```javascript
fromBase64(b64string, options)
```

--------------------------------

### Options Type Definition

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/types.md

Defines the configuration options for PDF conversion, allowing customization of quality, format, dimensions, and save settings. Properties are optional and have default values.

```typescript
export type Options = {
  quality?: number;
  format?: string;
  width?: number;
  height?: number;
  preserveAspectRatio?: boolean;
  density?: number;
  savePath?: string;
  saveFilename?: string;
  compression?: string;
  units?: 'Undefined' | 'PixelsPerInch' | 'PixelsPerCentimeter';
};
```

--------------------------------

### Default Configuration Options

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Displays the default configuration values used by pdf2pic when no specific options are provided. These defaults cover format, quality, dimensions, and saving behavior.

```typescript
{
  quality: 0,
  format: 'png',
  width: 768,
  height: 512,
  density: 72,
  preserveAspectRatio: false,
  savePath: './',
  saveFilename: 'untitled',
  compression: 'jpeg',
  units: 'PixelsPerInch'
}
```

--------------------------------

### Set Output Image Format

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Specify the desired output image format using `setFormat()`. Supported formats include 'png', 'jpg', 'jpeg', 'tiff', 'bmp', and 'gif'.

```typescript
const gm = new Graphics();
gm.setFormat('jpg').setQuality(90);
```

--------------------------------

### Configure Units for PDF Conversion

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/configuration.md

Set the unit of measurement for density and dimensions. Defaults to PixelsPerInch.

```typescript
// Pixels per inch (default)
const convert = fromPath('./doc.pdf', { 
  density: 300,
  units: 'PixelsPerInch'
});

// Pixels per centimeter
const convert = fromPath('./doc.pdf', { 
  density: 118, // ~300 DPI in metric
  units: 'PixelsPerCentimeter'
});

// No unit specification
const convert = fromPath('./doc.pdf', { 
  units: 'Undefined'
});
```

--------------------------------

### Set Image Compression Method

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Configures the compression method for image output. Available options may vary based on image format and GraphicsMagick version.

```typescript
const gm = new Graphics();
gm.setCompression('lossless').setFormat('png');
```

--------------------------------

### Error Handling in pdf2pic

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/README.md

Demonstrates how to catch and handle different types of errors that may occur during PDF to image conversion.

```typescript
try {
  const result = await convert(1);
} catch (error) {
  if (error.message.includes('Page number')) {
    // Handle invalid page number
  } else if (error.code === 'ENOENT') {
    // Handle file not found
  } else if (error.code === 'EACCES') {
    // Handle permission denied
  } else {
    // Handle other errors
  }
}
```

--------------------------------

### Switch GraphicsMagick Implementation

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Allows switching between ImageMagick and GraphicsMagick, or specifying a custom path to the gm binary.

```typescript
const gm = new Graphics();

// Use ImageMagick
gm.setGMClass(true);

// Or specify a custom path
gm.setGMClass('/opt/local/bin/gm');

// Use default GraphicsMagick
gm.setGMClass(false);
```

--------------------------------

### setCompression()

Source: https://github.com/yakovmeister/pdf2image/blob/master/_autodocs/api-reference/graphics-class.md

Sets the compression method for image output. Available options depend on the image format and GraphicsMagick version.

```APIDOC
## setCompression(compression: string): Graphics

### Description
Sets the compression method for image output.

### Parameters
#### Path Parameters
- **compression** (string) - Required - Compression method (e.g., 'jpeg', 'zip', 'lossless', 'lossy'). Defaults to 'jpeg'.

### Example
```typescript
const gm = new Graphics();
gm.setCompression('lossless').setFormat('png');
```
```
Tokens:
Raw