🎨 image-editorHomeUser GuidePro GuideInstallArchitectureAnalysisPlanChangelog

image-editor — Implementation Plan

Companion to analysis.md. Turns the research into a concrete, phased build. Reuses image_selector's conventions: PySide6/Qt UI, Qt-decoupled pure-array ops, atomic Unicode-safe full-resolution save.

Date: 2026-09-11 · Status: planning

Guiding constraints (from analysis §0)

  1. Full-resolution, non-destructive — preview on a proxy, always render the final at native resolution with format/quality control.
  2. Photoshop-capable, phone-app-simple — power (masks/layers/inpainting) lives under a direct-on-image UI. Every feature ships an algorithm and a simple interaction, together.
  3. Models are optional — phases 1–5 run with zero ML deps; ML degrades gracefully when a model/GPU is absent.

Target architecture

MVC like image_selector, but the "model" grows from a flat EditState into a Document (layer stack). The core is Qt-free so it can back an MCP server later.

image-editor/
├── main.py                   # entry point — boots Qt, opens Document, wires window
├── config.py                 # JSON config (~/.config/image-editor/)
├── img_io.py                 # COPIED from image_selector — Unicode-safe imread/imwrite
├── core/                     # zero Qt imports — pure numpy/opencv
│   ├── document.py           # Document, layer stack, render(), history
│   ├── layers.py             # Layer types (Adjustment, Heal, Pixel, ...)
│   ├── mask.py               # Mask type + sources (shapes, brush, parametric, ML)
│   ├── ops.py                # ported edit_ops.py — brightness/contrast/curves/...
│   ├── film_luts.py          # COPIED from image_selector (film sims as ops)
│   ├── curves.py             # monotone-spline → 256-LUT
│   ├── blend.py              # alpha composite, blend modes, seamlessClone, colour-match
│   ├── heal.py               # inpaint dispatch: telea | patchmatch | lama
│   ├── render.py             # proxy vs full-res rendering, export (quality/format)
│   └── backends/             # ML wrappers, lazy-imported, optional
│       ├── segment.py        # SAM 2 + rembg  (returns a Mask)
│       └── inpaint_lama.py   # LaMa erase (+ optional SD)
├── widgets/                  # Qt view layer
│   ├── main_window.py        # window, toolbar, keyboard, open/save
│   ├── canvas.py             # zoom/pan preview (port preview_widget.py) + gestures
│   ├── tool_overlay.py       # on-canvas brush/shape/handles (port crop overlay)
│   ├── tools_panel.py        # the simple tool rail (Erase, Adjust, Curves, Crop...)
│   └── adjust_panel.py       # slider/curve UI for the active tool
├── app_controller.py         # actions ↔ Document ↔ widgets
├── requirements.txt
└── docs/{analysis.md, plan.md, changelog.md, versioning/...}

Core data model

# core/mask.py
@dataclass
class Mask:
    data: np.ndarray            # float32 HxW in [0,1], image-resolution (or None = all-ones)
    invert: bool = False
    feather_px: float = 0.0     # gaussian fallback
    edge_aware: bool = False    # guided-filter refine against image
    def resolve(self, img) -> np.ndarray: ...   # -> concrete float32 HxW in [0,1]

# core/layers.py
@dataclass
class Layer:
    kind: str                   # "adjust" | "heal" | "pixel"
    params: dict                # op name + values, or heal engine, or rgba+transform
    mask: Mask | None = None
    blend_mode: str = "normal"
    opacity: float = 1.0
    visible: bool = True

# core/document.py
@dataclass
class Document:
    base: np.ndarray            # immutable original BGR (full res)
    layers: list[Layer]
    crop_rect: tuple | None = None
    rotation: int = 0
    def render(self, scale: float = 1.0) -> np.ndarray: ...   # proxy or full-res

render() = start from (rotated, cropped) base, apply each visible layer top-to-bottom via blend.composite(base, effect, mask, mode, opacity). The same method renders the proxy (scale<1, for live preview) and the full-res export (scale=1) — guaranteeing what you see is what you save.

Phase 0 — Project scaffold (0.5 day)

Phase 1 — Document, layers, compositor, masks (3–4 days) — the spine

Phase 2 — Local adjustments (2 days)

Phase 3 — Curves (1–2 days)

Phase 4 — Classical heal / erase (1–2 days)

Phase 5 — Seamless paste + colour match (2 days)

Phases 0–5 ship a genuinely useful editor with zero ML dependencies. Everything below is additive and optional.

Phase 6 — AI segmentation (2–3 days)

Phase 7 — LaMa erase (2–3 days) — the headline feature

Phase 8 — Optional extras (as desired)

Phase 9 — Pro-grade capabilities (the "professional look")

From the professional-editing research in analysis.md §11. Ordered by leverage on a professional result ÷ effort. Items 9.1–9.6 are pure OpenCV/NumPy (no new deps) and slot into the existing layer/mask/curve engine — do these first. 9.7–9.10 follow the optional-backend pattern proven with LaMa/SAM.

No new dependencies (highest leverage first)

Optional backends (bigger, higher image-quality tier)

Suggested order: 9.2 → 9.4 → 9.3 → 9.1 → 9.5 → 9.8 → 9.6 → 9.7, then the backend tier 9.9 → 9.10 → 9.12 → 9.11. Until RAW/denoise/upscale land, pair image-editor with a free RAW processor (Darktable / RawTherapee) for those steps.

Cross-cutting concerns

Rough sequencing

Milestone Phases Outcome
M1 — "better than the phone" 0–3 full-res open/edit/save, masks, local adjust, curves — no ML
M2 — classical retouch 4–5 heal small stuff, seamless paste, colour match
M3 — "erase anyone" 6–7 SAM tap-select + LaMa erase, the headline feature
M4 — creative/optional 8 SD replace/outpaint, AI looks, RAW/HEIC, batch
M5 — pro-grade look 9 colour grading/HSL, WB picker, clarity/dehaze, sharpening, dodge & burn, frequency separation, presets/batch, then RAW · denoise · upscale · lens correction