| 1 |
<?xml version="1.0" encoding="utf-8"?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml"> |
| 4 |
|
| 5 |
<head> |
| 6 |
<title>PodofoImpose - some words</title> |
| 7 |
<meta name="AUTHOR" content="Pierre Marchand"/> |
| 8 |
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> |
| 9 |
<style type="text/css"> |
| 10 |
body{ |
| 11 |
width:360pt; |
| 12 |
margin:auto; |
| 13 |
font-family:sans-serif; |
| 14 |
font-size:11.2pt; |
| 15 |
} |
| 16 |
.section{ |
| 17 |
/* background-color:#ddd; */ |
| 18 |
border-left:1pt solid #333; |
| 19 |
padding-left:12pt; |
| 20 |
|
| 21 |
} |
| 22 |
.code-abs{ |
| 23 |
font-family:mono; |
| 24 |
font-weight:bold; |
| 25 |
font-size:9pt; |
| 26 |
background-color:#eee; |
| 27 |
color:#222; |
| 28 |
} |
| 29 |
.command{ |
| 30 |
font-family:monospace; |
| 31 |
font-size:9pt; |
| 32 |
background-color:#222; |
| 33 |
color:#eee; |
| 34 |
padding:6pt; |
| 35 |
} |
| 36 |
.file{ |
| 37 |
border:1pt dotted black; |
| 38 |
width:90%; |
| 39 |
margin:12pt auto; |
| 40 |
} |
| 41 |
.file .name{ |
| 42 |
text-align:right; |
| 43 |
font-family:monospace; |
| 44 |
font-weight:bold; |
| 45 |
font-size:8pt; |
| 46 |
background-color:#eee; |
| 47 |
} |
| 48 |
.file .content{ |
| 49 |
margin:0; |
| 50 |
padding:0; |
| 51 |
border:0; |
| 52 |
white-space:pre; |
| 53 |
} |
| 54 |
</style> |
| 55 |
</head> |
| 56 |
<body> |
| 57 |
<h2>PodofoImpose</h2> |
| 58 |
<div id="intro">PodofoImpose is a utility program which aims to provide a rather simple way to impose PDF documents. Originally written for my own use, it ended up in PoDoFo release as a show-case (don’t rely too much on it). |
| 59 |
</div> |
| 60 |
|
| 61 |
<h3>Plan (built-in)</h3> |
| 62 |
<div class="section"><!-- Plan own --> |
| 63 |
PodofoImpose is driven by a PLAN file. This file describes how pages from a source PDF document have to be relayout into a target document. We’ll describe how this file must be formatted. |
| 64 |
<h4>Records</h4> |
| 65 |
<div> |
| 66 |
Most of the PLAN file is composed of record lines of the form: |
| 67 |
<div class="code-abs"> |
| 68 |
source page; target page; rotation; horizontal translation; vertical translation; |
| 69 |
</div> |
| 70 |
Each element of the record can be a numeric value, a constant or an expression involving both numerics and constants. |
| 71 |
</div> |
| 72 |
<h4>Constants</h4> |
| 73 |
<div> |
| 74 |
Constants can be declared everywhere in the PLAN file except in loops. They are 8 bits char strings (except "=") with a leading "$" character which makes them easy to identify. Their value is always interpreted as a float through std::atof. You can "overload" a constant value by redeclaring it. They are declared in this form: |
| 75 |
<div class="code-abs"> |
| 76 |
$MyConstant = 123.456 |
| 77 |
</div> |
| 78 |
Note that a PLAN file is valid only if it contains 2 required constants which are "$PageWidth" and "$PageHeight", giving target document dimensions. Now support the "$ScaleFactor" constant -- means that the declared scale factor will be added to the current transformation matrix for each placed page. Constants declarations can hold expressions: |
| 79 |
<div class="code-abs"> |
| 80 |
$MyConstant = $AnotherConst * .5; |
| 81 |
</div> |
| 82 |
Source document pages count is provided as "$PageCount". |
| 83 |
Source first page geometry is provided as "$SourceWidth" and "$SourceHeight", reflecting geometry given by the MediaBox. |
| 84 |
</div> |
| 85 |
<h4>Expressions</h4> |
| 86 |
<div> |
| 87 |
An expression is a set of basic mathematic operations +, -, *,/ and % (operands of modulo will be first rounded). As a convenience, we added the | as "max(a,b)" it’s mainly there to allow user to prevent division by 0. |
| 88 |
<div class="code-abs"> |
| 89 |
$ValueA / ( $ValueB | 0.000001 ) |
| 90 |
</div> |
| 91 |
Operations are executed from left to right without taking care of any kind of precedance. You can use parenthesis to enclose operations that need to be computed separately. Example: |
| 92 |
<div class="code-abs"> |
| 93 |
123.456 * ( $ConstantA - ( $ConstantB / 3.14 ) ) |
| 94 |
</div> |
| 95 |
</div> |
| 96 |
<h4>Loops</h4> |
| 97 |
<div> |
| 98 |
Loops allow users to programmatically generate records. While the concept itself is familiar to programmers I can imagine that regular users would feel not so easy with it. So let me introduce a simple example to explain the thing. |
| 99 |
</div> |
| 100 |
<div> |
| 101 |
Let say we have a source document, A4 format, which has 1000 pages and we just want to position each page of the first half of the document on the center of an A3 plate. |
| 102 |
<div class="file"> |
| 103 |
<div class="name">A4onA3.plan</div> |
| 104 |
<div class="content">$PageWidth=842.6 |
| 105 |
$PageHeight=1195.2 |
| 106 |
## SourceWidth & SourceHeight |
| 107 |
$sw=597.6 |
| 108 |
$sh=842.4 |
| 109 |
$page=1 |
| 110 |
<$PageCount/2[$page+1] |
| 111 |
$page; $page; 0; ($PageWidth-$sw)/2; ($PageHeight-$sh)/2; |
| 112 |
> |
| 113 |
</div> |
| 114 |
</div> |
| 115 |
The loop is what’s enclosed by "<" and ">"characters, the second just indicates the end of the loop. The first first indicates how many iterations (loops) have to be performed — 500 here. Then comes the interesting part, constants which appear in parenthesis will be incremented by the value following the "+" (can be a minus one, in that case don’t turn the "+" into a "-", just prefix the value with "-" as in [$foo+-1.23]), which means in this example that at each iteration, $page will see its value increased by 1. |
| 116 |
</div> |
| 117 |
<div> |
| 118 |
Constants (which finally turn into variables ;-)) must be declared before the loop. Many constants can be put in loop declaration, separate them with semicolons. |
| 119 |
</div> |
| 120 |
<div> |
| 121 |
<!-- No, loops can’t be nested! --> |
| 122 |
There is an experimental support of nested loops. |
| 123 |
</div> |
| 124 |
<h4>Running</h4> |
| 125 |
<div> |
| 126 |
Once you’ve wrote the PLAN file you can run the program: |
| 127 |
<div class="command"> |
| 128 |
podofoimpose source.pdf target.pdf plan.plan |
| 129 |
</div> |
| 130 |
Note the source can be either a PDF file or a text file which is a listing of PDF files. In this case, listed files will be first merged in order. |
| 131 |
</div> |
| 132 |
</div> <!-- Plan --> |
| 133 |
<h3>Plan (Lua)</h3> |
| 134 |
<div class="section"><!-- lua plan --> |
| 135 |
PoDoFoImpose now supports Lua scripted plan files. Note that, mainly for security reasons, only the following modules are loaded: base, table, string, math. If you need more, just add luaopen_* calls to LuaMachina::LuaMachina(). |
| 136 |
<h4>Format</h4> |
| 137 |
<div> |
| 138 |
Records are pushed with: |
| 139 |
<div class="command"> |
| 140 |
PushRecord(source page, target page, rotation, x, y); |
| 141 |
</div> |
| 142 |
As for regular plan files, there are a couple of provided information through global variables, specifically: "SourceWidth", "SourceHeight", "PageCount". You need to set "PageWidth" and "PageHeight". You may alter the global scale factor (from source to target) by setting "Scale". |
| 143 |
</div> |
| 144 |
<h4>Running</h4> |
| 145 |
<div> |
| 146 |
There is no format detection mechanism, so you need to append "lua" keyword to podofoimpose invocation when you want it to process a Lua script. |
| 147 |
</div> |
| 148 |
|
| 149 |
</div> <!-- lua plan --> |
| 150 |
|
| 151 |
<h3>Examples</h3> |
| 152 |
<div class="section"><!-- Examples --> |
| 153 |
<div> |
| 154 |
For Lua scripts, some samples can be found in directory tools/podofoimpose/plans/lua of PoDoFo sources tree. |
| 155 |
</div> |
| 156 |
<h5>Add a stamp to a document</h5> |
| 157 |
Shame on me, don’t even have a real stamp at my "office". So I tried something and it worked! Say you have that official one page A4 doc, named official.pdf, on which you want to add a nice stamp. You have your stamp in the file stamp.pdf. You first have to create two files: |
| 158 |
<div class="file"> |
| 159 |
<div class="name"> |
| 160 |
pdf.list |
| 161 |
</div> |
| 162 |
<div class="content">official.pdf |
| 163 |
stamp.pdf</div> |
| 164 |
</div> |
| 165 |
<div class="file"> |
| 166 |
<div class="name">stamponator.plan</div> |
| 167 |
<div class="content">$PageWidth=597.6 |
| 168 |
$PageHeight=842.4 |
| 169 |
# original page is left unchanged; |
| 170 |
1; 1; 0; 0; 0; |
| 171 |
# positioning stamp is up to you! |
| 172 |
2; 1; 0; 350; 100;</div> |
| 173 |
</div> |
| 174 |
Now you can run: |
| 175 |
<div class="command">podofoimpose pdf.list stamped-official.pdf stamponator.plan</div> |
| 176 |
|
| 177 |
<h5>Make a tiled poster</h5> |
| 178 |
<div> |
| 179 |
Printing a large graphic onto a set of little paper sheets can be handful. Doing it automatically is even better! <!--You can find files used in this example here: <a href="poster.pdf">poster.pdf</a>, |
| 180 |
<a href="poster_mask.pdf">poster_mask.pdf</a>, |
| 181 |
<a href="poster.plan">poster.plan</a> and |
| 182 |
<a href="poster.list">poster.list</a>. Here constants are a bit abbreviated in order to fit in the frame.--> |
| 183 |
Latest changes allow us to provide you with a quasi all-automatic solution. The only thing that you would want to change (apart from debugging) is the output paper size (here ISO-A4, "Europe oblige !"). |
| 184 |
<div class="file"> |
| 185 |
<div class="name">poster.plan</div> |
| 186 |
<div class="content"> |
| 187 |
##POSTER printed on tiled A4 paper sheets. |
| 188 |
# destination (A4) |
| 189 |
$PageWidth = 597.6 |
| 190 |
$PageHeight = 842.4 |
| 191 |
|
| 192 |
$sW = $SourceWidth |
| 193 |
$sH = $SourceHeight |
| 194 |
|
| 195 |
# with a little trick to get integers |
| 196 |
$rows = (($sH / $PageHeight) + 1) % (2 * (($sH / $PageHeight)+1)) |
| 197 |
$cols = (($sW / $PageWidth) + 1) % (2 * (($sW / $PageWidth )+1)) |
| 198 |
|
| 199 |
$hbox = ($sW / ($cols | 1)) |
| 200 |
$vbox = ($sH/ ($rows | 1)) |
| 201 |
$hm = ($PageWidth - $hbox ) / 2 |
| 202 |
$vm = ($PageHeight - $vbox ) / 2 |
| 203 |
|
| 204 |
$R = 1 |
| 205 |
$C = 1 |
| 206 |
<$rows[$R+1] |
| 207 |
<$cols[$C+1] |
| 208 |
1; (($R - 1)*$cols) + $C; 0; $hm - (($C -1) * $hbox); $vm - (($R-1) * $vbox); |
| 209 |
> |
| 210 |
> |
| 211 |
|
| 212 |
</div> |
| 213 |
</div> |
| 214 |
</div> |
| 215 |
<div class="command">podofoimpose poster.pdf poster_tiled.pdf poster.plan </div> |
| 216 |
<div>Etc.</div> |
| 217 |
</div><!-- Examples --> |
| 218 |
</body> |
| 219 |
</html> |