Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Joints: a new joint between faces that already meet leaves the part as it is (#2709) (#2710)

NOWN-DEV768e69c4c7dc
diff --git a/crates/doc/src/joints.rs b/crates/doc/src/joints.rs
index ff84addcd9..b9520c4775 100644
--- a/crates/doc/src/joints.rs
+++ b/crates/doc/src/joints.rs
@@ -1737,6 +1737,26 @@ mod face;
pub use face::{end_faces, face_name_at, named_face_spot, pin_end, round_end_at};
pub use reach::{REACH_TOL, Reach, Reached, reach};
+/// The rest angle that turns B least as joint `j` is made, as B sits now: none or a half turn
+/// about the joint's z. Origins whose x is chosen for them (a face, a circle, a point without
+/// x) get opposite x when their z are opposite, so two faces that already meet would, at angle
+/// 0, spin B a half turn about their shared normal.
+pub fn least_turn_angle(doc: &Document, st: &ModelState, j: &Joint) -> f64 {
+ let (Ok(fa), Ok(fb)) = (resolve_origin(doc, st, &j.a), resolve_origin(doc, st, &j.b)) else { return 0.0 };
+ let (ta, tb) = (occurrence_world(doc, j.a.occurrence), occurrence_world(doc, j.b.occurrence));
+ let mut q = j.values.clone();
+ q.resize(j.kind.dofs().len(), 0.0);
+ clamp(j, &mut q);
+ let turn = |angle: f64| {
+ let k = Joint { angle, ..j.clone() };
+ through(&k, &(fa, fb), &q, true, &ta).map(|m| mismatch(&m, &tb).1)
+ };
+ match (turn(0.0), turn(std::f64::consts::PI)) {
+ (Some(none), Some(half)) if half + 1e-9 < none => std::f64::consts::PI,
+ _ => 0.0,
+ }
+}
+
/// The frame matrix for an explicit origin / z / x (public for commands).
pub fn frame_of(o: Vec3, z: Vec3, x: Option<Vec3>) -> Option<Mat> {
frame(o, z, x)
diff --git a/crates/engine/src/cmd/joints.rs b/crates/engine/src/cmd/joints.rs
index 7fe68860ed..2dbe97540d 100644
--- a/crates/engine/src/cmd/joints.rs
+++ b/crates/engine/src/cmd/joints.rs
@@ -23,7 +23,8 @@ pub static COMMANDS: &[CommandSpec] = &[
"type: rigid|revolute|slider|cylindrical|pin_slot|planar|ball; a, b: joint origins ({occurrence, face|circle|edge|point: [x,y,z] in world, or face|circle: \"<face name>\"; end?, x? as joint.origin} | origin name); \
values?: [angles in deg or expressions, distances]; limits?: [[min, max] | null…]; flip?: bool (default false: the origins are mated, \
b's z against a's as two faces meet; true: b's z along a's, so two origins given at one point with the same z stay as they are); \
- offset?: mm or an expression; angle?: deg or an expression; name?; quiet?: bool (leave out dof and fixed). An expression (text) is \
+ offset?: mm or an expression; angle?: deg or an expression (default: none, or a half turn where that turns b less, so faces that \
+ already meet stay as they are); name?; quiet?: bool (leave out dof and fixed). An expression (text) is \
kept with the joint and worked out again whenever the design changes, so the joint follows the parameters it names; a joint whose \
expression no longer works out (a parameter deleted) is left out of the solve with the reason in its errors",
),
@@ -629,10 +630,10 @@ fn joint(s: &mut Session, p: &Value) -> Result<Value> {
None => 0.0,
};
let angle = match p.get("angle") {
- Some(v) => value(s, v, true, cmd)?,
- None => 0.0,
+ Some(v) => Some(value(s, v, true, cmd)?),
+ None => None,
};
- let j = Joint {
+ let mut j = Joint {
id,
name,
kind,
@@ -642,10 +643,15 @@ fn joint(s: &mut Session, p: &Value) -> Result<Value> {
limits: limits_param(s, p, kind, cmd)?,
flip: bool_(p, "flip").unwrap_or(false),
offset,
- angle,
+ angle: angle.unwrap_or(0.0),
suppressed: false,
exprs: JointExprs { offset: typed(p.get("offset")), angle: typed(p.get("angle")), values: value_exprs(p) },
};
+ // No angle given: B keeps its turn about the joint's axis where a half turn would otherwise
+ // come only from how its origin's x was chosen.
+ if angle.is_none() {
+ j.angle = joints::least_turn_angle(&s.doc, &s.model.state(), &j);
+ }
add_joint(s, j, p)
}
@@ -1418,3 +1424,6 @@ mod reach_tests;
#[cfg(test)]
#[path = "joints_tests.rs"]
mod tests;
+#[cfg(test)]
+#[path = "joints_turn_tests.rs"]
+mod turn_tests;
diff --git a/crates/engine/src/cmd/joints_turn_tests.rs b/crates/engine/src/cmd/joints_turn_tests.rs
new file mode 100644
index 0000000000..4e645a8efe
--- /dev/null
+++ b/crates/engine/src/cmd/joints_turn_tests.rs
@@ -0,0 +1,79 @@
+//! A new joint given no angle keeps the part's turn about the joint's axis: two faces that
+//! already meet stay as they are instead of the part spinning a half turn about their normal.
+
+use serde_json::json;
+use solidcraft_geom::Vec3;
+
+use super::tests::{occ, place, run};
+use crate::Session;
+
+/// A grounded panel 80 x 30 x 3 at z 3 and a hinge plate of the same size under it, each with a
+/// hole off its middle at x = 20: the two faces that meet at z = 3 have opposite normals.
+fn panel_and_hinge() -> Session {
+ let mut s = Session::default();
+ run(&mut s, "component.create", json!({"name": "Panel"}));
+ run(&mut s, "solid.box", json!({"length": 80, "width": 30, "height": 3, "corner": [0, 0, 3]}));
+ run(&mut s, "solid.hole", json!({"position": [20, 15, 6], "diameter": 5.5}));
+ run(&mut s, "component.activate", json!({"component": "root"}));
+ run(&mut s, "component.create", json!({"name": "Hinge"}));
+ run(&mut s, "solid.box", json!({"length": 80, "width": 30, "height": 3, "corner": [0, 0, 0]}));
+ run(&mut s, "solid.hole", json!({"position": [20, 15, 3], "diameter": 5.5}));
+ run(&mut s, "component.activate", json!({"component": "root"}));
+ let panel = occ(&s, "Panel");
+ run(&mut s, "occurrence.ground", json!({"occurrence": panel, "grounded": true}));
+ s
+}
+
+fn stays(s: &Session) -> bool {
+ [Vec3::new(20.0, 15.0, 0.0), Vec3::new(80.0, 0.0, 3.0)].iter().all(|p| place(s, "Hinge", *p).dist(*p) < 1e-6)
+}
+
+#[test]
+fn joining_two_faces_that_already_meet_leaves_the_part_where_it_is() {
+ // Each face's frame takes an x of its own; with opposite normals those x are opposite, and
+ // the joint used to spin the hinge a half turn about the normal, its hole to x = 60.
+ for kind in ["rigid", "slider", "planar"] {
+ let mut s = panel_and_hinge();
+ let r = run(
+ &mut s,
+ "joint.create",
+ json!({"type": kind, "a": {"occurrence": "Panel", "face": [30, 25, 3]}, "b": {"occurrence": "Hinge", "face": [30, 25, 3]}, "name": "J"}),
+ );
+ assert!(stays(&s), "{kind}: the hinge moved to {:?}: {r}", place(&s, "Hinge", Vec3::new(20.0, 15.0, 0.0)));
+ // Its value still moves it along the joint's axis (the faces' normal), without a turn.
+ if kind == "slider" {
+ run(&mut s, "joint.drive", json!({"joint": "J", "value": 5}));
+ let p = place(&s, "Hinge", Vec3::new(20.0, 15.0, 0.0));
+ assert!(p.dist(Vec3::new(20.0, 15.0, -5.0)) < 1e-6, "{p:?}");
+ }
+ }
+ // An angle given is kept as given.
+ let mut s = panel_and_hinge();
+ run(
+ &mut s,
+ "joint.create",
+ json!({"type": "rigid", "a": {"occurrence": "Panel", "face": [30, 25, 3]}, "b": {"occurrence": "Hinge", "face": [30, 25, 3]}, "angle": 0}),
+ );
+ assert!(!stays(&s));
+ let j = s.doc.assembly.joints.last().map(|j| j.angle);
+ assert_eq!(j, Some(0.0));
+}
+
+#[test]
+fn an_angle_typed_as_an_expression_is_not_replaced_by_the_kept_turn() {
+ // `turn` is 0 deg: the hinge takes the half turn the angle says, not the one that would
+ // leave it where it is, and follows the parameter when it changes.
+ let mut s = panel_and_hinge();
+ run(&mut s, "parameters.add", json!({"name": "turn", "expression": "0 deg"}));
+ run(
+ &mut s,
+ "joint.create",
+ json!({"type": "rigid", "a": {"occurrence": "Panel", "face": [30, 25, 3]}, "b": {"occurrence": "Hinge", "face": [30, 25, 3]}, "angle": "turn", "name": "J"}),
+ );
+ assert!(!stays(&s));
+ let j = s.doc.assembly.joints.last().map(|j| (j.angle, j.exprs.angle.clone()));
+ assert_eq!(j, Some((0.0, Some("turn".to_string()))));
+ run(&mut s, "parameters.change", json!({"name": "turn", "expression": "180 deg"}));
+ assert!(stays(&s), "{:?}", place(&s, "Hinge", Vec3::new(20.0, 15.0, 0.0)));
+ assert!(s.doc.assembly.joints.last().is_some_and(|j| j.exprs.angle.as_deref() == Some("turn")));
+}
diff --git a/docs/book/src/guide/assemblies.md b/docs/book/src/guide/assemblies.md
index 3280f83c8e..bbd40dda89 100644
--- a/docs/book/src/guide/assemblies.md
+++ b/docs/book/src/guide/assemblies.md
@@ -165,8 +165,11 @@ it where it is), and it moves.
`joint.drive` answers the joint's values as `joint.list` gives them, in degrees and millimetres
with their units and limits, and `moved` says whether any part moved. A joint's origins are mated
by default: B's z axis is turned against A's, as two faces meet. `flip: true` lines them up
-instead, so two origins given at one point with the same z stay as they are. For scripts that
-drive many steps, `quiet: true` leaves the per-part degrees of freedom out of joint answers, and
+instead, so two origins given at one point with the same z stay as they are. Without an
+`angle`, a new joint takes no turn or a half turn about its axis, whichever turns B less: two
+faces that already meet, a plate under a panel, stay as they are instead of B spinning about
+their shared normal. For scripts that drive many steps, `quiet: true` leaves the per-part
+degrees of freedom out of joint answers, and
`motion.play` with `quiet: true` gives the poses of only the parts that moved.
**Motion Trace** (`motion.trace`, on the **ASSEMBLE** panel) draws the path a point of a part