or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdconversion.mdindex.mdinput-sources.md
tile.json

tessl/npm-pdf2pic

A utility for converting pdf to image formats with support for different outputs: directly to file, base64 or buffer.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pdf2pic@3.2.x

To install, run

npx @tessl/cli install tessl/npm-pdf2pic@3.2.0

index.mddocs/

pdf2pic

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.

Package Information

  • Package Name: pdf2pic
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install pdf2pic

Prerequisites

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

  • Node.js: >= 14.x
  • GraphicsMagick: Image processing library
  • Ghostscript: PDF processing library

Core Imports

import { fromPath, fromBuffer, fromBase64 } from "pdf2pic";

For CommonJS:

const { fromPath, fromBuffer, fromBase64 } = require("pdf2pic");

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.

Basic Usage

import { fromPath } from "pdf2pic";

// Configure conversion options
const options = {
  density: 100,
  saveFilename: "page",
  savePath: "./images",
  format: "png",
  width: 600,
  height: 600
};

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

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

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

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

Architecture

pdf2pic is built around several key components:

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

Capabilities

PDF Input Sources

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

function fromPath(filePath: string, options?: Options): Convert;
function fromBuffer(buffer: Buffer, options?: Options): Convert;
function fromBase64(b64string: string, options?: Options): Convert;

PDF Input Sources

PDF Conversion

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

interface Convert {
  (pages?: number): Promise<WriteImageResponse>;
  (pages: number, options: { responseType?: undefined }): Promise<WriteImageResponse>;
  (pages: number, options: { responseType: 'image' }): Promise<WriteImageResponse>;
  (pages: number, options: { responseType: 'base64' }): Promise<ToBase64Response>;
  (pages: number, options: { responseType: 'buffer' }): Promise<BufferResponse>;
  
  bulk: {
    (pages?: number | number[]): Promise<WriteImageResponse[]>;
    (pages: number | number[], options: { responseType?: undefined }): Promise<WriteImageResponse[]>;
    (pages: number | number[], options: { responseType: 'image' }): Promise<WriteImageResponse[]>;
    (pages: number | number[], options: { responseType: 'base64' }): Promise<ToBase64Response[]>;
    (pages: number | number[], options: { responseType: 'buffer' }): Promise<BufferResponse[]>;
  };
  
  setOptions(): void;
  setGMClass(gmClass: string | boolean): void;
}

PDF Conversion

Configuration Options

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

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

Configuration Options

Types

Response Types

interface BaseResponse {
  size?: string;
  page?: number;
}

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

interface ToBase64Response extends BaseResponse {
  base64?: string;
}

interface BufferResponse extends BaseResponse {
  buffer?: Buffer;
}

type ConvertResponse = WriteImageResponse | ToBase64Response | BufferResponse;

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

interface ConvertOptions {
  /** Output format for the conversion result */
  responseType: ResponseType;
}

Troubleshooting

Common Setup Issues

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

  • macOS: brew install graphicsmagick ghostscript
  • Ubuntu/Debian: sudo apt-get install graphicsmagick ghostscript
  • Windows: Download and install from official websites, ensure PATH is updated

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

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