MeshToBody CLI - Mesh to Solid Converter

Command-line tool to convert mesh files (STL, OBJ, etc.) to refined solid bodies using FreeCAD in headless mode.

Features

• Converts meshes to FreeCAD PartDesign Bodies with refined solids
• Handles multi-component meshes with automatic fusion
• Conservative mesh repair for better conversion quality
• Batch processing - each file gets its own output
• Automatic output filename generation
• Multiple export formats (STEP, FCStd, STL, IGES)
• No GUI required - runs completely headless

Installation

Prerequisites

• FreeCAD 0.20 or later must be installed
• Python 3.x (included with FreeCAD)

Quick Start

1. Clone or download this repository
2. The wrapper scripts will automatically find your FreeCAD installation:
   • meshtobody.bat for Windows
   • meshtobody.sh for Linux/Mac

Windows: The script searches for FreeCAD in C:\Program Files\FreeCAD* automatically.

Linux/Mac: If auto-detection fails, set the path manually:

export FREECAD_PYTHON_ENV=/path/to/freecad/python

Usage

Simple Usage (Auto-generates output)

Convert single file to STEP:

meshtobody.bat input.stl

Creates input.step

Convert all STL files in directory:

meshtobody.bat *.stl

Creates file1.step, file2.step, etc.

Different output format:

meshtobody.bat input.stl -f iges

Creates input.iges

Advanced Usage

Specify output file (single file only):

meshtobody.bat input.stl -o custom_name.step

Convert to FreeCAD format:

meshtobody.bat input.stl -f fcstd

Creates input.FCStd

Export back to STL (as solid):

meshtobody.bat input.stl -f stl

Creates input_solid.stl (avoids overwriting input)

Process large meshes (>50 components):

meshtobody.bat large.stl --no-skip-large

Command-Line Options

positional arguments:
  input_files           Input mesh file(s) (STL, OBJ, etc.)

options:
  -h, --help            Show help message
  -o OUTPUT, --output OUTPUT
                        Output file path (optional, auto-generated by default)
  -f FORMAT, --format FORMAT
                        Output format: step, fcstd, stl, iges, igs
                        (default: step)
  --no-skip-large       Process meshes with >50 components (may be very slow)
  --version             Show version number

How It Works

The conversion process follows these steps:

1. Evaluation - Analyzes mesh properties (solid, manifold, components)
2. Strategy Selection - Chooses optimal conversion path:
   • Clean meshes -> direct conversion
   • Multi-component -> split and fuse
   • Self-intersecting -> component splitting
   • Invalid solid -> repair attempt
3. Mesh to Shape - Converts triangulated mesh to FreeCAD shape
4. Shape to Solid - Creates solid from shell of faces
5. Refinement - Optimizes solid geometry (with fallback if it fails)
6. Body Creation - Wraps solid as BaseFeature in PartDesign Body
7. Export - Saves to specified format

Batch Processing

When multiple files are provided:

• Each file is processed independently
• Each gets its own output file with matching name
• Files are processed in order: simple to complex (by component count, then facet count)

Guardrails

• Meshes with >50 components are skipped by default (use --no-skip-large to override)
• Meshes with >10,000 facets show warning about long processing time
• Per-file timing is displayed for performance monitoring

Supported File Formats

Input Formats

• STL (binary and ASCII)
• OBJ
• OFF
• PLY
• Any format supported by FreeCAD's Mesh module

Output Formats

• STEP (.step, .stp) - Industry standard CAD format (default)
• FCStd - FreeCAD native format
• IGES (.iges, .igs) - Legacy CAD format
• STL - Export converted solid back to mesh

Troubleshooting

"FreeCAD Python modules not found"

Make sure you're running the script with FreeCAD's Python interpreter, not system Python.

Windows:

"C:\Program Files\FreeCAD 1.0\bin\python.exe" meshtobody_cli.py input.stl

Linux:

freecad-python3 meshtobody_cli.py input.stl

Or use the wrapper scripts which handle this automatically.

Conversion Fails

Try these approaches:

1. Repair mesh first - Use Blender or MeshLab to fix mesh issues
2. Simplify mesh - Reduce facet count if >10,000 facets
3. Split manually - Separate components in mesh editing tool before import
4. Check mesh quality - Ensure mesh is manifold, watertight, and has consistent normals

Very Slow Processing

• Large facet counts (>10k) significantly increase processing time
• Many components (>50) are skipped by default - convert separately if needed
• Self-intersecting meshes require splitting and may be slow

Real-World Examples

# Convert single part to STEP
meshtobody.bat "HMG7.3 Creality OEM-CR10S-Ender3-5 2-Screw Mount V2.stl"
# Creates: HMG7_3_Creality_OEM_CR10S_Ender3_5_2_Screw_Mount_V2.step

# Batch convert all STL files in directory to STEP
meshtobody.bat *.stl
# Creates: part1.step, part2.step, part3.step...

# Convert to FreeCAD format for further editing
meshtobody.bat wing.stl -f fcstd
# Creates: wing.FCStd

# Convert to IGES for legacy CAD software
meshtobody.bat bracket.stl -f iges
# Creates: bracket.iges

Additional Tools

Add Sleeves to Holes (add_sleeves.py)

Visual hole detection and sleeve installation for reducing hole diameters in STEP files:

# Interactive mode with visual hole markers
python add_sleeves.py model.step

# Non-interactive mode (auto-select all holes)
python add_sleeves.py model.step --no-visual --auto-all

# Custom hole detection parameters
python add_sleeves.py model.step --min-diameter 3.0 --max-diameter 5.0

# Custom sleeve parameters
python add_sleeves.py model.step --sleeve-target-diameter 3.6 --sleeve-thickness 0.25

Features:

• Detects both analytical and tessellated cylindrical holes
• Visual hole markers with ocp_vscode (optional)
• Interactive selection of holes for sleeve installation
• Automatic 1:1 matching between detected holes and installed sleeves
• Conservative defaults: target 3.6mm inner diameter

Requirements: build123d, numpy, ocp_vscode (optional for visual display)

Workflow:

1. Convert STL to STEP using meshtobody.bat
2. Add sleeves using add_sleeves.py
3. Result: STEP file with reduced hole diameters

Architecture

Based on the original FreeCAD MeshToBody macro by NSUBB (DesignWeaver3D), adapted for command-line use with:

• Headless FreeCAD operation
• Per-file processing for batch operations
• Automatic filename generation
• Improved error handling and progress reporting

License

GPL-3.0-or-later

Links

• Original Macro Repository: https://github.com/NSUBB/MeshToBody
• FreeCAD Forum Thread: https://forum.freecad.org/viewtopic.php?t=101189

Credits

CLI Version: 2.2.0 (2025-12-04) Original Macro Author: NSUBB (DesignWeaver3D)