Skip to main content

Crate ferrocad_core

Crate ferrocad_core 

Source
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

§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, the petgraph recompute DAG, transaction-backed undo/redo, Observers, and the expression parser/evaluator.
  • M4 (slices 1–16) — the Base/App surface bound to Python: geometry helpers, persistence (SavedDocument), document metadata, extensions/groups, links, observers that fire, Python-object/Proxy persistence, 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::Enumeration and 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 .FCStd container.
fcstd_write
Writing FreeCAD’s binary .FCStd container.
format
Document format selection and the read/write dispatch.
geometry
Base geometry value types (FreeCAD’s Base module): Vector3, Matrix4, Rotation, Placement, and TypeId.
native
FerroCAD’s native document serializer: JSON plus a format/version envelope.
object_registry
Registered document-object types and their behaviour.
prop_status
Public PropertyType flag bits (mirror FreeCAD.PropertyType).
property_types
Registered property types: the App::Property half of FreeCAD’s Base::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
DocumentObject
ExtensionValue
A boxed module value, with the impls Property’s derives require.
Matrix4
Placement
PropertyContainer
Quantity
Rotation
SavedDocument
A document as persisted to disk by the native (.ferrocad) serializer.
StringHasher
StringId
TypeId
Unit
Vector3
ViewState
The view state of one document object.

Enums§

DocumentFormat
The serializers a document path can select.
Property
ScaleType

Traits§

DocumentObserver
A listener for document lifecycle events (FreeCAD’s App::DocumentObserver).
ExtensionData
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 0xRRGGBBAA colour.
parse_unit
Parse a (possibly compound) unit expression such as "F/m" or "mm^2" into a Unit. Returns None if 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 / getPropertyStatus text names for a status mask. Order follows the upstream getTypeOfProperty docstring.

Type Aliases§

Color
An RGBA colour, each component in 0.0..=1.0 (FreeCAD’s Base::Color).
DocumentHandle
A shared, mutable document. The registry and any Python wrapper for it hold the same handle.
ObjectId