nils-image-processing 0.3.9

CLI crate for nils-image-processing in the nils-cli workspace.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# image-processing

## Overview
`image-processing` is a batch image CLI with two execution paths:
- Rust SVG path:
  - `convert --from-svg <path> --to png|webp|svg --out <file>`
  - `svg-validate --in <svg> --out <svg>`
- Legacy transform path (ImageMagick):
  - `auto-orient|convert|resize|rotate|crop|pad|flip|flop|optimize`

`generate` has been removed. Use intent -> SVG -> `svg-validate` -> `convert --from-svg` instead.

## Usage
```text
Usage:
  image-processing <subcommand> [flags]

Subcommands:
  info | svg-validate | auto-orient | convert | resize | rotate | crop | pad | flip | flop | optimize

Help:
  image-processing --help
```

## Commands
- `info`: Probe inputs and emit metadata summary (no output mode).
- `svg-validate`: Validate + sanitize one SVG input into one SVG output.
- `convert`: Convert image formats.
  - Legacy mode: `--in ... --to png|jpg|webp`.
  - SVG mode: `--from-svg <path> --to png|webp|svg --out <file>` (optional `--width`/`--height` for raster outputs).
- `resize`: Resize by `--scale`, `--width`/`--height`, or `--aspect` + `--fit` (`contain|cover|stretch`).
- `rotate`: Rotate by degrees; requires `--degrees`.
- `crop`: Crop by `--rect`, `--size`, or `--aspect` (exactly one).
- `pad`: Pad to a target size; requires `--width` and `--height`.
- `flip`: Apply ImageMagick `-flip`.
- `flop`: Apply ImageMagick `-flop`.
- `optimize`: Optimize `jpg` or `webp` outputs; supports `--quality`, `--lossless`, `--no-progressive`.

## Common flags
- Inputs (legacy transform commands only): `--in <path>` (repeatable, required), `--recursive`, `--glob <pattern>` (repeatable)
- Source SVG mode: `--from-svg <path>` (convert only)
- Output mode: `--out <file>`, `--out-dir <dir>`, or `--in-place` (requires `--yes`)
- Output controls: `--overwrite`, `--dry-run`, `--json`, `--report`
- Transform options: `--no-auto-orient`, `--strip-metadata`, `--background <color>`

## `--from-svg` contract (v1)
- Allowed only on `convert`.
- Required: `--to png|webp|svg`, `--out <file>`.
- Forbidden with `--from-svg`: `--in`, `--recursive`, `--glob`, `--out-dir`, `--in-place`.
- `--out` extension must match `--to`.
- Optional: `--width`/`--height` for raster output sizing (`png`/`webp`); a single side keeps aspect ratio.
- `--to svg` does not support `--width`/`--height`.
- This path is Rust-backed (`usvg`/`resvg`) and does not require ImageMagick.

## `svg-validate` contract
- Required: exactly one `--in <svg>` and `--out <svg>`.
- Forbidden: `--from-svg`, `--recursive`, `--glob`, `--out-dir`, `--in-place`.
- Output is deterministic for identical input.

## Examples
```bash
mkdir -p out/plan-doc-examples
```

```bash
cargo run -p nils-image-processing -- svg-validate \
  --in crates/image-processing/tests/fixtures/llm-svg-valid.svg \
  --out out/plan-doc-examples/llm.cleaned.svg
```

```bash
cargo run -p nils-image-processing -- convert \
  --from-svg out/plan-doc-examples/llm.cleaned.svg \
  --to png \
  --out out/plan-doc-examples/llm.png \
  --json
```

```bash
cargo run -p nils-image-processing -- convert \
  --from-svg crates/image-processing/tests/fixtures/sample-icon.svg \
  --to webp \
  --out out/plan-doc-examples/sample.webp \
  --width 512 \
  --json
```

## Exit codes
- `0`: Success with no item errors.
- `1`: Runtime failure or one-or-more items failed.
- `2`: Usage/validation error.

## Dependencies
- `convert --from-svg` and `svg-validate`: no external binary dependency (Rust backend).
- Legacy transform subcommands: ImageMagick (`magick`, or `convert` + `identify`).
- Optional: `cjpeg`/`djpeg` for JPEG optimize, `cwebp`/`dwebp` for WebP optimize.

## Docs

- [Docs index](docs/README.md)
- [LLM SVG workflow runbook](docs/runbooks/llm-svg-workflow.md)