Add support for Separation colors

Author: Philippe Plantier

rollup.config.js

@@ -9,6 +9,7 @@ const IgnoredWarnings = [
   // Mac & Linux
   'Circular dependency: es/api/PDFDocument.js -> es/api/PDFFont.js -> es/api/PDFDocument.js',
   'Circular dependency: es/api/PDFDocument.js -> es/api/PDFImage.js -> es/api/PDFDocument.js',
+  'Circular dependency: es/api/PDFDocument.js -> es/api/PDFSeparation.js -> es/api/PDFDocument.js',
   'Circular dependency: es/api/PDFDocument.js -> es/api/PDFPage.js -> es/api/PDFDocument.js',
   'Circular dependency: es/api/PDFPage.js -> es/api/PDFDocument.js -> es/api/PDFPage.js',
   'Circular dependency: es/api/PDFDocument.js -> es/api/PDFEmbeddedPage.js -> es/api/PDFDocument.js',
@@ -25,6 +26,7 @@ const IgnoredWarnings = [
   // Windows
   'Circular dependency: es\\api\\PDFDocument.js -> es\\api\\PDFFont.js -> es\\api\\PDFDocument.js',
   'Circular dependency: es\\api\\PDFDocument.js -> es\\api\\PDFImage.js -> es\\api\\PDFDocument.js',
+  'Circular dependency: es\\api\\PDFDocument.js -> es\\api\\PDFSeparation.js -> es\\api\\PDFDocument.js',
   'Circular dependency: es\\api\\PDFDocument.js -> es\\api\\PDFPage.js -> es\\api\\PDFDocument.js',
   'Circular dependency: es\\api\\PDFPage.js -> es\\api\\PDFDocument.js -> es\\api\\PDFPage.js',
   'Circular dependency: es\\api\\PDFDocument.js -> es\\api\\PDFEmbeddedPage.js -> es\\api\\PDFDocument.js',

src/api/PDFDocument.ts

@@ -10,6 +10,7 @@ import PDFFont from 'src/api/PDFFont';
 import PDFImage from 'src/api/PDFImage';
 import PDFPage from 'src/api/PDFPage';
 import PDFForm from 'src/api/form/PDFForm';
+import PDFSeparation from 'src/api/PDFSeparation';
 import { PageSizes } from 'src/api/sizes';
 import { StandardFonts } from 'src/api/StandardFonts';
 import {
@@ -33,6 +34,7 @@ import {
   PDFWriter,
   PngEmbedder,
   StandardFontEmbedder,
+  SeparationEmbedder,
   UnexpectedObjectTypeError,
 } from 'src/core';
 import {
@@ -61,11 +63,13 @@ import {
   pluckIndices,
   range,
   toUint8Array,
+  error,
 } from 'src/utils';
 import FileEmbedder, { AFRelationship } from 'src/core/embedders/FileEmbedder';
 import PDFEmbeddedFile from 'src/api/PDFEmbeddedFile';
 import PDFJavaScript from 'src/api/PDFJavaScript';
 import JavaScriptEmbedder from 'src/core/embedders/JavaScriptEmbedder';
+import { Color, ColorTypes, colorToComponents } from './colors';
 
 /**
  * Represents a PDF document.
@@ -185,6 +189,7 @@ export default class PDFDocument {
   private readonly formCache: Cache<PDFForm>;
   private readonly fonts: PDFFont[];
   private readonly images: PDFImage[];
+  private readonly separationColorSpaces: PDFSeparation[];
   private readonly embeddedPages: PDFEmbeddedPage[];
   private readonly embeddedFiles: PDFEmbeddedFile[];
   private readonly javaScripts: PDFJavaScript[];
@@ -206,6 +211,7 @@ export default class PDFDocument {
     this.formCache = Cache.populatedBy(this.getOrCreateForm);
     this.fonts = [];
     this.images = [];
+    this.separationColorSpaces = [];
     this.embeddedPages = [];
     this.embeddedFiles = [];
     this.javaScripts = [];
@@ -997,6 +1003,32 @@ export default class PDFDocument {
     return pdfFont;
   }
 
+  /**
+   * Embed a separation color space into this document.
+   * For example:
+   * ```js
+   * import { rgb } from 'pdf-lib'
+   * const separation = pdfDoc.embedSeparation('PANTONE 123 C', rgb(1, 0, 0))
+   * ```
+   *
+   * @param name      The name of the separation color space.
+   * @param alternate An alternate color to be used to approximate the intended
+   *                  color.
+   */
+  embedSeparation(name: string, alternate: Color): PDFSeparation {
+    const ref = this.context.nextRef();
+    const alternateColorSpace = getColorSpace(alternate);
+    const alternateColorComponents = colorToComponents(alternate);
+    const embedder = SeparationEmbedder.for(
+      name,
+      alternateColorSpace,
+      alternateColorComponents,
+    );
+    const separation = PDFSeparation.of(ref, this, embedder);
+    this.separationColorSpaces.push(separation);
+    return separation;
+  }
+
   /**
    * Embed a JPEG image into this document. The input data can be provided in
    * multiple formats:
@@ -1243,6 +1275,7 @@ export default class PDFDocument {
   async flush(): Promise<void> {
     await this.embedAll(this.fonts);
     await this.embedAll(this.images);
+    await this.embedAll(this.separationColorSpaces);
     await this.embedAll(this.embeddedPages);
     await this.embedAll(this.embeddedFiles);
     await this.embedAll(this.javaScripts);
@@ -1393,3 +1426,10 @@ function assertIsLiteralOrHexString(
     throw new UnexpectedObjectTypeError([PDFHexString, PDFString], pdfObject);
   }
 }
+
+// prettier-ignore
+const getColorSpace = (color: Color) => 
+    color.type === ColorTypes.Grayscale  ? 'DeviceGray'
+  : color.type === ColorTypes.RGB        ? 'DeviceRGB'
+  : color.type === ColorTypes.CMYK       ? 'DeviceCMYK'
+  : error(`Invalid alternate color: ${JSON.stringify(color)}`);

src/api/PDFPage.ts

@@ -1,4 +1,4 @@
-import { Color, rgb } from 'src/api/colors';
+import { Color, rgb, separation } from 'src/api/colors';
 import {
   drawImage,
   drawLine,
@@ -55,6 +55,7 @@ import {
   assertRangeOrUndefined,
   assertIsOneOfOrUndefined,
 } from 'src/utils';
+import PDFSeparation from './PDFSeparation';
 
 /**
  * Represents a single page of a [[PDFDocument]].
@@ -763,6 +764,30 @@ export default class PDFPage {
     this.lineHeight = lineHeight;
   }
 
+  /**
+   * Creates a local Separation color for this page. The color can then be
+   * used to draw text or fill shapes. For example:
+   * ```js
+   * const pdfSeparation = await pdfDoc.embedSeparation(
+   *   'PANTONE 123 C',
+   *   cmyk(0, 0.22, 0.83, 0),
+   * );
+   * const color = page.getSeparationColor(pdfSeparation, 0.5);
+   * page.drawText('This text will be printed using a spot color', { color });
+   * ```
+   *
+   * @param pdfSeparation A PDFSeparation object that was embedded into the
+   *                      document.
+   * @param tint          The tint (intensity) value to use for the color.
+   *
+   * @returns The name of the color space in the page's resources.
+   */
+  getSeparationColor(pdfSeparation: PDFSeparation, tint: number): Color {
+    const name = pdfSeparation.name;
+    const ref = pdfSeparation.ref;
+    return separation(this.node.newColorSpace(name, ref), tint);
+  }
+
   /**
    * Get the default position of this page. For example:
    * ```js

src/api/PDFSeparation.ts

@@ -0,0 +1,73 @@
+import Embeddable from 'src/api/Embeddable';
+import PDFDocument from 'src/api/PDFDocument';
+import { PDFRef } from 'src/core';
+import SeparationEmbedder from 'src/core/embedders/SeparationEmbedder';
+import { assertIs } from 'src/utils';
+
+/**
+ * Represents a file that has been embedded in a [[PDFDocument]].
+ */
+export default class PDFSeparation implements Embeddable {
+  /**
+   * > **NOTE:** You probably don't want to call this method directly. Instead,
+   * > consider using the [[PDFDocument.embedSeparation]] method which will
+   * > create instances of [[PDFSeparation]] for you.
+   *
+   * Create an instance of [[PDFSeparation]] from an existing ref and embedder
+   *
+   * @param ref The unique reference for this file.
+   * @param doc The document to which the file will belong.
+   * @param embedder The embedder that will be used to embed the file.
+   */
+  static of = (ref: PDFRef, doc: PDFDocument, embedder: SeparationEmbedder) =>
+    new PDFSeparation(ref, doc, embedder);
+
+  /** The unique reference assigned to this separation within the document. */
+  readonly ref: PDFRef;
+
+  /** The document to which this separation belongs. */
+  readonly doc: PDFDocument;
+
+  /** The name of this separation. */
+  readonly name: string;
+
+  private alreadyEmbedded = false;
+  private readonly embedder: SeparationEmbedder;
+
+  private constructor(
+    ref: PDFRef,
+    doc: PDFDocument,
+    embedder: SeparationEmbedder,
+  ) {
+    assertIs(ref, 'ref', [[PDFRef, 'PDFRef']]);
+    assertIs(doc, 'doc', [[PDFDocument, 'PDFDocument']]);
+    assertIs(embedder, 'embedder', [
+      [SeparationEmbedder, 'SeparationEmbedder'],
+    ]);
+    this.ref = ref;
+    this.doc = doc;
+    this.name = embedder.separationName;
+
+    this.embedder = embedder;
+  }
+
+  /**
+   * > **NOTE:** You probably don't need to call this method directly. The
+   * > [[PDFDocument.save]] and [[PDFDocument.saveAsBase64]] methods will
+   * > automatically ensure all separations get embedded.
+   *
+   * Embed this separation in its document.
+   *
+   * @returns Resolves when the embedding is complete.
+   */
+  async embed(): Promise<void> {
+    if (!this.embedder) return;
+
+    // The separation should only be embedded once. If there's a pending embed
+    // operation then wait on it. Otherwise we need to start the embed.
+    if (this.alreadyEmbedded) return;
+    this.alreadyEmbedded = true;
+
+    await this.embedder.embedIntoContext(this.doc.context, this.ref);
+  }
+}

src/api/colors.ts

@@ -2,16 +2,21 @@ import {
   setFillingCmykColor,
   setFillingGrayscaleColor,
   setFillingRgbColor,
+  setFillingSpecialColor,
   setStrokingCmykColor,
   setStrokingGrayscaleColor,
   setStrokingRgbColor,
+  setStrokingSpecialColor,
+  setFillingColorspace,
 } from 'src/api/operators';
 import { assertRange, error } from 'src/utils';
+import { PDFName } from 'src/core';
 
 export enum ColorTypes {
   Grayscale = 'Grayscale',
   RGB = 'RGB',
   CMYK = 'CMYK',
+  Separation = 'Separation',
 }
 
 export interface Grayscale {
@@ -34,7 +39,13 @@ export interface CMYK {
   key: number;
 }
 
-export type Color = Grayscale | RGB | CMYK;
+export interface Separation {
+  type: ColorTypes.Separation;
+  name: PDFName;
+  tint: number;
+}
+
+export type Color = Grayscale | RGB | CMYK | Separation;
 
 export const grayscale = (gray: number): Grayscale => {
   assertRange(gray, 'gray', 0.0, 1.0);
@@ -61,20 +72,33 @@ export const cmyk = (
   return { type: ColorTypes.CMYK, cyan, magenta, yellow, key };
 };
 
-const { Grayscale, RGB, CMYK } = ColorTypes;
+export const separation = (name: PDFName, tint: number): Separation => {
+  assertRange(tint, 'tint', 0, 1);
+  return { type: ColorTypes.Separation, name, tint };
+};
+
+const { Grayscale, RGB, CMYK, Separation } = ColorTypes;
+
+export const setFillingColorspaceOrUndefined = (color: Color) =>
+  color.type === Separation ? setFillingColorspace(color.name) : undefined;
 
 // prettier-ignore
 export const setFillingColor = (color: Color) => 
-    color.type === Grayscale ? setFillingGrayscaleColor(color.gray)
-  : color.type === RGB       ? setFillingRgbColor(color.red, color.green, color.blue)
-  : color.type === CMYK      ? setFillingCmykColor(color.cyan, color.magenta, color.yellow, color.key)
+    color.type === Grayscale  ? setFillingGrayscaleColor(color.gray)
+  : color.type === RGB        ? setFillingRgbColor(color.red, color.green, color.blue)
+  : color.type === CMYK       ? setFillingCmykColor(color.cyan, color.magenta, color.yellow, color.key)
+  : color.type === Separation ? setFillingSpecialColor(color.tint)
   : error(`Invalid color: ${JSON.stringify(color)}`);
 
+export const setStrokingColorspaceOrUndefined = (color: Color) =>
+  color.type === Separation ? setFillingColorspace(color.name) : undefined;
+
 // prettier-ignore
 export const setStrokingColor = (color: Color) => 
-    color.type === Grayscale ? setStrokingGrayscaleColor(color.gray)
-  : color.type === RGB       ? setStrokingRgbColor(color.red, color.green, color.blue)
-  : color.type === CMYK      ? setStrokingCmykColor(color.cyan, color.magenta, color.yellow, color.key)
+    color.type === Grayscale  ? setStrokingGrayscaleColor(color.gray)
+  : color.type === RGB        ? setStrokingRgbColor(color.red, color.green, color.blue)
+  : color.type === CMYK       ? setStrokingCmykColor(color.cyan, color.magenta, color.yellow, color.key)
+  : color.type === Separation ? setStrokingSpecialColor(color.tint)
   : error(`Invalid color: ${JSON.stringify(color)}`);
 
 // prettier-ignore

src/api/form/appearances.ts

@@ -23,6 +23,7 @@ import {
   grayscale,
   cmyk,
   Color,
+  setFillingColorspaceOrUndefined,
 } from 'src/api/colors';
 import { reduceRotation, adjustDimsForRotation } from 'src/api/rotations';
 import {
@@ -157,9 +158,12 @@ const updateDefaultAppearance = (
   fontSize: number = 0,
 ) => {
   const da = [
+    setFillingColorspaceOrUndefined(color)?.toString(),
     setFillingColor(color).toString(),
     setFontAndSize(font?.name ?? 'dummy__noop', fontSize).toString(),
-  ].join('\n');
+  ]
+    .filter(Boolean)
+    .join('\n');
   field.setDefaultAppearance(da);
 };
 

src/api/index.ts

@@ -14,6 +14,7 @@ export * from 'src/api/StandardFonts';
 export { default as PDFDocument } from 'src/api/PDFDocument';
 export { default as PDFFont } from 'src/api/PDFFont';
 export { default as PDFImage } from 'src/api/PDFImage';
+export { default as PDFSeparation } from 'src/api/PDFSeparation';
 export { default as PDFPage } from 'src/api/PDFPage';
 export { default as PDFEmbeddedPage } from 'src/api/PDFEmbeddedPage';
 export { default as PDFJavaScript } from 'src/api/PDFJavaScript';