# bim-image

> Image format conversion, metadata, annotation, and QA for AEC workflows. Handles site photos, rendered views, and HEIC output from phones and drones.

## When to use bim-image

Use bim-image when you have images from site visits (phone HEIC), renderings (PNG/JPG), or drawing scans (TIFF) and need to normalize formats, extract GPS or capture metadata, annotate for review, diff revisions, or bundle images into a PDF.

## Requirements

- `sibling:exiftool` — required for `exif` verbs. Vendored with bim-cli.
- `sibling:heif-convert` — required for HEIC/HEIF decode. Vendored with bim-cli.

Check with `bim doctor --json` — both should show `ok: true`.

## Supported formats

Input: `.png`, `.jpg`/`.jpeg`, `.tif`/`.tiff`, `.webp`, `.bmp`, `.heic`, `.heif`
Output: `png`, `jpg`, `tiff`, `bmp` (HEIC output not supported — convert from HEIC only)

Detection is by magic bytes, not extension. Renamed files are handled correctly.

## Verb reference

### Inspection
- `bim image info <file>` — format, dimensions (px), color model, DPI, EXIF presence flag

### Conversion & resizing
- `bim image convert --in FILE --out FILE [--format png|jpg|tiff|bmp] [--quality 90]` — convert format; format inferred from `--out` extension if omitted
- `bim image resize --in FILE --out FILE [--width N] [--height N] [--max-edge N] [--fit contain|cover|stretch] [--rotate 90|180|270] [--auto-orient] [--quality 90]`
  - `--max-edge` caps the longest edge, scales both dimensions proportionally — use for consistent thumbnail sizes
  - `--auto-orient` reads EXIF Orientation, rotates pixels, strips the tag from output (fix upside-down phone photos)

### EXIF metadata
- `bim image exif read --in FILE` — GPS, datetime, make/model, orientation, dimensions as JSON
- `bim image exif strip --in FILE --out FILE` — write metadata-free copy (for delivery or privacy)
- `bim image exif set --in FILE --out FILE --tag TAG --value VALUE` — set one EXIF tag (batch mode in v0.2)

### Annotation
- `bim image annotate --in FILE --out FILE --ops JSON_ARRAY [--quality 90]` — draw onto an image

`--ops` is a JSON array of drawing operations:
```json
[
  {"type":"rect","x":100,"y":200,"width":300,"height":150,"color":"#ff0000","linewidth":2,"filled":false},
  {"type":"line","x1":0,"y1":0,"x2":100,"y2":100,"color":"#00ff00","linewidth":1},
  {"type":"arrow","x1":50,"y1":50,"x2":200,"y2":200,"color":"#0000ff","linewidth":2},
  {"type":"text","x":100,"y":100,"text":"Room 101","color":"#ffffff","size":24}
]
```

Pass `"-"` to read NDJSON ops from stdin (one op per line).

### Diff
- `bim image diff --a BASELINE --b CANDIDATE [--out DIFF_IMAGE] [--threshold 0.1] [--fail-over RATIO]`
  - `--threshold` — per-pixel color distance 0–1; pixels above this are counted as changed
  - `--fail-over` — exit code 1 when changed pixel ratio exceeds this value (e.g. `0.01` = fail if >1% changed)
  - `--out` — write diff image with changed pixels highlighted in red

### PDF wrapping
- `bim image to-pdf --out FILE [--page-size A4|letter] [--dpi 300] image1 image2 ...` — wrap images as pages in a new PDF; positional args are input files

## Workflow patterns

**Normalize HEIC photos from site visit:**
```
bim image info photo.heic
bim image convert --in photo.heic --out photo.jpg --quality 85
bim image resize --in photo.jpg --out photo-web.jpg --max-edge 1920 --auto-orient
```

**Strip metadata before sending to client:**
```
bim image exif strip --in photo.jpg --out photo-clean.jpg
```

**Annotate a rendered view for review:**
```
bim image annotate --in render.png --out render-markup.png --ops '[{"type":"rect","x":400,"y":300,"width":200,"height":100,"color":"#ff0000","linewidth":3,"filled":false},{"type":"text","x":405,"y":295,"text":"revise window","color":"#ff0000","size":18}]'
```

**QA diff between two renders:**
```
bim image diff --a baseline.png --b revised.png --out delta.png --fail-over 0.02
```

**Bundle site photos into a PDF for submittal:**
```
bim image to-pdf --out site-photos.pdf --page-size A4 photo1.jpg photo2.jpg photo3.jpg
```

## Gotchas

- HEIC files require `heif-convert` sibling; verify with `bim doctor --json` before processing HEIC
- `--auto-orient` modifies pixel data — use it once at import, not repeatedly
- `annotate --ops` expects a JSON array string, not a file path; for large op lists, use stdin: `cat ops.json | bim image annotate --in FILE --out FILE --ops -`
- `diff` exit code 1 means pixel ratio exceeded `--fail-over` threshold — not an error in the tool itself
- `to-pdf` uses `--dpi` as a resolution hint for page sizing, not for rasterization quality
- Color values in annotate ops are HTML hex (`#rrggbb`) — alpha not supported