Concept for dvi3v project
v3.9.2.208

Problem: Creating vector outlines of physical objects requires manual tracing in software like Inkscape or Illustrator.

Solution: Automated extraction from photos—snap a picture, get an SVG.

Problem: Simple image-to-SVG converters don't preserve real-world scale.

Solution: Uses reference paper (A4, Letter, etc.) to calculate precise mm dimensions.

Problem: Real-world photos have varying lighting, backgrounds, and object positions.

Solution: Robust detection with auto-optimizing threshold, works with any background.

Problem: Objects with holes (scissors, keys) or complex shapes are difficult.

Solution: Optional hole-filling mode, morphological operations for cleanup.

Challenge: Convert pixels to millimeters

Method: three detection strategies, tried in order until one validates against the expected paper aspect ratio:

1. Automatic color detection (default, when --paper-color is not given): the photo is reduced to its dominant colors by color clustering (ImageMagick's built-in quantization), and each large-enough color is tried as a match target, largest first.
2. Named color match (when --paper-color names a non-neutral color, e.g. red; also used internally by step 1 for each candidate): the photo is matched by color distance against that color's RGB value, with tolerance for lighting and camera white balance.
3. Brightness match (the only method for a neutral --paper-color — white, gray, light/dark gray, or black — and the fallback if 1–2 find nothing valid): the photo is converted to grayscale and searched for the largest sufficiently bright region of the right aspect ratio.

Once the paper region is found: measure its pixel dimensions, then calculate scale: px_per_mm = pixels / known_mm, applied to the whole image. If no valid paper region is found by any method, batch mode falls back to an EXIF-based estimate (subject distance and focal length, when available) or --reference-mm if given.

Formats Supported:

Paper Colors: any color name accepted by --color (see below) can be given via --paper-color; automatic detection (method 1 above) handles most colored paper without the flag at all.

Challenge: Identify the correct object among noise, artifacts, background

Method: candidate selection, then multi-factor scoring

At each threshold tried, two thresholding polarities are tried and the better-scoring candidate kept: "dark" (object darker than its background) and "light" (object lighter than its background) — which applies cannot be assumed from the photo alone (a white object on colored paper needs "light"; most other cases need "dark"). Within each polarity, connected-component candidates are filtered by two safeguards before scoring:

• A candidate covering more than 70% of the frame is rejected outright — a legitimate, centered, not-cut-off object never fills most of the photo.
• A candidate whose bounding box contains more than 85% of the detected reference paper's own area is rejected — the paper is never legitimately "the object", even though it can be large and centered enough to otherwise look plausible.

The surviving candidate closest to center (with a bounded, non-runaway area term, so a bigger region is never preferred purely for being bigger) is picked for that threshold/polarity, then scored on 5 factors (0-100 points) for the auto-threshold comparison across thresholds:

Auto-Threshold:

• Tests N threshold values (default: 30-80% range)
• Evaluates each (both polarities) with the scoring system above
• Selects optimal balance between detection quality and stability

Purpose: Clean object edges, fill holes, add margins

Operations Used:

• Close: Fill small gaps, connect nearby regions
• Open: Remove noise, smooth edges
• Dilate: Expand object (for margins)
• Erode: Shrink object (part of Close/Open)

Hole Filling (–no-holes / -n, a boolean flag, no argument):

Method: Topological exterior flood-fill
1. Clean edges (morphology Close Disk:3)
2. Flood-fill the exterior background from a border corner, marking it;
   whatever the flood cannot reach is an enclosed hole
3. Turn every enclosed hole white (filled); restore the marked exterior
   to black
4. Despeckle (morphology Open Disk:2) to remove isolated noise pixels
   before the margin is added -- otherwise a single stray pixel becomes
   a disproportionate solid disk once dilated by the margin
5. Result: internal holes filled, of any size or shape, without eroding
   thin frames (unlike a fixed-radius morphological close)

Default (no -n): holes are preserved, not filled.
Usage: -n    # fill all enclosed holes
       (no strength/radius parameter)

Tool: potrace (bitmap to vector converter)

Settings:

• --tight: Minimize SVG file size
• --alphamax 0.8: Corner detection sensitivity
• --opttolerance 0.3: Curve optimization

Output: Single SVG path element with fill color

Formula:

Reported at runtime (console output, and in debug_info.txt under -d; not embedded in the SVG itself — see Output SVG Structure below):

• Scale factor (px/mm) and detection method (paper-detected — and by which of the three paper-detection methods — EXIF-estimated, or user-provided via --reference-mm)
• Reference paper format and color (when paper-detected)
• Object dimensions (width × height in mm) and polarity (dark/light)
• Margin applied and fill color

Rationale:

• Bash: Universal on Linux/Unix systems
• ImageMagick: Powerful image processing, already installed on most systems
• Core SVG extraction needs neither Python nor a compiled toolchain (Python 3 is used only by the optional --stl export's default backend; --stl scad uses OpenSCAD instead, and STL is skipped entirely, with a warning, if neither is available)

Trade-off: Less performance than compiled code, but sufficient for typical use

Rationale:

• Common, available everywhere (A4, Letter)
• Known dimensions (210×297mm, 216×279mm)
• No special equipment needed

Alternative considered: QR codes with embedded scale → Rejected (too complex)

Rationale:

• Users naturally place subject in center
• Reduces false positives (background objects)

Alternative considered: Machine learning detection → Rejected (overkill, dependencies)

Rationale:

• Manual threshold selection tedious
• Optimal value varies per image
• Quality scoring enables automation

Implementation: Multi-factor scoring (v2.4+) with threshold stability

Rationale:

• Some objects need holes preserved (eyeglass frames)
• Some need holes filled (scissors handles, keys)
• User choice is best

Implementation: Flood fill from edges