CIB pdf toolbox technical guide (EN)

15. Stationary function, overly of texts, graphics and barcodes

15.2. Overlay function

General
 Text
 Graphic
 Barcode
 Releaseplan
General

The overlay function for the CIB pdf toolbox allows the insertion of graphics and text at any position in PDF files. In the following, the entire range of functions is specified in more detail.

By specifying the "Overlay" property when calling PDF-Join, instructions for the overlay function can be specified. The "Overlay" property contains the following information:

  • A plane and position indication with optional size indication. For graphics, it is possible to specify their height and width, for texts this specification is omitted.
  • A font specification (for texts) with optional rotation.
  • A page selection with and without priorities.
  • Additional data, consisting alternatively of:
    • A filename.
    • A text string, which can optionally contain {PAGE}, {NUMPAGES} or {DATE} in the middle.
    • A barcode specification, starting with „BARCODE:“

 

<Overlay>:= <TextOverlay>*;<GrafikOverlay>*;<BarcodeOverlay>*

<TextOverlay>:=

POS:Plane|X-Position;Y-Position;PageReference;FONT:Font;Font-Size;Font-Style;Font-Color;[Orientation] (since Toolbox 1.2.56);Text

<GrafikOverlay>:= (since Toolbox 1.2.56) :=

POS:Plane|X-Position,Width;Y-Position,Height;PageReference;Graphic

 

<BarcodeOverlay>:= (since Toolbox 1.4.84):=

POS:Plane;X-Position;Y-Position;PageReference;BARCODE:Type;Value;Orientation;Width;Height;CheckNumber

These property specifications are specified in more detail below, divided into text, graphics and barcodes. These can be specified in the "Overlay" property as often as required, separated by ";". Please note that the keyword specification is case-sensitive.


Text

The texts specified in the "Overlay" property are placed at the desired position in the result document of the join.

The priorities are regulated here in the same way as described in the Stationery section.

The keyword POS: identifies the position part of the specification and the keyword FONT: the part containing the font information.

Name

Value

Effect

Plane

Negative number

Arrangement behind all elements that are already in the document. The smaller the number, the further back the text is inserted. (To arrange several texts in the background)

Positive Number

(including 0)

0 indicates the text that is inserted first.

The larger the number, the further ahead the text is inserted.

A positive number means that the text will be placed in front of all elements already in the document.

 

“Top”

Right in the front. If several texts are marked by "Top", they are inserted in the call sequence, i.e. the text mentioned last is placed at the very front of the document.

not specified

(The separator must still be specified).

Corresponds to „-1“

 

Note:

As separators "|" or "/" are possible.

X-Position

„Center“

Center on page in horizontal direction.

0 or not specified

Left margin

Number > 0

Distance from left in mm

Y-Position

„Center“

Center on page in vertical direction.

0 or not specified

Upper margin

Number > 0

Distance from top in mm

Font

Helvetica

Courier

Times

The font can be specified here. Possible are the Type1 standard fonts from Pdf.

Font-Size

Positive number

Half steps also possible

e.g. 3.5

Alternatively, by specifying <width>,<height> a dynamic font size is possible. (since CIB pdf toolbox 1.4.78)

Font size in pt

or width and height in mm.

 

The text is enlarged proportionally until it reaches the smaller value of width or height.

Possible rotations only take place after scaling.

 

Font-Style

bold

Text is printed bold

italic

Text is printed in italics

Font-Color

RGB code, components separated by dots. (R.G.B)

Example:

0.0.0          = Black

255.0.0     = Red

0.128.0     = Green

0.0.255     = Blue

Default: black (the separator ";" must still be specified)

The text is displayed in the specified color. The colour components must be indicated separated by dots.

Orientation

(since CIB pdf toolbox 1.2.56)

Angle > 0

The text is rotated clockwise by this angle

Page number(s)

Not specified or “All”

Distribute on all pages

“Odd”

Distribute on odd pages

“Even”

Distribute on even pages

“First”

Only on the first page

“Last”

Only on the last page

“NoFirst”

All pages except the first

“NoLast”

All pages except the last

Number1-Number2

From page Number1 to Number2

Number1-Number2,Number3, ...,NumberN-NumberM

Distribute on several pages or page areas (comma as separator)

Text

(at this time any text and {PAGE},{DATE},{NUMPAGES} is supported (without start number and number type),

since CIB pdf toolbox 1.2.56)

Any text (can also contain the following Word fields)

The specified text is inserted into the document.

If several Word fields are entered consecutively, they must be separated by at least one blank.

{PAGE \* start number \* number type}

The following values are possible for "numbertype":

Arabic = 1,2,3....

ArabicDash = -1-,-2-,-3-...

alphabetic = a,b,c....

ALPHABETIC = A,B,C…

roman = i,ii,iii….

ROMAN = I,II,III....

Inserts the current page number, the options allow you to specify start number and type of numbering.

{NUMPAGES \*numbertype}

Inserts the number of pages in the document.

{DATE \@ dd.MM.yyyy hh:mm:ss}

Inserts the current date in the desired format.


Note on the page numbers

The page specifications have different priorities, so that lower priorities can be overwritten by higher ones. The priorities are distributed as follows:

Priority None: All, Odd, Even, NoLast, NoFirst

Priority DIRECT: Last, First, Number

Priority RANGE: Number1 – Number2

The following order of priority applies: Priority None < RANGE < DIRECT

 

If two indications concerning a particular page have the same priority, both apply, otherwise the one with the higher priority applies and the lower priority indication is not applied.


Examples

The examples show possible calls via the CIB runshell.

The command line of the examples reads as follows:

  1. Property Overlay
  2. Runshellcommand PDF-Join = cibrsh.exe –fj
  3. input output

  • cibrsh.exe Overlay=“POS:-1|Center;20;All;FONT:Helvetica;12;bold;0.0.0;;Infoblatt” –fj inhalt.pdf output.pdf

Here the text "Info sheet" is inserted on the backmost level (-1), centered in horizontal direction (Center), 2 cm from the top edge (20), in Helvetica font and font size 12, bold, on all pages (All) of the document content.pdf with the font color black. The result is returned in output.pdf.

  • cibrsh.exe Overlay=“POS:Top|180;280;All;FONT:Helvetica;10;italic;255.0.0;;{PAGE}“–fj  inhalt.pdf output.pdf

Here, on the front level (Top) 18 cm from the left and 28 cm from the top in Helvetica font and font size 10 italics, the current page number is inserted on each page of the document input.pdf in Arabic with font colour red (1,2,3...).  The result is returned in output.pdf.

  • cibrsh.exe Overlay=“

POS:2|20;20;First,Last;FONT:Helvetica;24;;0.0.255;;TextVorn;

POS:1|30;30;First,Last;FONT:Helvetica;24;;255.0.0;;TextMitte;

POS:0|40;40;First,Last;FONT:Helvetica;24;;0.128.0;;TextHinten;

“ –fj inhalt.pdf output.pdf

 

Here, first 4cm left and right from the edge are removed, the text " TextBack" is inserted in Helvetica font and font size 24 with font color green on the first and last page of the document input.pdf.

Before this (1) 3cm from both edges are removed. The text "TextMiddle" with font colour red and again in front of (2) 2cm from the edge "TextFront" "with font colour blue is inserted. This allows the effect that several texts are written offset one above the other.  The result is returned in output.pdf.


Graphic

This functionality is supported since Toolbox 1.2.56. The formats allowed so far are bmp, jpg, gif and png.

The graphics specified in the "Overlay" property are placed at the desired position in the result document of the join.

The priorities are regulated here in the same way as described in the Stationery section.

The "Overlay" property is assigned as follows:

[POS:Layer|X-Position,Width;Y-Position,Height;]Page Specifications;Graphic

 

Name

Value

Effect

Layer

Same as Text

 

 

X-Position

Same as Text

 

 

Width

“ScaleToPage”

Adjust to page width.

0 or not specified

Original width of the graphic(1 pixel=1 pt=1/72in)

Number > 0

Width of the graphic in mm.

Y-Position

Same as Text

 

 

Height

“ScaleToPage”

Auf Adjust to page height.

0 or not specified

Original height of the graphic(1 pixel=1 pt=1/72in)

Number > 0

Height of the graphic in mm.

Page number(s)

Same as Text

 

 

Graphic

Path to graphic file

The graphic from this file is inserted

(since version 1.4.83)

MEMORYBLOCK: <memoryblock-Delimiter>;<memoryblocks>

 <memoryblocks> ::=
<memoryblock> [<memoryblock-Delimiter> <memoryblock>]...

memoryblock::=
<Adress> <memoryblock-Delimiter> <Länge>

The graphic can also be transferred in memory. For this purpose the memory addresses are transferred to the CIB pdf toolbox.

A <memory block delimiter> is a single character unequal to ";", which if possible does not occur in a file name, e.g. "#", "?".

Address and length are decimal numbers.

Instead of a file name, you can specify that a colored rectangle, line or Bezier curve is to be placed at the specified location. The file name must then be replaced as follows:

RECT:Color[;Orientation;Transparency]

LINETO:Color;X2,Y2

BEZIERTO:Color;SX1,SY1,SX2,SY2,X2,Y2

Lines and Bezier curves have no width and height indication. They cannot be centered using the "Center" value for X and Y position. The specification of this value is interpreted as "-1".

Name

Value

Effect

RECT: Color

(since CIB pdf toolbox 1.2.56)

LINETO: Color

BEZIERTO: Color

(since CIB pdf toolbox 1.4.75)

RGB code, components separated by dots. [R.G.B.]

Examples:

0.0.0  = black

255.0.0 = red

0.128.0 = green

0.0.255  = blue

The rectangle or line or Bezier curve is displayed in the specified color. The colour components are to be indicated separated by dots.

Orientation

> 0

Rectangle is rotated clockwise by the specified angle.

Transparency

> 0

Degree of transparency for the rectangle

Example: 75 means that the rectangle is 75% transparent.

A transparency of 100% means that the rectangle becomes invisible.

X2

(X coordinate for the end point of the line or Bezier curve))

0

Left margin

 

Number > 0

Distance from left in mm.

Y2

(Y-coordinate for the end point of the line or Bezier curve)

0

Upper edge.

 

Number > 0

Distance from top in mm.

SX1, SX2

(X-coordinates for the first and second point of the Bezier curve)

0

Left edge.

 

Number > 0

Distance from left in mm.

SY1, SY2

(Y-coordinates for the first and second point of the Bezier curve)

0

Upper edge.

 

Number > 0

Distance from top in mm.


Examples

The examples show possible calls via the CIB runshell.

The command line of the examples reads as follows:

  1. Property Overlay
  2. Runshellkommando PDF-Join = cibrsh.exe –fj
  3. input output

1)     cibrsh.exe Overlay=“POS:-1|Center,100;Center,100;Odd;Graphic.jpg“ –fj content.pdf output.pdf

Here, on the backmost level (-1), centered in X-direction and Y-direction (Center), the image Graphic.pdf is inserted on all odd pages (Odd) of the document content.pdf. This will be scaled to the dimensions 10x10 cm. The result is returned in output.pdf.

2)     cibrsh.exe Overlay=“POS:Top|20,0;Center,0;2-8;Graphic.jpg“ –fj content.pdf output.pdf

Here, the image Graphic.jpg in original size is inserted on the front level (Top) 2 cm from the left and centered in Y-direction on pages 2-8 of the document Input.pdf The result is returned in output.pdf.cibrsh.exe Overlay=“POS:Top|Center,ScaleToPage;Center,ScaleToPage;First;Grafik.jpg“ –fj inhalt.pdf output.pdf

Here, the image Graphic.jpg is inserted on the top level (Top), page-centered in both X and Y direction, on the first page of the document input.pdf. The image is scaled to the dimensions of the page. The result is returned in output.pdf.

3)     cibrsh.exe Overlay=“POS: Top|180,10;280,10;All;RECT: 255.255.255;POS:Top|180;280;All;FONT:Helvetica;10;italic;0.0.0;;{PAGE}“ –fj content.pdf output.pdf

Here, a white rectangle measuring 1cm x 1cm is first inserted on the front level (top) 18 cm from the left and 28 cm from the top. Then, in Helvetica font and font size 10 italics, the current page number is inserted in Arabic at this point on each page of the document input.pdf (1,2,3...) The result is returned in output.pdf.

4)     cibrsh.exe Overlay=“POS:Top|0;0;All;LINETO: 255.0.0;210,297;“ –fj content.pdf output.pdf 

Here, a red line is inserted at the front level (Top) from the upper left edge (0.0) to the lower right edge (210.297). The result is returned in output.pdf.

5)     cibrsh.exe Overlay=“ POS:Top|0;150;All;BEZIERTO: 255.255.255;100,60,150,110,210,150“ –fj content.pdf output.pdf

Here, a red Bezier curve with a starting point (0,150), end point (210,150) and the support points (100,60) and (150,110) is inserted at the front level (Top). The result is returned in output.pdf.


Barcode

(since CIB pdf toolbox Release 1.4.84)

The barcodes specified in the "Overlay" property are placed at the desired position in the result document of the join.

The priorities are regulated here in the same way as described in the Stationery section

The "Overlay" property is assigned as follows:

[POS:Level|X-Position;Y-Position;] PageReferences;BARCODE:Type;Value;Orientation;Width;Height;CheckDigit;CodePage

QR [POS:Level|X-Position;Y-Position;] PageReferences;BARCODE:QR;Type;Value;Orientation;Width;Height;CheckDigit;CodePage;CorrectionLevel

Name

Value

Effect

Level

Same as Text

 

 

X-Position

Same as Text

 

 

Y-Position

Same as Text

 

 

Pagenumber(s)

Same as Text

 

 

Type

A barcode type from the set of types supported by CIB format:

 

Code ITF

Code 2/5 Industry

Code 2/5 Matrix

Code 39

Code 39 extended

Code 128 (A, B, C)

EAN 8

EAN 13

EAN 128

DataMatrix

PDF417

Code 93

Code 93 Extended

OMR Barcodes

QR

This barcode type is used

Value

Numbers

The individual value that the barcode should represent.

Orientation

horizontalleft

Vertical lines side by side, first character left.

 

horizontalright

Vertical lines side by side, first character on the right.

verticalleft

Horizontal lines below each other, first character on top.

verticalright

Horizontal lines above each other, first character below.

Width

Line width in mm

(x.xmm; or x,xmm both allowed)

Sets the bar width of the barcode

Height

Height of the barcode bars in mm

(x.xmm; or x,xmm both allowed)

Sets the height of the barcode bars

Check digit / CorrectionLevel

 

(since version 1.26.0)

default

Barcode is generated with check digit

nochecksum

Barcode is generated without check digit

The check digit is not available for 2D barcodes (QR).

The default is therefore nochecksum.

However, the correction level (ECL) can be specified here.

The level goes from 0 (low correction) to 3 (maximum correction = default).

 

Codepage

Specifies code page for QR barcode data.

Default: Ansi;

Possible Values:

  • Ascii
  • Pca
  • Ansi
  • CodePageMac
  • CodePagePc
  • CodePagePdf
  • CodePage932ShiftJIS
  • CodePage949Hangul
  • CodePage936GB2312
  • CodePage950ChineseBIG5
  • CodePage1255Hebrew
  • CodePage1256Arabic
  • CodePage1253Greek
  • CodePage1254Turkish
  • CodePage1258Vietnamese
  • CodePage874Thai
  • CodePage1250EastEurope
  • CodePage1251Cyrillic
  • CodePage1257Baltic
  • CodePageUnicode
  • CodePageIdentity
  • CodePage1252Latin1
  • CodePageUtf8

Note:
If "CodePageUtf8" was used, missing BOM (byte order marker) is added at the beginning of the incoming barcode data.

Size

(since version 1.26.0)

QR Code: The size has not been used so far.

Now the version can be specified here.

The size of the QR Code is determined by the version.

Example:
Version 13 implies a size of 69x69


For the assignment of the parameters after "value", please refer to the corresponding documentation regarding barcode realization in CIB format. Which parameters must be assigned which value depends strongly on the barcode type.


Releaseplan

The overlay function is implemented in several stages. The functionality must be implemented according to the following step plan:

  • Specification of the Word mail merge field {PAGE} with default option Arabic, possibility to specify font, size, color and position of the text itself.
  • Logos without rotation.
  • arbitrary text with rotation.
  • Support for other fields (like {NUMPAGES} or {DATE} with options anywhere in the text.
  • Barcode support.

It must be examined to what extent the layer function can be used or supported. Please note that this is not included in PDF 1.3 and is not supported by older viewers.

Since Toolbox 1.2.56, overlay of text (including rotation), graphics and rectangles are supported.