dan/ScanSlicer
dan/ScanSlicer
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

docs: finalize README, attribute fork, sync AGENTS.md

Browse source 
- 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
This commit is contained in:
dan 2026-09-11 23:24:54 +02:00
parent 426a18f342
commit 5f71b61596
3 changed files with 79 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

13
AGENTS.md
View file

@ -14,12 +14,15 @@ Vannini). Runs on Linux over Wayland or X11.
This repo is a **local fork** of This repo is a **local fork** of
[macrodev8/ScanSlicer](https://github.com/macrodev8/ScanSlicer) (upstream owner [macrodev8/ScanSlicer](https://github.com/macrodev8/ScanSlicer) (upstream owner
inactive). License: GNU GPL v3 (must be preserved). Attribution: keep upstream inactive). License: GNU GPL v3 (must be preserved). Attribution: keep upstream
credit and the "inspired by PhotoSlicer" note. credit and the "inspired by PhotoSlicer" note; `pyproject.toml` lists both the
fork maintainer and the upstream author, and `README.md` states the fork
relationship and the changes made.
## Goals of this fork ## Goals of this fork
1. Fix the mirrored-export orientation bug and add an explicit left/right 1. Fix the mirrored-export orientation bug and add an explicit left/right
orientation workflow (implemented, see below). This is the primary patch. orientation workflow. Implemented, tested in the GUI, and committed — see
"The orientation fix" below. This was the primary patch.
2. Keep the app usable on the maintainer's own photo scans; afterwards only 2. Keep the app usable on the maintainer's own photo scans; afterwards only
minimal maintenance is expected. minimal maintenance is expected.
3. Push to the maintainer's Forgejo instance at `code.dgerdesmann.de` (no 3. Push to the maintainer's Forgejo instance at `code.dgerdesmann.de` (no
@ -114,6 +117,12 @@ uv run scanslicer /path/to/scans # or: python -m scanslicer
- Dependencies (from `pyproject.toml`): PySide6, opencv-python-headless, numpy. - Dependencies (from `pyproject.toml`): PySide6, opencv-python-headless, numpy.
- Python >= 3.10; dev env is Python 3.12 in `.venv`. - Python >= 3.10; dev env is Python 3.12 in `.venv`.
Dependency / supply-chain decisions (deliberate — keep them):
- `opencv-python-headless` is intentional: the app uses no OpenCV GUI/highgui.
- Pillow was removed (it was unused). Don't re-add without a concrete need.
- The AppImage build exports hashes from `uv.lock` and installs with
`pip install --require-hashes`.
### AppImage build: Docker context gotcha ### AppImage build: Docker context gotcha
The maintainer's Docker points at Docker Desktop (`desktop-linux` context). Its The maintainer's Docker points at Docker Desktop (`desktop-linux` context). Its

152
README.md
View file

@ -1,10 +1,27 @@
# ScanSlicer # ScanSlicer (fork)
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. 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.
Inspired by [PhotoSlicer](https://github.com/francescovannini/photoslicer) by Francesco Vannini. 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.
This repository keeps GNU GPL v3 licensing for compatibility with that upstream work. 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 ## What It Does
@ -13,136 +30,99 @@ This repository keeps GNU GPL v3 licensing for compatibility with that upstream
- Provides manual correction tools (corner drag, edge drag, rotate, move, add/remove box). - Provides manual correction tools (corner drag, edge drag, rotate, move, add/remove box).
- Saves only locked boxes, each as a perspective-corrected output image. - Saves only locked boxes, each as a perspective-corrected output image.
- Includes auto-tuning with feedback learning from your prior saved results. - Includes auto-tuning with feedback learning from your prior saved results.
- Works on Linux desktops over Wayland or X11.
## Requirements ## Requirements
- Python `>=3.10` - Python >= 3.10
- Linux desktop session (for example KDE Plasma) over Wayland or X11 - A Linux desktop session over Wayland or X11
- System libraries required by Qt/OpenCV (see `Dockerfile` for a known-good package set) - System libraries required by Qt/OpenCV (see `Dockerfile` for a known-good set)
Project dependencies (from `pyproject.toml`): Project dependencies (from `pyproject.toml`): `PySide6`, `opencv-python-headless`, `numpy`.
- `PySide6`
- `opencv-python-headless`
- `numpy`
## Quick Start ## Quick Start
### Run with `uv` ### Run from source (uv)
```bash ```bash
uv sync --frozen uv sync --frozen
uv run scanslicer
```
Open a specific input directory at launch:
```bash
uv run scanslicer /path/to/scans uv run scanslicer /path/to/scans
``` ```
Choose backend explicitly: Open with no startup directory, or select the display backend explicitly:
```bash ```bash
uv run scanslicer
uv run scanslicer --backend wayland uv run scanslicer --backend wayland
uv run scanslicer --backend x11 uv run scanslicer --backend x11
``` ```
### Run with Python directly You can also run the installed package directly with `python -m scanslicer`.
### Run the AppImage (preferred)
Build the AppImage and run it:
```bash ```bash
python -m scanslicer 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 ### CLI
```text ```text
scanslicer [path] [--backend {auto,wayland,x11}] scanslicer [path] [--backend {auto,wayland,x11}]
``` ```
- `path`: optional startup directory containing scan images.
- `--backend`: display backend selection. `auto` is default.
## Typical Workflow ## Typical Workflow
1. Open an input directory. 1. Open an input directory.
2. Verify output directory (defaults to the opened input directory). 2. Verify the output directory (defaults to the opened input directory).
3. Click `Detect` (or use auto detection triggered on image load). 3. Run detection (`Detect`), or rely on automatic detection on image load.
4. Adjust boxes as needed. 4. Adjust boxes as needed (drag corners/edges, rotate, move, add/remove).
5. Lock boxes you want to export (or use lock-all). 5. Lock the boxes to export (or use lock-all).
6. Choose save format (`jpg` or `png`) and quality/compression. 6. Choose the save format (`jpg` or `png`) and quality/compression.
7. Click `Save images`. 7. Click `Save images`.
Only locked boxes are exported. Only locked boxes are exported.
## Runtime Behavior ## Configuration
- Detection and auto-tune run in background worker tasks (`QThreadPool`) so UI stays responsive. ScanSlicer stores its defaults, presets, auto-tune feedback, and a session
- Status events are written to a session log file and reflected in the status bar. status log under `~/.config/scanslicer/` (or `$XDG_CONFIG_HOME/scanslicer/`).
- Detection results are cached (normal and filter preview) to avoid unnecessary re-processing when toggling filter preview. All paths can be overridden via `SCANSLICER_*_PATH` environment variables. See
[docs/runtime-config.md](docs/runtime-config.md).
## Data and Config Files ## Docker
Persistence paths depend on how ScanSlicer is run. A GUI-oriented compose setup is provided for Linux desktop use:
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 ```bash
docker compose up --build docker compose up --build
``` ```
See `.env.example` and `docker-compose.yml` for required host UID/GID and Wayland/XDG settings. See `.env.example` and `docker-compose.yml` for 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 ## Documentation
- `docs/README.md` - documentation index See [docs/README.md](docs/README.md) for an index and recommended reading order
- `docs/user-guide.md` - end-user operation guide (end-user guide, parameters, auto-tune, architecture, runtime config,
- `docs/architecture.md` - code architecture and execution flow AppImage, development).
- `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 ## Repository
```text ```text
scanslicer/ - Application source (UI, controllers, canvas, detection) scanslicer/ application source (package)
packaging/appimage/ - AppImage recipe and build scripts packaging/appimage/ AppImage recipe and build scripts
Dockerfile - Runtime image docs/ end-user and developer documentation
docker-compose.yml - GUI container runtime wiring Dockerfile / docker-compose.yml container runtime
pyproject.toml - Python package metadata and dependencies 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.

3
pyproject.toml
View file

@ -10,7 +10,8 @@ readme = { file = "README.md", content-type = "text/markdown" }
requires-python = ">=3.10" requires-python = ">=3.10"
license = { text = "GPLv3" } license = { text = "GPLv3" }
authors = [ authors = [
{ name = "macrodev", email = "macron.dev@proton.me" } { name = "dan", email = "dan@noreply.code.dgerdesmann.de" },
{ name = "macrodev", email = "macron.dev@proton.me" },
] ]
classifiers = [ classifiers = [
"License :: OSI Approved :: GNU General Public License v3 (GPLv3)", "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",