FerroCAD

FerroCAD is the project formerly known as freecad-rs-poc: a Rust reimplementation of FreeCAD's
C++ App core, designed to be a drop-in replacement for the FreeCAD Python package. The
Python import namespace stays FreeCAD; the project/distribution is ferrocad.
Milestones 0–4 (slice 16): run a FreeCAD headless "hello world" Python script on a pure-Rust core, with the C++ Python bindings replaced by Rust bindings.
- M0 — hello world on a Rust object model, bridged to Python over a temporary C ABI +
ctypes. - M1 — the bridge migrated to PyO3 (
FreeCAD._core); the temporaryctypespath stood in as a fallback until it was removed in favour of a hard dependency on the CPython headers. - M2 — the pure-Rust core (
ferrocad_core): quantities, properties, a dependency-graph recompute order, transactions (open/commit/abort/undo/redo), observers, and an expression engine. - M3a — inventory the upstream
.pyistubs (320 files → 329 classes / 2210 methods). - M3b — PyO3 bindings over
ferrocad_core(ferrocad_py, moduleferrocad) became the sole backend of theFreeCADfacade; the legacyctypesfallback was removed. - M3c — generate PyO3 skeleton bindings (
ferrocad_gen) from the.pyimodel; behaviour stays inferrocad_core(hand-written glue). - M3d — a conformance harness that runs upstream
Mod/Testfiles against ourFreeCADand reports the parity gap. - M4 (slice 1) — the
FreeCAD.Base/Units/Console/ParamGet/StringHashersurface. - M4 (slice 2) — the full
FreeCAD.Unitssystem (Unit/Quantity+ expression parser). - M4 (slice 3) —
Base.Vector/Matrix/Placement/Rotation/TypeId+App::FeatureTest. - M4 (slice 4) — document
saveAs/save/open/copyObject(JSON persistence). - M4 (slice 5) — geometry tuple setters,
PlacementList/RotationListproperties, document metadata (ActiveObject/findObjects/setAutoCreated),TypeIdclassmethods,addPropertyflags,addDocumentObserver(no-op) +FreeCAD.PropertyType. - M4 (slice 6) — dynamic extensions (
addExtension/hasExtensionwithGroupExtensionPython→GroupExtensioninheritance), groups (App::DocumentObjectGroup+App::PartwithGrouplink list,addObject/hasObject/getObject/getParentGroup/getParentGeoFeatureGroup/OutList/InList, single-group enforcement), and a console-modeFreeCADGuistub +ViewObject→None. - M4 (slice 7) —
App::Origin.getSubObject(axes/planes with the standard frames; FreeCAD'sretTypeconvention) + a row-majorMatrix4fix (transform/Placement.to_matrixwere inconsistent, inverting rotations). - M4 (slice 8) — link properties read/write as
DocumentObjects; arbitrary object attributes (obj.Proxy) via an instance__dict__; object__hash__;abi3minimum 3.10. - M4 (slice 9) —
Document.Meta+Document.settings(namespace)(typed get/set, validation),Document.RootObjects/TopologicalSortedObjects,DocumentObject.ID, id-awaregetObject,ColorList. - M4 (slice 10) —
PropertyLinkSub((object, subnames)round-trip);listDocuments()returns a dict (upstream shape) andopenDocumentis exposed. - M4 (slice 11) — document observers that fire: a global observer registry + an object
identity cache (so observer arguments satisfy
is), pending/named transactions, and event emission at the exact FreeCAD points (document lifecycle, object create/change/delete/recompute, dynamic properties/extensions, transactions, save). AllDocumentObserverCasespass. - M4 (slice 12) — persistence/recovery:
Document.dumpContent/restoreContent/restore,DocumentObject.dumpContent/restoreContent/dumpPropertyContent/restorePropertyContent,canWriteRecoverySnapshot/TransientDirandwriteRecoverySnapshotToTransientDir. - M4 (slice 13) — Python-object &
Proxypersistence:App::PropertyPythonObjectvalues and an object'sProxy(dumps/loadsprotocol) survive save/restore. - M4 (slice 14) — expression engine:
int→Floatcoercion, self-relative paths (10mm,%), cycle detection (RuntimeError),ExpressionEngine/evalExpression/touch, andApp::DocumentObjectFileIncluded. - M4 (slice 15) — widen the conformance harness to eight upstream files (
BaseTests,TestIntPairList,FreeCADInitTestsadded); fullParameterGrprewrite; a matrix inverse transpose fix; and a broadBasegeometry surface (Matrix/Rotation/Placementhelpers,Vector2d/Material/BoundBox,IntPairList). - M4 (slice 16) — matrix decomposition (
Matrix.decompose()/hasScale()/ScaleType) plus the rotation-numerics cluster: FreeCAD's verbatim Gauss-Jordan inverse, quaternion normalizingto_matrix,decompose-basedfrom_matrix, angle wrapping, quaternionyaw_pitch_roll, andRotation.Axes; conformance now 146 passing (BaseTests48/49). - MVP slice A1 — object state, property status & touch: per-property
PropertyTypestatus flags (getPropertyStatus/setPropertyStatus/getTypeOfProperty), touch-on-assign (Prop_Output/Prop_NoRecomputesuppress it),Prop_NoPersistdropped on save,purgeTouched,getStatusString, and a fullState(Invalid/Touched/Up-to-date). - MVP slice B1 — object name/label semantics: names are sanitized
(
My Label→My_Label) and made unique; labels are unique unless theDuplicateLabelsdocument preference is set (then the requested label is kept verbatim), for bothaddObjectandcopyObject. - MVP slice A2 —
PropertyEnumeration+ type validation: an enumeration property (set-from-list, select by index/value,enum_vals),addObject/addProperty/findObjectsreject extension / non-property types withTypeError. This continues the MVP track. - MVP slice B2 — the undo/redo engine: transactions now record a general, reversible
change set (property edits, object add/remove, expression set/remove) and expose
UndoNames/RedoNames/UndoCount/RedoCount/clearUndos. Opening a second transaction commits the first on its next change, a new change drops the redo stack, and aborting leaves no entry.ActiveObjectfollowsaddObjectand is cleared when that object is undone; removing an object records the group link-list edits so group membership is restored;InListis link-type-aware (anyLink/LinkList/LinkSub, plus expression backlinks); and transactions carry process-unique ids (getBookedTransactionID,getAvailableUndos/getAvailableRedos), withUndoModereported as1(assignment accepted and ignored). Conformance is now 160 passing (UndoRedoCases,MultiDocumentUndoandTestIntPairListare fully green).
This is a proof of concept, not a product. It exists to validate the single
riskiest assumption of the rewrite plan: that a Python script written against
FreeCAD's public App API can be served by a Rust implementation instead of the
C++ one, without changing the script.
The idea
flowchart TD
S["hello_freecad.py<br/>(unchanged FreeCAD API)"]
M["python/FreeCAD<br/>facade"]
P["crates/ferrocad_py<br/>ferrocad (PyO3)"]
K["crates/ferrocad_core<br/>pure-Rust core"]
S -->|"import FreeCAD"| M
M --> P
P --> K
hello_freecad.pyuses only the public FreeCAD API. The same file is intended to run against upstream FreeCAD.python/FreeCAD/is a drop-in module that speaks that API; it knows nothing about C++ or Coin. Sinceferrocadis just a document-object model (no "application"), the facade adds the small App-level layer it lacks: a document registry,ActiveDocument, unique-name allocation, andVersion.crates/ferrocad_py/exposes the model as real#[pyclass]types via PyO3 (importable asferrocad).crates/ferrocad_core/is the pure-Rust implementation behindferrocad_py: no Python, no UI, just the object model.
Workspace layout
FerroCAD is a Cargo workspace (edition 2024). Crate status:
| Crate | Role | Status |
|---|---|---|
crates/ferrocad |
the base app: runs the general edition (cargo run -p ferrocad) |
published (app binary) |
crates/ferrocad_core |
pure-Rust model: quantities, properties, documents, recompute DAG | primary |
crates/ferrocad_py |
PyO3 extension over ferrocad_core (module ferrocad) |
primary |
crates/ferrocad_gen |
generated PyO3 skeleton bindings from the .pyi model (M3c) |
useful — drives the codegen tests |
crates/ferrocad_widgets |
reusable bite-gpui widgets (window chrome, field, console) |
published |
crates/ferrocad_gpui |
library: reusable app shell (run/run_with + HostConfig), boots CPython |
primary |
crates/xtask |
build tasks: cargo xtask bundle stages a distribution |
tool |
The GUI crates (ferrocad_widgets, ferrocad_gpui, ferrocad) are excluded from default-members
so cargo build/cargo test stay fast; ferrocad_gpui additionally carries the PyO3
auto-initialize feature, which conflicts with the extension-module feature of the extension crates.
Build & run
Expected output:
FreeCAD version : 0.1.0
Active document : HelloWorld
Document label : HelloWorld
Object count : 1
- Box (App::FeaturePython) label='Hello, FreeCAD'
obj.Description : Created by the Rust core
Properties : ['Description']
Documents : ['HelloWorld']
Active after close: None
OK
Tests:
&& PYTHONPATH=python PYTHONPATH=python PYTHONPATH=python PYTHONPATH=python &&
Regenerate the M3c skeleton (crates/ferrocad_gen/src/lib.rs, committed):
Run upstream tests against our FreeCAD (conformance harness, M3d):
Documentation
The Rust crates carry Diátaxis-structured rustdoc — a tutorial, how-to guides, an explanation of the design, and the generated item reference:
The crate page of ferrocad_core (crates/ferrocad_core/src/lib.rs) reads as a tutorial and an
explanation with How-to/Reference sections; it is rendered on docs.rs when published. The
per-module pages are the reference.
The product surface is Python (import FreeCAD) and deliberately mirrors upstream FreeCAD, so
its API reference is FreeCAD's own. FerroCAD-specific Python guidance therefore lives in the
python/FreeCAD facade docstrings and the repository docs/ (milestones, MVP path, architecture,
app-shell vision, repackaging, rewrite strategy). A Sphinx/mkdocstrings site is the natural next step once a Python doc
build can run in CI; until then rustdoc is the verifiable source of truth.
Packaging
pyproject.toml builds the distribution ferrocad with
maturin: it compiles crates/ferrocad_py into the top-level module
ferrocad and ships the pure-Python FreeCAD/FreeCADGui packages from python/. A user still
writes import FreeCAD.
The Rust library crates (ferrocad_core, ferrocad_py, ferrocad_widgets, ferrocad_gpui) and the
app (ferrocad) publish to crates.io, and the wheel publishes to PyPI. A v* tag drives both
../.github/workflows/crates.yml (publish order, payload staging) and
../.github/workflows/release.yml (the platform artifacts). The
abi3/extension-module notes, the publish order, and the staging commands are in
../docs/releasing.md and ../docs/distribution.md.
cargo install ferrocad produces a self-contained binary: crates/ferrocad embeds the workspace
python/ (and, when published with workbenches, mods/) and unpacks it on first run, because Cargo has
no data-file install step. The publish staging (cargo xtask stage-payload) keeps those directories out
of the crate source; they are copied in only for cargo publish and removed after.
Application artifacts (AppImage, .dmg, Windows zip) are built by
../packaging from the payload staged by cargo xtask bundle.
Tagging v* runs .github/workflows/release.yml,
which verifies the tag against the workspace version, runs the tests, builds the
three artifacts with the pinned Python runtime, and publishes a GitHub Release.
The same tag runs .github/workflows/crates.yml,
which publishes the library crates to crates.io (needs a CARGO_REGISTRY_TOKEN
secret).
Embedded Python (running scripts from Rust)
The shell library (crates/ferrocad_gpui) embeds CPython and drives it from Rust. It passes
four headless #[gpui::test]s, one of which embeds the interpreter, imports a Python module, and
round-trips a click through a Python callback back into a bite-gpui element
(cargo test -p ferrocad_gpui). The base app (crates/ferrocad) is a thin binary over it
(cargo run -p ferrocad). This is the Blender-style model the M5 UI track builds on: Python
declares the UI/workbench, Rust owns the process and renders.
Note the layering: ferrocad_core is pure Rust and does not embed Python; the embedding lives
in the shell library. Workbench Python is driven by the shell, while the FreeCAD facade talks to
the ferrocad extension the ordinary ways (import).
Python-only scripts & file loading
A plain workbench-style script that uses only the public FreeCAD API runs today —
hello_freecad.py is one, and examples/file_roundtrip.py demonstrates the file path:
create a document, doc.saveAs(path), FreeCAD.open(path), and read the objects/PropertyLength
back. The on-disk format is FerroCAD's own JSON under a .FCStd name; it is not yet upstream's
.FCStd/zip and importing real Part geometry is still out of scope.
PYTHONPATH=python
The Python bridge
crates/ferrocad_py builds the PyO3 extension ferrocad (M3b). ferrocad.Document /
ferrocad.DocumentObject are native #[pyclass] types over
Arc<Mutex<ferrocad_core::Document>>, built with abi3 and
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1, because this sandbox runs CPython 3.14, which is
newer than PyO3 0.25 officially targets. FreeCAD/__init__.py imports it unconditionally
and reports FreeCAD.backend == "ferrocad".
PyO3 is a hard build dependency on the CPython headers (CI installs python3-dev).
An earlier M0 ctypes/C-ABI fallback was removed: it was not a second transport for the
same core but a second, narrower model, and every capability it had is available through
PyO3. See ../docs/architecture.md for the call-path diagrams
and the decision.
See ../docs/rewrite-strategy.md for the direction and
../docs/coin-bridge-reuse-assessment.md
for the underlying analysis.
What is implemented vs. not
Implemented in ferrocad_core / ferrocad_py (the real model, not just a stub):
- a full
Quantity/Unitsystem: 8-dimension signatures, an internal unit table (SI base + derived + imperial + prefixes), an expression parser (fractions, scientific notation, compound units,pi/sin/cos/tan, feet-inchesN'(expr)"), arithmetic,Value/UserString/getValueAs/toNumber. Property/PropertyContainer,StringHasher/StringID.Document/DocumentObjectwith default naming, apetgraphdependency graph, topological recompute order, andremoveObject.- transactions (
open/commit/abort+undo/redo), anObservertrait, and an expression parser/evaluator withObject.Propertynames andrecompute().
Exposed through the FreeCAD facade (enough for the hello world and a workbench-style script):
- documents:
newDocument,closeDocument,getDocument,listDocuments,ActiveDocument, unique-name allocation,Name/Label. - objects:
addObject(default naming),getObject,removeObject,Objects,CountObjects,Name/Label/TypeId/Document,recompute. - properties:
addProperty,get/setPropertyByName, dynamic attribute mapping (obj.Foo),PropertiesList,getTypeIdOfProperty. - a single Python bridge, reported as
FreeCAD.backend("ferrocad").
Not implemented (deliberately out of scope for this milestone):
- the geometry kernel (
Part::Boxetc. produce no shape), - upstream's
.FCStd(zip) format — persistence is FerroCAD's own JSON, App/Guisplit, Coin3D, Qt,FeaturePythonscripting callbacks,- thread-safety guarantees beyond a coarse global mutex.
Next: the MVP app shell
The headless engine is the foundation; the next chunk is a single interactive window
that drives it — a developer tool with five pillars: open/close/load/save, undo/redo,
a DOM-like inspector, a property editor, and a Python console. It is one
bite-gpui window embedding CPython, calling the engine only through the public FreeCAD
API, so commands, console input and property edits all take the same path (and every edit is
one more undoable transaction). The ferrocad_gpui spike already proves the
Python-declared-UI ↔ bite-gpui round-trip headlessly.
The plan, architecture and slices (S1 shell skeleton → S2 lifecycle + commands → S3 inspector
→ S4 property editor → S5 console → S6 polish) are in
../docs/app-shell-vision.md. The 3D viewport is a later
track that docks into the shell's placeholder pane.
S1 is implemented (crates/ferrocad_gpui): a titled bite-gpui window that boots an
embedded CPython interpreter, creates a sample document, and shows a model inspector, a
read-only property editor, a viewport placeholder, a Python console and a status bar — all
driven live through the FreeCAD API (python/ferrocad_shell). Run it with
cargo run -p ferrocad (needs a display); the headless #[gpui::test] is the CI-proof path.
Repository layout
Cargo.toml Cargo workspace (edition 2024)
LICENSE LGPL-2.1-or-later (the `license` field is the SPDX id)
screenshot.png the shell screenshot above
pyproject.toml maturin packaging (distribution `ferrocad`)
hello_freecad.py the milestone script (public FreeCAD API only)
examples/file_roundtrip.py saveAs / open a document (file loading)
run.sh / build.sh convenience wrappers
python/FreeCAD/ drop-in module: __init__.py (facade)
Base.py core data types re-exported from ferrocad (Vector/Matrix/Rotation/…)
Units.py units facade (Quantity)
Console.py minimal Print* logging facade
python/ferrocad.abi3.so built PyO3 bindings (module `ferrocad`, gitignored; for the wheel/`build.sh`, not the app)
python/ferrocad_gen.abi3.so generated skeleton bindings, M3c (gitignored)
python/FreeCADGui/ console-mode Gui stub
python/ferrocad_spike/ Python declarative UI spike module
crates/ferrocad_core/ pure Rust core: quantities, properties, DAG, tx/observers/expr
crates/ferrocad_py/ PyO3 bindings over ferrocad_core (module `ferrocad`)
crates/ferrocad_gen/ generated PyO3 skeleton bindings (module `ferrocad_gen`)
src/lib.rs GENERATED by tools/codegen.py (committed)
crates/ferrocad/ the base app binary (cargo run -p ferrocad)
src/main.rs entry: calls ferrocad_gpui::run()
src/payload.rs finds/unpacks the embedded Python payload (cargo install)
build.rs embeds python/ + mods/ when staged (embedded-payload feature)
crates/ferrocad_gpui/ library: FerroCAD's bite-gpui app shell (boots CPython)
src/lib.rs run/run_with + HostConfig + window options
src/python.rs embedded-CPython bridge (boot, model_tree, properties, evaluate)
src/shell.rs the Shell view: inspector / property editor / console / status bar
src/spike.rs kept feasibility spike (Python-declared UI, headless)
crates/ferrocad_widgets/ reusable bite-gpui widgets (window chrome, field, console)
crates/xtask/ cargo xtask tasks (bundle: stage a distribution)
src/main.rs `cargo xtask bundle [--debug]`
.cargo/config.toml the `cargo xtask` alias
mods/ workbenches (FreeCAD Mod/ equivalent); packaged into the dist
packaging/ per-platform packagers wrapping the staged payload
linux/appimage.sh AppImage (needs appimagetool)
macos/app.sh .app + .dmg
windows/portable.ps1 portable folder + .zip
icon/ferrocad.svg icon source
python/ferrocad_shell/ Python side of the shell (sample document, console, model queries)
tools/inventory.py M3a: parse upstream .pyi stubs into an API model (Python ast)
tools/test_inventory.py M3a tests (hermetic fixtures + upstream integration guard)
tools/codegen.py M3c: emit PyO3 skeleton bindings from the API model
tools/test_codegen.py M3c tests (hermetic generator logic)
tools/conformance.py M3d: run upstream Mod/Test files against our FreeCAD
tools/test_conformance.py M3d tests (hermetic harness helpers)
tests/test_parity.py behavioural checks (M0/M1)
tests/test_base_surface.py end-to-end FreeCAD surface smoke tests (M4)
tests/test_fc_core.py ferrocad_core via Python (M3b)
tests/test_codegen.py generated skeleton surface (M3c)