A FreeCAD workbench for viewing, creating, and editing geometry described in GDML — the standard geometry format used by GEANT4, ROOT, and OpenMC Monte Carlo simulation frameworks.
This workbench bridges two communities that need to work together:
Physicists and simulation engineers who build detector or experiment geometries in GEANT4/ROOT using GDML can open those geometries in FreeCAD to visualise, inspect, and modify them — without needing deep CAD expertise.
Mechanical engineers and CAD designers who work in FreeCAD can design components and assemblies and export them directly to GDML, making the geometry immediately usable in GEANT4, ROOT, or OpenMC simulations — without needing to know the simulation frameworks.
The workbench also supports the reverse path described by L. Helary et al.: starting from a GEANT4 geometry, generating a STEP file for use in mechanical CAD workflows.
GDML (Geometry Description Markup Language) is an XML-based, application-independent format for describing 3D geometry. It is the primary geometry language for:
- GEANT4 — the widely used particle physics Monte Carlo simulation toolkit
- ROOT — CERN's data analysis and simulation framework
- OpenMC — an open-source Monte Carlo particle transport code popular in nuclear engineering
Viewing CERN's LHCb Velo detector geometry:
- Import GDML files from GEANT4, ROOT, or OpenMC — including large, complex detector geometries
- View and navigate volume hierarchies with display mode cycling (solid / wireframe / hidden)
- Create GDML geometry from scratch using native GDML solid types within FreeCAD
- Edit solid parameters, materials, placements, and rotations interactively
- Export to GDML for use in Monte Carlo simulations
- Tessellate complex CAD shapes for GDML using FreeCAD's built-in mesher or Gmsh
- Convert between GDML and STEP/STL/OBJ for exchange with mechanical CAD tools
- FEM preparation — create compound objects and material assignments for finite element analysis
The easiest way to install the workbench:
- Open FreeCAD
- Go to Tools → Addon Manager
- Search for GDML and click Install
| Library | Status | Notes |
|---|---|---|
lxml |
Bundled in FreeCAD 0.19+ | No action needed for modern FreeCAD |
gmsh |
Must be installed manually | See below |
Gmsh must be installed for the same Python interpreter that FreeCAD uses. If there is a version mismatch, the workbench will display an error message showing exactly which Python version FreeCAD is running and the correct install command to use.
To find which Python FreeCAD uses, open a terminal and run:
freecad -c
import sys
print(sys.version)
print(sys.executable)Then install gmsh targeting that Python:
# Using FreeCAD's Python directly (replace path as shown above):
/path/to/freecad-python -m pip install gmsh
# Or using pip with an explicit target directory:
pip install --upgrade --target /path/to/freecad/site-packages gmsh/Applications/FreeCAD\ 1.0.0.app/Contents/Resources/bin/python3.11 -m pip install gmshD:\FreeCAD\bin\python -m pip install --upgrade pip
D:\FreeCAD\bin\python -m pip install --target="D:\FreeCAD\bin\Lib\site-packages" gmshPaste the following into FreeCAD's Python console:
import gmsh
gmsh.initialize()
print(gmsh.option.getString("General.BuildInfo"))
gmsh.finalize()- Select the GDML workbench from the workbench dropdown
- File → Open and select your
.gdmlfile - A dialog will appear with two options:
- Import — load the full geometry (suitable for small to medium files)
- Scan Vol — load volume names only, expanding individual volumes on demand (recommended for large files like
alice.gdml)
- Use the tree view to navigate the volume hierarchy
- Click the cycle display icon (first icon on the GDML toolbar) to toggle a selected volume between solid, wireframe, and hidden
Large files: For complex detectors, use Scan Vol mode. Volumes not yet expanded are prefixed with
NOT_Expanded_. Select one and click an Expand icon to process it.
- Select the GDML workbench and choose File → New — this loads a default GDML document with materials and a World Volume
- Click a GDML solid icon on the toolbar to create a solid (Box, Tube, Sphere, etc.) — the solid is created inside a Part (GDML Volume) automatically
- Select the object in the tree and edit its properties (dimensions, material, placement)
- Drag volumes into the correct position in the tree hierarchy
- When ready, select the World Volume and use File → Export, choosing GDML as the file type
Full documentation is available on the GDML Workbench Wiki, including:
- Converting STEP files to GDML
- Tessellating Part Design objects
- Extruded sketches
- Revolved sketches
- Arrays of objects
- Mirrored objects
- Scaled objects
- Optical properties
- Import of OBJ files
- Gmsh Min Tessellate
When a FreeCAD shape cannot be represented exactly as a GDML primitive solid, it is tessellated — broken into triangular or quadrilateral facets — and exported as a GDML <tessellated> solid.
Creates a GDML tessellated solid from any FreeCAD shape using FreeCAD's built-in mesher.
Opens a Gmsh panel with controls for mesh type (Triangular, Quadrangular, Parallelogram) and characteristic lengths. Allows iterative re-meshing before committing. As with Gmsh Min Tessellate, the original source object is suppressed from GDML export and only the resulting GmshTessellated object is written.
Tessellates the selected object using Gmsh's STL-based recombination algorithm. A cube, for example, becomes 6 quad facets rather than 12 triangles, keeping GDML files compact.
When Gmsh Min Tessellate is run on an object, a new GmshTessellated object is created as a sibling in the document tree. On export, only the GmshTessellated object is written to GDML — the original source object is automatically suppressed (its exportFlag property is set to False). Re-running the command on the same source object updates the existing tessellation in place.
- FC Mesh → GDML Tessellated
— converts any FreeCAD mesh (STL, PLY, etc.) to a GDML tessellated solid - GDML Tessellated → FC Mesh
— converts back for use with FreeCAD's mesh tools
Creates a tetrahedral mesh of a shape using Gmsh and exports it as a GDML Assembly of GDML Tetra elements.
All standard GDML primitives are supported on import, including all solids used in the CERN Alice and LHCb detector geometries.
| FreeCAD object | GDML solid |
|---|---|
| Cube | Box |
| Cone | Cone |
| Cylinder | Tube |
| Sphere | Sphere |
Objects that do not map to a GDML primitive are automatically tessellated on export. Planar objects produce 3- or 4-vertex facets; curved objects are meshed to triangular facets.
- Select the World Volume in the tree (default name:
WorldVol) - File → Export
- Set file type to GDML
- Give the file a
.gdmlextension
Select the Materials Group in the tree view and use File → Export to save material definitions as an XML file (use .xml extension, not .gdml). This file can be imported into another FreeCAD document to transfer material definitions.
The Materials/ directory includes pre-built material XML files including the full NIST materials database.
Use the Compound icon 
to prepare a GDML geometry for FEM analysis:
- Select the World Volume and click the Compound icon — this creates a Compound object and an FEM Analysis object, with all GDML materials added automatically
- Switch to the FEM Workbench to proceed with meshing and analysis
GDML material objects carry thermal parameters that can be edited before creating the compound, enabling thermal FEM analysis on simulation geometries.
Command-line utilities for working with GDML files outside FreeCAD are maintained in a separate repository: GDML_Command_Line_Utils.
The Utils/ directory also contains gdml2step.py for converting a GDML file to STEP format:
python3 gdml2step.py <input.gdml> <output.step>The SampleFiles/ directory contains example GDML files. Notable examples:
lhcbvelo.gdml— the LHCb Velo detector. This is a large, complex file that takes over a minute to import. Use the volume toggle icon (first GDML icon) to selectively display volumes as solid or wireframe.
If this workbench contributed to published research, please cite it:
Selected publications using this workbench:
-
Helary et al. — GEANT4 → STEP → CAD workflow: http://doi.org/10.1140/epjs/s11734-021-00249-z
-
Le, Hashemi, Ottensmeyer, Sabet — Flexible and Generic Framework for Complex Nuclear Medicine Scanners using FreeCAD/GDML Workbench arXiv:2411.12751 | CAD Journal Vol. 23 No. 1
-
VPG4 — Versatile Parallelizable Geant4 Interface ResearchGate
-
Munther Hindi — presentation at the 15th GEANT4 Space Users Workshop, NASA Pasadena: Video | PDF
Core:
- Support for OpenMC geometry format (PR open)
- Change XML handling to use Python classes rather than global variables
- Add support for GDML
quantityelements - Add facility to edit Materials, Isotopes, and Elements interactively
- Add further GDML solid types
Workbench:
- Dialog for setting initial GDML object parameter values
- Analyse FreeCAD file to identify objects that convert directly vs. require tessellation
- Provide mesh preview for objects that will be tessellated on export
- Controls to tune tessellation quality per object before export
Core developers: Keith Sloan · Munther Hindi · Damian Lambert
Graphic icons: GDML shapes by Jim Austin (jmaustpc) · Cycle icon by Flaticon (www.flaticon.com)
Special thanks: Munther Hindi for extensive problem solving · Luzpaz for documentation help
Contributors: Louis Helary · Emmanuel Delage · Ami Hashemi · Wouter Deconnink · Hilden Timo · Atanu Quant · Masaki Morita
FreeCAD forum: wmayer · Joel_graff · chrisb · DeepSOIC · ickby · edwilliams16 · looooo · easyw-fc · bernd · vocx · sgrogan · onekk (Carlo D) · OpenBrain · Roy_043 · TheMarkster · jeno
OpenCASCADE forum: Sergey Slyadnev · Stack Overflow: Daniel Haley
- Bug reports: Open an issue
- Test files: Small to medium GDML files for testing are always welcome
- Contact: keith[at]sloan-home[dot]co[dot]uk
Based on gdml.xsd. Key structural constraints:
- Volumes must have a solid ref and a material ref
- PhysVol must contain a volref (or file); the volref must not be the same as the current volume name; may contain position/rotation or refs to defined position/rotation
NIST materials database: https://www.nist.gov/pml/productsservices/physical-reference-data