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](https://github.com/francescovannini/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` (recommended for local dev)

```bash
uv sync --frozen
uv run scanslicer
```

Open a specific input directory at launch:

```bash
uv run scanslicer /path/to/scans
```

Choose backend explicitly:

```bash
uv run scanslicer --backend wayland
uv run scanslicer --backend x11
```

### Run with Python directly

The package directory now matches the published name:

```bash
python -m scanslicer
```

### CLI

```text
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

Default host paths:

- 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`

Container behavior:

- When running in container and `/work` exists, these are stored under `/work/.scanslicer/`.

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:

```bash
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

```text
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
```