Chapter 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,

cpdf -stamp-on logo.pdf in.pdf odd -o out.pdf

stamps the file logo.pdf onto the odd pages of in.pdf, writing to out.pdf. A watermark should go underneath each page:

cpdf -stamp-under topsecret.pdf in.pdf -o out.pdf

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:

cpdf -combine-pages over.pdf under.pdf -o out.pdf

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.

cpdf -add-text "Copyright 2014 ACME Corp." in.pdf -o out.pdf

The default is black 12pt Times New Roman text in the top left of each page. The text can be placed underneath rather than over the page by adding the -underneath option.

Text previously added by cpdf may be removed by the -remove-text operation.

cpdf -remove-text in.pdf -o out.pdf

8.2.1 Page Numbers

There are various special codes to include the page number in the text:

%Page       Page num berinarabic notation(1,2,3...)
%PageDiv2   Page num berinarabic notationdividedby two
%roman      Page num berinlower-case rom an notation (i,ii,iii...)
%Roman      Page num berinupp er-case roman notation(I,II,III...)
%EndPage    Lastpage ofdocum entinarabic notation
%Label      Th epage labelofthepage
%EndLabel   Th epage labelofthelastpage
%filename   Th efullfilen am e ofthe inp utdocum ent

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

%%aA  AFubbllrweveiaetkeddawyneaemkdea(ySnunamdae&# (Sun,M on etc.)
%b  A bbreviatedm onthnam e(Jan,Febetc.)
%B  Fu llm onthnam e(Jan uary,Februaryetc.)
%d  D ayofthe month (01–31)
%e  D ayofthe month (1–31)
%H  H ourin24-hour clock(00–23)
%I  H ourin12-hour clock(01–12)
%j  D ayofthe year (001–366)
%m  M onthof the year(01–12)
%M  M inuteofthehour (00–59)
%p  ”a.m” or”p.m”
%S  Second ofthem inu te (00–61)
%T  Sam eas %H :% M :% S
%u  W eekday (1–7,1= Sunday)
%w  W eekday (0–6,0= Sunday)
%Y  Year(0000–9999)
%%  Th e% character.

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:

cpdf -add-text "Page ID: %Bates" -bates 23745 in.pdf -o out.pdf

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

The position of the text may be specified either in absolute terms:

-pos-center "200 200"

Position the center of the baseline text at (200pt, 200pt)

-pos-left "200 200"

Position the left of the baseline of the text at (200pt, 200pt)

-pos-right "200 200"

Position the right of the baseline of the text at (200pt, 200pt)

Positions relative to certain common points can be set:

-top 10            C enter ofbaseline10p ts down from the top center
-topleft 10        L eftofb aseline 10ptsdow n andinfrom topleft
-topright 10       R ight ofbaseline10p ts down and leftfrom top right
-left 10           L eftofb aseline 10ptsinfrom center left
-bottomleft 10     L eftofb aseline 10ptsinand up from bottom left
-bottom 10         C enter ofbaseline10p ts upfrom bottom center
-bottomright 10    R ight ofbaseline10p ts upand infro m bottom right
-right 10          R ight ofbaseline10p ts in from thecenterright
-diagonal          D iag onal,botto m leftto topright,centered on page
-reverse-diagonal  D iag onal,topleftto bottom right,centered on page
-center            C entered onpage

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 default position is equivalent to -topleft 100.

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:

TTimim eess-R-B oomldan
Tim es-Italic
Tim es-B oldItalic
Helvetica
Helvetica-B old
Helvetica-O blique
Helvetica-B oldO blique
Courier
Courier-Bold
Courier-Obliq ue
Courier-BoldObliqu e
Symb ol
ZapfDingbats

For example, page numbers in Times Italic can be achieved by:

cpdf -add-text "-%Page-" -font "Times-Italic" in.pdf -o out.pdf

See Section 14.3 for how to use other fonts. The font size can be altered with the -font-size option, which specifies the size in points:

cpdf -add-text "-%Page-" -font-size 36 in.pdf -o out.pdf

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:

-Color--R,G-,B--
 white  1,1,1
 black   0,0,0
 red     1,0,0
 green   0,1,0
 blue    0,0,1

cpdf -add-text "Hullo" -color "red" in.pdf -o out.pdf

cpdf -add-text "Hullo" -color "0.5 0.5 0.5" in.pdf -o out.pdf

cpdf -add-text "Hullo" -color "0.75" in.pdf -o out.pdf

cpdf -add-text "Hullo" -color "0.5 0.5 0.4 0.9" in.pdf -o out.pdf

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

cpdf -add-text "DRAFT" -color "red" -opacity 0.3 -o out.pdf

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:

cpdf -add-text "DRAFT" -diagonal -outline in.pdf -o out.pdf

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).

cpdf -add-text "Specification' n%Page of %EndPage"
               -topright 10 in.pdf -o out.pdf

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.

cpdf -add-text "Specification' n%Page of %EndPage"
               -topright 10 -line-spacing 1.5 in.pdf -o out.pdf

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:

cpdf -add-text "Long line' nShort" -justify-right
               in.pdf -o out.pdf

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:

cpdf -add-rectangle "200 300" -pos-right 30 -color red -outline
                    in.pdf -o out.pdf

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.

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

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

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.

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

Java Interface

 
/* CHAPTER 8. Logos, Watermarks and Stamps */ 
 
/** Stamps another 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. 
@param stamp_pdf stamp PDF document 
@param pdf PDF document 
@param range page range */ 
public native void stampOn(Pdf stamp_pdf, Pdf pdf, Range range) 
    throws CpdfError; 
 
/** Stamps another 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. 
@param stamp_pdf stamp PDF document 
@param pdf PDF document 
@param range page range */ 
public native void stampUnder(Pdf stamp_pdf, Pdf pdf, Range range) 
    throws CpdfError; 
 
/** A stamping function with extra features. 
@param pdf first PDF document 
@param pdf2 second PDF document 
@param range page range 
@param isover if <code>true</code>, <code>pdf</code> goes over 
<code>pdf2</code> otherwise under 
@param scale_stamp_to_fit if <code>true</code> scales the stamp to fit 
the page. 
@param anchor position anchor, such as {@link #posCentre posCentre} 
@param p1 position parameter one 
@param p2 position parameter two 
@param relative_to_cropbox if <code>true</code>, the position is relative 
to the crop box rather than the media box. */ 
public native void stampExtended(Pdf pdf, Pdf pdf2, Range range, 
                                 boolean isover, 
                                 boolean scale_stamp_to_fit, int anchor, 
                                 double p1, double p2, 
                                 boolean relative_to_cropbox) 
    throws CpdfError; 
 
/** Combines the two PDFs page-by-page, putting each page of over over 
each page of under. */ 
public native Pdf combinePages(Pdf under, Pdf over) throws CpdfError; 
 
/** Adds text to the pages in the given range. 
@param metrics if <code>true</code>, only collect metrics 
@param pdf PDF document 
@param range page range 
@param text the text to stamp, including any special codes 
@param anchor position anchor, such as {@link #posCentre posCentre} 
@param p1 position parameter one 
@param p2 position parameter two 
@param linespacing line spacing 
@param bates starting bates number 
@param font font, such as {@link #timesRoman timesRoman} 
@param fontsize font size 
@param r red component of colour 
@param g green component of colour 
@param b blue component of colour 
@param underneath if <code>true</code>, text goes under page 
@param cropbox if <code>true</code>, 
relative to cropbox rather than media box 
@param outline text is outline 
@param opacity opacity 
@param justification justification, 
such as {@link #leftJustify leftJustify} 
@param midline position is relative to midline not baseline 
@param topline position is relative to topline not baseline 
@param filename file name, if requied by special code in text 
@param linewidth line width 
@param embed_fonts if true, embed fonts 
*/ 
public void addText(boolean metrics, Pdf pdf, Range range, String text, 
                    int anchor, double p1, double p2, double linespacing, 
                    int bates, int font, double fontsize, double r, 
                    double g, double b, boolean underneath, 
                    boolean cropbox, boolean outline, double opacity, 
                    int justification, boolean midline, boolean topline, 
                    String filename, double linewidth, boolean embed_fonts) 
    throws CpdfError; 
 
/** Adds text with most parameters default. 
@param pdf PDF document 
@param range page range 
@param text the text to stamp, including any special codes 
@param anchor position anchor, such as {@link #posCentre posCentre} 
@param p1 position parameter one 
@param p2 position parameter two 
@param font font, such as {@link #timesRoman timesRoman} 
@param fontsize font size 
*/ 
public void addTextSimple(Pdf pdf, Range range, String text, int anchor, 
                          double p1, double p2, int font, double fontsize) 
    throws CpdfError; 
 
/** Removes any text added by Jcpdf from the given pages. */ 
public native void removeText(Pdf pdf, Range range) throws CpdfError; 
 
/** Returns the width of a given string in the given font in thousandths of 
a point. 
@param font font, such as {@link #timesRoman timesRoman} 
@param text text*/ 
public int textWidth(int font, String text) throws CpdfError; 
 
/** Adds page content before or after the existing content to pages in the 
given range in the given PDF. 
@param s page content to add 
@param before if <code>true</code> new content goes before, else after 
@param pdf PDF document 
@param range page range */ 
public void addContent(String s, boolean before, Pdf pdf, Range range) 
    throws CpdfError; 
 
/** Stamps a PDF onto the pages in the given range in pdf as a shared Form 
XObject. The name of the newly-created XObject is returned. 
@param pdf PDF document 
@param range page range 
@param stamp_pdf PDF document to stamp */ 
public native String stampAsXObject(Pdf pdf, Range range, Pdf stamp_pdf) 
    throws CpdfError;