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.