Introduction

A stamp item begins with the Begin_Message and ends with the End_Message keywords. Each stamp file can have many stamp items. Each text stamp item uses various parameters for the text item. Each parameter will be described in detail below.

The table below summarizes all the parameters available for stamp items.

Type	Parameter	Text	Image	Default	Comments
Begin	Begin_Message	✔	✔		Start of stamp item
Label	Name	✔	✔		Name for stamp
	UndoLabel	✔	✔		Permits the later removal of a stamp
	Type	✔	✔		Required: Stamp Type; Text, UTF8, UTF16, Barcode, Image or PDF
Pagination	StartPage	✔	✔	1	Start page for stamp
	EndPage	✔	✔	-1	End page for stamp
	PageIncrement	✔	✔	1	How many pages to skip between stamps
	PageRange	✔	✔	all	Which individual pages to stamp
Positioning	Top, Right	✔		From options block	Margins for stamp.  Overrides margins of the page boundaries set in the options block for the stamp item.
	Bottom, Left	✔	✔
	Position	✔	✔	Top	Position and orientation on page
	Justification	✔	✔	Center	Left, right or center
	Angle	✔		0	Angle to rotate text stamp
	Underlay	✔	✔	No	Above (no) or beneath (yes) existing text/images
	PageBox	✔	✔	Cropbox	Sets which set of page boundaries are used to position the stamp
	OffsetX	✔	✔		Horizontal placement offset
	OffsetY	✔	✔		Vertical placement offset
Text Options	Size	✔		12	Font size in points
	Font	✔		Helvetica-Bold	Name of font
	FontFile	✔			Location of font file, if necessary
	TextMode	✔		0	Mode: solid (0), outline (1) or invisible (2)
	Text	✔			Text to stamp
	WordWrap	✔		No	Insert line breaks to fit text within margins
	CharSpace, WordSpace	✔		0	Change spacing between characters and words
	LineSpace	✔		1	Change spacing between lines
	ColorSpace	✔		DeviceGray	DeviceGray, DeviceRGB or Device CMYK
	Gray	✔		0	DeviceGray: Gray level (0–100)
	Red,Green,Blue	✔		0,0,0,	DeviceRGB: RGB color values (0–255)
	Cyan,Magenta,Yellow,Black	✔		1,1,1,1	DeviceCMYK: CMYK color values (0–1)
	BatesDigit	✔		0	Number of digits in Bates number
	Opacity	✔		1	Transparency of text; 0–1
	LinkURL	✔			Specify URL link to be placed over the stamped text
	AutoScale	✔			Scale stamp to fit on a page regardless of page size
Image Options	Path		✔		Location of image file
	Scale		✔		Specify size of image
	PageNumber		✔		The page of a PDF to be stamped, only Type (PDF)
End	End_Message	✔	✔		End of stamp

Stamp parameters — detailed description

A stamp item begins with the Begin_Message and ends with the End_Message keywords. Each stamp file can have many stamp items. Each parameter will be described in detail below.

Label parameters

Name (optional)

Name identifies the stamp item. The Name parameter will help you keep track of many stamp items in one stamp file.

UndoLabel (optional)

UndoLabel allows you to remove the stamp later. UndoLabel can be any character string, such as:

UndoLabel (undostamp)

Avoid using the characters \ / : * ? ” < > | ^ and &. These characters cause problems when used on the command line. The UndoLabel is case sensitive.

A stamp created with an UndoLabel can be removed via the command line using the -u option. Using the command line and command line options are covered in Using StampPDF Batch. The command for undoing a stamp is:

stamppdf -u undostamp Sample1.pdf

After running this command, any stamp that has the UndoLabel of “undostamp” in its stamp item will be removed from the document. Many stamps can have the same UndoLabel in their stamp item; they will all be removed at the same time. For example, if you would like to have all stamps removed with one command, use the same UndoLabel for all of them.

If a stamp item does not have an UndoLabel specified in the stamp file, you will not be able to remove it later. So if you are not sure, it’s always good to specify an UndoLabel and keep a record.

Type (required)

The type of stamp you will be making. Text stamps can be plain text or Unicode. Image stamps can be JPEG, TIFF or PDF. Specify Barcode to stamp barcodes.

Specify the type of stamp using the following:

• Type (Text) for stamping plain text into your document
• Type (UTF8) for stamping UTF-8 Unicode characters into your document
• Type (UTF16) for stamping UTF-16 Unicode characters into your document
• Type (Barcode) for stamping code 128 barcodes
• Type (Image) for stamping JPEG or TIFF images onto your documents
• Type (PDF) for stamping PDF images onto your documents

For more information about Unicode stamps, see Using Unicode. For more information on stamping images or PDF files, see Creating Stamp Items for Image Stamps. For more information on stamping barcodes, see Stamping Barcodes.

Pagination parameters

StartPage (optional)

StartPage specifies the first page to be stamped. Enter any page number or use -1 which is a shorthand notation for the last page. If you would like stamping to begin on the second page, enter 2 for StartPage. If you would like stamping to begin on the fifth page, enter 5 for StartPage. StartPage is optional; if StartPage is omitted, stamping will begin on page 1.

EndPage (optional)

EndPage specifies the last page to be stamped. For example, if you have a stamp that you need applied only to pages 2 through 10, use StartPage (2) and EndPage (10).
If you wish to stamp to the end of the document, then EndPage can be set to (-1).  The (-1) is a notation for the last page of the document.

EndPage is optional; if EndPage is omitted, stamping will continue to the end of the file.

PageIncrement (optional)

PageIncrement specifies the increment to place stamps, i.e., on every other page, every fifth page, every tenth page, etc. For example, a PageIncrement of…

• 1 stamps every page
• 2 stamps every other page
• 5 stamps every fifth page

Page increments begin with the StartPage you specified. You can coordinate these parameters to stamp even pages, odd pages, or other increments of pages that you choose.

PageIncrement is optional; if PageIncrement is omitted, every page between StartPage and EndPage will be stamped.

The following table shows how the StartPage and PageIncrement parameters can be used together for stamping selected pages in a document:

StartPage	PageIncrement	stamps pages
1	1	1,2,3,4,5,etc.
1	2	1,3,5,7,9,etc.
2	2	2,4,6,8,10,etc.
1	5	1,6,11,16,21,etc.
5	5	5,10,15,20,25,etc.

You can apply different stamps on alternating pages, for example, to have the footer on even pages to be left-aligned, and on odd pages, right-aligned. You need two separate stamp items to achieve this: one with the left-aligned formatting and one with the right-aligned formatting. See the example below.

PageRange (optional)

PageRange lets you specify individual pages to stamp. PageRange overrides any range specified by StartPage, EndPage, and PageIncrement. To specify individual pages to stamp, list them separated by commas:

PageRange (1,3,6,8)

will stamp pages 1, 3, 6 and 8.

Positioning parameters

Position (optional)

Position specifies where on the page the stamp item will appear. Position is optional. If Position is omitted, the stamp will be applied to the top. The figure below illustrates how various positions for stamps appear on pages. Allowed values are:

• Top, stamps text horizontally across the top of the page
• Diag-BottomLeft, stamps text diagonally, corner to corner, across the page beginning at the bottom left corner margin
• Diag-TopLeft, stamps text diagonally, corner to corner, across the page beginning at the top left corner margin
• BottomUp-Left, draw text up from the bottom, on the left edge of the page
• BottomUp-Right, draw text up from the bottom, on the right edge of the page
• TopDown-Left, draw text down from the top, on the left edge of the page
• TopDown-Right, draw text down from the top, on the right edge of the page
• Bottom, stamps text horizontally across the bottom of the page
• VCenter, stamps text at the precise vertical center of the document, as defined by the margin settings. Horizontal positioning must still be defined by other parameters
• Angle, used with the Angle parameter described below, which will stamp text at any angle. Position must be set to Angle for the Angle parameter to work.

Justification (optional)

Justification specifies text alignment on document pages. Justification is optional. If Justification is omitted, the text will be centered. The figure below illustrates how stamps display on pages using various values. Possible values are:

• Left, aligns text with the left margin of the document.
• Right, aligns text with the right margin of the document.
• Center, horizontally centers text between the left and right margins. Diagonal text stamps that use centering will also be centered vertically in the space between the top and bottom margins.

Use this parameter with Position, described above, to create accurate placement of your stamp.

Angle (optional)

Angle specifies an angle for stamp positioning, in degrees. Angle is optional. If Angle is omitted, text will be stamped horizontally. While a diagonal stamp will angle text on the page diagonal, the Angle parameter can position a text stamp at any angle. In order for the Angle parameter to be read, the Position parameter described above must be set to Angle.

The pivot point for an angle is defined by the Bottom and Left parameters. Justification for Angle is always Left. Any other value set for Justification will be ignored. Angle takes as its input any positive or negative number.

Underlay (optional)

Underlay specifies whether to stamp under, or on top of, existing text and graphics of the input PDF document. The figure below illustrates how stamps will appear on pages. Underlay is optional. If Underlay is omitted, text will be stamped over existing text and graphics. The options are:

• Yes, stamps text underneath the PDF document text and graphics.
• No, stamps text on top of the PDF document text and graphics.

Notes on using the Underlay option

Set Underlay to Yes to prevent covering the original PDF content. Other options for not obscuring original text are outline text, TextMode (1) or transparent text, Opacity (0.5).

• If the color of the text you stamp is the same color as the text in the document, your stamp will obscure the document text. To avoid this, specify gray or a different color to make the stamp stand out from the overlaid text.
• Underlaid text stamped on PDF documents that are scanned as image files will not be visible. For these types of documents use an overlaid stamp, set Underlay to No.
• Some PDF files contain hidden text and images. Underlaid text will not be visible under hidden images. If you encounter this, overlay the stamped text, and use outline text, TextMode (1) or transparent text, Opacity (0.5).
• Under some circumstances, the combination of the printer driver and the application used to create the PDF document will create a white rectangle behind the PDF text. An underlying stamp will be hidden by the body of the PDF text and images. If you encounter this situation, create an overlay text stamp, and use outline text, TextMode (1) or transparent text, Opacity (0.5).

Top, Bottom, Left, and Right Margins (optional)

Top, Bottom, Left and Right parameters specify the margins used for the stamp item that override the page boundary margins set in the options block. These parameters define a rectangle in which to place a stamp. The Position and Justification parameters work relative to this new rectangle, rather than the margins set in the options block for that stamp item. See the figures below:

If you do not want to modify all of the margins, only set the ones you want changed. If you leave out one of the parameters, that margin remains as set in the options block.

Top, Bottom, Left and Right are optional; if any are omitted, the corresponding value from the options block will define the margin.

PageBox (optional)

This parameter sets which set of page boundaries are used to position the stamp. The options available for the PageBox parameter are mediabox, cropbox, artbox, trimbox and bleedbox. If the document you are stamping is cropped, set the PageBox parameter to cropbox.

Default value: cropbox

OffsetX (optional)

The OffsetX parameter allows you to specify a precise horizontal offset for a stamp item. The value of the offset is given in points, and can be positive or negative.  A positive value of OffsetX will move the stamp to the right; a negative value will move the stamp to the left.

If you have a left-justified stamp with OffsetX set to 36 and LeftMargin set to 60, the image would be stamped 96 points from the left edge of the document: 60 points for the LeftMargin plus 36 points for the X offset.

OffsetX (36)

If you have a left-justified stamp with OffsetX set to -36 and LeftMargin set to 60, the image would be stamped 24 points from the left edge of the document: 60 points for the LeftMargin plus -36 points for the X offset.

OffsetX (-36)

OffsetY (optional)

The OffsetY parameter allows you to specify a precise vertical offset for a stamp item.  The value of the offset is given in points and can be positive or negative. A positive value of OffsetY will move the stamp up; a negative value will move the stamp down. If you have a bottom-positioned stamp with OffsetY set to 20 and BottomMargin set to 72, the image would be stamped 92 points from the bottom edge of the document: 72 points for the BottomMargin plus 20 points for the Y offset.

OffsetY (20)

If you have a bottom-positioned stamp with OffsetY set to -20 and BottomMargin set to 72, the image would be stamped 52 points from the bottom edge of the document: 72 points for the BottomMargin plus -20 points for the Y offset.

OffsetY (-20)

Using a combination of OffsetX and OffsetY with Position and Justification parameters lets you place text and images very precisely in the document. See the figure below for examples of using these parameters.

As an example, a text stamp can be placed with a negative number of points to the left of the right margin of the stamp item when Justification has been set to Right. See Position (optional) and Justification (optional) for more detailed information.

#Options	Comment – Beginning of Stamp file
Begin_Options	Begin Options
Version (2)	Version Number
TopMargin (0)	Page – Top Margin
BottomMargin (0)	Page – Bottom Margin
LeftMargin (0)	Page – Left Margin
RightMargin (0)	Page – Right Margin
End_Options	End Options
# — Stamp Item —	Comment
Begin_Message	Begin Stamp Item
Name (Top Left)	Named Top Left
PageIncrement (1)	Stamp every page
StartPage (1)	Start on first page
EndPage (-1)	Stamp to the last page
Type (Image)	Image stamp
Path (./appligent_logo.jpg)	Path to image to be stamped
Position (top)	Position stamp at top
Justification (left)	Left justify
Underlay (no)	Place it over existing text and graphics
OffsetX (36)	X axis Offset
OffsetY (-36)	Y axis Offset
End_Message	End stamp item

 

The figure below shows the upper left hand corner of a file stamped with the stamp item parameters from the figure above. The page margins are all set to 0; without the offsets, both the text and image would be placed on the top-left edge of the page.

Text Options parameters

Size (optional)

Size specifies the point size of the font that you are stamping. Fractional point sizes are allowed, for example, 11.5. Size is optional. If you omit this option, text will be stamped 12 points. To help decide on a point size for your text stamp, most text you read is 10 or 12 points. Newspaper text, for example, is usually 10 points. Business letters are commonly done in 12 points.

To create a watermark that fills a whole letter-sized page diagonally, select a large point size: “Confidential” stamped in 128 points fills an 8 1/2 x11 inch page diagonally.

Font (optional)

Font specifies the name of the font to use. Font is optional. If Font is omitted, stamping will be done in Helvetica Bold.

There are four types of fonts StampPDF Batch can use:

• OpenType fonts
• TrueType fonts
• Postscript Type 1 fonts
• One of the PDF base 14 fonts

Metrics for the base 14 fonts are included with StampPDF Batch. The names of the base 14 fonts are:

•    Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique
•    Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique
•    Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
•    Symbol
•    Zapf Dingbats

Use the –listfonts command to see a list of all font names available for stamping. The font name should be used exactly as it is shown in the font list.

FontFile (deprecated)

The FontFile parameter has been deprecated. To use a non-base14 font with StampPDF Batch, add the font to one of the font directories and specify the font name in the Stamp Item FontName ( ) parameter as specified in Using Fonts. Any FontFile parameter entries will be ignored. If you are currently using the FontFile parameter in any of your stamp files, check that the font name being used in the stamp item is correct. Previous versions of StampPDF Batch would allow the specified font file to override the FontName; currently the FontName has priority.

Notes on fonts

StampPDF Batch also supports the use of barcode fonts and OCR fonts (Optical Character Recognition) for use with scanning documents. Use these fonts in the same way as any other font.

You can only use one font per stamp. However, if you would like to use two (or more) fonts and have them appear as the same stamp, make a separate stamp item for each font. For each item use the same position for the stamp, but insert spaces (not tabs) in the Text parameter of each stamp as placeholders for the characters in the other stamp so the two items do not overlap. For example, to create a stamp that has both Helvetica and Symbol characters, have one item stamping Helvetica and one stamping Symbol. The Font and Text parameters are:

Item 1:

Font (Helvetica)
Text (The circumference of a circle is 2    r.)

Item 2:

Font (Symbol)
OffsetX (176)
Text (                                   p)

The resulting stamp will look like this:

The circumference of a circle is 2πr.

TextMode (optional)

TextMode specifies stamp text as an outline, solid, or invisible. TextMode is optional; if TextMode is omitted, text will be solid. TextMode has three options:

• 0 stamps text as solid characters.
• 1 stamps text as outlined characters.
• 3 stamps invisible text.

The figure below illustrates the use of the TextMode parameter values.

Invisible text can be a useful aid for searching through a document. Acrobat’s Text Tool can highlight invisible text, showing its location in a PDF document. However, you won’t be able to see the text and it will not appear in the printed document.

Text (required)

Text specifies the content of the stamp. Type text exactly as you want it to appear. The figure below illustrates using the Text parameter.

With the Text parameter you can use variables to stamp dynamic information, such as the date and time of stamping or page numbers in a variety of formats. See Using variables in stamp files for more information.

WordWrap (optional)

WordWrap specifies whether long lines of text should wrap. WordWrap is optional. If WordWrap is omitted, any lines too long will be cut off. There are two possible values for WordWrap:

• Yes, if a line of text is too long to fit between the margins specified, it will continue on subsequent lines.
• No, if a line of text is too long to fit between the margins specified, it will be cut off at the edge of the margin.

CharSpace and WordSpace (optional)

CharSpace adjusts character spacing and WordSpace adjusts word spacing. Enter a positive real number with up to three digits following the decimal point. A positive value (greater than 0) will increase the spacing; a negative value (less than 0) will decrease the spacing. Default value is 0, no change in spacing.

LineSpace (optional)

LineSpace adjusts line spacing for multiple lines. Enter a positive real number with up to three digits following the decimal point. A value between 0 and 1 will decrease the line spacing; a value greater than 1 will increase the line spacing.  LineSpace (2) will stamp multiple lines as doublespace.

Default value is 1, no change in linespacing.

BatesDigit (optional)

BatesDigit is used to specify the number of Bates digits for a stamp item containing a Bates stamp variable (%J or %C).  If BatesDigit is set to 3, page 2 will be stamped as 002, a BatesDigit of 5 will stamp 00002. See Using Bates notation for page numbering for information about Bates numbering.

ColorSpace (optional)

ColorSpace specifies the text as grayscale or color. ColorSpace is optional; if ColorSpace is omitted, stamping will be done in DeviceGray. Specify the color of the stamp as follows:

• DeviceGray, a shade of gray. Use the Color parameter to specify the level of gray.
• DeviceRGB, a combination of Red, Green, and Blue values. Use the Red, Green, and Blue parameters to specify the color. This is common for on-line viewing.
• DeviceCMYK, a combination of Cyan, Magenta, Yellow, and Black values. Use the Cyan, Magenta, Yellow, and Black parameters to specify the color. This is common for print documents.

ColorSpace does not specify the color, only the type of color. You need to specify the color as described below.

Gray used with ColorSpace (DeviceGray)  (optional)

Use Gray if your ColorSpace is DeviceGray. Gray is optional. If Gray is omitted, the stamped text will be black. Gray specifies a shade of gray, use a value between 0 and 100, where 0 is black and 100 is white. A Gray of 95 is a very light gray, and a Gray of 15 is a dark gray.

Gray (15)

The Color parameter used in previous versions of StampPDF Batch is supported for backward compatibility.

Red, Green, and Blue used with ColorSpace (DeviceRGB) (optional)

Use Red, Green, and Blue if your ColorSpace is DeviceRGB. Red, Green, and Blue are optional. If they are omitted, the text will be stamped black. The values for these colors can be in the range of 0–255, where 0 represents none of the color and 255 represents 100% of the color. You can combine varying amounts of the three color components to generate virtually any color. Here are some examples:

To create a purple stamp enter the following values for the color components:

Red (102)
Green (51)
Blue (204)

To create a green stamp enter:

Red (0)
Green (150)
Blue (0)

By not specifying the full 255 of green, a value of 150 will generate a lighter shade of green.

You must include values for each color: Red, Green, and Blue. Use a setting of 0 for colors you do not want.

Cyan, Magenta, Yellow, and Black used with ColorSpace (DeviceCMYK) (optional)

Use Cyan, Magenta, Yellow, and Black if your ColorSpace is DeviceCMYK. Cyan, Magenta, Yellow, and Black are optional. If they are omitted, the text will be stamped black. The values for these colors can be in the range of 0–1, where 0 represents none of the color and 1 represents 100% of the color. You can combine varying amounts of the four color components to generate virtually any color. Here are some basic examples:

To create the same color purple stamp enter the following values for the color components:

Cyan (0.63)
Magenta (0.76)
Yellow (0)
Black (0)

To create a yellow stamp enter:

Cyan (0)
Magenta (0)
Yellow (0.5)
Black (0)

By not specifying the full 1 of Yellow, a value of 0.5 will generate a lighter shade of yellow.

You must include values for each color: Cyan, Magenta, Yellow, and Black. Use a setting of 0 for colors you do not want.

Notes on Color: RGB vs. CMYK

If you’re not familiar with color spaces, you may be confused by the differences in the way colors are specified in RGB or CMYK.

RGB is a color space for televisions and computer monitors. Color is created by mixing red, green, and blue light. The maximum values result in white light. Since computer monitors are digital, RGB levels are specified in a four-bit word, from 0 to 255.

CMYK is a color space for printing. Color is created by mixing cyan, magenta, yellow, and black inks. The maximum values result in black ink. Ink levels are specified in percentages, from 0 to 1.

Notes on Color: How to select colors using RGB or CMYK components

Online, Visibone Webmaster’s Color Lab have tools to help you select a color. When you select a color that you like, the code for that color is given in RGB (Red, Green, Blue), CMYK (Cyan, Magenta, Yellow, and Black), and/or hexadecimal (used in HTML for web pages). Copy the RGB or CMYK values given and enter them into the corresponding parameters in the stamp file. You may also have software already installed on your computer that will help you design colors by accepting different values for color and displaying the results.

The values for RGB must be integers in the range 0–255. If you find colors defined as percentages, convert them to the 0–255 range. For example, 25% Red is 0.25 × 255 = 64. The values for CMYK must be in the range 0–1. If you find the colors defined as percentages, convert to decimal equivalent. For example 52% Cyan is 0.52.

Opacity (optional)

Opacity specifies the transparency of the text. Values range from 0 to 1, where 0 is completely transparent (invisible) and 1 is completely opaque. Opacity allows you to place a stamp over existing text or graphics without completely obscuring the original. As an example, for a watermark that says “Draft” or “Confidential” and is a medium transparency use the following line in the stamp item:

Opacity (0.3)

LinkURL (optional)

The LinkURL parameter specifies a URL link to be associated with a text stamp.  Example below:

LinkURL (http://www.some_company.com/link_to_somewhere)

Note: If you wish to apply a LinkURL to a JPEG or TIFF image, you must create two stamp items in your stamp file. The first stamp item must be the image and the second stamp item must be the LinkURL you wish to stamp on the image.

AutoScale (optional)

This parameter will automatically scale your stamp to fit on the page without having to set any other options such as Page Margins.  The value for AutoScale specifies the font size as a percentage of the larger dimension of the page size (example: if your document is 8 1/2 x 11, with AutoScale set to (3), the stamp would be set at 3% of 11 inches. By using the AutoScale parameter in your stamp items, you will be able to apply the same stamp across multiple files regardless of their page size.

A sample text stamp

The figure below shows the stamp item in letterstamp.txt to place a watermark looks like this:

# — Stamp Item —	Comment
Begin_Message	Begin Stamp Item
Name (Watermark)	Named Watermark
Type (Text)	Text stamp
StartPage (1)	Start on page 1
EndPage (-1)	Stamp to the last page
PageIncrement (1)	Stamp every page
Position (diag-topleft)	Position diagonally from the top left corner
Justification (center)	Center it both vertically and horizontally on the page
Underlay (yes)	Place it underneath existing text and graphics
Size (84)	Text size is 84 points
Font (Helvetica Bold)	Font is Helvetica Bold
TextMode (1)	Text will be an outline
Text (Confidential)	Text says “Confidential”
WordWrap (no)	Do not wrap to a new line
Opacity (1)	Text will be opaque
Gray (50)	Medium gray color
PageBox  (CropBox)	Use CropBox to set page boundaries to position the stamp
UndoLabel (undoStamp)	Name of the undo label to remove stamps
End_Message	End Stamp Item