ImageToSketch

ImageToSketch is an open-source tracing library, currently at version 0.2.0-wip as of October 3, 2026. It operates by normalising an input image, determining the colour channel that highlights the part, and deriving closed outlines based on thresholds between the part's tone and the background's tone. The library then verifies each outline against the real edge, subtracting smooth ramps and probing edges for sharp steps to establish their positions.

The confidence level is determined by the proportion of the outline that aligns with sharp steps, categorised as high, middling, or low.

The software aims to use the minimal number of lines, arcs, circles, and splines necessary to accurately represent the part, incorporating bridges for small bumps and ensuring closed outlines. It builds the sketch within the FreeCAD environment, overlaying the original image at true scale to facilitate further manual adjustments if needed. The scale is derived from various sources such as a printable marker sheet, a known picture width, a known mm-per-pixel value, or a square of known size in the picture.

To install ImageToSketch in FreeCAD, users can run python3 install.py, which automatically adds the add-on to FreeCAD's user Mod folder and installs OpenCV into the add-on's _deps folder. The first-time user interface offers the option to install OpenCV upon opening the ImageToSketch dialog. For those who prefer to install manually, the directory can be copied into Mod as ImageToSketch. The installation process includes commands for Linux, and an uninstallation command is also provided.

Upon launching the ImageToSketch workbench in FreeCAD, users can browse to the desired image, with a preview appearing for further inspection. Options for determining the scale from a marker sheet are provided, including saving a printable marker sheet, printing it at 100%, laying the part in the middle, and photographing it straight above with all four markers visible. Measurements of the 100 mm line are used to adjust the scale if necessary, followed by creating and padding the sketch.

Several settings influence the process, including forcing the part to be interpreted as dark or light, adjusting for hard-edged shadows or bevels, ignoring inner edges for bevelled parts, and setting the smallest real feature threshold for holes and bumps. Users can also adjust the fit tolerance, with automatic settings at 0.5 px, increasing for blurrier images.

Performance benchmarks have been conducted on simulated images with known geometry, using various damage types and random seeds. The library demonstrated high accuracy, with false detections below 0.005 mm, radius errors under 0.01 mm, and straight-edge length errors around 0.03 mm. The full benchmark details are available in docs/BENCHMARK.md.

The library has undergone extensive testing, including automated tests and comparisons against stand-in FreeCAD modules and OpenCascade, the geometry kernel used by FreeCAD. It has been tested with OpenCV versions 4.6, 4.13, and 5.0, as well as NumPy 1.26 and 2.x. The software is tested on Linux systems only and has not been tested with real photographs or in real FreeCAD environments.

In terms of limitations, ImageToSketch has not been validated with real photographs of real parts and has not been tested in actual FreeCAD installations. It does not require a GPU and remains memory-efficient, though performance can vary based on the hardware used. The library is compatible with SVG and DXF formats, which can be imported into various CAD software applications, ensuring seamless integration into the design workflow.