ScanSlicer/docs/user-guide.md

# User Guide

## Goal

ScanSlicer helps you turn a single scan image (for example, a flatbed scan containing many printed photos) into individual straightened output files.

## Supported Input/Output

- Input directory scan for files ending with: `.png`, `.jpg`, `.jpeg`
- Output formats:
  - `jpg` with quality control (`1-100`)
  - `png` with compression control (`0-9`)

## Main UI Areas

- Left panel:
  - Directory and image navigation
  - Save settings
  - Presets and auto-tune
  - Detection parameter controls
- Right panel:
  - Preview canvas with detected/manual boxes
  - Toolbar actions (detect, lock, rotate mode, add/remove box, etc.)
- Bottom status bar:
  - Current status text
  - Current filename

## Basic Workflow

1. Click `Open directory`.
2. Confirm `Output Directory` (or click `Set output directory`).
3. Select sorting mode (`Name` or `Time`) if needed.
4. Load an image from the image dropdown, or use previous/next buttons.
5. Run detection (`Detect`) or rely on automatic detect-on-load.
6. Review and edit boxes.
7. Lock the boxes to export.
8. Click `Save images`.

## Box Editing

### Select and inspect

- Click inside a box to make it active.
- Active box index is shown in the toolbar (`Active Box: N`).

### Corner drag

- Drag corner handles to reshape the quadrilateral freely.

### Move entire box

- Double-click inside a box, then drag to move it.

### Rotate mode

- Toggle rotate mode (toolbar rotate button).
- Drag corner handles to rotate the active box.

### Squarize

- Converts active quadrilateral into a cleaner rectangle while preserving tilt.
- Enables side handles for edge-length adjustment.

### Reset rotation

- Resets active box orientation to axis-aligned while keeping center/size.

### Add/remove

- `Add box`: inserts a new manual box (starts locked).
- `Remove active box`: deletes current active box.

## Locking Behavior

- Only locked boxes are saved.
- `Lock/unlock active` toggles one box.
- `Lock/unlock all` toggles every box currently shown.
- During new detections, locked boxes are preserved and merged with new candidates (overlap-aware).

## Canvas Navigation

- Right-click drag: pan.
- Mouse wheel: zoom.
- `Reset view`: re-fit image to viewport.

## Preview Filter Toggle

- `Filter` shows the processed detection mask preview instead of the original image.
- This uses cached results from the last detection run.

## Auto-Tune Workflow

1. Choose profile (`Fast`, `Balanced`, `Thorough`, `Exhaustive`).
2. Click `Auto-tune`.
3. Auto-tune runs a coarse candidate scan then refines top candidates.
4. Best parameter set is applied automatically.
5. Run detection again (handled by app after auto-tune completion).

## Presets and Defaults

- `Load defaults`: load saved defaults if present; else factory defaults.
- `Save new defaults`: persist current parameters as default.
- `Save as preset...`: save current parameter set with a name.
- `Delete current preset`: remove a user preset.
- Preset dropdown:
  - `Custom` means unsaved/manual state.
  - Built-in presets are currently empty; user presets are supported.

## Saving Outputs

- Save filename format:
  - `<input_basename>_<index>.<ext>`
  - Example: `scan_003.jpg`
- Export uses perspective transform per box, so output is straightened to the box geometry.
- If no locked boxes exist, save is blocked with a warning.

## Status and Logs

- Status messages are shown in the bottom bar.
- A session log is also written to disk (`status.log` path depends on runtime config).

## Tips

- If no photos are detected:
  - Try toggling `Preview filter` to inspect mask quality.
  - Adjust threshold/canny, morphology, and area/aspect controls.
  - Use `Auto-tune` with a deeper profile.
- For mixed photo sizes:
  - Relax `Min Photo Size` and widen aspect ratio bounds.
- For border artifacts:
  - Increase `Ignore Border Margin`.