# Factorize Vision — 5-minute quickstart

Film your shelf with a phone; get cropped product photos, names, price
suggestions, and filming feedback — all analyzed by a vision model on **your
own Ollama server**. Nothing leaves your network.

## Prerequisites

- WordPress 6.2+ with WooCommerce active (the page requires the
  `manage_woocommerce` capability, and drafts are WooCommerce products)
- PHP 7.4+
- An [Ollama](https://ollama.com) server reachable from your WordPress
  server — a spare PC on the LAN is fine. GPU strongly recommended; on CPU a
  frame takes 1–3 minutes.
- A phone video of your products: slow pan, pause 2–3 seconds on each item.

## Install

1. Copy the `factorize-vision` folder into `wp-content/plugins/` (or upload
   the zip via **Plugins → Add New**).
2. Activate **Factorize Vision**. A **Factorize** menu appears in the admin
   sidebar — this plugin alone creates the shared hub.

## First value in 5 steps

1. **Point it at your Ollama box.** The default is `192.168.1.6:11434`. If
   yours differs:

   ```bash
   wp option update factorize-vision_options '{"ollama_host":"YOUR_HOST"}' --format=json
   ```

   (Or use the `factorize-vision_config` filter in a small plugin. There is
   no settings screen yet.)

2. **Open Factorize → Vision Intake.** The page checks the server on load.
   If it is reachable but has no vision model, click **Prepare model** — it
   downloads `moondream` (~1.7 GB) once, which can take several minutes.
3. **Pick your video**, choose a **Mode** (*Catalog* = one row per named
   product; *Count* = one row per physical unit, tracked by look and
   position, names optional — use it when you need to know how many things
   are on the shelf), choose an **Intensity** (1 = one quick pass per
   frame, 2 = a second pass cross-checks, 3 = three passes vote), leave
   **Analyze the whole video** ticked, and click **Analyze video**. The
   estimate line tells you the frame count, model calls, Factorize tokens
   (1 token = 1 model call; 50 included per month — text or call
   330-519-9231 for more), and minutes before you start; a live meter runs
   during analysis. Frame
   thumbnails appear as the browser samples the video (the sharpest of every
   three candidates); each frame is then sent to the model, which lists
   every product it can see in that frame.
4. **Read the Video feedback panel** — too fast (blurry frames), rushed
   single-frame items, lingering shots, gaps with no product, and condition
   warnings like "box crushed".
5. **Turn detections into products.** Each card shows a cropped photo, a
   name, and a suggested retail price. Click **Save image to library**, then
   **Create draft product**, then follow the edit link to review and publish.

## Configuration

Defaults merge with the `factorize-vision_options` option (override any
subset), filtered through `factorize-vision_config`. The legacy
`empire-vision-intake_options` option still works.

| key | default | effect |
|---|---|---|
| `ollama_host` | `192.168.1.6` | LAN address of the Ollama server |
| `ollama_port` | `11434` | Ollama port |
| `model` | `qwen2.5vl:7b` | preferred vision model (used when installed) |
| `fallback_model` | `moondream` | offered for one-click download when the server has no vision model |
| `frame_interval` | `2.5` | seconds between frame slots |
| `whole_video` | `true` | cover the full duration (a 60s video ≈ 25 frames); untick on the page for the clip budget |
| `whole_video_cap` | `60` | safety cap on frame slots for very long videos |
| `max_frames` | `8` | clip budget when whole-video is off — each frame is one model call per pass |
| `frame_size` | `512` | longest frame side in px (smaller = much faster) |
| `intensity` | `1` | default passes per frame (1–3); selectable per run |
| `num_ctx` | `4096` | context window per call — keeps a 128k-context model from allocating tens of GB (52GB → 15GB for qwen2.5vl:7b) |
| `num_predict` | `700` | cap on reply tokens per call |
| `keep_alive` | `15m` | how long Ollama keeps the model warm between calls |
| `timeout` | `600` | per-call timeout, seconds (the first call reloads the model) |

## Troubleshooting

- **"Cannot reach Ollama at http://192.168.1.6:11434"** — the default host
  is almost certainly not yours. Set `ollama_host`/`ollama_port` as above,
  and make sure Ollama listens on the LAN (`OLLAMA_HOST=0.0.0.0`), not just
  localhost.
- **The first frame sits at "Analyzing frame 1…" for minutes** — that is the
  cold model load, not a hang. The per-call timeout is 600 s for exactly this
  reason, and `keep_alive` (15m) keeps later frames fast. Do not refresh. If
  *every* run starts cold and frames take 40 s+ on a GPU box, check that the
  model fits in VRAM: `curl host:11434/api/ps` should show `size_vram` close
  to `size`. The plugin requests a 4k context (`num_ctx`) so it does — with
  a 128k context the same 7B model is 52GB and falls back to CPU.
- **"No products detected in this video"** — get closer and slow down.
  Frames shot mid-walk or from across the aisle come back as "no clear
  product" and end up in the gap feedback instead. Shelf shots are fine —
  the model lists every product it can identify in a frame — but rows whose
  name is only a brand or product line ("M18 FUEL") mean the type was not
  readable; they start unchecked with a "brand only" status.
- **No Factorize → Vision Intake menu item** — your user lacks the
  `manage_woocommerce` capability. Activate WooCommerce and use an
  administrator or shop manager account.

## The review layer (v1.1)

Analysis never touches your store directly. Results land in a review table:
edit any name or price, untick anything wrong, then either **Export CSV
(spreadsheet only)** — a download, zero store changes — or **Add checked to
WooCommerce**, which creates draft products (they stay drafts until you
publish). Detections are fuzzy-matched against your existing inventory;
likely duplicates show a match % (up to three ranked candidates) with a link
to the existing product and start unchecked. At intensity 2–3 each row also
shows how many passes agreed ("3/3 passes agree"), and the Status column
counts the frames a product was seen in. iPhone .MOV (HEVC) videos work in
Edge/Chrome on Windows 11; if a video will not decode, convert it to
MP4/H.264 first. The **Run analytics** panel at the bottom keeps your last
50 runs — tokens, time, consensus, products — so you can see what each
intensity level buys on your hardware.

