Document

A Document wraps one PDF. You get one from imposio.open(), imposio.newDocument(), imposio.activeDocument(), or from operations that produce a new document (generateImposition(), splitPages(), copyPages()).

All page indexes are 0-based. Ranges are strings: "all", "1-5", "odd", "even", "2,4,7" (empty = all). Lengths are in the current unit unless given as a suffixed string.

Information

Method	Returns	Description
isValid()	bool	Whether the document loaded correctly.
pageCount()	int	Number of pages.
filePath()	string	Source file path (empty for new docs).
title()	string	The script-set title.
setTitle(title)	—	Set the tab title used by show() / save().

Page boxes & sizes

Each returns an object in the current unit (PDF coords, Y-up). pageSize returns {w, h}; the box getters return {x, y, w, h}.

Method	Returns
pageSize(pageIndex)	{w, h}
mediaBox(pageIndex)	{x, y, w, h}
cropBox(pageIndex)	{x, y, w, h}
trimBox(pageIndex)	{x, y, w, h}
bleedBox(pageIndex)	{x, y, w, h}

Page inspection (read-only)

Method	Returns
pageObjects(pageIndex)	Content-stream objects (recurses into Form XObjects): [{ indexPath:[…], type:"text\|path\|image\|shading\|form\|unknown", bbox:{x,y,w,h} }]
annotations(pageIndex)	[{ subtype:int, type:"Link\|Text\|Widget\|…", summary, bbox:{x,y,w,h} }]
resources(pageIndex)	[{ kind:"font\|image\|form", name, primary, secondary, warning:bool }]
structTree(pageIndex)	Tagged-PDF structure (empty for untagged): [{ type, title, altText, actualText, children:[…] }]
formFields()	Interactive form fields: [{ name, label, type, value, checked, choices:[…], readOnly, multiline }] (see Form fields below)

Page operations

These mutate the document in place (unless noted).

resizePages(range, width, height, opts?)

Resize pages to a new size. Trim/bleed/crop boxes and bleed content are preserved.

opts key	Values	Default
placement	"fit", "fill", "stretch", "keep"	"fit"

deletePages(range)

Delete the pages in range.

rotatePages(range, degrees, opts?)

Rotate pages. degrees is absolute (0/90/180/270); with opts.increment = true it is added to the current rotation.

duplicatePages(range, opts?)

Duplicate pages. opts.mode: "after" (default — a copy after each), "block", "append".

reversePages(range?, opts?)

Reverse page order. opts.mode: "inplace" (default) or "compact".

movePages(range, destIndex)

Move the pages in range to before destIndex (0-based, in the original page space).

setPageBoxes(range, boxes)

Set page boxes as insets from the MediaBox (current unit). boxes: { bleed, trim, crop }.

addBlankPage(at, width, height)

Insert a blank page (dimensions in the current unit) at index at (-1 = end).

addPagesFromFile(path, opts?)

Insert pages from a PDF or an image (PNG/JPEG/BMP/GIF/TIFF/WebP → one page).

opts key	Description
range	Which pages from the source (PDF only).
at	Insert index (-1 = end).

replacePages(targetRange, source, opts?)

Delete targetRange and insert pages from source (PDF or image) at that position. opts.range selects source pages (default all; ignored for images).

splitPages(cols, rows, opts?) → Document

Split each page into a cols × rows grid. Returns a new Document.

opts key	Values
area	"media", "trim", "bleed", "crop"
range	pages to split

rasterizePages(range?, dpiOrOpts?)

Replace pages with a rasterised version (rendered, flattened onto white — no transparency). In place. The second argument is a DPI number (legacy) or an object:

opts key	Values	Default
dpi	number	300
cmyk	bool	false (RGB)
intent	"perceptual", "relative", "saturation", "absolute" (or 0–3)	—
iccProfile	path to .icc	bundled GRACoL

generateBleed(range?, opts?)

Build a bleed frame around pages from the artwork's own edge (GUI Generate Bleed). The page grows by size on each edge; the trim box is set to the original page and the bleed box to the new edge, so imposition crops it correctly. Only the added frame is rasterised — the page stays vector. Pages that already have bleed are skipped. Returns the number of changed pages.

opts key	Values	Default
size	length — bleed width	—
source	length — source strip width (narrower than size = stretched)	—
method	"mirror", "extend", "replicate", "solid"	—
dpi	raster DPI of the frame	300
blur	soften the frame	false
force	also process pages that already have bleed	false

copyPages(range?, opts?) → Document

Copy pages into a new document (like GUI Copy → New). Returns the new Document or null. opts.bakeLayer: false keeps the Imposio edit layer out of the copy (clean PDF artwork).

Page content edits

Edit or remove objects of the page's own content stream (the artwork itself, not the edit layer). indexPath comes from pageObjects() — e.g. [3], or [3, 2] for a child inside a Form XObject. All edits are layout-preserving: the rest of the page stays byte-identical (no reflowed text alignment).

Method	Description
setPageObjectText(page, indexPath, newText, opts?)	Change a text object's text. opts { x, y, w, h } moves/resizes it in the same step.
setPageObjectBounds(page, indexPath, x, y, w, h)	Move/resize an object (current unit, Y-up).
setPageObjectOpacity(page, indexPath, opacity)	Non-destructive opacity 0–1 (0 = hidden).
duplicateObject(page, indexPath, opts?)	Vector duplicate as a movable edit-layer shape; opts { dx, dy } offset. Returns the new shape ID.

smartDeleteObjects(pageIndex, indexPaths, opts?)

Delete objects matching template objects across many pages (GUI Smart Delete) — e.g. a watermark or header repeated everywhere. pageIndex + indexPaths (one indexPath or an array of them) pick the template objects. Returns the number of deleted objects, -1 on error.

opts key	Values	Default
mode	"identical" (same object) or "position" (whatever sits there)	"identical"
range	pages to process	"all"
tolerance	match tolerance (current unit)	0.5 pt
verify	re-render each modified page and skip it if anything else changed	true

Form fields

Read and fill interactive PDF (AcroForm) fields. Values are written into the form and stay editable; use flattenForms to bake them permanently into the page content.

formFields()

Return the document's interactive fields. Each entry:

Key	Description
name	Fully-qualified field name — the key for setFormField.
label	Human label (/TU, falls back to name).
type	"text", "checkbox", "radio", "choice", "pushbutton", "signature".
value	Current value (text/choice value; on-state name for buttons).
checked	true/false for check boxes & radio buttons.
choices	Options for choice fields (and the on-state names for radios).
readOnly	Locked by the form author.
multiline	Text field allows line breaks.

setFormField(name, value)

Set one field's value. value is a string for text and choice fields, a boolean (or "on"/"off") for check boxes, and the on-state name for radio buttons. The read-only flag is ignored — the value is overwritten. Returns true if applied.

setFormFields(values)

Set many fields at once from an object { name: value, … } (one pass per source; unknown names are skipped).

var d = imposio.open("invoice-template.pdf");
d.setFormFields({
  customer: "ACME Ltd",
  agree:    true,        // check box
  color:    "/green",    // radio on-state
  city:     "Kosice"     // choice
});
d.save("invoice-filled.pdf");

flattenForms(range?)

Bake interactive form-field values (and annotations) into the page content so they survive resize, split and imposition. In place; range defaults to "all".

Variable data

mergeData(table, opts)

Merge data records into the document (GUI Variable Data → Generate): for every record the source pages are copied and the mapped elements are expanded — text/frame-text templates replace the text, image templates expand to a file path, checkbox templates decide the tick (1/yes/true ticks, empty/0/no unticks). Placeholders: {column}, {i:03}, {=expression}, {{ = literal.

table is the object from imposio.loadData (or { columns: […], rows: [[…]] } built in the script); null = counter-only merge.

opts key	Description
mapping	Required. [{ page: 0, shape: id, template: "{name}" }]. Image mappings also take fit: "fit"\|"fill"\|"stretch"\|"keep" and align: "top-left"…"center"…"bottom-right" (or 0–8).
mode	"new" (default), "append", "fill".
sourcePages	1-based range; default = the pages used in mapping.
records	"all", "1-100", …
targets	"fill" only: pages that receive the elements (default = pages after the source block).
replace	"fill" only: true replaces target-page elements, false adds on top.
counters	[{ name: "i", start: 0, step: 1, max: 100 }] — max optional; with max the merge works even without a table.
imageBaseDir	Base folder for relative image paths.
hidden	[{ page: 0, shape: id }] — Visibility: items left out of the output.
pdfContent	false leaves out the underlying PDF content of the source pages (elements on blank pages; new/append). Default true.

Returns a new Document for "new", the number of merged records for "append"/"fill". Throws on error (the document is unchanged).

var data = imposio.loadData("guests.csv");
var doc  = imposio.activeDocument();
var out  = doc.mergeData(data, {
  mapping: [{ page: 0, shape: 3, template: "{firstname} {lastname}" }],
  counters: [{ name: "i", start: 1 }],
});
out.save("badges.pdf");

Export, save & render

exportImage(path, opts?)

Render pages to image files. path is a folder or a file (the folder is derived).

opts key	Values	Default
format	"tiff", "png", "jpeg", "webp"	—
dpi	number	—
quality	number (JPEG/WebP)	—
box	"media", "trim", "bleed", "crop"	—
range	pages	all
pattern	filename pattern, e.g. "{p}" ({p} = PDF page no., {n} = output counter)	—
multipageTiff	bool — one TIFF for the whole job	—

save(path, opts?)

Save as PDF. Returns bool. opts.autoIndex = true appends _1, _2, … when the target file exists (default false = overwrite).

renderPng(pageIndex, dpi, outPath, opts?)

Render a single page to PNG. opts.background: "#rrggbb" or "none"/"transparent" (default white).

Metadata & security

Changes are written into the PDF on save() (dirty model); both are partial updates.

metadata() / setMetadata(m)

metadata() returns { title, author, subject, keywords, creator, producer, created, modified } (created/modified read-only). setMetadata({ title?, author?, subject?, keywords?, creator?, producer? }).

security() / setSecurity(s)

security() returns { encrypt, algorithm, userPassword, ownerPassword, allowPrint, allowHighResPrint, allowCopy, allowModify, allowAnnotate, allowForms, allowExtract, allowAssembly, wasEncrypted }.

setSecurity({ encrypt?, userPassword?, ownerPassword?, algorithm?, allow…? }) — encrypt: false removes security on save. algorithm: "rc4-128", "aes-128", "aes-256".

Display

show(title?)

Open this document as a new tab in the app (GUI Run). No-op when running headless/CLI.