ScanSlicer/README.md

ScanSlicer

ScanSlicer is a desktop Qt application for extracting multiple photos from a flatbed scan image. It detects photo regions, lets you correct boxes manually, then saves perspective-corrected crops.

Inspired by PhotoSlicer by Francesco Vannini.

This repository keeps GNU GPL v3 licensing for compatibility with that upstream work.

What It Does

• Detects photo boxes from .png, .jpg, and .jpeg source images.
• Supports threshold-based and Canny-based detection pipelines.
• Provides manual correction tools (corner drag, edge drag, rotate, move, add/remove box).
• Saves only locked boxes, each as a perspective-corrected output image.
• Includes auto-tuning with feedback learning from your prior saved results.
• Works on Linux desktops over Wayland or X11.

Requirements

• Python >=3.10
• Linux desktop session (for example KDE Plasma) over Wayland or X11
• System libraries required by Qt/OpenCV (see Dockerfile for a known-good package set)

Project dependencies (from pyproject.toml):

• PySide6
• opencv-python
• numpy
• Pillow

Quick Start

Run with uv

uv sync --frozen
uv run scanslicer

Open a specific input directory at launch:

uv run scanslicer /path/to/scans

Choose backend explicitly:

uv run scanslicer --backend wayland
uv run scanslicer --backend x11

Run with Python directly

The package directory now matches the published name:

python -m scanslicer

CLI

scanslicer [path] [--backend {auto,wayland,x11}]

• path: optional startup directory containing scan images.
• --backend: display backend selection. auto is default.

Typical Workflow

1. Open an input directory.
2. Verify output directory (defaults to the opened input directory).
3. Click Detect (or use auto detection triggered on image load).
4. Adjust boxes as needed.
5. Lock boxes you want to export (or use lock-all).
6. Choose save format (jpg or png) and quality/compression.
7. Click Save images.

Only locked boxes are exported.

Runtime Behavior

• Detection and auto-tune run in background worker tasks (QThreadPool) so UI stays responsive.
• Status events are written to a session log file and reflected in the status bar.
• Detection results are cached (normal and filter preview) to avoid unnecessary re-processing when toggling filter preview.

Data and Config Files

Persistence paths depend on how ScanSlicer is run.

Non-container runs (uv run scanslicer, python -m scanslicer):

• Defaults: ~/.config/scanslicer/defaults.json
• Named presets: ~/.config/scanslicer/presets.json
• Auto-tune feedback: ~/.config/scanslicer/autotune-feedback.json
• Session status log: ~/.config/scanslicer/status.log

If XDG_CONFIG_HOME is set, these are stored under $XDG_CONFIG_HOME/scanslicer/ instead.

Container runs:

• When running in container and /work exists, these are stored under /work/.scanslicer/.
• In the provided docker-compose.yml, the current repository is mounted as /work, so these files appear in .scanslicer/ inside the project directory on the host.

Environment variable overrides:

• SCANSLICER_DEFAULTS_PATH
• SCANSLICER_PRESETS_PATH
• SCANSLICER_FEEDBACK_PATH
• SCANSLICER_STATUS_LOG_PATH

Legacy override names are still accepted for backward compatibility.

Docker Compose

The repo includes a GUI-oriented compose setup for Linux desktop use:

docker compose up --build

See .env.example and docker-compose.yml for required host UID/GID and Wayland/XDG settings.

AppImage Build

AppImage build scripts and recipe are in packaging/appimage/.

• Local: bash packaging/appimage/build-appimage.sh
• Dockerized build: bash packaging/appimage/build-appimage-docker.sh

Detailed instructions: docs/appimage.md.

Documentation

• docs/README.md - documentation index
• docs/user-guide.md - end-user operation guide
• docs/architecture.md - code architecture and execution flow
• docs/parameters.md - full detection parameter reference
• docs/autotune.md - auto-tune and feedback internals
• docs/runtime-config.md - backend/environment and persistence paths
• docs/appimage.md - AppImage packaging details
• docs/development.md - contributor-focused architecture/workflow notes

Repository Layout

scanslicer/                  Application source (UI, controllers, canvas, detection)
packaging/appimage/           AppImage recipe and build scripts
Dockerfile                    Runtime image
docker-compose.yml            GUI container runtime wiring
pyproject.toml                Python package metadata and dependencies