# bim-pdf

> PDF analysis and manipulation for AEC workflows. Zero external dependencies — pure Go. Handles Revit-exported PDFs natively.

## When to use bim-pdf

Use bim-pdf when you have a PDF that came from Revit, or any AEC workflow that needs to split, collect, inspect, or enrich PDFs without a GUI. bim-pdf understands Revit's specific PDF encoding: BMC/BDC tagged content blocks, Type0 Identity-H fonts, and Adobe PDF Library 18.0.5 structure.

## Requirements

None for most verbs. `render` requires Ghostscript installed and on PATH.

## Revit PDF specifics

Revit exports PDFs with:
- **Producer:** Adobe PDF Library 18.0.5, PDF version 1.6
- **BIM element tags:** every visible element is wrapped in a BMC/BDC content block with a tag encoding its ElementId. `bim pdf marked` extracts these.
- **Font encoding:** Type0 Identity-H. Standard PDF text extractors return garbage — dimensions, room labels, and title block text are unreadable without ToUnicode CMap decoding. `bim pdf text` handles this.
- **Page labels:** Revit writes sheet numbers as PDF page labels. `bim pdf pages` returns these.
- **Combined export:** Revit exports all selected sheets into one combined file. A 100-sheet set is one 100-page PDF. Use `bim pdf page split` to separate.

## Verb reference

### Inspection
- `bim pdf info <file>` — page count, PDF version, producer, XMP namespaces, `has_bim_tags` flag
- `bim pdf pages <file>` — per-page dimensions (mm), OCG layer list, page labels (sheet numbers)
- `bim pdf text <file> [--page N]` — text with coordinates; ToUnicode CMap decoded
- `bim pdf marked <file> [--page N] [--tag regex]` — extract BMC/BDC tagged blocks with bounds; each block has `tag`, `element_id`, `bounds [x0,y0,x1,y1]`
- `bim pdf annot list <file> [--page N]` — annotation list (highlights, comments, stamps)

### Page operations
- `bim pdf page split <file> [--out-dir DIR] [--span N] [--by-bookmark]` — split into per-page or per-span PDFs
- `bim pdf page merge files... --out OUT` — merge multiple PDFs into one
- `bim pdf page collect <file> --pages 1,3,5-8 [--out OUT]` — extract specific pages
- `bim pdf page rotate <file> --degrees 90|180|270 [--pages RANGE] [--out OUT]`
- `bim pdf page crop <file> --box x0,y0,x1,y1 [--out OUT]` — crop to bounding box in PDF user units

### Modification
- `bim pdf optimize <file> [--out OUT]` — reduce file size without re-rendering
- `bim pdf stamp add <file> --text STR [--opacity 0.3] [--rotation 45] [--out OUT]` — watermark
- `bim pdf stamp remove <file> [--out OUT]`
- `bim pdf security encrypt <file> --user-password STR --owner-password STR [--out OUT]`
- `bim pdf security decrypt <file> --password STR [--out OUT]`
- `bim pdf annot remove <file> [--page N] [--type TYPE] [--out OUT]`

### Forms
- `bim pdf form fields <file>` — list AcroForm fields
- `bim pdf form fill <file> data.json [--out OUT]` — fill fields from JSON map
- `bim pdf form flatten <file> [--out OUT]` — make non-editable

### Attachments & BIM packages
- `bim pdf attach list <file>` — list embedded file attachments
- `bim pdf attach extract <file> [--out-dir DIR]`
- `bim pdf attach add <file> attachment [--out OUT]`
- `bim pdf package <file> metadata [--out OUT] [--no-marks]` — embed one or more JSON sidecars as PDF/A-3 associated files; creates a PDF–BIM Package
- `bim pdf enrich <file> sidecar [--tag-pattern STR] [--id-field STR]` — join marked output with a JSON lookup table; adds BIM properties alongside element bounds

### Bookmarks
- `bim pdf bookmark list <file>`
- `bim pdf bookmark export <file> [--out OUT]` — export bookmark tree as JSON
- `bim pdf bookmark import <file> bookmarks.json [--out OUT]`

### Rendering & viewer
- `bim pdf render <file> [--out-dir DIR] [--page N] [--format png|jpg] [--dpi 150]` — rasterize pages (requires Ghostscript)
- `bim pdf viewer <file> [--port 7701]` — local HTTP viewer for PDF–BIM packages; clicking an element zooms Revit to it (requires bim-revit add-in running)

## Workflow patterns

**Inspect a Revit export before processing:**
```
bim pdf info drawings.pdf
bim pdf pages drawings.pdf
```

**Split combined sheet set and collect by discipline:**
```
bim pdf page split drawings.pdf --out-dir ./sheets/
bim pdf page collect drawings.pdf --pages 12-24 --out structural.pdf
```

**Extract element IDs and resolve via Revit:**
```
bim pdf marked drawings.pdf | bim revit exec --file resolve-ids.cs
```

**Build a PDF–BIM Package for delivery:**
```
bim pdf marked drawings.pdf > marks.json
bim pdf package drawings.pdf marks.json --out delivery.pdf
```

**QA: check sheet count and first-page label:**
```
bim pdf info drawings.pdf
bim pdf pages drawings.pdf | head -1
```

## Gotchas

- Output file defaults to `<input>-out.<ext>` when `--out` is omitted on destructive verbs
- `marked` returns `null` element_id for linked-model elements (not in the host document)
- `render` exits with error if Ghostscript is not on PATH; check with `bim doctor --json`
- `enrich` matches by element_id from `marked` output — sidecar must have a matching id field
- `viewer` is long-running (HTTP server); it does not exit until killed. Use `--port` to avoid conflicts.
- `package` embeds files in PDF/A-3 format; not all PDF viewers display attachments

## Related pages
- https://bimcli.com/revit-pdf-export — workflow guide: split, collect, extract
- https://bimcli.com/revit/llms.txt — revit driver docs (for pairing with exec)