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, whose original maintainer is inactive. It is kept in a working state for the maintainer's own photo scans.

Upstream credit: the original is inspired by 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 from source (uv)

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

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

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.

Run the AppImage (preferred)

Build the AppImage and run it:

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

See docs/appimage.md for full details, including the local build path and a Docker Desktop caveat.

CLI

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.

Docker

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

docker compose up --build

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

Documentation

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

Repository

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. See THIRD_PARTY_NOTICES for bundled third-party components.