FreeCAD workbench with 3 custom tools for working with scan data/mesh files. Allows users to extract datums from mesh files to precisely align 3D scans to the global origin.
*not settled on the name
A robust, dependency-free reverse engineering and metrology toolkit for FreeCAD.
The Scan Alignment Workbench provides professional-grade tools to extract mathematical features (datums) from raw 3D scan data and bake absolute coordinate alignments into mesh vertices. It utilizes FreeCAD's native C++ intersections, NumPy, and Coin3D to deliver instant visual feedback without the bloat of external libraries.
### 1. 3D Zone Selection Tool
A brush-based selection tool that lets you physically "paint" directly onto your mesh to isolate specific mechanical features.
* **Paint:** Hold `SHIFT + Left-Click` and drag to paint facets.
* **Erase:** Hold `SHIFT + CTRL + Left-Click` and drag to erase.
* **Auto-Expand:** Magically grow your selection across flat or curved surfaces using the adjustable Planar/Curved angle tolerances.
* **Extract:** Spawns a dedicated sub-mesh based on your painted zone, inheriting the exact spatial placement of the parent.
### 2. Feature Extraction Panel
Extract infinite, mathematically perfect datums from your imperfect mesh selections using advanced Principal Component Analysis (PCA) and Singular Value Decomposition (SVD).
* **Basic Extraction:** Fit planes and unconstrained cylinders to selected meshes.
* **Constrained Extraction:** Extract Perpendicular Planes, Mutually Perpendicular Planes, Mid-Planes, and Constrained Cylinders locked perfectly to a specific reference plane.
### 3. Mesh Alignment Panel (3-2-1 Metrology)
Align scanned data to the absolute origin using a standard Primary-Secondary-Tertiary (3-2-1) hierarchy.
* Uses Gram-Schmidt orthogonalization to correct manufacturing/scanning imperfections between axes.
* **Destructive Geometry Baking:** Unlike standard FreeCAD placement wrappers, this tool physically mutates and overwrites the raw mesh vertices, ensuring the alignment is permanent and mathematically stable for downstream CAD operations.
Currently, this workbench is in Public Beta and must be installed manually.
- Download the latest
ScanAlignment.zipfile from the Releases page. - Extract the ZIP file.
- Move the extracted
ScanAlignmentfolder into your FreeCADModdirectory:- Windows:
C:\Users\YOUR_USERNAME\AppData\Roaming\FreeCAD\Mod\orC:\Program Files\FreeCAD 1.1\Mod\ - Linux:
~/.local/share/FreeCAD/Mod/ - macOS:
~/Library/Application Support/FreeCAD/Mod/
- Windows:
- Restart FreeCAD.
- Select Scan Alignment from the Workbench dropdown menu!
- Paint Zones: Select your raw mesh, open the 3D Zone Tool, and paint the faces you want to use for your Origin, Z-Axis, and X-Axis. Extract them.
- Extract Datums: Open the Extraction Panel. Select your extracted zones one by one and fit Datum Planes or Cylinders to them. Extract a Datum Point for your origin.
- Align: Open the Alignment Panel. Assign your Origin point, Primary axis (Z), and Secondary axis (X or Y).
- Execute Alignment: Click the execute button to snap the mesh to FreeCAD's global origin.
Workflow Note: When you execute the alignment, only the primary mesh moves. Your extracted zones and datums will stay behind in their original locations. This is intentional. Once the mesh is baked to the origin, you should model directly off FreeCAD's native global planes (XY, XZ, YZ) or new constrained planes, instead of the unconstrained extracted scan data.
- Disappearing Zones on File Load: If you save, close, and reopen a FreeCAD document, extracted Zones may appear to vanish from the 3D view. The geometry is not lost; it is just hidden inside the parent mesh. Changing the primary mesh's display settings to transparent will reveal them.
This project is licensed under the LGPL-2.1-or-later license, matching the FreeCAD ecosystem. See the LICENSE file for details.