8 Watermarks and Stamps

cpdf -stamp-on source.pdf
[-scale-stamp-to-fit] [<positioning command>] [-relative-to-cropbox]
in.pdf [<range>] [-fast] -o out.pdf

cpdf -stamp-under source.pdf
[-scale-stamp-to-fit] [<positioning command>] [-relative-to-cropbox]
in.pdf [<range>] [-fast] -o out.pdf

cpdf -combine-pages over.pdf under.pdf
[-fast] [-prerotate] [-no-warn-rotate] -o out.pdf

cpdf ([-add-text <text-format> | -add-rectangle <size>])
              [-font <fontname>]          [-font-size <size-in-points>]
              [-color <color>]            [-line-spacing <number>]
              [-outline]                  [-linewidth <number>]
              [-underneath]               [-relative-to-cropbox]
              [-prerotate]                [-no-warn-rotate]
              [-bates <number>]           [-bates-at-range <number>]
              [-bates-pad-to <number>]    [-opacity <number>]
              [-midline]                  [-topline]
              [-fast]
              in.pdf [<range>] -o out.pdf

See also positioning commands below.

cpdf -remove-text in.pdf [<range>] -o out.pdf

cpdf -prepend-content <content> in.pdf [<range>] -o out.pdf

cpdf -postpend-content <content> in.pdf [<range>] -o out.pdf

cpdf -stamp-as-xobject stamp.pdf in.pdf [<range>] -o out.pdf

NB: See discussion of -fast in Section 1.13.

8.1 Add a Watermark or Logo

The -stamp-on and -stamp-under operations stamp the first page of a source PDF onto or under each page in the given range of the input file. For example,

The position commands in Section 8.2.4 can be used to locate the stamp more precisely (they are calculated relative to the crop box of the stamp). Or, preprocess the stamp with -shift first.

The -scale-stamp-to-fit option can be added to scale the stamp to fit the page before applying it. The use of positioning commands together with -scale-stamp-to-fit is not recommended.

The -combine-pages operation takes two PDF files and stamps each page of one over each page of the other. The length of the output is the same as the length of the “under” file. For instance:

Page attributes (such as the display rotation) are taken from the “under” file. For best results, remove any rotation differences in the two files using -upright (see above) first.

The -relative-to-cropbox option takes the positioning command to be relative to the crop box of each page rather than the media box.

8.2 Stamp Text, Dates and Times.

The -add-text operation allows text, dates and times to be stamped over one or more pages of the input at a given position and using a given font, font size and color.

8.2.1 Page Numbers

For example, the format "Page %Page of %EndPage" might become ”Page 5 of 17”.

NB: In some circumstances (e.g in batch files) on Microsoft Windows, % is a special character, and must be escaped (written as %%). Consult your local documentation for details.

8.2.2 Date and Time Formats

8.2.3 Bates Numbers

Unique page identifiers can be specified by putting %Bates in the format. The starting point can be set with the -bates option. For example:

To specify that bates numbering begins at the first page of the range, use -bates-at-range instead. This option must be specified after the range is specified. To pad the bates number up to a given number of leading zeros, use -bates-pad-to in addition to either -bates or -bates-at-range.

8.2.4 Position

No attempt is made to take account of the page rotation when interpreting the position, so -prerotate may be added to the command line if the file contains pages with a non-zero viewing rotation (to silence the rotation warning, add -no-warn-rotate instead) This is equivalent to pre-processing the document with -upright (see chapter 3).

The -relative-to-cropbox modifier can be added to the command line to make these measurements relative to the crop box instead of the media box.

The -midline option may be added to specify that the positioning commands above are to be considered relative to the midline of the text, rather than its baseline. Similarly, the -topline option may be used to specify that the position is taken relative to the top of the text.

8.2.5 Font and Size

The font may be set with the -font option. The 14 Standard PDF fonts are available:

8.2.6 Colors

The -color option takes an RGB (3 values), CYMK (4 values), or Grey (1 value) color. Components range between 0 and 1. The following RGB colors are predefined:

Partly-transparent text may be specified using the -opacity option. Wholly opaque is 1 and wholly transparent is 0. For example:

8.2.7 Outline Text

The -outline option sets outline text. The line width (default 1pt) may be set with the -linewidth option. For example, to stamp documents as drafts:

8.2.8 Multi-line Text

The code \n can be included in the text string to move to the next line. In this case, the vertical position refers to the baseline of the first line of text (if the position is at the top, top left or top right of the page) or the baseline of the last line of text (if the position is at the bottom, bottom left or bottom right).

The -midline option may be used to make these vertical positions relative to the midline of a line of text rather than the baseline, as usual.

The -line-spacing option can be used to increase or decrease the line spacing, where a spacing of 1 is the standard.

Justification of multiple lines is handled by the -justify-left, -justify-right and
-justify-center options. The defaults are left justification for positions relative to the left hand side of the page, right justification for those relative to the right, and center justification for positions relative to the center of the page. For example:

8.2.9 Special Characters

If your command line allows for the inclusion of unicode characters, the input text will be considered as UTF8 by cpdf. Special characters which exist in the PDF WinAnsiEncoding Latin 1 code (such as many accented characters) will be reproduced in the PDF. This does not mean, however, that every special character can be reproduced – it must exist in the font. When using a custom font, cpdf will attempt to convert from UTF8 to the encoding of that font automatically.

(For compatibility with previous versions of cpdf, special characters may be introduced manually with a backslash followed by the three-digit octal code of the character in the PDF WinAnsiEncoding Latin 1 Code. The full table is included in Appendix D of the Adobe PDF Reference Manual, which is available at https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/pdfs/PDF32000_2008.pdf. For example, a German sharp s (ß) may be introduced by ' 337.)

8.3 Stamping Graphics

A rectangle may be placed on one or more pages by using the -add-rectangle <size> command. Most of the options discussed above for text placement apply in the same way. For example:

This can be used to blank out or highlight part of the document. The following positioning options work as you would expect: -topleft, -top, -topright, -right, -bottomright, -bottom, -bottomleft, -left, -center. When using the option -pos-left "x y", the point (x, y) refers to the bottom-left of the rectangle. When using the option -pos-right "x y", the point (x, y) refers to the bottom-right of the rectangle. When using the option -pos-center "x y", the point (x, y) refers to the center of the rectangle. The options -diagonal and -reverse-diagonal have no meaning.

8.4 Low-level facilities

These two operations add content directly to the beginning or end of the page data for a page. You must understand the PDF page description language to use these.

The -fast option may be added (see Chapter 1). The -stamp-as-xobject operation puts a file in another as a Form XObject on the given pages. You can then use -prepend-content or -postpend-content to use it.

C Interface

/* CHAPTER 8. Logos, Watermarks and Stamps */

/*
* cpdf_stampOn(stamp_pdf, pdf, range) stamps stamp_pdf on top of all the
* pages in the document which are in the range. The stamp is placed with its
* origin at the origin of the target document.
*/
void cpdf_stampOn(int, int, int);

/*
* cpdf_stampUnder(stamp_pdf, pdf, range) stamps stamp_pdf under all the
* pages in the document which are in the range. The stamp is placed with its
* origin at the origin of the target document.
*/
void cpdf_stampUnder(int, int, int);

/*
* cpdf_stampExtended(pdf, pdf2, range, isover, scale_stamp_to_fit, pos,
* relative_to_cropbox) is a stamping function with extra features. - isover
* true, pdf goes over pdf2, isover false, pdf goes under pdf2 -
* scale_stamp_to_fit scales the stamp to fit the page - pos gives the
* position to put the stamp - relative_to_cropbox: if true, pos is relative
* to cropbox not mediabox.
*/
void cpdf_stampExtended(int, int, int, int, int, struct cpdf_position, int);

/*
* cpdf_combinePages(under, over) combines the PDFs page-by-page, putting
* each page of over over each page of under.
*/
int cpdf_combinePages(int, int);

/* Adding text. Adds text to a PDF, if the characters exist in the font. */

/*
* Special codes
*
* %Page     Page number in arabic notation (1, 2, 3...)
*
* %roman    Page number in lower-case roman notation (i, ii, iii...)
*
* %Roman    Page number in upper-case roman notation (I, II, III...)
*
* %EndPage  Last page of document in arabic notation
*
* %Label    The page label of the page
*
* %EndLabel The page label of the last page
*
* %filename The full file name of the input document
*
* %a        Abbreviated weekday name (Sun, Mon etc.)
*
* %A        Full weekday name (Sunday, Monday etc.)
*
* %b        Abbreviated month name (Jan, Feb etc.)
*
* %B        Full month name (January, February etc.)
*
* %d        Day of the month (01-31)
*
* %e        Day of the month (1-31)
*
* %H        Hour in 24-hour clock (00-23)
*
* %I        Hour in 12-hour clock (01-12)
*
* %j        Day of the year (001-366)
*
* %m        Month of the year (01-12)
*
* %M        Minute of the hour (00-59)
*
* %p        "a.m" or "p.m"
*
* %S        Second of the minute (00-61)
*
* %T        Same as %H:%M:%S
*
* %u        Weekday (1-7, 1 = Monday)
*
* %w        Weekday (0-6, 0 = Monday)
*
* %Y        Year (0000-9999)
*
* %%        The % character
*/

/* The standard fonts */
enum cpdf_font {
  cpdf_timesRoman,           /* Times Roman */
  cpdf_timesBold,            /* Times Bold */
  cpdf_timesItalic,          /* Times Italic */
  cpdf_timesBoldItalic,      /* Times Bold Italic */
  cpdf_helvetica,            /* Helvetica */
  cpdf_helveticaBold,        /* Helvetica Bold */
  cpdf_helveticaOblique,     /* Helvetica Oblique */
  cpdf_helveticaBoldOblique, /* Helvetica Bold Oblique */
  cpdf_courier,              /* Courier */
  cpdf_courierBold,          /* Courier Bold */
  cpdf_courierOblique,       /* Courier Oblique */
  cpdf_courierBoldOblique    /* Courier Bold Oblique */
};

/* Justifications for multi line text */
enum cpdf_justification {
  cpdf_leftJustify,   /* Left justify */
  cpdf_CentreJustify, /* Centre justify */
  cpdf_RightJustify   /* Right justify */
};

/* Add text */
void cpdf_addText(int,                  /* If true, dont actually add text but
                                         * collect metrics. */
                  int,                  /* Document */
                  int,                  /* Page Range */
                  const char[],         /* The text to add */
                  struct cpdf_position, /* Position to add text at */
                  double,               /* Linespacing, 1.0 = normal */
                  int,                  /* Starting Bates number */
                  enum cpdf_font,       /* Font */
                  double,               /* Font size in points */
                  double,               /* Red component of colour, 0.0 - 1.0 */
                  double, /* Green component of colour, 0.0 - 1.0 */
                  double, /* Blue component of colour, 0.0 - 1.0 */
                  int,    /* If true, text is added underneath rather
                           * than on top */
                  int,    /* If true, position is relative to crop box
                           * not media box */
                  int,    /* If true, text is outline rather than
                           * filled */
                  double, /* Opacity, 1.0 = opaque, 0.0 = wholly
                           * transparent */
                  enum cpdf_justification, /* Justification */
                  int,          /* If true, position is relative to midline
                                 * of text, not baseline */
                  int,          /* If true, position is relative to topline
                                 * of text, not baseline */
                  const char[], /* filename that this document was read from
                                 * (optional) */
                  double,       /* line width */
                  int           /* embed fonts */
);

/* Add text, with most parameters default. */
void cpdf_addTextSimple(int,                  /* Document */
                        int,                  /* Page range */
                        const char[],         /* The text to add */
                        struct cpdf_position, /* Position to add text
                                               * at */
                        enum cpdf_font,       /* font */
                        double);              /* font size */

/*
* cpdf_removeText(pdf, range) will remove any text added by libcpdf from the
* given pages.
*/
void cpdf_removeText(int, int);

/*
* Return the width of a given string in the given font in thousandths of a
* point.
*/
int cpdf_textWidth(enum cpdf_font, const char[]);

/* cpdf_addContent(content, before, range, pdf) adds page content before (if
* true) or after (if false) the existing content to pages in the given range
* in the given PDF. */
void cpdf_addContent(const char[], int, int, int);

/* cpdf_stampAsXObject(pdf, range, stamp_pdf) stamps stamp_pdf onto the pages
* in the given range in pdf as a shared Form XObject. The name of the
* newly-created XObject is returned. */
char *cpdf_stampAsXObject(int, int, int);

Chapter 8Watermarks and Stamps