dan
929c828438
- Drop unused Pillow dependency - Switch opencv-python to opencv-python-headless (~=4.13.0) - Verify package hashes in the AppImage build (uv export hashes, pip install --require-hashes, separate --no-deps wheel install) - Sync dependency docs and third-party notices
148 lines
4.5 KiB
Markdown
148 lines
4.5 KiB
Markdown
# 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-headless`
|
|
- `numpy`
|
|
|
|
## Quick Start
|
|
|
|
### Run with `uv`
|
|
|
|
```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
|
|
|
|
```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
|
|
|
|
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`
|
|
|
|
## 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
|
|
```
|