Skip to content

Polish the public beta community launch #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jayktopus merged 1 commit into from
Aug 4, 2026
Merged

Polish the public beta community launch #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions KNOWN_LIMITATIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Known limitations

Scan2Sketch is a public beta. This document describes the current boundaries so
that results can be evaluated responsibly.

## Geometry and measurement

- A single flatbed scan contains a 2D silhouette, not complete 3D geometry.
- Hidden features, part height, thread dimensions and functional tolerances
cannot be inferred reliably from one image.
- Scanner DPI metadata is only a nominal scale. Accurate work requires a saved
Scan2Sketch calibration for every resolution in use.
- Shadows, chamfers, translucent materials, reflections and parts that do not
sit flat can make the physical material edge ambiguous.
- Subpixel fitting can improve a visible edge location but cannot prove which
of several visible edge bands is the intended functional boundary.
- Critical dimensions must be checked with suitable measuring equipment.

## Performance

- 1200 dpi scans require substantially more memory and processing time than
300 or 600 dpi scans.
- The optional SAM and Light HQ-SAM modes require additional model weights and
isolated dependencies. OpenCV remains the deterministic fallback.
- Very large full-bed scans should be cropped to the relevant region when
practical.

## Platform support

- Windows with FreeCAD 1.1.1 is the primary tested configuration.
- macOS support is beta. The OpenCV workflow has been tested on Apple silicon;
full-vision model backends are experimental.
- Linux is not yet an officially supported installation target.
- Scan2Sketch is not yet distributed through the FreeCAD Addon Manager.

## Input recommendations

For the most repeatable results, use lossless PNG, a flat opaque part, fixed
scanner settings, disabled automatic sharpening and a valid calibration for
the selected DPI. Avoid JPEG for measurement work.

When reporting a problem, attach the exported diagnostic report and, if its
licence and privacy allow it, the smallest scan that reproduces the issue.
137 changes: 87 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,73 +1,110 @@
<div align="center">

# Scan2Sketch

Scan2Sketch is an open-source FreeCAD add-on that converts calibrated flatbed
scans of flat parts into editable, validated Sketcher geometry. It can also
create a uniform Part Design pad with a user-specified height.
**Turn calibrated flatbed scans into clean, editable FreeCAD sketches.**

[![FreeCAD 1.1](https://img.shields.io/badge/FreeCAD-1.1-0175C2?style=flat-square)](https://www.freecad.org/)
[![Tests](https://img.shields.io/github/actions/workflow/status/Jayktopus/Scan2Sketch-OpenSource/core-tests.yml?branch=main&style=flat-square&label=tests)](https://github.com/Jayktopus/Scan2Sketch-OpenSource/actions/workflows/core-tests.yml)
[![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)

![Scan2Sketch demonstration: scan selection, contour review, sketch creation and pad](media/demo/scan2sketch-demo.gif)

</div>

Scan2Sketch is an open-source FreeCAD add-on for reconstructing the measurable
2D silhouette of a flat physical part. It combines scanner calibration,
computer vision and CAD-aware contour fitting, then validates the result before
creating a real `Sketcher::SketchObject`.

> Scan2Sketch is beta software. Always verify safety-critical and
> manufacturing-critical dimensions against the physical part.

> **Beta software:** verify critical dimensions and the final FreeCAD shape
> before manufacturing a part.
## How it works

Deutsch: [README_DE.md](README_DE.md)
1. **Scan** the part flat on the scanner glass and save it as a lossless PNG.
2. **Calibrate** the scanner once for each resolution you use.
3. **Analyze** the scan and select the intended component and holes.
4. **Review** colour-coded contours, measurements and geometric candidates.
5. **Create** a validated FreeCAD sketch and, optionally, a uniform pad.

## Highlights
The correction workspace supports both a guided workflow for new users and
fine-grained tools for advanced contour editing.

- PNG, JPEG and TIFF input with DPI metadata and scanner calibration
- hybrid OpenCV, SAM and Light HQ-SAM object detection with an OpenCV fallback
- local, full-resolution material-edge refinement and uncertainty estimates
- selectable components, holes and colour-coded smart segments
- guided correction workflow plus an expert toolbox
- line, circle, arc and B-spline fitting with continuity-aware smoothing
- freehand material-edge guidance, masks, undo/redo and direct measurement
- topology validation before creating a real `Sketcher::SketchObject`
- optional XY clearance and `PartDesign::Pad`
- German UI on German systems and English fallback
- local processing: scans are not uploaded by Scan2Sketch
## Capabilities

Scan2Sketch reconstructs a 2D silhouette. It does not infer hidden geometry or
part height from a single scan.
| Area | What Scan2Sketch provides |
| --- | --- |
| Input and scale | PNG, JPEG and TIFF input; DPI metadata; ruler and grid calibration; measurements in millimetres |
| Detection | Hybrid OpenCV, SAM and Light HQ-SAM workflow with a deterministic OpenCV fallback |
| Edge quality | Full-resolution material-edge refinement, multiple contour candidates and uncertainty estimates |
| Geometry | Lines, circles, arcs and continuity-aware B-splines; holes and colour-coded smart segments |
| Correction | Guided review, freehand edge guidance, masks, direct measurement, undo and redo |
| FreeCAD output | Topology validation, real Sketcher geometry, optional XY clearance and `PartDesign::Pad` |
| Privacy | Local processing; Scan2Sketch does not upload scans |

Scan2Sketch reconstructs a **2D silhouette**. It does not infer hidden geometry,
functional dimensions or part height from a single image. See
[Known limitations](KNOWN_LIMITATIONS.md) for the current boundaries.

## Installation

The primary supported environment is **Windows with FreeCAD 1.1.1**; macOS
support is in beta. The OpenCV workflow has been tested on Apple silicon, while
the optional SAM / Light HQ-SAM full-vision mode remains experimental on
macOS. Install from source using [INSTALL.md](INSTALL.md)
(Windows) or [INSTALL_MACOS.md](INSTALL_MACOS.md). The installation stays inside the
current user's FreeCAD data directory and uses isolated Python environments;
it does not modify FreeCAD program files or install global Python packages.
### Windows

Windows with FreeCAD 1.1.1 is the primary tested environment. Follow the
[Windows installation guide](INSTALL.md). Installation is confined to the
current user's FreeCAD data directory and isolated Python environments; no
FreeCAD program files or global Python packages are modified.

### macOS

macOS support is in beta. The OpenCV workflow has been tested on Apple silicon;
the optional SAM and Light HQ-SAM full-vision mode remains experimental. Follow
the [macOS installation guide](INSTALL_MACOS.md).

Uninstallation instructions: [Windows](UNINSTALL.md).

## Recommended scan settings

For reproducible input, use NAPS2 with the scanner's WIA or TWAIN driver:

Uninstallation: [UNINSTALL.md](UNINSTALL.md).
- save as lossless PNG;
- disable automatic sharpening and enhancement where possible;
- use 600 dpi for general work or 1200 dpi for small critical features;
- calibrate every DPI mode used by Scan2Sketch;
- keep the part flat against the glass; and
- verify important dimensions with a caliper.

## Recommended scanning workflow
## Project status

For reproducible results, NAPS2 is recommended: select the scanner's WIA or
TWAIN driver, save as lossless PNG, disable automatic sharpening where
possible, and use 600 dpi for normal work or 1200 dpi for small critical
features. Complete Scan2Sketch's calibration sequence for every DPI mode used.
Keep the part flat against the glass and verify important dimensions with a
caliper.
Scan2Sketch is an active public beta. The current priorities are reliable
installation, broader scanner testing, measurable contour quality and a clear
path toward the FreeCAD Addon Manager.

## Development and tests
- [Roadmap: Now, Next and Ideas](ROADMAP.md)
- [Known limitations](KNOWN_LIMITATIONS.md)
- [Open issues](https://github.com/Jayktopus/Scan2Sketch-OpenSource/issues)
- [Community discussions](https://github.com/Jayktopus/Scan2Sketch-OpenSource/discussions)

```powershell
& '.\.venv-opencv\Scripts\python.exe' -m unittest discover -s tests -p 'test_*.py'
```
## Contributing

On macOS and Linux:
Bug reports, licensed example scans, documentation improvements and code
contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the
issues labelled
[`good first issue`](https://github.com/Jayktopus/Scan2Sketch-OpenSource/labels/good%20first%20issue)
or [`help wanted`](https://github.com/Jayktopus/Scan2Sketch-OpenSource/labels/help%20wanted).

```bash
./.venv-opencv/bin/python -m unittest discover -s tests -p 'test_*.py'
```
> I’m looking for contributors interested in contour fitting, FreeCAD
> integration, documentation and testing across different scanners.

Development setup is documented in
[docs/development_setup.md](docs/development_setup.md). Contributions and
reproducible issue reports are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
[docs/development_setup.md](docs/development_setup.md).

## License

Scan2Sketch is free software licensed under
[GNU GPL v3 or later](LICENSE). The GPL permits use, modification,
redistribution and commercial use, while requiring distributed derivative
works to preserve the corresponding source and GPL freedoms. Third-party
libraries and optional model weights retain their own licenses; see
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
[GNU GPL v3 or later](LICENSE). Third-party libraries and optional model weights
retain their own licences; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
136 changes: 94 additions & 42 deletions README_DE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,110 @@
<div align="center">

# Scan2Sketch

Scan2Sketch ist ein quelloffenes FreeCAD-Add-on, das kalibrierte
Flachbettscans flacher Bauteile in bearbeitbare und geprüfte
Sketcher-Geometrie umwandelt. Optional entsteht daraus ein Part-Design-Pad mit
einer ausdrücklich eingegebenen Höhe.
**Aus kalibrierten Flachbettscans werden saubere, bearbeitbare FreeCAD-Skizzen.**

[![FreeCAD 1.1](https://img.shields.io/badge/FreeCAD-1.1-0175C2?style=flat-square)](https://www.freecad.org/)
[![Tests](https://img.shields.io/github/actions/workflow/status/Jayktopus/Scan2Sketch-OpenSource/core-tests.yml?branch=main&style=flat-square&label=Tests)](https://github.com/Jayktopus/Scan2Sketch-OpenSource/actions/workflows/core-tests.yml)
[![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)

![Scan2Sketch-Demonstration: Scan auswählen, Kontur prüfen, Skizze und Pad erzeugen](media/demo/scan2sketch-demo.gif)

</div>

Scan2Sketch ist ein quelloffenes FreeCAD-Add-on zur Rekonstruktion der
messbaren 2D-Silhouette eines flachen realen Bauteils. Es verbindet
Scannerkalibrierung, Bildverarbeitung und CAD-gerechte Konturanpassung. Vor der
Erzeugung eines echten `Sketcher::SketchObject` wird das Ergebnis geprüft.

> Scan2Sketch ist Beta-Software. Sicherheits- und fertigungsrelevante Maße
> müssen immer am realen Bauteil kontrolliert werden.

## So funktioniert es

1. **Scannen:** Bauteil flach auf das Scannerglas legen und verlustfrei als PNG speichern.
2. **Kalibrieren:** Den Scanner einmal für jede verwendete Auflösung vermessen.
3. **Analysieren:** Gewünschtes Bauteil und Innenkonturen auswählen.
4. **Prüfen:** Farbcodierte Konturen, Messwerte und Geometrievorschläge kontrollieren.
5. **Erzeugen:** Eine geprüfte FreeCAD-Skizze und optional ein gleichmäßiges Pad erstellen.

> **Beta-Software:** Kritische Maße und das endgültige FreeCAD-Modell müssen
> vor der Fertigung kontrolliert werden.
Das Korrekturfenster bietet einen geführten Ablauf für neue Nutzer und präzise
Einzelwerkzeuge für fortgeschrittene Konturbearbeitung.

## Wichtigste Funktionen
## Funktionsumfang

- PNG-, JPEG- und TIFF-Import mit DPI-Metadaten und Scannerkalibrierung
- hybride OpenCV-/SAM-/Light-HQ-SAM-Erkennung mit OpenCV-Rückfallmodus
- lokale Materialkantenverfeinerung in Originalauflösung
- auswählbare Bauteile, Löcher und farbcodierte Smart-Segmente
- geführte Korrektur sowie ein erweiterter Werkzeugbereich
- Geraden, Kreise, Bögen und stetigkeitsbewusste B-Splines
- Nachzeichnen der Materialkante, Maskenwerkzeuge, Undo/Redo und Maßband
- Topologieprüfung vor der echten `Sketcher::SketchObject`-Erzeugung
- optionales XY-Spiel und `PartDesign::Pad`
- deutsche und englische Oberfläche
- ausschließlich lokale Verarbeitung durch Scan2Sketch
| Bereich | Funktionen |
| --- | --- |
| Eingabe und Maßstab | PNG, JPEG und TIFF; DPI-Metadaten; Zollstock- und Rasterkalibrierung; Messungen in Millimetern |
| Erkennung | Hybrider OpenCV-, SAM- und Light-HQ-SAM-Ablauf mit deterministischem OpenCV-Rückfallmodus |
| Kantenqualität | Materialkantenverfeinerung in Originalauflösung, mehrere Konturkandidaten und Unsicherheitsangaben |
| Geometrie | Geraden, Kreise, Bögen und stetigkeitsbewusste B-Splines; Löcher und farbcodierte Smart-Segmente |
| Korrektur | Geführte Prüfung, Nachzeichnen der Materialkante, Masken, Maßband sowie Rückgängig/Wiederholen |
| FreeCAD-Ausgabe | Topologieprüfung, echte Sketcher-Geometrie, optionales XY-Spiel und `PartDesign::Pad` |
| Datenschutz | Lokale Verarbeitung; Scan2Sketch lädt keine Scans hoch |

Scan2Sketch rekonstruiert eine 2D-Silhouette. Verdeckte Geometrie oder die Höhe
eines Bauteils werden nicht aus einem einzelnen Scan erfunden.
Scan2Sketch rekonstruiert eine **2D-Silhouette**. Verdeckte Geometrie,
Funktionsmaße oder die Höhe eines Bauteils werden nicht aus einem einzelnen
Bild abgeleitet. Die aktuellen Grenzen stehen unter
[Bekannte Einschränkungen](KNOWN_LIMITATIONS.md).

## Installation

Primär unterstützt wird **Windows mit FreeCAD 1.1.1**. macOS-Unterstützung ist
als Beta verfügbar: Der OpenCV-Ablauf wurde auf Apple Silicon getestet, der
optionale SAM-/Light-HQ-SAM-Vollmodus gilt dort noch als experimentell. Die
Anleitungen stehen in [INSTALL_DE.md](INSTALL_DE.md) für Windows und
[INSTALL_MACOS.md](INSTALL_MACOS.md) für macOS. Die Installation bleibt im
FreeCAD-Benutzerordner und verändert weder FreeCAD-Systemdateien noch die
globale Python-Installation.
### Windows

Primär getestet wird Windows mit FreeCAD 1.1.1. Die
[deutsche Windows-Anleitung](INSTALL_DE.md) führt durch die Installation. Das
Add-on bleibt im FreeCAD-Benutzerordner und verändert weder
FreeCAD-Programmdateien noch die globale Python-Installation.

### macOS

macOS-Unterstützung ist im Beta-Stadium. Der OpenCV-Ablauf wurde auf Apple
Silicon getestet; der optionale SAM-/Light-HQ-SAM-Vollmodus ist dort noch
experimentell. Anleitung: [INSTALL_MACOS.md](INSTALL_MACOS.md).

Deinstallation: [UNINSTALL_DE.md](UNINSTALL_DE.md).

## Empfohlener Scanablauf
## Empfohlene Scan-Einstellungen

Für reproduzierbare Eingaben wird NAPS2 mit dem WIA- oder TWAIN-Treiber des
Scanners empfohlen:

- verlustfrei als PNG speichern;
- automatische Schärfung und Bildverbesserung möglichst abschalten;
- 600 dpi für normale Bauteile oder 1200 dpi für kleine kritische Merkmale;
- jede verwendete DPI-Stufe in Scan2Sketch kalibrieren;
- das Bauteil flach auf das Glas legen; und
- wichtige Maße mit einer Schieblehre kontrollieren.

## Projektstatus

Scan2Sketch ist eine aktive öffentliche Beta. Im Mittelpunkt stehen eine
zuverlässige Installation, Tests mit weiteren Scannern, messbare Konturqualität
und die Vorbereitung für den FreeCAD Addon Manager.

- [Roadmap: Jetzt, Als Nächstes und Ideen](ROADMAP.md)
- [Bekannte Einschränkungen](KNOWN_LIMITATIONS.md)
- [Offene Issues](https://github.com/Jayktopus/Scan2Sketch-OpenSource/issues)
- [Community-Diskussionen](https://github.com/Jayktopus/Scan2Sketch-OpenSource/discussions)

## Mitwirken

Empfohlen wird NAPS2 mit WIA- oder TWAIN-Treiber und verlustfreiem PNG. Soweit
möglich automatische Schärfung abschalten. 600 dpi eignen sich für normale
Bauteile, 1200 dpi für kleine kritische Merkmale. Jede verwendete DPI-Stufe
muss in Scan2Sketch kalibriert werden. Das Bauteil flach auflegen und wichtige
Maße zusätzlich mit einer Schieblehre prüfen.
Fehlerberichte, lizenzierte Beispielscans, Dokumentationsverbesserungen und
Codebeiträge sind willkommen. Der Einstieg steht in
[CONTRIBUTING.md](CONTRIBUTING.md). Besonders geeignete Aufgaben sind mit
[`good first issue`](https://github.com/Jayktopus/Scan2Sketch-OpenSource/labels/good%20first%20issue)
oder [`help wanted`](https://github.com/Jayktopus/Scan2Sketch-OpenSource/labels/help%20wanted)
markiert.

## Mitwirken und Lizenz
Gesucht werden Mitwirkende für Konturanpassung, FreeCAD-Integration,
Dokumentation und Tests mit unterschiedlichen Scannern.

Tests und Entwicklungsaufbau stehen in
[docs/development_setup.md](docs/development_setup.md). Hinweise zum Mitwirken:
[CONTRIBUTING.md](CONTRIBUTING.md).
## Lizenz

Scan2Sketch steht unter der [GNU GPL v3 oder neuer](LICENSE). Die GPL erlaubt
Nutzung, Veränderung, Weitergabe und auch kommerzielle Nutzung; bei der
Weitergabe abgeleiteter Versionen müssen der zugehörige Quellcode und die
GPL-Freiheiten erhalten bleiben. Hinweise zu Fremdkomponenten stehen in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
Scan2Sketch ist freie Software unter der [GNU GPL v3 oder neuer](LICENSE).
Fremdbibliotheken und optionale Modellgewichte behalten ihre eigenen Lizenzen;
Einzelheiten stehen in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
39 changes: 39 additions & 0 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Scan2Sketch roadmap

This roadmap communicates direction, not a promise of dates. Priorities may
change as real scanner data and contributor feedback reveal better paths.

## Now

- Stabilise the public beta on FreeCAD 1.1.1 for Windows.
- Validate installation and diagnostics on clean user systems.
- Expand the scanner and real-part compatibility matrix.
- Measure contour accuracy on reproducible synthetic and real benchmarks.
- Improve documentation, examples and first-time contributor tasks.
- Complete the packaging review for a future FreeCAD Addon Manager submission.
- Validate the OpenCV workflow on macOS and clearly document the limits of the
optional full-vision backends.

## Next

- Investigate a supported Linux installation path.
- Improve line, circle, arc and B-spline fitting on mixed technical contours.
- Add more licensed example scans with expected measurements and topology.
- Reduce manual correction effort for difficult shadows, chamfers and
reflective surfaces.
- Expand translations and platform-specific troubleshooting.
- Automate more FreeCAD integration tests across supported platforms.

## Ideas

- Optional paired scans with the part rotated by 180 degrees to distinguish
illumination artefacts from stable material edges.
- A specialised boundary model trained on opt-in, reviewed flatbed-scan data.
- Opt-in export of user-corrected masks for benchmark and training datasets.
- Additional vectorisation backends evaluated against the same CAD metrics.
- Carefully constrained multi-view reconstruction for simple parts, kept
separate from the primary 2D workflow.

Please open or join a
[discussion](https://github.com/Jayktopus/Scan2Sketch-OpenSource/discussions)
before starting a large roadmap item.
Loading
Loading