ScanSlicer/docs/architecture.md

Architecture

Overview

ScanSlicer is a Qt desktop app split into UI mixins, controller mixins, canvas subsystems, and image-processing/autotune engines.

Top-level startup path:

1. scanslicer.entry:main
2. Backend/environment resolution and validation
3. scanslicer.main:run_app
4. QtScanSlicer window composition

Module Map

• scanslicer/entry.py
  • CLI parsing
  • Wayland/X11 backend selection
  • Qt platform environment configuration
• scanslicer/main.py
  • QtScanSlicer main window lifecycle
  • Theme handling and app icon resolution
  • App bootstrap (run_app)
• scanslicer/controller*.py
  • UI action handlers split by responsibility
• scanslicer/ui_builders*.py
  • Widget construction for control panel, preview panel, and shared UI helpers
• scanslicer/canvas*.py
  • Interactive image canvas for box display/editing
• scanslicer/autoslicer.py
  • Detection/export engine wrapper
• scanslicer/autoslicer_detection.py
  • Detection pipelines and contour-to-box extraction
• scanslicer/autoslicer_feedback.py
  • Auto-tune profiles, candidate scoring, and feedback persistence
• scanslicer/params.py
  • Parameter model, defaults, and user presets
• scanslicer/slices.py
  • Box geometry model and polygon IoU helper

UI Composition

QtScanSlicer inherits:

• ScanSlicerUiBuilderMixin (UI construction)
• ScanSlicerControllerMixin (behavior)

Controller mixin composition:

• ScanSlicerStatusMixin (status/logging/busy state)
• ScanSlicerCanvasActionsMixin (box operations and preview toggles)
• ScanSlicerDetectionMixin (worker orchestration)
• ScanSlicerImageIOMixin (directory/image loading and save/export)
• ScanSlicerParamsMixin (parameter/default/preset/autotune interactions)

Detection Execution Flow

1. User action triggers update_preview().
2. Detection starts in DetectionTask (QRunnable) on QThreadPool (single worker).
3. Worker runs Autoslicer.autodetect_slices(...).
4. On completion:

• Cache normal preview image
• Cache filter preview image
• Update canvas image
• Merge/update boxes

5. Toolbar status and box state are refreshed.

Key properties:

• One detection worker at a time.
• Busy state disables controls during processing.
• Task IDs prevent stale callbacks from old tasks mutating UI.

Auto-Tune Execution Flow

1. User clicks Auto-tune.
2. AutotuneTask runs in the same single-thread pool.
3. autotune_for_current_image():

• Builds candidate parameter sets
• Ranks by current-image + prior feedback similarity
• Coarse pass on downscaled image (fast_mode=True)
• Fine pass on top finalists
• Applies best candidate to parameter model

4. UI controls sync from model and detection re-runs.

Canvas System

• QtSlicingCanvas = interaction + rendering + state mixins
• Stores:
  • image and zoom/pan state
  • list of PhotoSlice objects
  • active slice index
  • drag modes (corner, side, rotation, box drag, panning)
• Emits active_slice_changed signal to keep toolbar state synchronized.

Geometry Model

PhotoSlice stores a 4-point quadrilateral and flags:

• locked
• side_handles_enabled
• swapped (persistent left/right mirror state, honored by normalization)

It supports:

• top-left normalization and winding correction
• rectangle detection (is_perfect_rectangle)
• squarize while preserving tilt
• reset to axis-aligned orientation
• explicit left/right swap (swap_left_right)

Persistence Model

Paths are runtime-dependent (host vs container), with environment overrides:

• Defaults JSON
• Presets JSON
• Auto-tune feedback JSON
• Session status log

Persistence writes are performed through explicit actions (save defaults/preset, save slices with feedback, status updates).

Export Pipeline

For each locked box:

1. Compute output width/height from opposing edge lengths.
2. Build perspective transform from box quad to rectangle.
3. Warp source image with cv2.warpPerspective.
4. Save with format-specific encoding params.

Packaging Surfaces

• Python package/CLI (pyproject.toml, script scanslicer)
• Docker runtime (Dockerfile, docker-compose.yml)
• AppImage (packaging/appimage/)