scansplitter 0.5.1

Automatically detect, split, and rotate multiple photos from scanned images

ScanSplitter

Automatically detect, split, and rotate multiple photos from scanned images.

Drop a scan containing multiple photos and get individual, correctly-oriented images back.

Quick Start

One-time setup - Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Run ScanSplitter (no clone needed):

uvx scansplitter api

Opens at http://localhost:8000 - drag & drop your scans and export cropped photos. If port 8000 is already in use, pick another:

uvx scansplitter api --port 8001

Features

• Multiple detection modes - Choose between ScanSplitterv1, ScanSplitterv2 (default), and AI (U2-Net)
• Interactive editing - Adjust, rotate, and resize bounding boxes before cropping
• Auto-rotation - Detects and corrects 90°/180°/270° rotations
• PDF support - Extract and process pages from PDF files
• Persistent projects - Import large collections, review only uncertain scans, and continue across restarts
• Archival workflow - Add dates, places, captions, people, restoration settings, lossless masters, and manifests
• Web UI - Modern React interface with Fabric.js canvas editor
• CLI - Batch process files from the command line

Detection Modes & Models

Photo detection (splitter)

• ScanSplitterv2 (default): An improved contour-based detector. It applies contrast enhancement (CLAHE), adaptive thresholding, adaptive morphology (kernel scales with resolution), and contour quality filtering (solidity/aspect/extent). It can also use convex-hull borders for irregular edges.
• ScanSplitterv1: The first contour-based detector used with adaptive threshold + fixed morphology + minAreaRect filtering. It’s simpler and can be useful as a fallback if v2 behaves unexpectedly on a specific scan.
• AI (U2-Net): A deep-learning salient-object model (ONNX) that produces a mask; ScanSplitter then extracts regions from that mask. It’s best for difficult scans (busy backgrounds, low contrast), but requires downloading a model on first use. Might be less accurate for multiple photos at once.

Auto-rotation model

• Orientation model: An EfficientNetV2-based ONNX classifier that predicts the correct 0°/90°/180°/270° rotation for each cropped photo. ScanSplitter may fall back to classic heuristics if the model can’t be loaded.

Model downloads

Some modes require downloading models on first use (U2-Net (5Mb / 176MB) and the orientation model (80MB)). The web UI shows download progress while this is happening.

Installation Options

Option 1: Run directly with uvx (recommended)

No installation needed - just run:

uvx scansplitter api

Option 2: Install with pipx

pipx install scansplitter
scansplitter api

Option 3: Install from source

git clone https://github.com/madnex/scansplitter
cd scansplitter
uv sync
uv run scansplitter api

Usage

Web Interface

scansplitter api
# or: uvx scansplitter api

Opens at http://localhost:8000 with:

• Drag & drop file upload (images and PDFs)
• Interactive bounding box editor (drag, resize, rotate)
• Multi-file support with tabs
• PDF page navigation
• JPEG or lossless PNG export

The web interface has two modes:

• Quick processes an ad-hoc set of scans and exports the current results.
• Projects keeps a named collection on disk, detects bulk uploads in the background, and tracks review, metadata, restoration, and delivery settings.

Projects workflow

Projects are intended for larger collections that may take more than one session to finish:

1. Open Projects, create a named project, and add images or PDFs. PDF pages become individual scans. Detection starts in the background.
2. ScanSplitter automatically approves clear detections and marks uncertain scans CHECK. Use Start review or open a scan from the grid.
3. In review, adjust the photo boxes when necessary and choose Approve. Press Enter to approve and advance, or use the arrow keys to move through the queue. Re-detect runs detection again for the current scan.
4. Add collection or per-scan metadata such as dates, places, captions, people, album/roll, and event. Front/back pairing links a photographed print's reverse side to its front; record any inscription manually in the caption.
5. Optionally enable non-destructive deskew, color/fade correction, or 2× upscale. Compare previews the first photo without changing the stored scan; each photo can override the project defaults.
6. Export approved photos as JPEG or lossless PNG. Projects can also create a PNG/TIFF master, organize files by metadata, include a JSON/CSV manifest, or deliver to a watched folder, Immich, or Nextcloud WebDAV.

Connect Immich

ScanSplitter only uploads approved JPEG or PNG access copies. It does not read, modify, or delete assets already stored in Immich, so its API key needs only the asset.upload permission:

1. Sign in to Immich as the user who should own the uploaded photos.
2. Open Account Settings → API Keys and create a key named, for example, ScanSplitter.
3. Choose custom/scoped permissions and enable only asset.upload. Do not grant all, asset deletion, or administrator permissions.
4. In ScanSplitter, open the project, choose Deliver → Immich, and enter:
   • Immich server: the public base URL, such as https://photos.example.com. A URL ending in /api also works.
   • API key: the key created above.
5. To avoid entering the connection again, enable Remember this connection securely. The API key is stored in the operating system credential vault, never in the project or browser storage. If no supported vault is available, ScanSplitter keeps using one-time credential entry.
6. Choose Deliver. Saved credentials can later be reused, updated, or forgotten from the Delivery dialog. Saved-secret features are available only while ScanSplitter runs in local mode.

The uploaded photos belong to the Immich user who created the API key. If delivery returns 401 or 403, check that the key is valid and has asset.upload. A reverse proxy must allow POST requests and the size of the photos being uploaded to Immich's /api/assets endpoint.

Flags explain why a scan needs review. They can report that no photo was found, a box touches a scan edge, a box has an unusual aspect ratio or size, boxes overlap, or the detected photo count differs from most scans in the project. Flags are warnings rather than hard errors: correct the boxes if needed, then approve the scan. Only approved and automatically approved scans are exported.

Projects persist under ~/.scansplitter/projects/. Set SCANSPLITTER_DATA_DIR to use another data directory. Original project scans remain untouched by metadata, restoration, and export operations. ScanSplitter is designed as a local, single-user application and does not provide an authentication layer for a publicly exposed server.

For implementation details, see the roadmap and the binding feature specifications.

Command Line

# Process a scanned image
uv run scansplitter process scan.jpg -o ./output/

# Process a PDF
uv run scansplitter process document.pdf -o ./output/

# Multiple files
uv run scansplitter process scan1.jpg scan2.png -o ./output/

# Options
uv run scansplitter process scan.jpg \
  --no-rotate \
  --min-area 5 \
  --max-area 70 \
  --detection-mode scansplitterv2 \
  --format jpg \
  -o ./output/

CLI Options:

Option	Description
-o, --output	Output directory (default: ./output)
--no-rotate	Disable auto-rotation
--min-area	Minimum photo size as % of scan (default: 2)
--max-area	Maximum photo size as % of scan (default: 80)
--detection-mode	scansplitterv2 (default), scansplitterv1 (legacy), or u2net (deep learning); classic is an alias for scansplitterv2
--u2net-full	Use full U2-Net model instead of lite (slower, more accurate)
--format	Output format: png or jpg (default: png)

How It Works

1. Photo detection - Runs the selected detection mode (ScanSplitterv1 / ScanSplitterv2 / AI (U2-Net)) to produce rotatable bounding boxes.
2. Interactive adjustment - You can refine boxes in the web UI before cropping.
3. Cropping - Extracts rotated regions using the adjusted boxes.
4. Auto-rotation (optional) - Uses the orientation model (with fallbacks) to fix 90°/180°/270° rotations.

Credits

ScanSplitter depends on excellent open models and upstream work:

• U²-Net (salient object detection) by Xuebin Qin et al. — paper: https://arxiv.org/abs/2005.09007, code: https://github.com/xuebinqin/U-2-Net
• U2-Net ONNX weights are downloaded from rembg releases by Daniel Gatis (with a ScanSplitter backup mirror) — https://github.com/danielgatis/rembg
• Orientation model (EfficientNetV2) is downloaded from Duarte Barbosa’s deep image orientation detection project (with a ScanSplitter backup mirror) — https://github.com/duartebarbosadev/deep-image-orientation-detection

Development

Frontend Development

# Start API server
uv run scansplitter api --reload

# In another terminal, start frontend dev server
cd frontend
npm install
npm run dev

Frontend runs on http://localhost:5173 with hot reload, proxying API requests to :8000.

Build Frontend

cd frontend
npm run build

Builds to src/scansplitter/static/, which FastAPI serves automatically.