Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

optional-skills/creative/draw-your-font/references/troubleshooting.md

@@ -0,0 +1,51 @@
+# 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.