Expand description
§FerroCAD core (ferrocad_core)
The pure-Rust document model behind the FreeCAD Python package: typed
properties, a document object model with a dependency graph, transactions with
undo/redo, observers, expressions, and FreeCAD’s geometry and unit types. No
Python and no UI.
This crate is the engine. ferrocad_py
binds it to Python, and the pure-Python FreeCAD facade (the ferrocad
distribution) presents it as the drop-in import FreeCAD package.
The documentation is organised following Diátaxis: a tutorial to get started, how-to guides for common tasks, an explanation of the design, and a reference (the item pages).
§Tutorial
Build a document, wire a dependency with an expression, and recompute it.
use ferrocad_core::{Document, Property};
let mut doc = Document::new();
let width = doc.add_object("Width", "App::Feature");
let area = doc.add_object("Area", "App::Feature");
// A value on one object…
doc.set_property(width, "Value", Property::Float(10.0)).unwrap();
// …an expression on another (dependencies are tracked automatically)…
doc.set_expression(area, "Result", "Width.Value * 2").unwrap();
// …and a recompute in dependency order (returns the objects executed).
assert_eq!(doc.recompute().unwrap().len(), 2);
assert_eq!(
doc.object(area).unwrap().properties.get("Result"),
Some(&Property::Float(20.0)),
);§How-to guides
- Add a typed property with flags:
Document::add_propertytakes a value and aPropertyTypebitmask (seeprop_status); unlikeDocument::set_propertyit does not touch the object. Setting a property touches it unless it isOutput/NoRecompute. - Undo a change: wrap edits in
Document::open_transaction…Document::commit_transaction, thenDocument::undo/Document::redo. - Persist a document:
format::read/format::writeselect the serializer by suffix (.ferrocadnative JSON,.FCStdupstream);Document::save_to_file/Document::load_from_fileare the native JSON shortcut. Properties flaggedNoPersistare dropped from the saved form. The.FCStdwriter isfcstd_write::write_fcstd, a direct-call API that is not yet wired intoformat::write. - React to changes: register an
ObserverwithDocument::add_observer. - Report a failed rebuild: an
object_registry::ObjectType::executemarks the object withDocument::mark_invalid; recompute keeps the flag until a later execute succeeds. - Name objects:
Document::add_object_withapplies FreeCAD’s rules — names are sanitized (sanitize_name) and made unique, labels are unique unless duplicates are allowed.
§Explanation
A Document owns a set of DocumentObjects and a dependency graph over
them. Each object is a PropertyContainer — a name → value map where every
property also carries a status bitmask (prop_status). Recompute walks the
graph in dependency order and evaluates each object’s expressions.
Editing goes through transactions: Document::set_property records a
reversible change so a whole edit can be undone or redone. Assigning a property
touches the object (sets its must_execute flag) so a later recompute knows
what is dirty; Output/NoRecompute properties opt out.
The value types mirror FreeCAD’s Base module: Quantity/Unit for values
with units, and Vector3/Matrix4/Rotation/Placement for geometry.
Names are FreeCAD-compatible: internal names are sanitized and made unique,
display labels are a separate, user-facing string.
§Implemented capabilities
The crate grew milestone by milestone (see the repository docs/record/milestones.md):
- M2 — the core model:
Property/PropertyContainer,Quantity/Unit, thepetgraphrecompute DAG, transaction-backed undo/redo,Observers, and the expression parser/evaluator. - M4 (slices 1–16) — the
Base/Appsurface bound to Python: geometry helpers, persistence (SavedDocument), document metadata, extensions/groups, links, observers that fire, Python-object/Proxypersistence, expressions, and matrix decomposition / rotation numerics. - MVP slice A1 — object state and per-property status flags; touch-on-assign.
- MVP slice B1 — name/label semantics (
sanitize_name,Document::unique_name). - MVP slice A2 —
Property::Enumerationand type-registry validation. - MVP slice B2 — a general reversible undo/redo change set (property edits,
object add/remove, expressions) with named, id-carrying transactions, an active-object
pointer, and FreeCAD’s undo metadata (
Document::undo_names,Document::getAvailableUndos,Document::active_object).
§Reference
The item pages (Document, DocumentObject, Property, the geometry and unit
types, and the supporting modules) are the reference. The mod items below are
the module-level documentation.
Modules§
- fcstd
- Reading FreeCAD’s binary
.FCStdcontainer. - fcstd_
write - Writing FreeCAD’s binary
.FCStdcontainer. - format
- Document format selection and the read/write dispatch.
- geometry
- Base geometry value types (FreeCAD’s
Basemodule):Vector3,Matrix4,Rotation,Placement, andTypeId. - native
- FerroCAD’s native document serializer: JSON plus a format/version envelope.
- object_
registry - Registered document-object types and their behaviour.
- prop_
status - Public
PropertyTypeflag bits (mirrorFreeCAD.PropertyType). - property_
types - Registered property types: the
App::Propertyhalf of FreeCAD’sBase::Type. - quantity
- A
Quantity(value + unit) with FreeCAD’s unit-expression parser and arithmetic. - unit
- FreeCAD-style units: an 8-dimensional signature (plus angle) and a scale.
Structs§
- Application
- The registry of open documents and the active one.
- Document
- Document
Object - Extension
Value - A boxed module value, with the impls
Property’s derives require. - Matrix4
- Placement
- Property
Container - Quantity
- Rotation
- Saved
Document - A document as persisted to disk by the native (
.ferrocad) serializer. - String
Hasher - String
Id - TypeId
- Unit
- Vector3
- View
State - The view state of one document object.
Enums§
- Document
Format - The serializers a document path can select.
- Property
- Scale
Type
Traits§
- Document
Observer - A listener for document lifecycle events (FreeCAD’s
App::DocumentObserver). - Extension
Data - A module-owned property value.
- Observer
Functions§
- application
- The process-wide application (FreeCAD’s
App::GetApplication()). - canonical_
name - A canonical string for a signature using the internal base units.
- color_
from_ packed - Decode a packed colour (
0xRRGGBBAA) into RGBA components. - color_
to_ packed - Encode RGBA components as a packed
0xRRGGBBAAcolour. - parse_
unit - Parse a (possibly compound) unit expression such as
"F/m"or"mm^2"into aUnit. ReturnsNoneif it is not a pure unit expression. - sanitize_
name - Strip a leading ‘.’ from a self-relative expression path.
FreeCAD
Base::Tools::getIdentifier: keep identifier characters, replace every other code point with_, and prepend_if the first character is not a valid identifier start (e.g. a digit). - status_
from_ name - Map a status text name to its bit (case-insensitive).
- status_
names - The
getTypeOfProperty/getPropertyStatustext names for a status mask. Order follows the upstreamgetTypeOfPropertydocstring.
Type Aliases§
- Color
- An RGBA colour, each component in
0.0..=1.0(FreeCAD’sBase::Color). - Document
Handle - A shared, mutable document. The registry and any Python wrapper for it hold the same handle.
- Object
Id