dan
5f71b61596
- Rewrite README for fork context, add changes-from-upstream section, prune sections duplicated by docs/, surface AppImage as preferred run - Add fork maintainer alongside upstream author in pyproject.toml - Sync AGENTS.md with completed patch and deliberate supply-chain decisions
128 lines
4 KiB
Markdown
128 lines
4 KiB
Markdown
# 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)**,
|
|
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](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 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`.
|
|
|
|
### Run the AppImage (preferred)
|
|
|
|
Build the AppImage and run it:
|
|
|
|
```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, including the local
|
|
build path and a Docker Desktop caveat.
|
|
|
|
### 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.
|