npm package: @polotno/pdf-export
Description: Convert Polotno JSON into vector PDF
Author: Anton Lavrenov
Latest version: 0.1.38

# Polotno to Vector PDF

Convert polotno JSON into vector PDF file from NodeJS with optional PDF/X-1a print-ready export.

```bash
npm install @polotno/pdf-export
```

## Basic Usage

```js
import fs from 'fs';
import { jsonToPDF } from '@polotno/pdf-export';

async function run() {
  const json = JSON.parse(fs.readFileSync('./polotno.json'));

  // Standard PDF export
  await jsonToPDF(json, './output.pdf');
}

run();
```

## PDF/X-1a Print-Ready Export

For professional printing, use the PDF/X-1a option which ensures:

- CMYK color space conversion
- Transparency flattening
- Font embedding/outlining
- Print industry compliance

```js
// PDF/X-1a export
await jsonToPDF(json, './print-ready.pdf', {
  pdfx1a: true,
});

// PDF/X-1a with custom metadata
await jsonToPDF(json, './book-cover.pdf', {
  pdfx1a: true,
  validate: true, // Optional validation
  metadata: {
    title: 'My Book Cover',
    author: 'Author Name',
    application: 'KDP CoverCreator v1.0',
  },
});
```

## Spot Color / Foil Support

For professional printing with special inks like metallic foils, Pantone colors, or other spot colors:

```js
await jsonToPDF(json, './output.pdf', {
  pdfx1a: true,
  spotColors: {
    // Map any color to a spot color
    'rgba(255,215,0,1)': {
      name: 'Gold Foil',
      type: 'pantone',
      pantoneCode: 'Pantone 871 C', // Optional reference
      cmyk: [0, 0.15, 0.5, 0], // CMYK fallback (0-1 range)
    },
    '#C0C0C0': {
      name: 'Silver Foil',
      type: 'custom',
      cmyk: [0, 0, 0, 0.25],
    },
  },
});
```

**How it works:**

- Any element with a matching fill or stroke color is automatically converted to use the spot color
- Colors are matched flexibly - `'#FFD700'`, `'#ffd700'`, and `'rgba(255,215,0,1)'` all match
- Spot colors are preserved as separation color spaces in PDF/X-1a output
- CMYK fallback values are used when viewers don't support spot colors
- Works with all element types: text, shapes, lines, and SVG elements

**Color Format Support:**

- Hex: `'#FFD700'` or `'#ffd700'`
- RGB: `'rgb(255,215,0)'`
- RGBA: `'rgba(255,215,0,1)'`

**Tips:**

- Use professional color references (like Pantone codes) to communicate exact requirements to printers
- Provide accurate CMYK fallback values for preview and proof prints
- Spot colors work best with PDF/X-1a export enabled
- You can verify spot colors in Adobe Acrobat by checking Output Preview > Separations

## DPI Handling

The library automatically handles DPI conversion to ensure correct physical dimensions in the output PDF. By default, it uses the `dpi` value from your JSON file (or 72 DPI if not specified).

```js
// JSON with dpi specified
const json = {
  width: 1920,
  height: 1080,
  dpi: 300, // 300 DPI input
  // ... rest of JSON
};

// Use JSON dpi automatically
await jsonToPDF(json, './output.pdf');

// Override DPI via attrs (takes precedence over JSON dpi)
await jsonToPDF(json, './output.pdf', {
  dpi: 150, // Override to 150 DPI
});
```

**How it works:**

- Input JSON coordinates are in **pixels** at the specified DPI
- PDF uses **points** (1 point = 1/72 inch)
- The library converts: `points = pixels × (72 / dpi)`
- This ensures the PDF has correct physical dimensions for printing
- All element positions, sizes, and coordinates are automatically scaled

**Example:**

- A 1920×1080 pixel canvas at 300 DPI = 6.4" × 3.6" in the PDF
- The same canvas at 72 DPI = 26.67" × 15" in the PDF

## Requirements

- **GhostScript** must be installed for PDF/X-1a conversion
- macOS: `brew install ghostscript`
- Ubuntu: `apt-get install ghostscript`
- Windows: Download from [ghostscript.com](https://www.ghostscript.com/)

## Development

```bash
npm run build  # Build the library
npm test       # Run tests
```