# Troubleshooting capture & segmentation

The binarizer is adaptive (local background estimate) with two knobs on
`segment`/`make`:

- `--delta N` (default 40): how much darker than the local paper a pixel must
  be to count as ink. Lower = more sensitive (catches faint pens, also more
  noise). Raise to 55–70 for photos with heavy shadows misread as ink.
- `--cap N` (default 165): absolute grey ceiling for ink after contrast
  normalization. Anything lighter is never ink - this is what erases the
  template's grey guides. Lower to 140 if printed guides survive into blobs;
  raise to 190 for a very faint pencil (expect more noise).

Re-running segment rewrites blobs.json and renumbers every blob - discard
any labels.json written earlier and relabel from the fresh contact sheet
(prefer a fresh `-d` workdir).

## Symptoms → fixes

**Hundreds of tiny blobs** - noisy paper texture or aggressive delta. Re-run
segment with `--delta 55`. If the photo is low light, ask for a brighter shot.

**A huge blob spanning the page** - a shadow edge or the page border got
thresholded. Crop the photo to just the paper (or re-shoot from directly
above), or raise `--delta`.

**Letters missing entirely** - pen too faint (pencil, gel on glossy paper).
Try `--delta 25 --cap 190`. If still missing, the honest fix is rewriting
with a darker pen; say so.

**Strokes broken into fragments** - thin ballpoint. Try `--delta 30`, then
`build --weight 1` to fatten what traced. Recommend a 0.5mm+ pen for the
re-shoot.

**Two letters in one box** - they touch on paper. No code fix; ask the user
to re-write just those letters with space between them, segment the new
photo, and merge via labels.

**Template guides appear as blobs** - printer printed the grey too dark.
Re-run with `--cap 140`. If their printer only does solid black, they can
still use the template - the guides will show as long thin blobs; label them
all `""`.

**i/j dots detached as separate blobs** - normally auto-merged; if the dot is
very far from the stem it may not be. Label the stem blob with the letter and
the dot `""` - or better, relabel both after a re-shoot. (A dotless i still
reads fine in most handwriting.)

**Rotated/skewed photo** - mild angles are fine and become part of the font's
character. A strongly rotated photo (>5°) will slant every glyph; ask for a
straighter shot rather than trying to compensate.