ScanSlicer/README.md

# ScanSlicer (fork)

ScanSlicer is a desktop Qt application (Python/PySide6) that detects multiple photos in a flatbed scan image, lets you correct each box manually, and exports perspective-corrected crops. It runs on Linux desktops over Wayland or X11.

This is a **fork of [macrodev8/ScanSlicer](https://github.com/macrodev8/ScanSlicer)**.

Upstream credit: the original is inspired by
[PhotoSlicer](https://github.com/francescovannini/photoslicer) by Francesco Vannini. This repository keeps the GNU GPL v3 license for compatibility with that upstream work.

## Changes from upstream

- Fixed mirrored slice exports: added an explicit left/right orientation workflow with a **Swap L/R** button and color-coded left/right corners and edges.
- Orientation corrections now persist through "squarize" and "reset rotation" (previously they were silently overwritten).
- Hardened dependencies: switched to `opencv-python-headless`, removed the unused Pillow dependency, and made the AppImage build verify package hashes.

## 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.

## Requirements

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

Project dependencies (from `pyproject.toml`): `PySide6`, `opencv-python-headless`, `numpy`.

## Quick Start

### Run the AppImage (recommended)

Use the provided AppImage file under "Releases", or build and run it yourself:

```bash
bash packaging/appimage/build-appimage-docker.sh
./appimage/dist/ScanSlicer-<version>-x86_64.AppImage
```

See [docs/appimage.md](docs/appimage.md) for full details.

### Run from source (uv)

```bash
uv sync --frozen
uv run scanslicer /path/to/scans
```

Open with no startup directory, or select the display backend explicitly:

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

You can also run the installed package directly with `python -m scanslicer`.

### CLI

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

## Typical Workflow

1. Open an input directory.
2. Verify the output directory (defaults to the opened input directory).
3. Run detection (`Detect`), or rely on automatic detection on image load.
4. Adjust boxes as needed (drag corners/edges, rotate, move, add/remove).
5. Lock the boxes to export (or use lock-all).
6. Choose the save format (`jpg` or `png`) and quality/compression.
7. Click `Save images`.

Only locked boxes are exported.

## Configuration

ScanSlicer stores its defaults, presets, auto-tune feedback, and a session status log under `~/.config/scanslicer/` (or `$XDG_CONFIG_HOME/scanslicer/`). All paths can be overridden via `SCANSLICER_*_PATH` environment variables. See
[docs/runtime-config.md](docs/runtime-config.md).

## Docker

A GUI-oriented compose setup is provided for Linux desktop use:

```bash
docker compose up --build
```

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

## Documentation

See [docs/README.md](docs/README.md) for an index and recommended reading order (end-user guide, parameters, auto-tune, architecture, runtime config, AppImage, development).

## Repository

```text
scanslicer/                 application source (package)
packaging/appimage/         AppImage recipe and build scripts
docs/                       end-user and developer documentation
Dockerfile / docker-compose.yml   container runtime
pyproject.toml / uv.lock    package metadata and pinned dependencies
```

## License

GNU GPL v3 — see [LICENSE](LICENSE). See
[THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES) for bundled third-party components.