# 🎨 Image Pipeline — Napkin Notes

## What the spec wants
Seller uploads phone photo → system auto-standardizes → consistent product catalogue
- Background removal
- Colour correction
- Lighting normalization
- Resize/crop to exact same dimensions
- Store processed image against product variant

## What we found (FAFO'd 2026-09-13)

### 🥇 Photoroom (recommended for production)
- **URL:** https://app.photoroom.com/create (signed up as `celestjux`)
- **Docs:** https://docs.photoroom.com/
- **Pricing:** Basic $20/mo (BG removal only) · Plus $100/mo (full pipeline) · Enterprise custom
- **Per image:** $0.02 (Basic) / $0.10 (Plus)
- **Apparel-specific features:**
  - Ghost Mannequin — makes clothes look worn without a real model
  - Virtual Model — AI fashion models wearing the clothes
  - Virtual Try-On — customers see clothes on themselves
  - AI Ironing — smooth wrinkles on clothes
  - AI Relight — fix lighting
  - AI Shadows — realistic shadows
  - Product Staging, AI Backgrounds, AI Beautifier, AI Expand
- **Batch:** yes, directory/Google Drive/Sheets
- **Sandbox:** 1,000 free watermarked calls + 10 real for testing
- **Verdict:** Does EVERYTHING the spec asks in one API call. $100/mo for 1K images.
  Ghost mannequin + AI ironing = killer for men's apparel.

### 🥈 Bria AI (good BG removal, lighter features)
- **API key:** saved at `~/.bria/credentials`
- **Skills installed:** `/root/.claude/skills/bria-skills/`
- **Tested:** ✅ BG removal works (RMBG 2.0), 39% transparent pixels on test image
- **Features:** BG removal, relighting, upscale, product photography, object editing
- **No ghost mannequin, no AI ironing, no virtual try-on**
- **Verdict:** Good for BG removal + basic edits. Fallback to Photoroom for apparel-specific stuff.

### 🥉 rembg (free, self-hosted, offline)
- **Installed:** ✅ via pip, u2net model (170MB) cached at `/root/.rembg/models/`
- **Tested:** ✅ works, decent edges, white-on-light handled ok
- **Limit:** BG removal ONLY. No colour correction, no lighting, no crop.
- **Speed:** ~20s on CPU per image
- **Verdict:** Free forever. Good offline fallback. Need OpenCV/Pillow on top for the rest.

### Quick-RMBG / Claude Background Removal Plugin
- **Repo:** cloned at `/mnt/playground/Playground_V2/Claude-Background-Removal-Plugin/`
- **What it is:** Claude Code skill wrapper around rembg (single/two-pass/batch/Dolphin right-click)
- **pipx install blocked** by ctx git shim — not installed yet
- **Verdict:** Nice wrapper but not needed if we use Photoroom/Bria for the platform.

## Architecture decision

```
Production:  Photoroom Plus API ($100/mo)
             └─ one call = bg removal + lighting + shadows + crop + resize
             └─ ghost mannequin for clothes-on-invisible-model shots
             └─ AI ironing for wrinkle-free product photos

Fallback:    Bria RMBG 2.0 (free tier / per-image)
             └─ BG removal when Photoroom is down or over quota

Offline:     rembg + Pillow/OpenCV
             └─ dev/testing, batch processing without API costs
```

## ✅ BUILT 2026-09-15 evening — the pipe is real, end to end

```
phone/disk photo -> Image Studio (admin page) -> Photoroom /v2/edit
                 -> unattached ActiveStorage blob -> review before/after
                 -> Apply -> Spree product (existing, or created here)
```

- **Admin page:** `/admin/image_studio` (sidebar, between Products and Customers).
  Multi-upload from the device, background + size presets, per-file before/after,
  then attach to an existing product **or create a new listing** (name, price,
  publish toggle). Nothing touches the catalogue until Apply — the result is held
  as an unattached blob, so Discard is just navigating away.
- **CLI:** `scraped-catalogue/photoroom_to_spree.py --slug <slug> [--live]`
- **Proven live:** a 6.52 MB phone PNG → 543 KB at 1000×1000; and two uploads →
  a new published product visible on the storefront at R259.11.

### The architecture question, settled

Abang's call, and he was right: **the page is needed.** I had argued for a silent
auto-on-upload hook (the spec says *"seller uploads → system standardises"*), but
a seller wants to choose the shot and see the result before it ships. Fully
automatic means a bad cutout goes live silently and the customer finds it first.
**Manual control at the front, programmatic pipe behind it.**

Photoroom's *Shopify Products* connector is a red herring for us — it exists for
merchants with no backend. We have one, so the plain API is the simpler path.

### Money, accurately

| | Reality |
|---|---|
| API free tier | **10 images/month**, not 7 days. 9 left as of 2026-09-15 |
| Sandbox | 1000/month, free, **every output watermarked** |
| 7-day trial | That's the **web app**, a separate meter. Its Batch tool does **250 images at once** through the browser and costs no API credits |
| Plus | $100/mo for the full pipeline |

🔴 **Photoroom adds little to the existing 160 products.** They are scraped
studio shots already on white — background removal removes a background that is
already gone. Across 160 first-images there are only **3 aspect ratios and 4
sizes**; framing is the sole real defect, and Pillow squares them for free,
offline. Photoroom earns its money on *phone photos of new stock*, which is
exactly what Image Studio is for.

### Still open
- [ ] **Batch** — capped at `MAX_PHOTOS = 8`, synchronous, ~3-5s per image. More
      needs a background job
- [ ] Currently on the **sandbox** key, so everything is watermarked. Flip
      `PHOTOROOM_API_KEY` in the backend `.env` for clean output
- [x] ~~Pillow square-and-pad backfill for the existing 160~~ — **scrapped 2026-09-15,
      measured and unnecessary.** See below.
- [ ] Never tested on a real phone photo from Lisa — the actual input this exists
      for. Ghost mannequin and AI ironing have nothing to work with on a scraped
      studio shot
- [ ] Virtual Try-On — could be a differentiator for the platform
- [ ] Self-hosted option — for v2, when volume justifies building our own pipeline

## 📐 Framing survey — 2026-09-15, the backfill that wasn't needed

I had the Pillow square-and-pad backfill queued as the next job. Measuring the
160 source images first killed it. The real distribution of **first images**:

| Size | Ratio | Count |
|---|---|---|
| 762×1100 | 0.693 | 122 |
| 800×1200 / 801×1200 | 0.667 | 32 |
| 1200×1800 | 0.667 | 4 |
| 1524×2200 | 0.693 | 1 |
| **2400×2400** | **1.000** | **1** |

The grid renders at `aspect-[3/4]` (0.75) with `object-cover`. At 0.693 the crop
takes 7.6% of the height; at 0.667 it takes 11%. The **entire** inconsistency
across 159 products is a 3.4% difference in vertical crop — invisible. Padding
them to square would also be self-defeating: a square displayed in a 3/4 frame
gets re-cropped, so the padding I just added is what gets cut.

🔴 **One image was genuinely broken** — `129-adidas-lifestyle-barreda-shoes-men-white-jp5928`,
the only 1:1 in the catalogue. A square in a 3/4 frame loses **12.5% off each
side**, which cut the heel and the toe off the shoe. Its 22 sibling shoe
listings are all 762×1100 with the subject at 90-95% width and 24-33% height, so
it was reframed to match: crop to the subject bbox, scale to 93% width, centre on
the source's own background (234,238,239). 186KB → 65KB. Applied live via
`reframe_129.py --apply` (upload at position 1, verify by re-read, then delete
the original).

**The lesson, not the fix:** the napkin said "3 aspect ratios and 4 sizes,
framing is the sole real defect" and I turned that into a 160-file job. The
numbers were right and the conclusion was wrong — nobody had checked how far
apart those ratios actually were. Measure the spread, not the count.

### Spree API shape — two gotchas that cost a run

- **Flat objects, not JSON:API.** `/api/v3/admin/products` returns fields on the
  object itself (`p["slug"]`), not under `p["attributes"]["slug"]`. The helper in
  `photoroom_to_spree.py` only survives because its fallback scan happens to use
  the flat form.
- **`per_page` is silently ignored** — it pages on `limit`. Sending `per_page=100`
  gets you 25 rows and no error, so a scan that stops at page 1 "finds" nothing.
  Meta key is `pages`, not `total_pages`.


**Keys:** `/root/.photoroom/credentials` (chmod 600) on the house box;
`PHOTOROOM_API_KEY` in the backend `.env`.