# 05 — Quality Improvement Levers

Three levers control FLUX output quality, in order of impact:

## 1. Prompt (highest impact, zero cost)

Incoherent objects in the frame are almost always prompt bleed — the model fills
empty or ambiguous space with training-data defaults. Fix by naming every part of
the frame explicitly.

**Background** — name it, don't imply it:
- Bad: "living room" (model invents furniture, decor, wall art)
- Good: "plain cream painted wall with a single frosted sliding glass door"

**Floor material** — always explicit:
- "plush cream berber carpet" or "light oak hardwood floor"
- Ambiguous floor → random floor type generated

**Ceiling** — if visible, name it; if not wanted, push it out of frame with a
lower camera angle:
- "white drop ceiling with recessed can lights"
- Or: lower the angle until ceiling exits the frame entirely

**Negative scene elements** — add inline, not as a separate negative prompt
(FLUX Schnell ignores negative prompts):
- "no furniture clutter, no decorative objects, no picture frames, no signage"
- "no cleaning equipment, no machines, no people"

**What not to use:**
- "wide shot" without a camera angle qualifier — produces flat frontal views
- Vague room names ("office", "lobby") without specifying what fills the space

## 2. Steps (marginal gain, 2x slower)

FLUX Schnell is distilled to 4 steps. The distillation process compresses
a full diffusion model's quality into very few steps.

| Steps | Quality change | Time impact |
|---|---|---|
| 4 (default) | Baseline | ~4 min/image |
| 6 | Slightly sharper edges, cleaner fine detail | ~6 min/image |
| 8 | Diminishing returns past 6 | ~8 min/image |

Not recommended as a first fix. The distillation ceiling is the constraint,
not step count. Step increases help texture detail but will not fix scene
incoherence — that requires prompt changes.

KSampler in `gen-images-flux.py`:
```python
"steps": 4,   # increase to 6 for detail passes
```

## 3. Model size (real quality jump, 6x slower on CPU)

| Model | Steps | Quality | CPU time/image |
|---|---|---|---|
| FLUX.1 Schnell (current) | 4 | Good depth, some coherence gaps | ~4 min |
| FLUX.1 Dev (full, non-distilled) | 20-30 | Better coherence, sharper geometry | ~20-30 min |

FLUX Dev would fix most coherence issues. At current CPU-only speed (2GB VRAM
insufficient), a full 28-image batch would take 9+ hours.

**Practical path to FLUX Dev:**
- Cloud GPU: RunPod or Vast.ai A100 runs FLUX Dev in ~90 seconds/image
- Same prompts, same ComfyUI workflow — only model file and step count change
- Switch `flux1-schnell-Q8_0.gguf` → FLUX Dev GGUF, set steps to 20, cfg to 3.5

## Decision matrix

| Issue | Fix |
|---|---|
| Objects that shouldn't be in frame | Prompt: name every surface explicitly |
| Wrong floor/wall material | Prompt: be specific about material |
| Flat angle despite prompt | Prompt: add "low-angle", lens mm, "foreground sharp" |
| Soft edges on carpet fibers | Steps: increase 4 → 6 |
| Incoherent room geometry | Model: switch to FLUX Dev on cloud GPU |
| Overall composition wrong | Prompt: camera position + lens + foreground/bokeh split |

## Re-running specific images

To re-run only the problem frames without regenerating all 28:

1. Edit `tools/gen-images-flux.py`
2. Change the `IMAGES` list to include only the failed image keys
3. Run: `python3 tools/gen-images-flux.py 2>&1 | tee tools/flux-gen.log`
4. Run: `python3 tools/convert-to-webp.py` (converts only new JPGs)
5. Rebuild: `docker compose build --no-cache web && docker compose up -d`