media server 3/3 - vips

packages/media/cpp/.gitignore

@@ -1,5 +1,4 @@
 build/
-dist/
 .cache/
 CMakeUserPresets.json
 .vs/

packages/media/cpp/README.md

@@ -88,15 +88,108 @@ Sharp wraps libvips: **decode → process → encode**. We do the same with `vip
 - **HTTP `serve`**: cpp-httplib default thread pool (`CPPHTTPLIB_THREAD_POOL_COUNT` — see upstream `httplib.h`).
 - **libvips**: processing is thread-safe per image; configure process-wide concurrency with `VIPS_CONCURRENCY` (or `vips_concurrency_set` in code later if needed).
 
-## CLI overview
+## CLI examples
+
+Paths below use Unix style; on Windows run `dist\media-img.exe` and use `.\` or full paths as needed.
+
+### Help and version
 
 ```bash
-media-img resize --help
-media-img serve --help
-media-img ipc --help
+./dist/media-img --help
+./dist/media-img resize --help
+./dist/media-img -v
 ```
 
-`kbot` subcommand forwards to **`KBOT_EXE`** (optional).
+### `resize` — fit inside a box (default), write WebP / AVIF by extension
+
+```bash
+# Max 800×600, stay inside the box, Lanczos3 (default), write JPEG quality 85 (default)
+./dist/media-img resize photo.jpg out.jpg --max-width 800 --max-height 600
+
+# Same, explicit quality
+./dist/media-img resize photo.jpg out.jpg --max-width 800 --max-height 600 -q 90
+
+# WebP output (quality applies)
+./dist/media-img resize photo.jpg thumb.webp --max-width 400 --max-height 400 -q 82
+
+# AVIF output (quality applies; needs HEIF/AVIF support in your libvips build)
+./dist/media-img resize photo.png out.avif --max-width 1200 --max-height 1200 -q 50
+
+# Force output format when the path has no extension you trust
+./dist/media-img resize in.tif /tmp/out --format webp --max-width 512
+```
+
+### `resize` — square images (1:1)
+
+Use the **same** `--max-width` and `--max-height` (that value is the square side in pixels). Pick **`--fit`**:
+
+| `fit` | Result |
+|-------|--------|
+| **`cover`** | Fills the square; crops overflow (default crop: `--position centre`, or `attention` / `entropy` for smart crop). |
+| **`contain`** | Full image inside the square; **letterboxing** on two sides if needed (`--background`). |
+| **`fill`** | Stretches to the square (ignores aspect ratio). |
+
+```bash
+# 512×512 crop-to-square (avatars, thumbnails)
+./dist/media-img resize portrait.jpg avatar.jpg --fit cover --max-width 512 --max-height 512
+
+# 1080×1080 WebP, smart crop on subject
+./dist/media-img resize product.png grid.webp --fit cover --max-width 1080 --max-height 1080 --position attention -q 85
+
+# Square canvas, no crop — padded bands with a colour
+./dist/media-img resize panoramic.jpg square.jpg --fit contain --max-width 800 --max-height 800 --background '#111111'
+
+# Exact square by stretching (rare)
+./dist/media-img resize any.jpg out.jpg --fit fill --max-width 256 --max-height 256
+```
+
+**REST / IPC JSON:** e.g. `"max_width": 512, "max_height": 512, "fit": "cover", "position": "attention"`.
+
+### `resize` — cover (crop), contain (letterbox), rotate / flip
+
+```bash
+# Cover: fill 1200×630, crop centre (use --position attention for smart crop)
+./dist/media-img resize wide.jpg social.jpg --fit cover --max-width 1200 --max-height 630
+
+# Contain: fit inside 800×600 canvas, letterbox with a background
+./dist/media-img resize logo.png padded.png --fit contain --max-width 800 --max-height 600 --background '#1a1a1a'
+
+# EXIF autorotate (default), then rotate 90° CCW, vertical flip
+./dist/media-img resize img.jpg rotated.jpg --max-width 1024 --rotate 90 --flip
+```
+
+### `serve` — HTTP REST
+
+```bash
+# Default: http://127.0.0.1:8080 — GET /health, POST /v1/resize with JSON body
+./dist/media-img serve --host 127.0.0.1 -p 8080
+```
+
+Example resize request (paths must be readable/writable by the server process):
+
+```bash
+curl -s http://127.0.0.1:8080/health
+curl -s -X POST http://127.0.0.1:8080/v1/resize \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"/path/in.png","output":"/path/out.webp","max_width":400,"quality":80}'
+```
+
+### `ipc` — one JSON line per connection (TCP; Unix socket on Linux/macOS)
+
+```bash
+./dist/media-img ipc --host 127.0.0.1 -p 9333
+# elsewhere: send a single line, read one line back, e.g.
+# {"input":"/tmp/a.jpg","output":"/tmp/b.webp","max_width":320,"format":"webp"}
+```
+
+### `kbot` — forward to another binary (optional)
+
+Requires **`KBOT_EXE`** pointing at the kbot executable; remaining args are passed through.
+
+```bash
+export KBOT_EXE=/path/to/kbot    # Windows: set KBOT_EXE=C:\path\to\kbot.exe
+./dist/media-img kbot ai --prompt "hello"
+```
 
 ## Tests