optional-skills/creative/draw-your-font/references/troubleshooting.md
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).
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.