fix(assembly): add datum plane logging + fix cross-product singularity #317

forbes · 2026-02-22T21:52:52Z

forbes commented

2026-02-22 21:52:52 +00:00

Two related fixes:

Diagnostic logging for Distance joint classification:
- getDistanceType() now logs datum plane detection with joint name, geometry combination, and resulting DistanceType
- buildSolveContext() logs every Distance joint's DistanceType→BaseJointKind mapping
- The default: fallback (unhandled types) now emits a warning
Cross-product singularity fix in the solver:
- All parallel-normal constraints (Parallel, Planar, Concentric, Revolute, Cylindrical, Slider, Screw) now use all 3 cross-product components instead of dropping cz
- Similarly, point_line_perp_components returns all 3 components
- This fixes a singularity where constraints were blind to yaw rotations when both normal vectors lay in the XY plane (e.g., face-to-datum-plane constraints for XZ_Plane or YZ_Plane)
- The extra residuals are rank-deficient at the solution; the Newton solver handles this correctly via its pseudoinverse
Tests for Distance joints to datum planes in TestAssemblyOriginPlanes.py:
- Vertex→datum-plane solves and pins position correctly
- Vertex→datum-plane preserves orientation (DOF=3)
- Face→datum-plane solves correctly

All 286 solver unit tests pass.

Two related fixes: 1. **Diagnostic logging** for Distance joint classification: - `getDistanceType()` now logs datum plane detection with joint name, geometry combination, and resulting DistanceType - `buildSolveContext()` logs every Distance joint's DistanceType→BaseJointKind mapping - The `default:` fallback (unhandled types) now emits a warning 2. **Cross-product singularity fix** in the solver: - All parallel-normal constraints (Parallel, Planar, Concentric, Revolute, Cylindrical, Slider, Screw) now use all 3 cross-product components instead of dropping `cz` - Similarly, `point_line_perp_components` returns all 3 components - This fixes a singularity where constraints were blind to yaw rotations when both normal vectors lay in the XY plane (e.g., face-to-datum-plane constraints for XZ_Plane or YZ_Plane) - The extra residuals are rank-deficient at the solution; the Newton solver handles this correctly via its pseudoinverse 3. **Tests** for Distance joints to datum planes in `TestAssemblyOriginPlanes.py`: - Vertex→datum-plane solves and pins position correctly - Vertex→datum-plane preserves orientation (DOF=3) - Face→datum-plane solves correctly All 286 solver unit tests pass.

forbes added 1 commit 2026-02-22 21:52:53 +00:00

fix(assembly): classify datum plane references in Distance joints

Build and Test / build (pull_request) Has been cancelled

Details

cf0cd3db7e

When a Distance joint references a datum plane (XY_Plane, XZ_Plane,
YZ_Plane), getDistanceType() failed to recognize it because datum
plane sub-names yield an empty element type. This caused the fallback
to DistanceType::Other → BaseJointKind::Planar, which adds spurious
parallel-normal residuals that overconstrain the system.

For example, three vertex-to-datum-plane Distance joints produced
10 residuals (3×Planar) with 6 mutually contradictory orientation
constraints, causing the solver to find garbage least-squares
solutions.

Add early detection of App::Plane datum objects before the main
geometry classification chain. Datum planes are now correctly mapped:
- Vertex + DatumPlane → PointPlane → PointInPlane (1 residual)
- Edge + DatumPlane → LinePlane → LineInPlane
- Face/DatumPlane + DatumPlane → PlanePlane → Planar

forbes merged commit 5c9212247a into main

2026-02-22 22:05:50 +00:00

forbes referenced this issue from a commit

2026-02-22 22:05:51 +00:00

Merge pull request 'fix(assembly): add datum plane logging + fix cross-product singularity' (#317) from fix/distance-datum-plane-classification into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: kindred/create#317