| name | process-pdf |
| description | Convert one page of a PDF into a PNG sized for floor-map SVG backgrounds. Use when extracting a specific floor / page from a multi-page architectural plan, converting PDF to PNG for an SVG background, or the user says "convert pdf", "extract page", "pdf to png". Requires `poppler` (pdftoppm + pdftotext) on PATH; the skill never installs anything itself.
|
process-pdf
Convert a single page of a PDF into a PNG sized for the floor-map
tracing flow. The agent's office floors validate contract requires
SVGs whose viewBox is 0 0 1920 1080; this skill produces a
1920-wide PNG by default so the output drops straight into
Inkscape as the background layer.
Why this exists
Inkscape's PDF-as-vector import produces unusable SVGs for tracing
(architect plans yield ~100k vector elements; Inkscape's Plain SVG
export then breaks the XML somewhere in the mountain). The supported
path is to convert the PDF page to a raster PNG, embed that as the
background layer in the SVG, and trace <rect class="seat"> /
<polygon class="room"> over it. This skill is the conversion step.
See docs/tracing-guide.md for the full tracing flow.
Prerequisites
The skill calls out to poppler's pdftoppm (extract + scale) and
pdftotext (label-based page lookup). It never installs them.
| Platform | Install command |
|---|
| macOS (Homebrew) | brew install poppler |
| Debian / Ubuntu | apt install poppler-utils |
| Fedora | dnf install poppler-utils |
If either binary is missing the skill exits 2 with a hint that
matches the platform.
Usage
bash .claude/skills/process-pdf/scripts/pdf-to-png.sh \
<pdf> <page-or-label> [out-png] [--width N] [--dpi N]
Two ways to pick the page:
- Page number — pass a positive integer (1-based).
- Text label — pass any string; the skill scans the PDF with
pdftotext and uses the page that contains it. Errors with a
candidate listing if zero or more than one page matches, so
selection is always unambiguous.
Defaults:
out-png → <basename-of-pdf>-page<N>.png in the current
directory.--width → 1920 (matches the floor SVG viewBox).--dpi → 150 (good enough for tracing without bloating
the file).
Examples
Canonical floor-tracing case — find the "Floor 5" page in a
multi-floor pack and write a 1920-wide PNG:
bash .claude/skills/process-pdf/scripts/pdf-to-png.sh \
~/Downloads/tipalti-floors.pdf "Floor 5" /tmp/floor5.png
Direct page number when you already know it:
bash .claude/skills/process-pdf/scripts/pdf-to-png.sh \
~/Downloads/tipalti-floors.pdf 7 /tmp/floor5.png
Custom width (e.g. for a higher-res render outside the
floor-tracing flow):
bash .claude/skills/process-pdf/scripts/pdf-to-png.sh \
plans.pdf 3 cover.png --width 3840 --dpi 300
Output
On success: prints the absolute path of the produced PNG to stdout
and exits 0. So callers can capture it:
out=$(bash .claude/skills/process-pdf/scripts/pdf-to-png.sh \
~/Downloads/tipalti-floors.pdf "Floor 5" /tmp/floor5.png)
file "$out"
Errors and exit codes
0 — success.1 — usage error (bad flags, missing positional args).2 — environment error (poppler missing, PDF not found, label
matches zero or multiple pages, page number out of range).
Stderr always includes a hint: line with the next concrete
action.
Out of scope
- PDF→SVG vector extraction (the failure mode that prompted this
skill).
- Auto-install of poppler.
- ImageMagick / sips fallbacks. Poppler is the single supported
toolchain.
- Multi-page batch extract.
- OCR.
