Explain the hybrid technology pipeline

README.md

@@ -9,7 +9,7 @@
 [![License: GPL-3.0-or-later](https://img.shields.io/badge/license-GPL--3.0--or--later-4C1?style=flat-square)](LICENSE)
 [![Public beta](https://img.shields.io/badge/status-public%20beta-D97706?style=flat-square)](https://github.com/Jayktopus/Scan2Sketch-OpenSource/releases)
 
-[Install](#installation) · [How it works](#how-it-works) · [Roadmap](ROADMAP.md) · [Contribute](CONTRIBUTING.md) · [Deutsch](README_DE.md)
+[Install](#installation) · [How it works](#how-it-works) · [Technology](TECHNOLOGY.md) · [Roadmap](ROADMAP.md) · [Contribute](CONTRIBUTING.md) · [Deutsch](README_DE.md)
 
 ![Scan2Sketch demonstration: scan selection, contour review, sketch creation and pad](media/demo/scan2sketch-demo.gif)
 
@@ -34,6 +34,9 @@ creating a real `Sketcher::SketchObject`.
 The correction workspace supports both a guided workflow for new users and
 fine-grained tools for advanced contour editing.
 
+For a plain-language overview and a detailed description of the hybrid
+pipeline, see [Technology explained](TECHNOLOGY.md).
+
 ## Capabilities
 
 | Area | What Scan2Sketch provides |

README_DE.md

@@ -9,7 +9,7 @@
 [![Lizenz: GPL-3.0-or-later](https://img.shields.io/badge/Lizenz-GPL--3.0--or--later-4C1?style=flat-square)](LICENSE)
 [![Öffentliche Beta](https://img.shields.io/badge/Status-öffentliche%20Beta-D97706?style=flat-square)](https://github.com/Jayktopus/Scan2Sketch-OpenSource/releases)
 
-[Installation](#installation) · [Funktionsweise](#so-funktioniert-es) · [Roadmap](ROADMAP.md) · [Mitwirken](CONTRIBUTING.md) · [English](README.md)
+[Installation](#installation) · [Funktionsweise](#so-funktioniert-es) · [Technologie](TECHNOLOGY_DE.md) · [Roadmap](ROADMAP.md) · [Mitwirken](CONTRIBUTING.md) · [English](README.md)
 
 ![Scan2Sketch-Demonstration: Scan auswählen, Kontur prüfen, Skizze und Pad erzeugen](media/demo/scan2sketch-demo.gif)
 
@@ -34,6 +34,9 @@ Erzeugung eines echten `Sketcher::SketchObject` wird das Ergebnis geprüft.
 Das Korrekturfenster bietet einen geführten Ablauf für neue Nutzer und präzise
 Einzelwerkzeuge für fortgeschrittene Konturbearbeitung.
 
+Eine verständliche Kurzfassung und die vollständige technische Beschreibung
+stehen unter [Technologie erklärt](TECHNOLOGY_DE.md).
+
 ## Funktionsumfang
 
 | Bereich | Funktionen |

TECHNOLOGY.md

@@ -0,0 +1,247 @@
+# Technology explained
+
+[Basic explanation](#basic-explanation) · [Detailed pipeline](#detailed-pipeline) · [Limits](#what-the-system-does-not-claim) · [Code map](#implementation-map) · [Deutsch](TECHNOLOGY_DE.md)
+
+Scan2Sketch does not ask one AI model to produce final CAD geometry. It uses
+several independent views of the scan, compares them, returns to the original
+pixels for measurement, and validates the resulting geometry before FreeCAD
+receives it.
+
+## Basic explanation
+
+### Why a hybrid exists
+
+Different methods fail in different ways:
+
+- OpenCV is deterministic and preserves full image resolution, but shadows or
+  internal texture can resemble an object boundary.
+- SAM is good at identifying the intended object, but its mask is not a
+  dimensional CAD measurement.
+- Light HQ-SAM often preserves small structures and corners better, but it is
+  still a segmentation model rather than a measuring instrument.
+- CAD fitting can produce clean lines and circles, but only after the correct
+  material edge and topology have been established.
+
+Scan2Sketch therefore gives each method a limited role instead of trusting any
+single result blindly.
+
+### The short version
+
+```mermaid
+flowchart LR
+    A["Calibrated scan"] --> B["OpenCV: component and full-resolution edges"]
+    B --> C["SAM: semantic object mask"]
+    B --> D["Light HQ-SAM: detailed object mask"]
+    C --> E["Mask candidates are scored"]
+    D --> E
+    B --> E
+    E --> F["Original pixels: material-edge refinement"]
+    F --> G["Lines, circles, arcs and B-splines"]
+    G --> H["User review and correction"]
+    H --> I["Topology and FreeCAD export checks"]
+```
+
+In normal language:
+
+1. Calibration turns pixels into millimetres and can correct a saved scanner
+   distortion profile.
+2. OpenCV proposes the physical component and examines its edges at the scan's
+   original resolution.
+3. SAM and Light HQ-SAM provide two additional interpretations of which pixels
+   belong to that component.
+4. Scan2Sketch creates several possible combinations, scores them against the
+   image and chooses a coarse working mask.
+5. The program examines the original image again to find consistent material
+   edges. The segmentation vote is not treated as the final CAD contour.
+6. Plausible geometric primitives and alternative edge candidates are offered
+   for review. The user can keep, replace or correct them.
+7. Only closed, non-branching and non-self-intersecting geometry is written to
+   FreeCAD. The exported sketch is checked against the accepted preview.
+
+## Detailed pipeline
+
+### 1. Input and calibration
+
+The image is loaded without changing the original file. A `mm_per_pixel` scale
+comes from a validated calibration rather than being inferred silently from
+object size. Saved calibration profiles can apply scale and two-dimensional
+distortion corrections to the neutral geometry.
+
+Image-processing tolerances are defined in physical units where practical and
+converted to pixels only at image-processing boundaries. This keeps a setting
+such as a 0.20 mm feature comparable at 300, 600 and 1200 dpi.
+
+### 2. OpenCV component bootstrap
+
+OpenCV finds connected component candidates using colour, contrast and
+threshold evidence. A click can select the intended component; the largest
+region is only a suggestion. The selected bounding box, centroid and area
+become the common region of interest for the other backends.
+
+A deterministic stability pass analyzes several threshold interpretations in
+the original-resolution region. Their consensus is refined toward visible
+image edges within a bounded physical distance. This supplies detailed edge
+evidence that is not limited by a neural encoder's input resolution.
+
+### 3. SAM and Light HQ-SAM masks
+
+The selected component supplies a box prompt and a robust positive point away
+from shadows and boundaries. Optional negative points identify regions that
+must not belong to the component.
+
+SAM and Light HQ-SAM run as independent backends. They return masks, not
+FreeCAD objects and not final dimensions. On a CUDA machine, neural inference
+can run on the GPU while deterministic full-resolution metrology occupies a
+CPU worker. CPU-only systems remain sequential to avoid oversubscription.
+
+### 4. Transparent mask fusion
+
+The three masks are reduced to the connected component selected by the user.
+Scan2Sketch then evaluates:
+
+- each original backend mask;
+- a pixel majority mask;
+- their union; and
+- their intersection.
+
+Candidates are scored using image-edge alignment, agreement between sources,
+expected area, contour complexity and hole count. These scores and the winning
+strategy are retained in analysis metadata. A specific safeguard prevents a
+single threshold mask from moving an otherwise agreed plain silhouette merely
+because a scanner shadow has a strong gradient.
+
+The fusion stage also restores credible enclosed or background-matching holes
+that prompt segmenters may fill, while tiny engraving-like gaps can be filled.
+These thresholds are expressed in physical units.
+
+### 5. Material-edge refinement
+
+The fused mask establishes topology and a search region. For supported shapes,
+the metrology stage samples the original scan again instead of accepting the
+mask boundary as a measurement.
+
+For rectangle-like parts, profiles are sampled normal to all four sides at
+several physical smoothing scales. Multiple edge bands are retained and the
+four sides are selected jointly, favouring consistent opposite edges over four
+unrelated local maxima.
+
+For circular boundaries and holes, radial profiles generate alternative radii.
+Candidates are evaluated across angle, scale, contrast, profile width and
+centre stability. Distinct plausible radii can remain available for visual
+selection instead of being silently collapsed.
+
+Material-edge replacement is applied only when the shape-specific fit passes
+its acceptance and confidence gates. Otherwise the reviewed contour remains
+the fallback.
+
+### 6. Geometry candidates and regularization
+
+Scan2Sketch proposes exact primitives only when their residuals and topology
+are plausible:
+
+- regular polygons with three, four, six or eight sides;
+- full circles for round outer boundaries and holes;
+- lines and circular arcs for supported intervals; and
+- B-splines for remaining smooth, non-primitive intervals.
+
+Candidate ranking considers image support and estimated uncertainty. The UI
+keeps mutually exclusive candidates separate so that a user can inspect the
+one currently under consideration. Manual masks, freehand edge guidance,
+segment recalculation, direct measurements and undo/redo modify the neutral
+geometry before export.
+
+Regularization is bounded in millimetres and is shown in the correction
+preview. If it breaks topology, Scan2Sketch rejects that regularization and
+keeps the earlier geometry. There is intentionally no hidden simplification
+after the user accepts the green contour.
+
+### 7. Uncertainty
+
+The displayed estimate combines separately tracked terms:
+
+```text
+combined uncertainty² =
+    pixel localization²
+  + edge localization²
+  + scanner calibration²
+  + model selection²
+  + repeatability²
+  + optional distortion residual²
+  + optional reference-measurement uncertainty²
+```
+
+The 95% value is currently reported as twice the combined standard
+uncertainty. It is an engineering estimate based on the available evidence,
+not a certification of the scanner or part.
+
+### 8. Topology and FreeCAD export
+
+Before export, the neutral geometry is checked for missing or open outer
+loops, zero and duplicate edges, branches, self-intersections, invalid hole
+containment, intersecting holes and invalid circle radii.
+
+The FreeCAD writer uses real Sketcher lines, circles, arcs and B-splines where
+the reviewed geometry contains those primitives. Document changes run inside
+a transaction and are rolled back on failure.
+
+After writing, Scan2Sketch verifies that:
+
+- the number of FreeCAD wires matches the expected contour count;
+- every wire is closed; and
+- each exported curve still passes through the coordinates accepted in the
+  preview within a strict numerical tolerance.
+
+This last gate prevents FreeCAD constraints or a second export-time fit from
+silently changing the confirmed contour.
+
+## Fallback behaviour
+
+- If model weights are absent, the OpenCV workflow remains available.
+- If a geometric replacement is uncertain, the measured polygon is retained.
+- If regularization invalidates topology, the unregularized geometry is kept.
+- If an optional pad fails, the valid sketch is preserved.
+- If geometry cannot be validated, Scan2Sketch refuses to create a misleading
+  final profile and reports actionable locations where possible.
+
+## What the system does not claim
+
+- Segmentation masks are not treated as ground-truth dimensions.
+- Subpixel localization cannot decide which of several visually real edges is
+  the functional edge of a chamfered or reflective part.
+- A single scan cannot reveal hidden geometry, height, thread dimensions or a
+  complete 3D object.
+- The uncertainty display is not a substitute for a traceable measurement or
+  a caliper check of critical dimensions.
+
+See [Known limitations](KNOWN_LIMITATIONS.md) for operational constraints.
+
+## Privacy and reproducibility
+
+Analysis runs locally. Scan2Sketch does not upload the scan. The external
+analysis process exchanges neutral JSON data with the FreeCAD add-on so that
+heavy image dependencies remain isolated from FreeCAD's Python environment.
+The result metadata records backend, fusion, candidate and uncertainty details
+for diagnostics and reproducible bug reports.
+
+## Implementation map
+
+| Responsibility | Main implementation |
+| --- | --- |
+| Backend contract | `scan2sketch/core/backends.py` |
+| OpenCV analysis | `scan2sketch/core/opencv_backend.py` |
+| SAM backend | `scan2sketch/core/sam_backend.py` |
+| Light HQ-SAM backend | `scan2sketch/core/light_hq_sam_backend.py` |
+| Hybrid orchestration | `scan2sketch/core/triple_hybrid_backend.py` |
+| Mask comparison | `scan2sketch/core/mask_fusion.py` |
+| Full-resolution edge stability | `scan2sketch/core/opencv_stability.py`, `boundary_refinement.py` |
+| Material-edge hypotheses | `scan2sketch/core/material_edge_optimizer.py` |
+| Candidate ranking | `scan2sketch/core/candidate_ranking.py` |
+| Primitive fitting and vectorization | `primitive_fitting.py`, `cad_primitives.py`, `contour_vectorization.py` |
+| Measurement uncertainty | `scan2sketch/core/measurement_uncertainty.py` |
+| Neutral topology validation | `scan2sketch/core/validation.py` |
+| FreeCAD sketch writer | `scan2sketch/freecad/sketch_writer.py` |
+| Isolated process boundary | `scripts/analyze_hybrid_external.py` |
+
+Contributions that change a decision rule should include a reproducible test
+case and describe how the change affects dimensional error, topology, runtime
+and manual correction effort.