@cley_faye/pdf-overlay

Add an overlay to all pages of a PDF.

This is a preliminary version; works as a CLI tool using Node.

Usage

You can use it without installation as long as NPM is available.

Pass the name of the config file as the only argument.

npx --package=@cley_faye/pdf-overlay <config file>

Configuration

The configuration must be provided in a JSON file with the following properties:

{
  "inputPDF": "input.pdf",
  "fileSource": "data.txt",
  "outputDirectory": "output",
  "filenameTemplate": "%{basename} - %{index} - %{text}",
  "overlay": [
    {
      "position": {"horizontal": "left", "vertical": "top"},
      "orientation": "horizontal",
      "textTemplate": "%{text}",
      "font": "Courier",
      "size": 12,
      "color": {"r": 0, "g": 0, "b": 0},
      "opacity": 1,
      "margin": 0,
      "pages": "all"
    },
    {
      "position": {"horizontal": "right", "vertical": "center"},
      "orientation": "vertical",
      "textTemplate": "Exemplaire %{index} / %{total}",
      "font": "Courier",
      "size": 12,
      "color": {"r": 0, "g": 0, "b": 0},
      "opacity": 1,
      "margin": 0
      "pages": "1"
    }
  ]
}

inputPDF

Name of the input PDF file.

fileSource

Name of the file containing all the "text" to use for overlay, one per line.

outputDirectory

Directory to put the overlaid files into. Optional, defaults to "output".

filenameTemplate

Template for the output filename. See the "Template string" section below for more details. Optional, defaults to "%{basename} - %{index} - %{text}".

overlay

Describe the overlays to apply to each pages. This property is an array and each entry is a single overlay text.

position

Position of the overlay. It is possible to specify a position in two ways:

• absolute position, starting from the bottom-left corner of a page: {"x": 50, "y": 50} (x is the horizontal offset, y the vertical one)
• relative to a page's edge: {"horizontal": "left", "vertical": "top"}

For the edge-based position, the valid values for horizontal are:

• "left"
• "center"
• "right"

The valid values for vertical are:

• "top"
• "center"
• "bottom"

textTemplate

The text to stamp with this overlay. See the "Template string" section below for more details.

font

Font for the text. Can be one of the standard PDF font:

• "Courier"
• "CourierBold"
• "CourierOblique"
• "CourierBoldOblique"
• "Helvetica"
• "HelveticaBold"
• "HelveticaOblique"
• "HelveticaBoldOblique"
• "TimesRoman"
• "TimesRomanBold"
• "TimesRomanItalic"
• "TimesRomanBoldItalic"
• "Symbol"
• "ZapfDingbats"

Alternatively, it is possible to pass the path to a font file. Optional, defaults to "Courier".

orientation

Change the orientation of the text. Possible values:

• "horizontal" (default value): text is horizontal
• "horizontalFlip": text is flipped 180°
• "vertical": text is vertical, rotated 90° clockwise from horizontal
• "verticalFlip": text is vertical, rotated 90° counterclockwise from horizontal

size

Font size. Optional, defaults to 12.

color

Color for the text. Must be provided as a triple with r for red, g for green and b for blue. Values goes from 0 to 1. Optional, defaults to black.

opacity

Text opacity. Range from 0 to 1. Optional, defaults to 1 (full opacity).

margin

Margin to add between the text and the page border. The unit is… let's say points. Optional, defauls to 0.

pages

Pages to put the overlay on. Defaults to all pages if not specified.

To define which page will get this specific overlay, you can use directives, which will be applied in the provided order. Each directives are separated by a semicolon.

Available directives:

• all: enable on all pages
• odd: enable on odd pages
• even: enable on even pages
• 3: enable on page 3 (any page number)
• -3: disable on page 3 (any page number)
• 4,7: enable on pages 4 to 7 (included)
• -4,7: disable on pages 4 to 7 (included)

Some examples:

• all;-10: enable on all pages except page 10
• odd;-11: enable on all odd pages except page 11
• even;3;-22,36: enable on all even pages plus page 3, except pages from 22 to 36
• 34: enable only on page 34
• 34,1664;-63: enable on pages from 34 to 1664 (included), except on page 63

Template string

For both the filename and the textTemplate properties in configuration, you can specify template variables. To do so, use this notation: %{variable name}.

Available variables:

• index: ID of the current output (starts at 1)
• total: total number of files that will be produced
• text: the line of text from the data source
• basename: the name of the input PDF file

The following string is a working example:

For %{text}, edition %{index} of %{total}