Docs / Documents & vectors

Documents & vectors v0.2.0

picturium can turn document pages into images through the normal pipeline, or give you back a PDF or SVG. Pick an image output format when you want to resize, crop, filter or watermark pages, and f=pdf or f=svg when you want a document instead of pixels.

/manual.pdf?page=3&w=1200&f=webp
/slides.pptx?page=1-4&w=1600&f=webp
/diagram.svg?style=YmFja2dyb3VuZDp3aGl0ZQ==&f=pdf
/artwork.ai?f=svg

f=svg only works for SVG and vector-art sources. f=pdf works for PDF, SVG, Office and vector-art sources. Anything else gets a 415. Document responses skip sizing, cropping, filters, quality, metadata, watermarks and output limits.

Page selection

page or pages takes page numbers starting at 1, separated by commas, with optional ascending ranges. A selection can cover at most pdf.max_pages pages (512 by default).

/manual.pdf?page=3
/manual.pdf?pages=2-4&w=1200&f=webp
/manual.pdf?pages=1,4-7,9&f=pdf

page=0, backwards ranges like 7-4, anything that isn’t a number, and selections over pdf.max_pages pages are rejected with a 400. The old thumb=page:... form still works, but the top-level parameter wins if you send both.

When you render pages to an image, picturium loads everything from the lowest selected page to the highest. pages=2,5 loads pages 2, 3, 4 and 5, so to get specific pages that aren’t next to each other, use f=pdf or make one request per page. Every loaded page goes through sizing, cropping, filters and watermarking on its own. What you get back depends on the format:

• WebP and GIF turn several pages into an animation, one page per frame. See Animation & video for timing and frame controls.
• JPEG, PNG, AVIF and JXL stack the pages vertically into one tall image.

With f=pdf and no page, you get the whole PDF. With a selection you get a new PDF containing exactly the requested pages that exist, in document order, with duplicates dropped. Pages past the end are ignored as long as at least one requested page exists; otherwise the request fails with 400. Bookmarks pointing at removed pages are cleaned up.

SVG

An SVG can take three routes:

• f=svg returns the SVG as-is. For vector art, Inkscape converts it to plain SVG first.
• f=pdf turns the SVG into a single-page vector PDF.
• An image format renders the SVG with libvips and runs it through the normal pipeline.

style passes base64-encoded CSS to the SVG renderer. dpi defaults to svg.load_dpi (72) and accepts auto or 1 to 3000. For image output it sets the render resolution. With f=pdf it sets the physical page size instead: doubling the DPI halves the page size in PDF points, but the artwork stays the same.

libvips normally refuses SVG files over 10 MB. Only set svg.unlimited=true if you trust the files. This limit only applies when rendering SVGs to images; it isn’t a general request size limit.

When converting SVG to PDF, images embedded as data: URIs are included. Local <image href="..."> files are left out unless you set svg.allow_local_resources=true. With that on, relative references are resolved next to the SVG but still have to stay inside data.dir, and absolute paths or .. that escape it are rejected. If your data directory holds files for different tenants, leave this off.

Changes to referenced files don’t invalidate the cached PDF, on purpose. After editing one, request the PDF with force=true: that skips the cache and HTTP validators, regenerates the PDF and replaces the cached copy. See Caching & force, and Configuration & operations for cache setup.

PDF

Rendering a PDF to an image uses page 1 unless you pick another with page. dpi overrides pdf.load_dpi (72); a higher DPI gives the pipeline more pixels to work with, but w and h still follow the usual sizing rules. Pages are drawn on pdf.background (white by default), and a bg parameter overrides that.

/report.pdf?page=2&dpi=144&w=1400&f=webp
/report.pdf?pages=1-3&w=1000&f=gif
/report.pdf?pages=2,5-7&f=pdf&download=extract.pdf

Limits

Three settings keep a single PDF from tying up a worker:

• pdf.max_file_size (256 MiB): larger PDFs aren’t rendered at all. picturium serves the original file untouched instead.
• pdf.max_pages (512): a larger page selection is rejected with a 400.
• pdf.max_image_pixels (64 megapixels): if the first page, at the scale it would be rendered at, is larger than this, the request fails with a 500. A high dpi or a large w/h on a big page is the usual cause.

If the request has a fallback, picturium renders that instead in all three cases, with the same parameters. See Errors & fallback.

/drawings/site-plan.pdf?w=800&f=webp&fallback=placeholders/document.png

f=pdf without a page selection serves the original file. A new PDF is only built when you select pages. Add download= to set a Content-Disposition filename; everything else about headers and caching works as described in Output format & quality.

Office documents

Office files need the soffice executable. picturium has LibreOffice convert them to PDF, then either serves that PDF or renders its pages. When you only need page 1 (no page parameter, or only page 1 selected), picturium converts just the first page for a quicker response and starts converting the full document for later requests. f=pdf without a page always waits for the whole document.

office.conversion_timeout (30 seconds by default) is how long a request waits for a conversion. If it runs out, the request fails but LibreOffice keeps going in the background, so the result is cached for the next request. office.kill_timeout (300 seconds by default) is the hard limit after which the conversion is killed. It can’t be lower than conversion_timeout.

office.max_processes caps how many LibreOffice processes run at once, background conversions included. Further conversions wait for a free slot, and the wait counts toward conversion_timeout. 0 (the default) means one process per logical CPU. Each process can use hundreds of MB of memory, so on machines with many cores and little RAM set a lower number.

Finished first-page and full conversions are stored in the normal memory and disk cache. Use force=true to redo them and replace the cached copies.

Vector art

AI, CDR, CMX, CDT, EPS and DXF files need the inkscape executable. picturium exports them to PDF for image output and f=pdf, and to plain SVG for f=svg. The export uses the file’s own page, except for DXF, which uses the drawing’s bounds because Inkscape always imports DXF onto an A4 page. These formats usually produce a single page.

vector.conversion_timeout defaults to 30 seconds. PDF and SVG conversions are cached separately, and force=true redoes and replaces them. How well Inkscape reads these files depends on which program and version created them, so try a few real files before relying on a format in production.

Serving other files unchanged

A file type picturium can’t process gets a 415, unless its extension is listed in data.serve. The list is case-insensitive and entries may start with a dot or not. * serves every unsupported file, including ones without an extension, so listing the extensions you actually need is safer.

[data]
serve = ["txt", "json", "zip"]

Allowlisted files come back untouched, with byte-range support; transform parameters don’t apply. original=true also returns any existing file as-is, and doesn’t need the extension to be in data.serve. The full parameter and status code tables are in the Reference.