diff --git a/crates/doc/src/joints.rs b/crates/doc/src/joints.rs index ff84addcd..b9520c477 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) -> Option { frame(o, z, x) diff --git a/crates/engine/src/cmd/joints.rs b/crates/engine/src/cmd/joints.rs index 7fe68860e..2dbe97540 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: \"\"; 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 { 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 { 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 000000000..4e645a8ef --- /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 3280f83c8..bbd40dda8 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