pdfstamp ======== pdfstamp is a terminal-only PDF stamp-region picker. It renders a coarse, content-aware page preview directly in the terminal and lets you place text and image stamps with the keyboard, save the layout as a JSON plan, and burn the stamps into an output PDF. It does coarse placement, not pixel-perfect editing. Zoom in for finer control over stamps, initials, signatures, dates, and labels. Build ----- pdfstamp uses MuPDF (via go-fitz) for rendering, which requires cgo. go-fitz bundles musl-built MuPDF static libraries (no system PDF library is needed), and the build links fully static: the one binary has no libc dependency and runs on both glibc and musl machines. On Alpine: apk add build-base go make build On Debian, install the musl toolchain and select it explicitly: apt install build-essential musl-tools make build CC=musl-gcc There is no native Windows build; on Windows, run the same static binary under WSL. Usage ----- pdfstamp pick INPUT.pdf [-o PLAN.json] place stamps; write the plan pdfstamp apply PLAN.json OUTPUT.pdf burn a plan into an output PDF pdfstamp INPUT.pdf OUTPUT.pdf pick then apply in one step With no -o, pick writes the plan to stdout. apply reads the plan from stdin when the path is -, so the two steps compose as a pipe: pdfstamp pick INPUT.pdf | pdfstamp apply - OUTPUT.pdf The picker draws to /dev/tty, so stdout carries only the plan. apply reads the source PDF path from the plan's "input" field. A sample document ships with the repo; try: pdfstamp pick example.pdf -o plan.json pdfstamp apply plan.json stamped.pdf Controls -------- The picker is modal on selection: with no stamp selected, h/j/k/l move the cursor; with a stamp selected (tab), they move the stamp. n / p next / previous page g go to page h j k l move cursor (or selected stamp) arrows move (same as h j k l) H J K L resize selected stamp space start / finish a rectangle, then add a stamp in it a add a stamp at the cursor (or edit the selected one) d delete the selected stamp P set the selected stamp's pages (e.g. 1,3-5 or all) o set the selected stamp's opacity (0-1) tab cycle stamp selection (and back to cursor mode) + / - zoom in / out enter save the plan (pick), or apply and quit (one-step) ? toggle help q quit A truecolor terminal (COLORTERM=truecolor) gets a colored half-block preview; otherwise a grayscale ASCII preview is used. tmux and screen usually strip COLORTERM; set it inside the multiplexer to keep the colored preview. Plan format ----------- The plan is plain JSON. Coordinates are PDF points with a bottom-left origin. Pages are 1-based. Text uses Helvetica, sized to fit the rectangle (no per-stamp font/size/color). Only printable ASCII is supported, as no font is embedded; plans with other characters are rejected. Images (PNG or JPEG) are scaled to fit the rectangle while preserving aspect ratio, anchored at the bottom-left corner. pick writes absolute paths so a saved plan applies from any directory. In a hand-written plan, relative "input" and "src" paths are resolved relative to the plan file's directory (or the working directory when the plan is read from stdin). { "version": 2, "input": "input.pdf", "stamps": [ { "id": "stamp-1", "type": "text", "content": "APPROVED", "pages": [1], "rect": { "x": 420, "y": 610, "w": 120, "h": 42 }, "opacity": 0.8 }, { "id": "stamp-2", "type": "image", "src": "sig.png", "pages": [1, 3], "rect": { "x": 100, "y": 90, "w": 80, "h": 40 }, "opacity": 1.0 } ] } How it works ------------ pick rasterizes each page with MuPDF and draws it as Unicode half-blocks, one character per two vertical pixels, mapping terminal cells to PDF points. apply builds an in-memory overlay PDF with one page per source page, drawing each stamp at its exact point coordinates (text via a base-14 Helvetica content stream, images as RGB XObjects with a soft-mask for transparency). pdfcpu then overlays that PDF onto the source 1:1 (multi-stamp, centered, scale 1, no rotation) and validates the result. Because the overlay pages share the source MediaBoxes, the overlay is an identity transform. On pages with /Rotate, the overlay uses the viewed page size and pdfcpu counter-rotates it, so stamps land where the picker showed them. Debugging --------- The overlay content streams are uncompressed and human-readable; dump the overlay or output with a viewer or `strings` to inspect the drawing operators (`cm`, `Tj`, `Do`). Run the integration test, which applies a known plan and asserts that stamps land in the expected pixel regions: make test On Debian, use the same musl compiler override as the build: make test CC=musl-gcc If stamps appear rotated or offset, check the watermark fields set in apply.go: pdfcpu defaults to a diagonal placement, so Rotation 0 and NoDiagonal must both be set to get a straight 1:1 overlay. Exit status ----------- 0 on success, 1 on runtime errors, 2 on usage errors. The picker exits 130 on SIGINT and 143 on SIGTERM, after restoring the terminal. Limitations ----------- apply refuses, rather than silently misplacing stamps, on pages it cannot map 1:1: pages whose MediaBox/CropBox origin is not at (0,0). Text stamps are printable ASCII only (no embedded font). Each stamp image is capped at 50 megapixels, with a 100-megapixel total across distinct images. License ------- pdfstamp links MuPDF (AGPL-3.0). Distributing the binary therefore puts it under the AGPL-3.0 unless you hold a commercial MuPDF license. pdfcpu is Apache-2.0.