Joints: link offsets in b's units, new joints start inside their limits, loop dof at dead points (#1415)

joint.motion_link offset is read in the linked value's units (degrees or mm, or an expression); links are still stored in radians, so saved designs open unchanged. A new joint whose values fall outside its limits starts at the nearer limit, stores it, and says so in warnings. Loop dof also counts at a nearby pose, so a part at a dead point of its loop keeps its mobility. The mechanisms skill is updated to match.

crates/engine/src/cmd/joints.rs

@@ -39,7 +39,7 @@ pub static COMMANDS: &[CommandSpec] = &[
     CommandSpec::new("joint.motion_link", "Motion Link", motion_link)
         .at("SOLID", "ASSEMBLE")
         .icon("motion_link")
-        .params("a, b: joints; ratio (b = ratio · a + offset); offset?; ia?, ib?: value indices (default 0)"),
+        .params("a, b: joints; ratio (b = ratio · a + offset); offset?: in b's units (deg for an angle, mm for a distance, or an expression); ia?, ib?: value indices (default 0)"),
     CommandSpec::new("joint.limits", "Joint Limits", limits).params("joint; index?: value index (default 0); min?, max? (omit both to clear)"),
     CommandSpec::new("joint.edit", "Edit Joint", edit).params("joint; type?, flip?, offset?, angle?, suppressed?, name?"),
     CommandSpec::new("joint.delete", "Delete Joint", delete).params("joint: id|name (or origin: name, link: index)"),
@@ -314,7 +314,7 @@ fn next_joint_id(s: &Session) -> u64 {
     s.doc.assembly.joints.iter().map(|j| j.id).max().unwrap_or(0) + 1
 }
 
-fn add_joint(s: &mut Session, j: Joint, p: &Value) -> Result<Value> {
+fn add_joint(s: &mut Session, mut j: Joint, p: &Value) -> Result<Value> {
     if s.doc.assembly.joints.len() >= 10_000 {
         return Err(EngineError::Other("too many joints".into()));
     }
@@ -327,6 +327,30 @@ fn add_joint(s: &mut Session, j: Joint, p: &Value) -> Result<Value> {
              (component.from_bodies)",
         ));
     }
+    // It starts at its values inside its limits. A value moved to a limit moves the part as it
+    // is joined, which the answer says.
+    let mut q = j.values.clone();
+    q.resize(j.kind.dofs().len(), 0.0);
+    joints::clamp(&j, &mut q);
+    let round = |v: &Value| v.as_f64().map(|x| (x * 1e6).round() / 1e6).unwrap_or(f64::NAN);
+    let warnings: Vec<String> = named_values(&j, &q)
+        .iter()
+        .zip(named_values(&j, &j.values))
+        .filter(|(now, was)| now["value"] != was["value"])
+        .map(|(now, was)| {
+            let unit = now["unit"].as_str().unwrap_or("");
+            format!(
+                "{} {} starts at {} {unit}, inside its limits [{}, {}], not at {} {unit}: the part moved there as it was joined",
+                j.name,
+                now["name"].as_str().unwrap_or(""),
+                round(&now["value"]),
+                round(&now["limits"][0]),
+                round(&now["limits"][1]),
+                round(&was["value"])
+            )
+        })
+        .collect();
+    j.values = q;
     let id = j.id;
     let name = j.name.clone();
     // A new joint can take a deleted one's id; it starts shown.
@@ -336,6 +360,9 @@ fn add_joint(s: &mut Session, j: Joint, p: &Value) -> Result<Value> {
     let mut out = sol_json(&sol, p);
     out["joint"] = json!(id);
     out["name"] = json!(name);
+    if !warnings.is_empty() {
+        out["warnings"] = json!(warnings);
+    }
     Ok(out)
 }
 
@@ -493,7 +520,12 @@ fn motion_link(s: &mut Session, p: &Value) -> Result<Value> {
     if ia >= dofs(a) || ib >= dofs(b) {
         return Err(bad(cmd, "the linked joints need moving values at those indices"));
     }
-    let offset = num(p, "offset").unwrap_or(0.0);
+    // In b's units, like its values and limits (stored in radians for an angle).
+    let angle = s.doc.assembly.joints.iter().find(|j| j.id == b).is_some_and(|j| j.kind.is_angle(ib));
+    let offset = match p.get("offset") {
+        Some(v) => value(s, v, angle, cmd)?,
+        None => 0.0,
+    };
     s.doc_mut().assembly.links.push(MotionLink { a, ia, b, ib, ratio, offset });
     let sol = resolve(s);
     Ok(sol_json(&sol, p))
@@ -614,8 +646,17 @@ fn list(s: &mut Session, p: &Value) -> Result<Value> {
                 "flip": j.flip, "offset": j.offset, "suppressed": j.suppressed, "visible": s.joint_visible(j.id), "frame_a": world(&j.a), "frame_b": world(&j.b)})
         })
         .collect();
-    let links: Vec<Value> =
-        s.doc.assembly.links.iter().map(|l| json!({"a": l.a, "ia": l.ia, "b": l.b, "ib": l.ib, "ratio": l.ratio, "offset": l.offset})).collect();
+    let links: Vec<Value> = s
+        .doc
+        .assembly
+        .links
+        .iter()
+        .map(|l| {
+            let angle = s.doc.assembly.joints.iter().find(|j| j.id == l.b).is_some_and(|j| j.kind.is_angle(l.ib));
+            let offset = if angle { l.offset.to_degrees() } else { l.offset };
+            json!({"a": l.a, "ia": l.ia, "b": l.b, "ib": l.ib, "ratio": l.ratio, "offset": offset, "unit": if angle { "deg" } else { "mm" }})
+        })
+        .collect();
     let origins: Vec<Value> = s.doc.assembly.origins.iter().map(|o| json!({"name": o.name, "occurrence": o.origin.occurrence})).collect();
     let mut out = sol_json(&sol, p);
     out["joints"] = json!(js);

crates/engine/src/cmd/joints_tests.rs

@@ -808,6 +808,32 @@ fn loops_report_their_mobility() {
     }
 }
 
+/// An actuator in line with the path of its tip pin, as modelled: a panel hinged at the origin,
+/// its tip pin at (30, 0) moving along Y, and a barrel and rod along Y from a root pin at
+/// (30, -40). There the rod only extends and the barrel's turn is zero to first order, but the
+/// barrel turns as soon as the panel does: it has one degree of freedom, at that pose too.
+#[test]
+fn a_part_at_a_dead_point_of_its_loop_keeps_its_mobility() {
+    let mut s = Session::default();
+    let (tip, root) = (Vec3::new(30.0, 0.0, 0.0), Vec3::new(30.0, -40.0, 0.0));
+    for (name, c) in [("Ground", Vec3::new(0.0, -40.0, 0.0)), ("Panel", tip), ("Barrel", root), ("Rod", (tip + root) * 0.5)] {
+        part(&mut s, name, [c.x, c.y, -5.0]);
+    }
+    let g = occ(&s, "Ground");
+    run(&mut s, "occurrence.ground", json!({"occurrence": g, "grounded": true}));
+    pin(&mut s, "revolute", "Hinge", "Ground", "Panel", Vec3::ZERO, Vec3::Z);
+    pin(&mut s, "revolute", "Root pin", "Ground", "Barrel", root, Vec3::Z);
+    pin(&mut s, "slider", "Stroke", "Barrel", "Rod", root, Vec3::Y);
+    pin(&mut s, "revolute", "Tip pin", "Rod", "Panel", tip, Vec3::Z);
+    for part in ["Panel", "Barrel", "Rod"] {
+        assert_eq!(dof_of(&mut s, part), 1, "dead point: {part}");
+    }
+    run(&mut s, "joint.drive", json!({"joint": "Hinge", "value": 5}));
+    for part in ["Panel", "Barrel", "Rod"] {
+        assert_eq!(dof_of(&mut s, part), 1, "driven: {part}");
+    }
+}
+
 /// A design file path in a fresh temporary folder (removed by the caller).
 fn temp_design(tag: &str, ext: &str) -> (std::path::PathBuf, String) {
     let dir = std::env::temp_dir().join(format!("solidcraft-joint-visibility-{tag}-{}", std::process::id()));
@@ -1054,3 +1080,72 @@ fn a_single_value_keeps_the_joints_other_values() {
     let r = run(&mut s, "joint.drive", json!({"joint": "Spindle", "values": [60]}));
     assert!((at(&r)[0] - 60.0).abs() < 1e-9 && (at(&r)[1] - 5.0).abs() < 1e-9, "{r}");
 }
+
+/// A motion link's offset is in the linked value's units, like joint values and limits: degrees
+/// for an angle, mm for a distance, or an expression. `joint.list` answers it the same way, it is
+/// stored in radians as before, and a saved link opens with the offset it had.
+#[test]
+fn a_link_offset_is_in_the_linked_values_units() {
+    let mut s = Session::default();
+    for (name, x) in [("Ground", 0.0), ("Dial", 80.0), ("Gear", 100.0), ("Car", 120.0), ("Cart", 140.0)] {
+        part(&mut s, name, [x, 0.0, -5.0]);
+    }
+    let g = occ(&s, "Ground");
+    run(&mut s, "occurrence.ground", json!({"occurrence": g, "grounded": true}));
+    for (kind, name, x) in [("revolute", "Dial", 80.0), ("revolute", "Gear", 100.0), ("slider", "Car", 120.0), ("slider", "Cart", 140.0)] {
+        pin(&mut s, kind, name, "Ground", name, Vec3::new(x, 0.0, 0.0), Vec3::Z);
+    }
+    run(&mut s, "joint.motion_link", json!({"a": "Dial", "b": "Gear", "ratio": 1, "offset": 10}));
+    run(&mut s, "joint.motion_link", json!({"a": "Car", "b": "Cart", "ratio": 1, "offset": "5 mm"}));
+    run(&mut s, "joint.drive", json!({"joint": "Dial", "value": 20}));
+    run(&mut s, "joint.drive", json!({"joint": "Car", "value": 3}));
+    let value = |l: &Value, name: &str| {
+        l["joints"].as_array().into_iter().flatten().find(|j| j["name"] == name).and_then(|j| j["values"][0]["value"].as_f64()).unwrap_or(f64::NAN)
+    };
+    let l = run(&mut s, "joint.list", json!({}));
+    assert!((value(&l, "Gear") - 30.0).abs() < 1e-9 && (value(&l, "Cart") - 8.0).abs() < 1e-9, "{l}");
+    let links: Vec<(f64, &str)> =
+        l["links"].as_array().into_iter().flatten().map(|k| (k["offset"].as_f64().unwrap_or(f64::NAN), k["unit"].as_str().unwrap_or(""))).collect();
+    assert!(
+        links.len() == 2 && (links[0].0 - 10.0).abs() < 1e-9 && links[0].1 == "deg" && (links[1].0 - 5.0).abs() < 1e-9 && links[1].1 == "mm",
+        "{l}"
+    );
+    assert!((s.doc.assembly.links[0].offset - 10f64.to_radians()).abs() < 1e-12);
+    // A design saved before offsets took degrees stored 0.1 rad, and opens turning Gear 5.73° past Dial.
+    s.doc_mut().assembly.links[0].offset = 0.1;
+    let (dir, path) = temp_design("link-offset", "solidcraft");
+    run(&mut s, "file.save", json!({"path": path}));
+    run(&mut s, "file.new", json!({}));
+    run(&mut s, "doc.open", json!({"path": path}));
+    let l = run(&mut s, "joint.list", json!({}));
+    assert!((value(&l, "Gear") - value(&l, "Dial") - 0.1f64.to_degrees()).abs() < 1e-9, "{l}");
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+/// A new joint starts at its values inside its limits. Limits that leave out 0 (or the values
+/// given) start it at the nearer limit, which it keeps, and the answer says the part moved there.
+#[test]
+fn a_new_joint_starts_inside_its_limits_and_says_so() {
+    let mut s = two_cubes();
+    let r = run(&mut s, "joint.as_built", json!({"type": "slider", "a": "A", "b": "B", "name": "Rail", "limits": [[2, 5]]}));
+    let w = r["warnings"].as_array().cloned().unwrap_or_default();
+    assert!(
+        w.len() == 1 && w[0].as_str().is_some_and(|w| w.starts_with("Rail distance starts at 2 mm, inside its limits [2, 5], not at 0 mm")),
+        "{r}"
+    );
+    assert!(near(place(&s, "B", Vec3::new(20.0, 0.0, 0.0)), Vec3::new(20.0, 0.0, 2.0)), "{:?}", place(&s, "B", Vec3::new(20.0, 0.0, 0.0)));
+    assert_eq!(s.doc.assembly.joints[0].values, [2.0]);
+    // Values given outside the limits start at the nearer one too; angles are answered in degrees.
+    let mut s = two_cubes();
+    let r = run(
+        &mut s,
+        "joint.create",
+        json!({"type": "revolute", "a": {"face": [5, 5, 10]}, "b": {"face": [25, 5, 0]}, "values": [90], "limits": [[0, 60]], "name": "Hinge"}),
+    );
+    let w = r["warnings"].as_array().cloned().unwrap_or_default();
+    assert!(w.len() == 1 && w[0].as_str().is_some_and(|w| w.contains("starts at 60 deg") && w.contains("not at 90 deg")), "{r}");
+    // Inside the limits, nothing to say.
+    let mut s = two_cubes();
+    let r = run(&mut s, "joint.as_built", json!({"type": "cylindrical", "a": "A", "b": "B", "name": "Spindle", "limits": [[-30, 30], [0, 5]]}));
+    assert!(r.get("warnings").is_none(), "{r}");
+}