feat(assembly): fixed reference planes (Top/Front/Right) + solver docs #307

forbes · 2026-02-21T15:09:39Z

forbes commented

2026-02-21 15:09:39 +00:00

Summary

Add SolidWorks-style fixed reference planes to assemblies and comprehensive solver documentation.

Assembly Origin Planes

When a new assembly is created, the three origin planes are now:

Visible by default (no need to manually toggle visibility)
Relabeled to intuitive names: Top (XY), Front (XZ), Right (YZ)
Selectable as joint references for constraining parts to the assembly origin

C++ Changes

AssemblyObject.cpp/h — setupObject() override

Relabels origin planes on assembly creation via App::Origin API
Called automatically by FreeCAD when the object is first created

AssemblyUtils.cpp — getObjFromRef() LCS resolution

Resolves App::LocalCoordinateSystem (Origin) to child datum elements (XY_Plane, XZ_Plane, etc.)
Required for the C++ solver pipeline to resolve joint references that target origin planes
Mirrors existing Python-side getObject() logic in UtilsAssembly.py

Python Changes

CommandCreateAssembly.py

After assembly creation, sets Origin.ViewObject.Visibility = True and makes all App::Plane features visible

Tests

TestAssemblyOriginPlanes.py — 9 integration tests:

Assembly structure (Origin with 3 planes + 3 axes)
Plane labels (Top, Front, Right)
Plane roles preserved (XY, XZ, YZ)
Assembly is grounded
Reference resolution (getObjFromRef for origin planes)
findPlacement returns identity for datum planes
Fixed joint to origin plane
Solver return code
Save/load round-trip preserves labels and visibility

Solver Documentation

Seven new documentation pages under docs/src/solver/:

Page	Content
`overview.md`	Architecture, pluggable solver interface, registry
`expression-dag.md`	Expression DAG extraction and serialization
`constraints.md`	Joint types, constraint mapping, DOF analysis
`solving.md`	Solving algorithms, convergence, performance
`diagnostics.md`	Error reporting, debugging, visualization
`assembly-integration.md`	FreeCAD Assembly module integration
`writing-a-solver.md`	Guide for implementing custom solver backends

Added Kindred Solver section to docs/src/SUMMARY.md.

## Summary Add SolidWorks-style fixed reference planes to assemblies and comprehensive solver documentation. ## Assembly Origin Planes When a new assembly is created, the three origin planes are now: - **Visible** by default (no need to manually toggle visibility) - **Relabeled** to intuitive names: Top (XY), Front (XZ), Right (YZ) - **Selectable** as joint references for constraining parts to the assembly origin ### C++ Changes **`AssemblyObject.cpp/h`** — `setupObject()` override - Relabels origin planes on assembly creation via `App::Origin` API - Called automatically by FreeCAD when the object is first created **`AssemblyUtils.cpp`** — `getObjFromRef()` LCS resolution - Resolves `App::LocalCoordinateSystem` (Origin) to child datum elements (XY_Plane, XZ_Plane, etc.) - Required for the C++ solver pipeline to resolve joint references that target origin planes - Mirrors existing Python-side `getObject()` logic in `UtilsAssembly.py` ### Python Changes **`CommandCreateAssembly.py`** - After assembly creation, sets `Origin.ViewObject.Visibility = True` and makes all `App::Plane` features visible ### Tests **`TestAssemblyOriginPlanes.py`** — 9 integration tests: 1. Assembly structure (Origin with 3 planes + 3 axes) 2. Plane labels (Top, Front, Right) 3. Plane roles preserved (XY, XZ, YZ) 4. Assembly is grounded 5. Reference resolution (getObjFromRef for origin planes) 6. findPlacement returns identity for datum planes 7. Fixed joint to origin plane 8. Solver return code 9. Save/load round-trip preserves labels and visibility ## Solver Documentation Seven new documentation pages under `docs/src/solver/`: | Page | Content | |------|---------| | `overview.md` | Architecture, pluggable solver interface, registry | | `expression-dag.md` | Expression DAG extraction and serialization | | `constraints.md` | Joint types, constraint mapping, DOF analysis | | `solving.md` | Solving algorithms, convergence, performance | | `diagnostics.md` | Error reporting, debugging, visualization | | `assembly-integration.md` | FreeCAD Assembly module integration | | `writing-a-solver.md` | Guide for implementing custom solver backends | Added Kindred Solver section to `docs/src/SUMMARY.md`.

forbes added 1 commit 2026-02-21 15:09:40 +00:00

feat(assembly): fixed reference planes + solver docs

Build and Test / build (pull_request) Failing after 7m52s

Details

acc255972d

Assembly Origin Planes:
- AssemblyObject::setupObject() relabels origin planes to
  Top (XY), Front (XZ), Right (YZ) on assembly creation
- CommandCreateAssembly.py makes origin planes visible by default
- AssemblyUtils.cpp getObjFromRef() resolves LocalCoordinateSystem
  to child datum elements for joint references to origin planes
- TestAssemblyOriginPlanes.py: 9 integration tests covering
  structure, labels, grounding, reference resolution, solver,
  and save/load round-trip

Solver Documentation:
- docs/src/solver/: 7 new pages covering architecture overview,
  expression DAG, constraints, solving algorithms, diagnostics,
  assembly integration, and writing custom solvers
- docs/src/SUMMARY.md: added Kindred Solver section

forbes merged commit 0f8fa0be86 into main

2026-02-21 15:09:57 +00:00

forbes deleted branch feat/assembly-origin-planes

2026-02-21 15:09:58 +00:00

forbes referenced this issue from a commit

2026-02-21 15:09:59 +00:00

Merge pull request 'feat(assembly): fixed reference planes (Top/Front/Right) + solver docs' (#307) from feat/assembly-origin-planes into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: kindred/create#307