Per-annotation mask complexity / polygon simplification (#24)

.claude/skills/temp-roadmap/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: temp-roadmap
+description: Create a temporary, self-removing roadmap/backlog section in CLAUDE.md from a set of identified work items (issue triage, audit findings, review feedback). Use when the user asks to "track these items", "write this list into CLAUDE.md as a plan", "create a backlog/roadmap in CLAUDE.md", or wants a work list that cleans itself up as PRs land.
+---
+
+# Temporary Self-Removing Roadmap in CLAUDE.md
+
+Turn a set of identified work items into a CLAUDE.md section that shrinks with
+every PR and disappears entirely when the work is done — so CLAUDE.md returns
+to its clean state without manual housekeeping.
+
+## When to use
+
+- After issue triage, a code audit, or a review produced a concrete list of
+  work items that will be resolved across several future PRs.
+- NOT for single-PR task tracking (use the todo list) and NOT for permanent
+  guidance (write a normal CLAUDE.md section or arc42 doc instead).
+
+## Structure to write into CLAUDE.md
+
+Insert a section near the top of CLAUDE.md (after the docs index, before
+project structure):
+
+```markdown
+## <Topic> Backlog (TEMPORARY section — self-deleting)
+
+**Deletion hook:** When a PR resolves one of the items below, DELETE its row
+from this table **in the same PR**. When the last row is gone, delete this
+entire section so CLAUDE.md returns to its clean state. Never let a finished
+item linger here.
+
+Items validated <YYYY-MM-DD>; source: <issue tracker / audit / review link>.
+
+| Item | Size | Task |
+|------|------|------|
+| #123 | quick win | One-line actionable description with file hints (`path/file.py`, function name, reporter-verified fix if any) |
+| #124 | medium | ... |
+| #125 | blocked | ... — name what it is blocked on so it can be re-checked |
+```
+
+## Rules
+
+1. **One line per item.** Concise but self-sufficient: a future session must be
+   able to start the item from the row alone — include file paths, function
+   names, and known pitfalls ("do NOT use setSortingEnabled — currentRowChanged
+   fires switch_image").
+2. **Classify every item**: `quick win` / `medium` / `large` / `blocked`.
+   For `blocked`, state the blocker.
+3. **Reference the source** (issue number, ticket, review comment) so context
+   can be recovered.
+4. **Date the validation** — rows describe code state at a point in time;
+   re-verify before implementing if the date is old.
+5. **The deletion hook is mandatory** and must appear verbatim-in-spirit at the
+   top of the section. It is the whole point: the section is a consumable, not
+   documentation.
+6. Mark items currently being worked on with *(in progress on this branch)* so
+   parallel sessions don't double-pick them.
+
+## Per-PR workflow (executing the hook)
+
+1. Pick item(s), implement on a feature branch.
+2. In the same PR: delete the resolved row(s) from the table.
+3. If the table is now empty: delete the entire section, including the heading
+   and the deletion-hook paragraph.
+4. The PR diff thus always shows both the fix and the backlog shrinking —
+   reviewers can see progress without a separate tracker.

.gitignore

@@ -9,10 +9,12 @@ models/
 *.iap
 
 # Local tooling — .claude is mostly local state, but the senior-reviewer
-# agent definition under .claude/agents/ is tracked (referenced by
-# CLAUDE.md as a mandatory quality gate), so un-ignore that subtree.
+# agent definition under .claude/agents/ and project skills under
+# .claude/skills/ are tracked (referenced by CLAUDE.md / used as shared
+# workflow tooling), so un-ignore those subtrees.
 .claude/*
 !.claude/agents/
+!.claude/skills/
 .venv
 
 # Python cache and build artifacts

CLAUDE.md

@@ -36,6 +36,21 @@ For detailed architecture and design information, see **[docs/](docs/)**:
 
 See [docs/README.md](docs/README.md) for full documentation index.
 
+## Upstream Issue Backlog (TEMPORARY section — self-deleting)
+
+**Deletion hook:** When a PR resolves one of the items below, DELETE its row
+from this table **in the same PR**. When the last row is gone, delete this
+entire section so CLAUDE.md returns to its clean state. Never let a finished
+item linger here.
+
+Issue numbers refer to https://github.com/bnsreenu/digitalsreeni-image-annotator/issues
+(validated 2026-06-22; already-fixed issues have close-request comments posted, not listed here).
+
+| Issue | Size | Task |
+|-------|------|------|
+| #74 | large | MLflow experiment tracking for model training (SAM fine-tuning / YOLO) |
+| #35 | large | Keypoint annotation tool |
+
 ## Project Structure
 
 ```
@@ -47,14 +62,17 @@ src/digitalsreeni_image_annotator/
 ├── __init__.py                   # Public API re-exports
 │
 ├── core/                         # constants, annotation_utils, image_utils
-├── controllers/                  # 7 controllers (project, image, sam, dino,
-│                                 #   yolo, annotation, class) + io_controller
+├── controllers/                  # 8 controllers (project, image, sam,
+│                                 #   sam_train, dino, yolo, annotation,
+│                                 #   class) + io_controller
 ├── widgets/
 │   ├── image_label.py            # ImageLabel canvas widget (dispatcher)
 │   ├── canvas_context.py         # CanvasContext read accessor (ADR-018)
 │   └── tools/                    # Per-tool handlers (ADR-019): rectangle,
 │                                 #   polygon, paint, eraser
 ├── inference/                    # sam_utils.py, dino_utils.py
+├── training/                     # SAM fine-tuning (ADR-021): sam_trainer.py
+│                                 #   (SAMFineTuner), sam_dataset.py
 ├── io/                           # export_formats.py, import_formats.py
 ├── ui/                           # menu_bar, sidebar, shortcuts, theme, stylesheets
 └── dialogs/                      # Standalone tool dialogs (statistics,
@@ -76,8 +94,10 @@ src/digitalsreeni_image_annotator/
 | `SAMController` | controllers/sam_controller.py | SAM model picker, debounce, in-flight guard (ADR-013) |
 | `DINOController` | controllers/dino_controller.py | DINO single/batch detection, batch review, temp-class workflow |
 | `YOLOController` | controllers/yolo_controller.py | YOLO training menu + prediction wiring |
-| `SAMUtils` | inference/sam_utils.py | Load SAM models, run inference |
+| `SAMUtils` | inference/sam_utils.py | Load SAM models (built-in + fine-tuned), run inference |
 | `DINOUtils` | inference/dino_utils.py | Grounding-DINO model load + inference |
+| `SAMFineTuner` | training/sam_trainer.py | Fine-tune SAM 2 decoder/encoder via custom loop over Ultralytics SAM2Model (ADR-021) |
+| `SAMTrainController` | controllers/sam_train_controller.py | SAM fine-tune menu, GPU gate, training thread, selector registration |
 
 See [Building Block View](docs/05_building_block_view.md) for detailed class documentation.
 
@@ -169,6 +189,11 @@ See [Runtime View](docs/06_runtime_view.md#multi-dimensional-image-loading) for
 | GPU model unload | `model.cpu()` → `gc.collect()` → `torch.cuda.empty_cache()` + `ipc_collect()` + `synchronize()` — full reclaim requires app restart due to per-process CUDA context | Setting refs to None alone leaves circular refs pinned and shows zero Task Manager drop. See [Releasing Model GPU Memory](docs/08_crosscutting_concepts.md#releasing-model-gpu-memory). |
 | Export image-path lookup | Exact-key match first, substring fallback only | `"bee.jpg" in "honeybee.jpg"` is True — substring-only matching writes the wrong file. See [Export Format Filename Matching](docs/08_crosscutting_concepts.md#export-format-filename-matching). |
 | F2 / global shortcuts | Use `QShortcut` with `Qt.ShortcutContext.ApplicationShortcut`, not `keyPressEvent` | `QTableWidget` consumes F2 for in-cell edit before it bubbles up. |
+| Canvas ↔ list selection sync | Canvas selection (idle-mode click/Shift/rubber-band) drives the annotation list via `apply_canvas_selection`; mirror the list with `blockSignals(True/False)` and match annotations by **value-equality**, never identity | PyQt round-trips `UserRole` dicts as copies and `image_label.annotations` is a deepcopy, so identity is never stable; un-blocked `setSelected` recurses through `update_highlighted_annotations`. Multi-select uses **Shift** (Ctrl stays pan). See [ADR-022](docs/09_architecture_decisions.md#adr-022-canvas-mask-selection-unified-with-the-annotation-list). |
+| Selection rendering | Don't recolour a selected mask. Keep its class colour; draw a class-colour-independent overlay (dashed `_SELECTION_COLOR` blue bounding box + bright handle squares at corners/edge-midpoints, OGP-style) in a final pass — `_draw_selection_overlay`. For a single selected shape those handles are draggable (resize/move, any shape). Default class colours come from `core/constants.py::default_class_color` (red last, muted) | Red selection was invisible on a red-class mask; a thin dashed outline alone was too faint; the handles carry the visibility. See ADR-022 amendment. |
+| Shape editing (#40) | Direct manipulation on the selection handles for **any** single selected shape (`_single_selected_shape()` — most shapes are `"segmentation"`, not `"bbox"`; gating on a bbox key made it unreachable). `_begin_shape_edit` records `kind`: a `"seg"` polygon **scales** its vertices (`_scale_segmentation`) / translates them; a `"bbox"` edits `[x,y,w,h]`. `_draw_selection_overlay` + `_bbox_handle_at` share `_bbox_handle_points` (visual == grab); resize anchors the opposite side (`_resize_bbox`); interior drag moves, **drag-gated**. `_sync_bbox_key` keeps an imported bbox consistent. Clamp + `bboxEditCommitted` → `commit_bbox_edit` on release; Esc reverts | Handles drawn since #75 were visual-only; dispatch sits before the rubber-band branch but stays gated on `_is_select_mode()`. Names keep the `bbox_edit` prefix = "edit via the bounding-box handles". See [ADR-023](docs/09_architecture_decisions.md). |
+| Bounds enforcement (#32/#36) | No commit may persist coords outside the image. **Clamp** manual edits (`clamp_segmentation`/`clamp_bbox`, per-coordinate, count-preserving) at edit commit; **clip** augmented polygons (`clip_polygon_to_bounds`, shapely intersection, may drop → `None`, augmenter must `continue`). Drawn shapes already clip in `finish_polygon`/`finish_rectangle` | Clamp keeps vertex correspondence mid-edit; clip is geometrically correct for batch augmentation. See [ADR-024](docs/09_architecture_decisions.md). |
+| Annotations table + Detail % (#24) | The Annotations panel is a **`QTableWidget`** (ID \| Class \| Area \| Detail %), not a list — col 0's UserRole holds the annotation (the #75 value-equality marker). Selection-mirror uses **`setRangeSelected`** (additive); `selectRow()` replaces in `ExtendedSelection`. Per-row Detail % spinbox → `on_detail_pct_changed` resolves the live obj (`_live_annotation`), simplifies from a lazy-captured `segmentation_raw` (`simplify_polygon`, 100=raw), refreshes Area+UserRole in place, saves. Connect `valueChanged` **after** the initial `setValue` so building the table doesn't fire it | Re-homing the selection bridge onto a table is the risk; reversibility needs the raw preserved. See [ADR-025](docs/09_architecture_decisions.md). |
 
 ## Development Workflow
 
@@ -245,6 +270,11 @@ See [Risks and Technical Debt](docs/11_risks_and_technical_debt.md) for full lis
 |--------|--------|
 | Ctrl+Wheel | Zoom |
 | Ctrl+Drag | Pan |
+| Click / Shift+Click (no tool) | Select / toggle mask |
+| Drag / Shift+Drag (no tool) | Rubber-band select / add |
+| Drag handle / inside (one shape selected) | Resize (scale) / move the shape |
+| Double-click | Vertex-edit mode |
+| Delete | Delete selected mask(s) |
 | Enter | Finish/Accept |
 | Esc | Cancel |
 | Up/Down | Navigate slices |

README.md

@@ -99,6 +99,14 @@ python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_
 
 You should see `True` and your GPU name. For other platforms or driver combinations, use the official selector at <https://pytorch.org/get-started/locally/>.
 
+#### Older NVIDIA GPUs (Pascal / Maxwell)
+
+PyTorch ≥ 2.8 wheels no longer include kernels for GPUs older than Volta (compute capability < 7.0), e.g. the GTX 10xx series (sm_61). On such cards the app detects the mismatch, warns once, and automatically runs inference on the CPU instead of crashing with `CUDA error: no kernel image is available`. To keep using the GPU, install an older PyTorch that still supports it:
+
+```bash
+pip install torch==2.4.1 torchvision==0.19.1 --index-url https://download.pytorch.org/whl/cu121
+```
+
 ## Usage
 
 1. Run the DigitalSreeni Image Annotator application:

docs/05_building_block_view.md

@@ -33,7 +33,8 @@ src/digitalsreeni_image_annotator/
 	├── utils.py                       # Cross-cutting utilities
 	├── core/                          # Constants, annotation utils, image utils
 	│   ├── constants.py
-	│   └── annotation_utils.py
+	│   ├── annotation_utils.py
+	│   └── torch_utils.py             # Shared torch device resolution + CPU fallback (#57)
 	├── widgets/
 	│   ├── image_label.py             # ImageLabel - canvas widget; dispatcher
 	│   ├── canvas_context.py          # CanvasContext - narrow read view (ADR-018)
@@ -155,6 +156,23 @@ The earlier subprocess approach is documented as
 [ADR-011](09_architecture_decisions.md#adr-011-run-torch-based-workers-in-isolated-subprocesses)
 (Superseded).
 
+### SAM Fine-Tuning Subsystem (`training/`)
+
+Lets users fine-tune SAM 2 / 2.1 on their own annotations, since
+Ultralytics ships no SAM trainer (ADR-021). Distinct from `inference/`
+because it is *training*, not inference.
+
+| Module | Responsibility |
+|--------|----------------|
+| `training/sam_trainer.py` | `SAMFineTuner` — custom decoder (optionally encoder) fine-tuning loop reusing `SAM2Predictor.get_im_features` / `prompt_inference` under autograd, focal+dice loss, AdamW, checkpoint save+reload-verify. Also geometry helpers (`polygon_to_mask`, `mask_to_xyxy`, `mask_to_point`), `make_custom_filename`, `list_custom_models`, and the `SampleGroup` lazy-rasterising dataset item. |
+| `training/sam_dataset.py` | `build_groups_from_project` (live `all_annotations`) and `build_groups_from_folder` (prepared dataset) → `list[SampleGroup]`, mirroring `export_yolo_v5plus` image resolution. |
+| `io/export_formats.py::export_sam_dataset` | Writes `images/` + `manifest.json` (authoritative bbox/segmentation specs) for an inspectable, re-trainable on-disk dataset. |
+
+Fine-tuned checkpoints save as `{"model": state_dict}` and reload
+through the unchanged `SAM(path)` inference path; `SAMUtils` gains a
+`custom_models` registry so they appear in the SAM selector alongside
+the eight built-ins.
+
 ### DINO Subsystem (Grounding DINO + SAM pipeline)
 
 LLM-assisted detection: the user gives free-form text phrases per class,
@@ -195,7 +213,7 @@ export time — see [Cross-cutting Concepts](08_crosscutting_concepts.md)).
 
 ## Level 3: Controllers
 
-Seven `QObject` controllers plus an `io_controller` helper module
+Eight `QObject` controllers plus an `io_controller` helper module
 carve `ImageAnnotator` into single-responsibility owners that the
 orchestrator delegates to. Each `QObject` controller holds `self.mw
 = main_window` and owns one slice of behaviour; the
@@ -208,12 +226,13 @@ the controller graph.
 | Controller | Responsibility |
 |------------|----------------|
 | `ProjectController` | `.iap` save/load, auto-save, backup/restore, missing-image prompts, window-title sync. Owns the `is_loading_project` autosave guard (load/save round-trip safety, v0.8.12). |
-| `ImageController` | Open / load / switch images and slices. TIFF + CZI loaders, the multi-dim `DimensionDialog`, the `[-ndim:]` axis-slice bug fix from the v0.9.0 era. |
+| `ImageController` | Open / load / switch images and slices. TIFF + CZI loaders (with `imagecodecs` codec-error handling — #56), the multi-dim `DimensionDialog`, the `[-ndim:]` axis-slice bug fix from the v0.9.0 era. Image-list annotation-status filter (`image_has_annotations`, `apply_image_filter` — #27) and alphabetical sort (`sort_image_list` — #60). |
 | `AnnotationController` | Annotation CRUD, list sorting, highlight, edit-mode entry/exit, `finish_polygon`, `finish_rectangle`, `replace_annotations` (eraser path). Validates writes before mutating `all_annotations`. |
 | `ClassController` | Class add / delete / rename / colour / visibility. `update_slice_list_colors`, `is_class_visible`. |
 | `SAMController` | SAM box/points tool lifecycle, debounce timer, `_sam_inference_in_flight` re-entrancy guard (ADR-013), model picker. |
 | `DINOController` | Single + batch detection, batch review navigation, temp-annotation accept/reject, custom-model browse, `DINOReviewEventFilter` ownership (ADR-015). |
 | `YOLOController` | Training menu, `TrainingThread`, prediction dialog, result processing. |
+| `SAMTrainController` | SAM fine-tuning menu, GPU gate, `SAMTrainingThread`, config dialog, registers fine-tuned checkpoints into the SAM selector (ADR-021). |
 | `io_controller` *(module-level functions, not a class)* | Thin UI wrappers around the pure `io/export_formats.py` and `io/import_formats.py` modules. |
 
 Communication: `ImageLabel` does not import controllers directly —