huppiflupp bff4be14c3 M10: Recognize text finds small print on large pages (tiled detection)
## What this changes

Recognize text now finds small print on large, dense pages (newspapers, small print, blurred photos).

The ocrs detection model reads a fixed 600 × 800 pixel input, so ocrs shrinks every page to that size before detecting words. A full page at 300 dpi (2480 × 3508) is shrunk about four times, and small letters disappear. With this change:

- **When (size):** an axis is cut in two when the page is at least twice the detector's input along it (width ≥ 1200 px, height ≥ 1600 px for the ocrs models). Any full page at 300 dpi becomes 2 × 2 tiles; a landscape page may become 2 × 1. The input size is read from the detection model when it loads. Pages below that size (72 to 150 dpi renders, screenshots) are read exactly as before and cost nothing extra.
- **When (text size):** a page that passes the size rule is tiled only if its text is small once the page is shrunk to the detector's input, decided by a cheap pixel signal, the **line pitch** (`crates/ocr/src/pitch.rs`). The page is box-averaged to a grey copy of at most 1600 px a side and cut into a 6 × 6 grid of blocks. In each block, the ink is summed per pixel row, the slow trend (shading, pictures) is removed with a moving average, and the autocorrelation is taken. The block autocorrelations are averaged, and the first strong peak is the pitch. Lines in columns that don't line up still agree on the period, and blank blocks are skipped. The same runs on pixel columns for sideways pages, and the axis with the stronger peak wins. The pitch is converted to detector pixels (pitch × 800 / page height). The rule:
  - pitch **under 9 detector pixels**: tile;
  - ink but **no clear line spacing** (no autocorrelation peak above 0.05): tile, because the measurement showed these pages (blurred, creased, oblique or moiré photos) gain on average;
  - large print, and blank pages: detect whole, as before.
  It costs 6.6 ms per page on average (median 5.1 ms, max 45 ms) and reads every pixel once.
- **How:** tiles overlap by 4 % of the page on each side of a cut. Words are **detected** tile by tile. A word is kept only by the tile whose core cell (its share of the page without the overlap) holds its centre, so a word in an overlap counts once. The words are moved back to page pixels, and then lines are formed and **recognised on the whole page** as before. Lines that cross a cut stay single lines, and recognition reads the same pixels it read before.
- The edge cells reach to infinity, so every finite word centre belongs to exactly one tile, including boxes that stick out past the page.

The change is small and lives in `crates/ocr/src/tiles.rs` plus a `detect_words` step in `Ocr::recognize`. While I was there I also made the existing RGBA length check use checked arithmetic (`width * height * 4` was a `u32` product).

### Measured

MDPBench de/es/fr (480 pages), official evaluation with CDM off, `en` recogniser. I ran the same harness build with and without the change (the baseline reproduces the earlier one exactly):

| | Digital | Photo | All | Time per page |
|---|---|---|---|---|
| before | 78.9 | 41.5 | 50.8 | 0.39 s (190 s total) |
| tiling every large page (this PR's first commit) | 80.4 | 42.8 | 52.2 | 0.58 s (281 s total) |
| **tiling only small or unclear print (this PR)** | **81.2** | **42.9** | **52.5** | 0.54 s (259 s total) |
| earlier prototype (full OCR per tile, outside the app) | 81.4 | 42.4 | 52.1 | n/a |

The three rows of this PR come from one harness binary with the rule switched by an environment variable. Each was timed twice (190/191, 281/281, 259/259 s). Per language, the line-pitch rule against tiling every large page: DE 62.9 vs 62.7, ES 47.9 vs 47.8, FR 46.8 vs 46.1. It tiles **214 of the 457** pages that pass the size rule.

**How the rule was chosen.** I measured first, in Python on the per-page scores of the official evaluation (`overall` per page, base vs. tiled). Per-page score gain from tiling, by measured pitch:

| pitch (detector px) | pages | mean gain | pages gaining / losing > 0.02 |
|---|---|---|---|
| < 4 | 40 | +0.018 | 10 / 4 |
| 4–6 | 40 | **+0.114** | 24 / 2 |
| 6–10 | 82 | +0.004 | 10 / 6 |
| 10–14 | 80 | **−0.013** | 5 / 26 |
| 14–35 | 144 | −0.003 | 22 / 25 |
| no clear line spacing | 82 | +0.029 | – |

The gain sits at small pitch, and pitches of 10–14 detector pixels (ordinary body text on a full page) **lose** a little when tiled. Picking tiled or base per page by this rule, and running the official evaluation on that mix, predicted exactly what the Rust build then scored (52.5 / 81.2 / 42.9). Thresholds between 8 and 10 give 52.4–52.5. Treating "no clear spacing" as "don't tile" instead gives 52.0 with only 132 pages tiled. The choice is tuned on these 480 pages, so take the last few tenths with that in mind.

**Time.** The saving is smaller than the page count suggests. The pages that stay tiled are the dense ones, where tiling finds many more words, and recognising those words costs more than the three extra detector runs. Tiling every large page cost +91 s. The pitch rule costs +69 s, so it removes about a quarter of the overhead and still scores higher.

Word recall in the benchmark's own per-kind table, before → after: de digital 61.9 → 78.5 %, fr digital 17.8 → 24.5 %, de/es/fr photos 38.1/37.7/10.1 → 42.1/43.2/12.6 %. Sideways photos are unchanged; those need rotation, which is a separate PR.

Detection runs four times instead of once on a tiled page (machine: Ryzen AI Max+ 395, CPU).

### How it composes with the open OCR PRs

- #5157 (reading order) ends `recognize` in `layout::reading_order`. This PR changes only the detection step before `find_text_lines`, so tiles are merged before lines are formed and before reading order runs, which is the order we want. I measured both together: the numbers above come from a harness tree that has #5157's reading order applied. The two diffs touch neighbouring lines in `recognize`, so whichever merges second needs a trivial rebase.
- #5171 (layout regions) and #5058 (line padding) work on lines and regions after detection, so they compose the same way.

## How you verified it

- [x] `cargo fmt --check`
- [x] `cargo clippy -p pdfcraft-ocr --all-targets -- -D warnings`
- [x] `cargo test -p pdfcraft-ocr`: 26 passed, **with the OCR models installed** (CI has none, so CI skips the model-backed tests). With the models, I also ran the OCR tests of `pdfcraft-engine` (`ocr`, `recogni` filters) and `pdfcraft-automation` (`ocr`, `scan`) locally, and all pass.
- [x] `cargo xtask layers`, `cargo xtask assets`, `cargo xtask parity`

**Tests.**
- Unit tests, no models (`crates/ocr/src/tiles.rs`): the tile geometry for small pages and for A4 at 300 dpi; every word centre, on cuts, edges and outside the page, belongs to exactly one tile, and NaN or infinity belongs to none; cropping, including out-of-range and overflowing crops, returns `None` without panicking.
- Unit tests, no models (`crates/ocr/src/pitch.rs`), on synthetic A4 pages at 300 dpi: a blank page is not tiled; large print (lines every 100 px, 22.8 detector px) is not; small print (every 30 px, 6.8 detector px) is, in grey, RGB and RGBA alike; sideways small print (lines running down the page) is; noise (ink without lines) is; the first strong autocorrelation peak is the pitch, not its multiple; empty, 1-pixel, short or long buffers, 0 or 5 channels, overflowing sizes, a zero-sized detector and slivers give an answer without panicking.
- Model-backed test `finds_small_print_on_a_large_page`: an A4 page at 300 dpi with four lines of small print. One sits inside a tile, one crosses the vertical cut, one is half in the overlap, and one crosses the horizontal cut. Each line must come back as exactly two words at the right place in page pixels.
- **Seen failing by reverting the fix:**
  - Detection on the whole page instead of tiles: 5 words instead of 8, unreadable ("FIOWOR", "In3").
  - Keeping every tile's words without the centre-in-core rule: 14 instead of 8, because the lines in the overlaps doubled.
  - Finite edge cells: `every_word_centre_belongs_to_exactly_one_tile` fails.
  - Never cutting: the geometry tests fail.
  - Line-pitch rule, each mutation reverted afterwards: tiling every page (the first commit's behaviour) fails `a_blank_page_is_not_tiled` and `large_print_is_not_tiled`. Never tiling on a measured pitch fails `small_print_is_tiled` and `sideways_small_print_is_tiled`. Rows only, without the column profile, fails `sideways_small_print_is_tiled`. Taking the strongest peak instead of the first strong one fails `the_first_strong_peak_is_the_pitch`. Not tiling unclear pages fails `ink_without_lines_is_tiled`. No detrending fails four tests. With the threshold lowered to 5 detector pixels, the model-backed `finds_small_print_on_a_large_page` finds 5 words instead of 8, so it exercises the rule too (its page measures 5.8).

## Never-crash

- [x] No new `unwrap`/`expect`/`panic!`/`unreachable!`/`todo!` outside tests
- [x] No indexing or slicing with input-derived positions: crops use checked arithmetic and `get`; tile bounds are clamped to the page; float-to-int casts are of values clamped to `0..=len`. The pitch measure checks that the buffer matches width × height × channels with checked arithmetic, reads pixels through iterators and `get`, and works on at most 1600 × 1600 values whatever the page size. It divides only by non-zero counts, so it returns an answer for any input.
- [x] No `unsafe`
- [x] n/a, this fixes no crash

## Provenance

- [x] No asset from an Adobe product
- [x] No font files
- [x] No GPL/AGPL code
- [x] Behaviour comes from our own measurements on MDPBench. The approach (overlapping tiles, keep by centre; line pitch from the autocorrelation of a projection profile) is a generic technique, not read from another implementation.
- [x] No new assets. One new dependency edge, `rten-imageproc` 0.26 (MIT/Apache-2.0), which was already in the tree through `ocrs`.

## Security

- [x] No path handling changed
- [x] No MCP or control channel changes
- [x] No network access

## Parity and reach

- [x] `ocr.recognize-text` notes say when pages are tiled (size and line pitch), and that the model-backed test runs only where the models are installed. The tiling and pitch unit tests are evidence.
- [x] Reachable headlessly: this is inside `Ocr::recognize`, so `ocr_recognize` and `ocr_recognize_files` get it unchanged.
- [x] No documented behaviour changed

## Anything a reviewer should look at first

- **The tiling rule:** an axis is cut only if each half still fills the detector's input, so a tile is never padded. A lower threshold would also tile mid-size pages. I kept it conservative so that small pages cost nothing. The prototype tiled every page; under this rule, 468 of the 481 benchmark images are cut along at least one axis and 337 along both.
- **The line-pitch rule (`pitch.rs`).** Its constants (1600 px working size, 6 × 6 blocks, peak floor 0.05, first peak ≥ 60 % of the strongest, 9 detector px) were chosen on MDPBench as described above. "No clear line spacing → tile" is deliberate. My first idea was the opposite, but the measurement favoured tiling.
- **Detect per tile, recognise on the whole page**, rather than full OCR per tile like the prototype. This is simpler: there are no lines to stitch back together and no rows to re-sort. It scores about the same as the prototype (all 52.2 vs 52.1, photo 42.8 vs 42.4, digital 80.4 vs 81.4).
2026-11-18 16:33:38 +07:00

ArtCraft

PdfCraft icon: an engraved lion on a red tile

PdfCraft

The PDF workbench; an open-source, modern PDF reader and editor, built in pure Rust.
Read, organize, combine, split and secure PDFs in a fast, native app, written in Rust from the ground up.
macOS · Windows · Linux · FreeBSD · the web

License: MIT OR Apache-2.0 Written in Rust Platforms: macOS, Windows, Linux, FreeBSD, web No account, no telemetry
Scanned by SonarCloud Reviewed by CodeRabbit

Join the ArtCraft community on Discord

PdfCraft on getartcraft.com · ArtCraft · All Crafting Apps


PdfCraft with the PdfCraft Showcase cover page open, the All tools panel on the left and 20 threaded comments on the right
The PdfCraft Showcase, a 13-page specimen PDF, open with the All tools panel and threaded comments.

Note

ArtCraft is a community of artists from all walks of life. Digital, generative, music, games — if you make things, you're one of us. Come say hi on Discord.

Highlights · Read · Find · Organize · Combine & split · Protect · Forms & layers · Everywhere · Agents · How it's built · Get started · What's next · Downloads · Crafting Apps


Community

PdfCraft is part of ArtCraft. Come say hello, get help and follow development:

The ArtCraft name and logos in docs/brand/ are trademarks of the ArtCraft Team and are not open source. They may be used only unmodified, and only as part of PdfCraft (see docs/brand/LICENSE-brand.txt). Forks and modified versions must remove them.

Highlights

Faithful

Real-world typography: world scripts, vertical Japanese, colour emoji, gradients, soft masks and transparency. All of it renders the way the author intended.

Fearless

Ordinary saves append your changes and leave the original bytes untouched. Edits to damaged objects whose xref and header generations disagree use a full rewrite, keeping both accepted references connected to the same repaired object. Writes are atomic, undo runs deep, and nothing is lost if you close by mistake.

Yours

No account, no telemetry, no cloud. It works offline and opens instantly. The engine, CLI and app are all open source.


Read anything, beautifully

PdfCraft renders PDFs with care for the details that make a page feel right: kerning and ligatures, right-to-left and complex scripts, vertical CJK, colour emoji, shadings, blend modes, soft masks and optional content.

The Scripts of the World page: Arabic, Hebrew, Devanagari, Thai, Greek, Cyrillic, Chinese, Korean, IPA, Armenian, Georgian and Tamil samples, with vertical Japanese in the right margin
Twelve writing systems on one page, plus vertical Japanese, at 125%.

  • Deep zoom stays sharp. Large pages render in tiles, so text stays crisp at any magnification.
  • Built to survive bad files. Every page renders in isolation and damaged documents are repaired. Across the 983-file pdf.js test corpus the result is 0 crashes.
  • Layouts for every task: continuous, single page, two-up, view rotation, full screen and a distraction-free Read mode.
  • Light and dark themes, both designed to be easy on the eyes for long sessions.
Two facing pages in Read mode with the dark theme: the Foreword and the Setting Text chapter with its drop cap and pull quote The dark theme showing the Code and Images chapter, a syntax-coloured listing and a fractal image, with the comments panel open
Two-up Read mode, ready for long reading The dark theme, with the comments panel open

Find it, select it, copy it

Search the whole document as you type, step through matches with ⌘G, and select text that comes out in the right reading order. That holds for columns, right-to-left runs and CJK too.

Navigate long documents

Launch with pdfcraft --two-paged file.pdf (or pdfcraft file.pdf --two-paged) to open each command-line PDF in noncontinuous two-page view. This optional launch override does not change saved default-layout preferences or PDFs restored from the previous session. An explicit --layout option takes precedence on the active document regardless of argument order; --default-layout retains its existing behavior for subsequently opened documents.

Right-click a PDF tab to close it, reopen the last closed file-backed tab, or reveal its file. Closing still asks about unsaved changes. Reopening reads the saved file from disk; it does not restore discarded edits. Reveal selects the file in Explorer or Finder. On Linux and FreeBSD it requests org.freedesktop.FileManager1.ShowItems, falling back to opening the containing directory with xdg-open when that service is unavailable. Reopen and Reveal are unavailable on the web; Reveal is also unavailable for pathless documents.

Bookmarks, page thumbnails and the document's own page labels (i, ii, 1, 2…) keep you oriented in long documents. Search bookmark titles in the Bookmarks panel to find nested entries even when their parents are collapsed. Matches keep their ancestors for context; Clear restores the unfiltered tree without changing its expansion state.

In Inspector > Pages, use Thumbnail size and the smaller/larger buttons to show more pages or inspect larger previews (50–150%). This changes only the thumbnails, keeping multi-page selection and the current page in view. The size belongs to the open document view and survives reloading its file; it is not remembered after restarting. Agents can set it with ui.set {"key":"thumbnail-zoom","value":"75"} and read active.thumbnail_zoom from ui.state.

The find bar showing match 10 of 16 for the word 'type', highlighted in the Expressive Type chapter heading The Bookmarks panel showing the nested outline of the showcase, with page labels such as Cover, i and ii, next to the Scripts of the World page
Find as you type: match 10 of 16 Nested bookmarks with the document's own page labels

Organize pages like cards on a table

Open Organize pages to see every page at once:

  • Select pages: click, ⌘-click or ⇧-click.
  • Change them: rotate, delete, insert blank pages, insert pages from another file, and move them earlier or later.
  • Undo anything: ⌘Z, then save.

The Organize pages grid with the showcase's pages as thumbnails, three of them selected, and the page toolbar above
Organize pages with three pages selected and the page tools in the toolbar above.

Undo that goes the distance. Each change is one step in a history you can walk backwards and forwards. The Edit menu names the step ("Undo Rotate pages"), and undo still works after you save.

Saves you can trust:

  • Incremental: the original bytes stay byte-for-byte intact.
  • Atomic: the file is written to a temporary copy, then swapped in.
  • Verified: independently checked with qpdf, on every CI run.

When open documents exceed the window width, scroll over the tab strip with the mouse wheel or trackpad, or use its horizontal scrollbar. Opening or switching to a document brings its tab into view.

Unsaved documents carry a dot on their tab, and closing or quitting asks before anything is lost. Changes are autosaved every minute. If PdfCraft ever quits unexpectedly, it offers to recover your work the next time it opens. Encrypted documents stay encrypted on disk.

The Split document dialog over the organize view, set to one page per file and reporting that it creates 13 files from 13 pages
Split document: one page per file makes 13 files.

Combine and split without losing a thing

Combine files merges any number of PDFs into one. Each file gets a bookmark, with its own bookmarks nested underneath.

Extract copies the pages you select into a new document. Split divides a document every n pages, or before the pages you choose.

Nothing quietly disappears along the way:

  • links and named destinations are rewired to the copied pages;
  • form fields stay interactive;
  • layers keep their on/off defaults;
  • attachments come along.

Every page of a combined document renders pixel-identical to its source.

pdfcraft-cli combine report.pdf appendix.pdf --out combined.pdf
pdfcraft-cli extract report.pdf --pages 1,3,5-8 --out highlights.pdf
pdfcraft-cli split   report.pdf --every 10 --out-dir parts/

Open protected documents and respect their rules

PdfCraft implements the PDF standard security handler completely:

  • every revision, from 40-bit RC4 to AES-256;
  • user and owner passwords, including Unicode passwords normalised with SASLprep;
  • crypt filters and attachment-only encryption.

Documents restricted by their author show a clear notice, and PdfCraft honours their permissions. Enter the owner password and the restrictions lift. Edits to encrypted documents are saved encrypted, under the same keys.

The Document Properties dialog on its Description tab, with editable title, author, subject and keywords, and tabs for Security, Fonts and Advanced
Document Properties, Description tab

Document Properties shows:

  • the document's title, author, subject and keywords, which you can edit;
  • the fonts it uses and whether each is embedded;
  • PDF version, page size, tags, fields, layers and attachments;
  • the full security picture: encryption method, which password opened it, and each permission.

Comments, forms, layers and attachments

The Interactive Form page with highlighted text fields, checkboxes, radio buttons, a list and a signature field, and the Fields panel listing all 13 fields and their values The Review and Markup page with highlights, shapes, ink and an APPROVED stamp under a DRAFT watermark, and the Layers panel with Draft watermark and Print-only notes
Forms: every field with its current value, field highlighting, and checkboxes, radio buttons, lists and signatures drawn the way their author designed them. Layers: switch optional content on and off and the page re-renders instantly. Comments appear as threaded conversations, and attachments can be opened or saved.

Scan pages, then read the words back before trusting them

Scan & OCR ▸ Recognize text turns a scan into searchable text — the current page, a range, or a folder of files written as searchable copies — with optional cleanup before reading (auto-rotate, deskew, denoise, binarize; word boxes map back to the original scan) and a second engine: an installed Tesseract joins the built-in one, merged per your strategy. A searchable result applies as one undoable step; the Editable text output opens the OCR Verify screen instead, where each word carries the engine's confidence as a colour, suspects are one keypress away, and corrections, a user dictionary and Re-OCR of a region or a page happen before Accept writes the new document. Scan & OCR ▸ Correct recognized text reviews any recognition there before it is applied.

The OCR Verify screen: a scanned note with each recognized word boxed in its confidence colour, the info strip reporting a 95% average confidence and one low-confidence word, and the confidence legend with its thresholds below
The OCR Verify screen: words coloured by confidence — the legend spells the thresholds out — reviewed and corrected before anything is applied.


Every tool, one keystroke away

Press ⌘K to search every tool and command, or browse the All tools catalogue. Tools that are still in development are marked with the milestone that will ship them.

The command palette searching for 'page', listing Page grid, Page labels, Rotate pages, Insert pages, Delete pages, Extract pages and more, each with the tool it belongs to The Welcome to PdfCraft home screen with recommended tools, a recent file, a privacy note, and the full tool catalogue in the side panel
The ⌘K command palette The home screen and the All tools catalogue

Runs everywhere, stays yours

  • Native on macOS, Windows, Linux and FreeBSD, and in the browser through WebAssembly, from the same Rust codebase. Windows builds come for x64, x86 and ARM64 (Windows on ARM, no emulation); every ARM64 change is tested on ARM64 hardware in CI.
  • Private by design. Documents never leave your machine. There's no account, no telemetry and no cloud processing.
  • Engine first. Parsing, rendering and editing live in reusable library crates. The interface is one swappable layer on top.
  • Scriptable. The pdfcraft-cli tool (see Built for agents, too) covers inspecting, rendering, extracting text, editing, combining, extracting pages and splitting. Robustness sweeps run on the same engine as the app.
pdfcraft-cli info  form.pdf                                  # structure as JSON
pdfcraft-cli text  paper.pdf --page 3                        # reading-order text
pdfcraft-cli edit  in.pdf --rotate 1,2:90 --delete 5 --title "Q3" --out out.pdf

Built for agents, too

Every engine feature is reachable without the GUI, through one table of JSON-Schema-described tools: open, inspect, render pages to PNG, extract and find text, rotate, delete, move and insert pages, edit bookmarks and page labels, add, reply to, restyle and delete comments (highlight a phrase just by naming it), list and fill in form fields, protect with passwords, set metadata, undo and redo, save, combine, extract and split. Three front doors share it:

  • pdfcraft-cli run, for one-off calls and JSON scripts:

    pdfcraft-cli tools                                        # every tool and its JSON Schema
    pdfcraft-cli run text_find doc=1 query=invoice            # key=value; values parse as JSON
    pdfcraft-cli run --script review.json                     # e.g. comment_add {"type": "highlight", "find": "total due"}
    pdfcraft-cli run --script steps.json --root ./work        # several steps in one session
    pdfcraft-cli run --script steps.json --report             # one JSON document: per step its number, tool, status, result or error
    

    With --root, every file the script's steps read or write stays in that directory, including the PNG a step saves with "out" (the script itself is read from wherever you name it).

  • An MCP server, for AI agents such as Claude. It is opt-in: PdfCraft never starts it on its own, and it opens no network port. It runs only while an agent launches pdfcraft-cli mcp, talks over stdin/stdout, and stops when the agent disconnects. To enable it, add it to your agent's MCP configuration:

    { "mcpServers": { "pdfcraft": { "command": "pdfcraft-cli", "args": ["mcp", "--root", "/path/to/your/pdfs"] } } }
    

    --compact shrinks the tool list the agent has to read: tools/list returns about ten core tools plus tool_search and tool_call, which find and run every other tool, so the list costs far fewer tokens. Every tool still works.

    --root confines every file the agent can read or write to one directory. Builds that should not include the server at all can use cargo build -p pdfcraft-cli --no-default-features.

  • The Rust API (pdfcraft_automation::Automation::call), for embedding.

Edits stay in memory, undoable, until doc_save. Saving to the same file appends an incremental update, so the original bytes are preserved, and the write is atomic. Unsaved changes are never discarded silently.

Driving the app itself

Start the desktop app with pdfcraft --control ~/.pdfcraft-control.json and an agent can see and operate the real interface: the widget tree with labels and positions (from the accessibility tree), clicks, typing, keys, commands, view options and screenshots. This is also off by default. It listens only on loopback, and every connection must present the random token written to that file, which only you can read.

Keep the control file in a folder only you can write, not a shared one such as /tmp: another user could create the file there first and receive your commands. pdfcraft-cli ui refuses a control file that is a symbolic link, or one that another user owns, or that another user or a group such as Administrators can read or write: on macOS, Linux and FreeBSD by its owner and mode (the app writes it with mode 600), on Windows by its owner and access list (the app gives it one with only you and SYSTEM on it). The app doesn't start if it can't write the file. On Windows, cmd.exe doesn't expand ~: use %USERPROFILE%\.pdfcraft-control.json there.

pdfcraft-cli ui --control ~/.pdfcraft-control.json inspect query=rotate      # find widgets
pdfcraft-cli ui --control ~/.pdfcraft-control.json click label="Organize pages"
pdfcraft-cli ui --control ~/.pdfcraft-control.json key key=K modifiers='["command"]'
pdfcraft-cli ui --control ~/.pdfcraft-control.json command id=comment.square   # pick a tool, then draw:
pdfcraft-cli ui --control ~/.pdfcraft-control.json drag from='[400,300]' to='[600,420]'
pdfcraft-cli ui --control ~/.pdfcraft-control.json screenshot --out window.png
pdfcraft-cli ui --control ~/.pdfcraft-control.json resize width=1200 height=800
pdfcraft-cli ui --control ~/.pdfcraft-control.json focus label="Read"
pdfcraft-cli ui --control ~/.pdfcraft-control.json inspect focused=true
pdfcraft-cli ui --control ~/.pdfcraft-control.json quit

ui.panel opens, closes or sizes a side panel: {"panel":"tools"|"side","open":true|false,"width":320}. tools is the Tools panel and side the panel the rail opens (reopening it shows the one open last). width is clamped to the panel's limits (Tools 240–520, side panel 260–520 points). ui.dock.reset resets the side panels: Tools open on the left, default widths. The control channel accepts these methods directly; ui.command also accepts {"id":"ui.panel","params":{...}}. Saved preferences keep the Tools side, the open panels and their widths. Invalid requests return an error without changing the document or the panels.

resize requests a native inner-window size in logical points (each dimension must be between 320 and 8192); the window manager may constrain it. state reports the observed window.width, window.height and window.pixels_per_point. focus accepts exactly one widget id or unique enabled, focusable label; subsequent key requests traverse or activate the actual widgets. inspect includes focusability and accepts a focused filter. quit takes no parameters: clean documents exit normally, while unsaved edits or typing open the existing Save/Don't save/Cancel prompt and return quitting: false, needs_confirmation: true. It never silently discards work. Window resizing and application quit are native-only.


How it's built

PdfCraft is a Cargo workspace of focused crates, layered so the core never depends on the UI:

Crate What it does
pdfcraft-filters Every PDF stream filter (Flate, LZW, ASCII85, RunLength, predictors), encode and decode, property-tested
pdfcraft-crypt The standard security handler: RC4, AES-128/256, revisions 2–6, permissions
pdfcraft-cos The PDF object layer: tolerant parsing, repair, copy-on-write edits, incremental and full writing
pdfcraft-organize Page operations, combine / extract / split, bookmarks, page labels, document information
pdfcraft-fonts Font metrics and encodings for generated appearances
pdfcraft-annot Comments: builders and appearance streams for notes, text markup, shapes, ink and text boxes; replies, status, edits
pdfcraft-forms Interactive forms: the field model, filling with regenerated appearances, Clear form
pdfcraft-render Rendering, inspection and text extraction with reading order
pdfcraft-engine The façade every frontend uses: sessions, edits, undo, saving, the tool catalogue
pdfcraft-automation Agent control: the headless tool table, pdfcraft-cli run, and the opt-in MCP server
pdfcraft-ui-egui The desktop and web interface

Quality gates. Every change passes the same automated checks:

  • formatting, and Clippy with warnings as errors;
  • 200+ unit, property and UI tests;
  • crate-layering rules and a WebAssembly build check;
  • an asset-licence audit.

On top of those, two corpus sweeps run over real-world files:

  • Opening and rendering: of the 983 pdf.js test files, 963 open and render cleanly, with 0 crashes.
  • Open, edit and save round trips: 958 succeed.

The output is verified against independent implementations: hayro and qpdf on every CI run, and poppler over the corpus on demand (cargo xtask text-oracle).

PdfCraft is a clean-room implementation. Its behaviour comes from the ISO 32000 specification and black-box observation, never from anyone else's code. Every icon, font and image is openly licensed and listed in ATTRIBUTION.md.

Get started

Building needs Rust 1.95 or later.

git clone https://github.com/storytold/pdfcraft
cd pdfcraft
cargo xtask models                                # fetch the OCR models Scan & OCR needs (release builds include them)
cargo run --release -p pdfcraft -- some.pdf     # desktop app
cargo xtask demo-pdf                              # build the showcase PDF used in these screenshots
cargo xtask screenshots                           # regenerate every screenshot in this README

The interface language is chosen in Menu → Edit → Preferences… (Command-comma on macOS, Ctrl-comma elsewhere, also with no document open; Auto follows the system language; see docs/localization.md) and saved. Japanese covers commands, dialogs, panels and keyboard shortcuts. Command search accepts the translated label, the English label and the stable command id; filenames, PDF contents, author names, custom action names and error details from the engine or the operating system keep their own text.

Japanese fonts come from craft-fonts, an optional build input that every release includes. To build with them (Japanese interface text, and Japanese text in edited PDFs):

git clone https://github.com/storytold/craft-fonts ../craft-fonts
CRAFT_FONTS_DIR=../craft-fonts cargo run --release -p pdfcraft -- some.pdf

Each GitHub release has ready-made builds for macOS, Windows, Linux (AppImage, Flatpak, .deb, .rpm and a tarball), FreeBSD and the web; see Downloads. On Gentoo, the community ::snakebyte overlay packages the Linux release as app-text/pdfcraft-bin (not maintained by the PdfCraft team):

eselect repository add snakebyte git https://github.com/switch87/snakebyte-overlay.git
emaint sync -r snakebyte
echo 'app-text/pdfcraft-bin ~amd64' >> /etc/portage/package.accept_keywords/pdfcraft
emerge --ask app-text/pdfcraft-bin

Logs, environment variables and other development notes are in docs/development.md.

What's next

PdfCraft is young and moving fast. The aim is a workbench where you can view, organize, annotate, fill, sign and edit PDFs, for professional and everyday workflows.

Where it stands (October 2026), honestly: PdfCraft is alpha. Most essential offline PDF features exist in some form (57% of the features tracked in docs/target-app-parity.md, 94% of core essentials). For everyday work (viewing, commenting, filling and signing forms, organizing pages) readiness is about 55%; across all professional workflows, about 49%; for someone who only needs the essentials, about 66%. Every everyday workflow can be completed, but converting and sharing is weak: no office-document-to-PDF, and .docx export that loses layout.

  • Good today: viewing and search; organizing, combining and splitting; most kinds of comment; filling and authoring forms (with sandboxed JavaScript); passwords, redaction and sanitizing; basic digital signatures; printing; the Accessibility Checker; agent control through the CLI and MCP.
  • Still borrowed: pages are drawn by the hayro crate while our own renderer is built.
  • Thin or missing: reliable editing of existing text (especially CJK and right-to-left), OCR beyond Latin script, office document import/export, signature tokens and online long-term validation, Preflight and PDF/X/UA, printing from the web build, physical printer fidelity, and full XFA forms.
  • Hardening: fuzzing still turns up crashes and hangs on hostile files; each one is fixed with a regression test. Quality has not yet been benchmarked side by side.

Next, in order: office-document-to-PDF and a .docx export that keeps layout, the reported bugs and the Chinese interface font, a fidelity harness against a reference renderer, editing existing content, then professional workflows (OCR, office formats, Preflight, signatures, accessibility tagging) and 1.0 polish.

The summary is in ROADMAP.md; the full assessment by dimension and area is in docs/target-app-parity.md, the ranked gaps in docs/gaps.md, and the milestones in docs/roadmap.md.


Downloads

New to PdfCraft? Download it from the PdfCraft page on getartcraft.com. That's the easiest way to install it.

Want a specific build or format? On GitHub, the latest release has every build listed below, and all releases has earlier versions and their notes. <ver> in the file names is the version number, and SHA256SUMS.txt lists a checksum for every file.

Windows

Build Installer Portable
x64 (64-bit Intel/AMD) pdfcraft-<ver>-windows-x64.msi pdfcraft-<ver>-windows-x64-portable.zip
arm64 (Snapdragon and other ARM PCs) pdfcraft-<ver>-windows-arm64.msi pdfcraft-<ver>-windows-arm64-portable.zip
x86 (32-bit) pdfcraft-<ver>-windows-x86.msi pdfcraft-<ver>-windows-x86-portable.zip

Installers and executables are code-signed.

The portable zip runs from any folder, a USB stick included. Its portable.txt keeps the settings, logs and crash recovery in a PdfCraftData folder next to pdfcraft.exe, so nothing is written to %APPDATA%; delete that file to use the normal per-user folders. Windows doesn't offer the portable copy as a default PDF app on its own, since it registers nothing; portable.txt has the PowerShell lines that register it for your user only, and how to undo them.

The MSI installs for your account only by default, without administrator privileges. Choose "Everyone on this computer" on its first page, or pass ALLUSERS=1 from an elevated terminal, to install for all users. It adds "Edit with PdfCraft" and "Combine files in PdfCraft" (select several PDFs: they land in the Combine files tab of the running PdfCraft) to the right-click menu of PDF files and "Create PDF with PdfCraft…" to the right-click menu of images (.png .jpg .jpeg .tif .tiff .gif .bmp .jp2 .j2k .jpx) in File Explorer (on Windows 11, under "Show more options"), without changing which app opens them by default. For unattended deployment without a desktop shortcut (add ALLUSERS=1, from an elevated terminal, for an all-users install):

msiexec /i "pdfcraft-<ver>-windows-x64.msi" /qn /norestart INSTALLDESKTOPSHORTCUT=0
Property =0 leaves out
INSTALLDESKTOPSHORTCUT the desktop shortcut
INSTALLPDFCONTEXTMENU "Edit with PdfCraft" and "Combine files in PdfCraft" on PDF files
INSTALLIMAGECONTEXTMENU "Create PDF with PdfCraft…" on images

All three are on for a first install. An upgrade keeps what the installed version has: a shortcut or menu entry that is there stays, and one that is missing (left out at install, or a desktop shortcut someone deleted) stays missing, so you don't need to pass them again. A value on the command line always wins: =1 puts one back and =0 removes it. Upgrading from a release that didn't have a menu yet (0.6.0 and earlier for the PDF menu, 0.2.1 and earlier for the image menu) adds it, as a first install would. Use the MSI for your architecture. Per-user installation overrides are not supported.

To install somewhere other than the default ArtCraft\PdfCraft folder, change the folder on the welcome screen (type it, or Browse…) or pass it on the command line: INSTALLFOLDER="D:\Apps\PdfCraft". It is installed for whoever the first screen chose (ALLUSERS=1 on the command line for everyone). An upgrade keeps the folder the installed version uses unless the command line gives another one.

Pin the checksum, not just the version. Release candidates of a version share its MSI version (MSI versions are numbers only, so 1.2.3-rc.1 and 1.2.3 are both 1.2.3), and the installer lets an MSI of the same version replace the installed one without asking. Two different 0.7.1 MSIs can't be told apart by version, so if your deployment tool checks the file, pin its SHA-256 from SHA256SUMS.txt (Get-FileHash <file> -Algorithm SHA256).

Signing identities. The Windows MSIs and both executables are signed through Azure Trusted Signing with a certificate issued to Learning Machines Inc (Atlanta, Georgia, US). The macOS app and command-line tool are signed with the Developer ID Learning Machines LLC (DJ6XS33FX8) and notarized. The MSI's manufacturer, shown as the publisher in Installed apps, is Learning Machines LLC.

macOS

Build File Notes
App, universal (Apple silicon + Intel) pdfcraft-<ver>-macos-universal.dmg Signed and notarized
Command-line tool, universal pdfcraft-cli-<ver>-macos-universal.zip Signed and notarized

Linux

Format x86_64 aarch64 (ARM64) Notes
AppImage pdfcraft-<ver>-linux-x86_64.AppImage pdfcraft-<ver>-linux-aarch64.AppImage Runs anywhere; updates itself with AppImageUpdate (.zsync files)
Flatpak pdfcraft-<ver>-linux-x86_64.flatpak pdfcraft-<ver>-linux-aarch64.flatpak Sandboxed; flatpak install --user <file>
Debian/Ubuntu pdfcraft-<ver>-linux-x86_64.deb pdfcraft-<ver>-linux-aarch64.deb
Fedora/RHEL/openSUSE pdfcraft-<ver>-linux-x86_64.rpm pdfcraft-<ver>-linux-aarch64.rpm
Tarball pdfcraft-<ver>-linux-x86_64.tar.gz pdfcraft-<ver>-linux-aarch64.tar.gz Unpack anywhere
Command-line tool pdfcraft-cli-<ver>-linux-x86_64.tar.gz pdfcraft-cli-<ver>-linux-aarch64.tar.gz pdfcraft-cli alone (and its opt-in MCP server), for servers, CI and agents

RISC-V (riscv64) builds come as tarballs only: pdfcraft-<ver>-linux-riscv64.tar.gz and pdfcraft-cli-<ver>-linux-riscv64.tar.gz. They are cross-compiled and need glibc 2.39 or newer (Ubuntu 24.04+, Debian 13+).

Every other Linux build needs glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+, Fedora 36+, RHEL 10).

FreeBSD

Build File
x86_64 pdfcraft-<ver>-freebsd-x86_64.tar.gz

Web (WebAssembly)

Build File Notes
Static site pdfcraft-web-<ver>.zip Runs in a modern browser; host it on any static server

The Crafting Apps

PdfCraft is one of the Crafting Apps: free, open-source creative tools from the ArtCraft team, each written from scratch in Rust and each able to stand on its own.

App What it's for Code Learn more
PhotoCraft Image editing: layers, masks, type and real PSD files GitHub Website
VectorCraft Vector illustration GitHub Website
FilmCraft Video editing, color and sound GitHub Website
LightCraft Photo library and raw development GitHub Website
PdfCraft Reading, organizing and protecting PDFs GitHub Website
EffectCraft Motion graphics and visual effects GitHub Website
DesignCraft Page layout and publishing GitHub Website
FigCraft Interface design and prototyping GitHub Website
WordCraft Word processing and documents GitHub Website
SoundCraft Audio recording and editing GitHub Website
DeckCraft Presentations and slide decks GitHub Website
CADCraft Computer-aided design GitHub Website
GridCraft Spreadsheets and data GitHub Website
TextureCraft 3D texture painting GitHub Website
Craft Anything See how any software works, then build your own GitHub Website
SolidCraft Parametric 3D CAD by Tangency Labs (community app) GitHub

And ArtCraft itself, our AI image and video studio for artists who want real control.


Join the ArtCraft community on Discord

Come make things with us

Our Discord is where artists of every kind hang out: people who paint, shoot, draw, cut film, set type, and people still figuring out what they like to make. Share what you're working on, ask for help, tell us what's broken, or tell us what you wish these tools could do. Whatever your medium and however long you've been at it, you're welcome here.

discord.gg/artcraft · getartcraft.com · The Crafting Apps · PdfCraft


License and credits

PdfCraft is dual-licensed under MIT or Apache-2.0, at your option. Copyright (c) 2026 ArtCraft Team and the PdfCraft contributors. Required notices are in NOTICE.

Bundled fonts, icons, images and other assets keep their own open licenses; each one is listed with its author, source and license in ATTRIBUTION.md. Release builds also embed the Japanese fonts of craft-fonts (SIL Open Font License 1.1).

The ArtCraft name, wordmark and logos in docs/brand/ are trademarks of the ArtCraft Team and are not covered by this license. They may be used only unmodified, and only as part of this repository and PdfCraft, under docs/brand/LICENSE-brand.txt. Forks and modified versions must remove them.

ArtCraft
Made by the ArtCraft team and community.

The Tools panel sits on the left, or on the right with Preferences ▸ Tools panel side. The rail stays at the right edge and opens one side panel beside it. Drag a panel's inner edge to resize it; widths are remembered. F4 shows or hides the side panel and Shift+F4 the Tools panel (also in the View menu); View ▸ Reset side panels restores the default arrangement.

Languages
Rust 99.3%
PowerShell 0.3%
HTML 0.2%
Shell 0.1%