SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Motion interference: a check cut short is not clear, and budget_s gives it time (#7855) (#7934)
austin62jake1e3cb3e36e0f
diff --git a/crates/engine/src/cmd/motion_analysis.rs b/crates/engine/src/cmd/motion_analysis.rsindex ab3c51d3f0..d10cc911b9 100644--- a/crates/engine/src/cmd/motion_analysis.rs+++ b/crates/engine/src/cmd/motion_analysis.rs@@ -14,7 +14,7 @@ use solidcraft_geom::{Aabb3, Vec3};use super::contact_sweep::{ContactGeometry, Member};use super::{drive_with_contact, joint_id, keyed, occurrences, path_world, study_index, traced_point, values_at};-use crate::params::{bad, bool_};+use crate::params::{bad, bool_, num};use crate::{EngineError, Result, Session};pub const PLOT_DOC: &str = "study: id|name; joints?: [id|name] (default: every joint that moves); occurrence? and point? (a point \@@ -30,10 +30,12 @@ pub const PLOT_DOC: &str = "study: id|name; joints?: [id|name] (default: every jpub const INTERFERENCE_DOC: &str = "study: id|name; occurrences?: [ids or names] (two or more, checked against each other; \default every occurrence), with against?: [ids or names] (then each of `occurrences` is checked only against these, such \as an arm against the parts it must miss), or contact_sets?: true (the pairs of the design's contact sets); samples? \- (2…1000, default the study's steps + 1) → collisions: [{a, b, first_step, last_step, steps: [[from, to]…] (the step ranges where they overlap), \+ (2…1000, default the study's steps + 1); budget_s?: seconds (above 0, at most 86400; default a fixed work budget): the \+ time the check may take instead, looked at between samples, for a mechanism such as a gear train that needs longer → collisions: [{a, b, first_step, last_step, steps: [[from, to]…] (the step ranges where they overlap), \depth_mm (how far into each other, the most at deepest_step), volume_mm3 (their overlap there; null when it was not \- cheap to work out)}], clear, \- pairs (checked), samples (taken), truncated (the work budget ran out; checked_to: the last step checked), stopped_at, \+ cheap to work out)}], clear (every sample checked and none collide; never while truncated), \+ pairs (checked), samples (taken), truncated (the work budget, or budget_s, ran out; checked_to: the last step checked), budget_s \+ (when given), stopped_at, \stopped_by_loop. The study plays as motion.play plays it but contact sets do not stop it, on a copy (the design is not \changed). Parts are tested at the samples only: one that passes wholly through another between two samples is missed";@@ -43,6 +45,8 @@ const MAX_SAMPLES: usize = 1000;const MAX_SERIES: usize = 256;/// Most collision work over a whole study (see `ContactGeometry::hits`).const MAX_WORK: usize = 500_000_000;+/// Longest time an interference check may be given (`budget_s`): a day, as `inspect.interference`.+const MAX_BUDGET_S: f64 = 86_400.0;/// Most colliding pairs whose overlap volume is worked out, and most body booleans that takes.const MAX_VOLUMES: usize = 16;const MAX_BOOLEANS: usize = 64;@@ -359,21 +363,42 @@ pub(super) fn checked_pairs(s: &Session, p: &Value, cmd: &str) -> Result<Contactpub(super) fn interference(s: &mut Session, p: &Value) -> Result<Value> {let cmd = "motion.interference";+ let seconds = match p.get("budget_s") {+ None | Some(Value::Null) => None,+ Some(_) => match num(p, "budget_s") {+ Some(v) if v > 0.0 && v <= MAX_BUDGET_S => Some(v),+ _ => return Err(bad(cmd, format!("`budget_s` must be a number of seconds above 0, at most {MAX_BUDGET_S}"))),+ },+ };+ interference_within(s, p, MAX_WORK, seconds)+}++/// `motion.interference` with at most `budget` collision work (see `ContactGeometry::hits`), or,+/// given `seconds`, with that time instead: the work is then not counted against a budget, and+/// the time is looked at before each sample, so the last one may run past it (#7855).+fn interference_within(s: &mut Session, p: &Value, budget: usize, seconds: Option<f64>) -> Result<Value> {+ let cmd = "motion.interference";+ let deadline = seconds.and_then(|v| std::time::Duration::try_from_secs_f64(v).ok()).and_then(|d| web_time::Instant::now().checked_add(d));+ let budget = if deadline.is_some() { usize::MAX } else { budget };let m = s.doc.assembly.studies.get(study_index(s, p, cmd)?).cloned().ok_or_else(|| bad(cmd, "study"))?;let n = samples(p, &m, 2, cmd)?;let geometry = checked_pairs(s, p, cmd)?;let mut found: BTreeMap<(u64, u64), Collision> = BTreeMap::new();let (mut work, mut checked, mut truncated) = (0usize, 0usize, false);let stop = play(s, &m, n, false, |t, k| {+ if deadline.is_some_and(|d| web_time::Instant::now() >= d) {+ truncated = true;+ return Ok(false);+ }// Placing the meshes is work too, also where nothing comes near.work = work.saturating_add(geometry.vertex_count());- if work > MAX_WORK {+ if work > budget {truncated = true;return Ok(false);}- let hits: Vec<(Member, Member, f64)> = match geometry.hits(t, &mut work, MAX_WORK, true) {+ let hits: Vec<(Member, Member, f64)> = match geometry.hits(t, &mut work, budget, true) {Ok(h) => h,- Err(_) if work > MAX_WORK => {+ Err(_) if work > budget => {truncated = true;return Ok(false);}@@ -401,7 +426,13 @@ pub(super) fn interference(s: &mut Session, p: &Value) -> Result<Value> {})?;// Nothing checked is not clear.if truncated && checked == 0 {- return Err(bad(cmd, "the check ran out of its work budget before its first step: check fewer parts (occurrences, against)"));+ return Err(bad(+ cmd,+ match seconds {+ Some(_) => "the check ran out of its budget_s before its first step: give it more time or check fewer parts (occurrences, against)",+ None => "the check ran out of its work budget before its first step: check fewer parts (occurrences, against) or give it a budget_s",+ },+ ));}let mut list: Vec<(&(u64, u64), &Collision)> = found.iter().collect();list.sort_by_key(|(_, c)| c.samples.first().copied().unwrap_or(usize::MAX));@@ -417,11 +448,16 @@ pub(super) fn interference(s: &mut Session, p: &Value) -> Result<Value> {"depth_mm": c.depth, "deepest_step": step_of(&m, c.deepest, n), "volume_mm3": volume})}).collect();- let mut out = json!({"study": m.name, "steps": m.steps, "clear": collisions.is_empty(), "collisions": collisions,+ // A check cut short says nothing about the steps it did not reach, so it is not clear (#7855).+ let clear = collisions.is_empty() && !truncated;+ let mut out = json!({"study": m.name, "steps": m.steps, "clear": clear, "collisions": collisions,"pairs": geometry.pair_count(), "samples": checked, "truncated": truncated});if truncated {out["checked_to"] = json!(checked.checked_sub(1).map(|k| step_of(&m, k, n)));}+ if let Some(v) = seconds {+ out["budget_s"] = json!(v);+ }out["stopped_at"] = stop["stopped_at"].clone();out["stopped_by_loop"] = stop["stopped_by_loop"].clone();Ok(out)@@ -431,6 +467,56 @@ pub(super) fn interference(s: &mut Session, p: &Value) -> Result<Value> {mod tests {use super::*;+ fn run(s: &mut Session, id: &str, p: Value) -> Value {+ s.execute(id, &p).unwrap_or_else(|e| panic!("{id} {p}: {e}"))+ }++ /// Cube B (x 20…30) slides from 10 mm away until it touches A (x 0…10) over the 15 steps of+ /// study "Push": nothing ever overlaps.+ fn touching() -> Session {+ let mut s = Session::default();+ for (name, x) in [("A", 0), ("B", 20)] {+ run(&mut s, "component.activate", json!({"component": "root"}));+ run(&mut s, "component.create", json!({"name": name}));+ run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10, "corner": [x, 0, 0]}));+ }+ run(&mut s, "component.activate", json!({"component": "root"}));+ let a = s.doc.find_component("A").and_then(|c| s.doc.occurrence_of(c)).map(|o| o.id).unwrap_or(0);+ run(&mut s, "occurrence.ground", json!({"occurrence": a, "grounded": true}));+ run(&mut s, "joint.create", json!({"type": "slider", "a": {"face": [10, 5, 5]}, "b": {"face": [20, 5, 5]}, "name": "Rail"}));+ run(&mut s, "joint.drive", json!({"joint": "Rail", "value": 10}));+ run(&mut s, "motion.study", json!({"name": "Push", "steps": 15, "keys": [{"joint": "Rail", "points": [[0, 10], [15, 0]]}]}));+ s+ }++ /// #7855: a check its work budget cuts short is not clear, though nothing collided in the+ /// steps it reached.+ #[test]+ fn a_check_cut_short_is_not_clear() {+ let mut s = touching();+ let p = json!({"study": "Push"});+ let full = run(&mut s, "motion.interference", p.clone());+ assert!(full["clear"] == true && full["truncated"] == false && full["samples"] == 16, "{full}");+ assert!(full.get("budget_s").is_none(), "{full}");+ // The least work that checks a first step stops long before the last.+ let cut = (0..31).find_map(|i| interference_within(&mut s, &p, 1usize << i, None).ok()).unwrap_or_default();+ assert!(cut["truncated"] == true && cut["samples"].as_u64().is_some_and(|n| (1..16).contains(&n)), "{cut}");+ assert!(cut["collisions"] == json!([]) && cut["clear"] == false, "{cut}");+ }++ /// #7855: given `budget_s`, the time is the budget, not the work: the smallest work budget,+ /// which stops a check before its first step, no longer stops it.+ #[test]+ fn a_time_budget_takes_the_place_of_the_work_budget() {+ let mut s = touching();+ let p = json!({"study": "Push"});+ assert!(interference_within(&mut s, &p, 1, None).is_err(), "one unit of work checks no step");+ let timed = interference_within(&mut s, &p, 1, Some(600.0)).unwrap_or_default();+ assert!(timed["clear"] == true && timed["truncated"] == false && timed["samples"] == 16, "{timed}");+ let r = run(&mut s, "motion.interference", json!({"study": "Push", "budget_s": 600}));+ assert!(r["clear"] == true && r["samples"] == 16 && r["budget_s"] == 600.0, "{r}");+ }+/// The differences are exact for a quadratic: its velocity and acceleration everywhere,/// the ends too.#[test]diff --git a/crates/engine/src/cmd/motion_analysis_tests.rs b/crates/engine/src/cmd/motion_analysis_tests.rsindex 88c2cd41c4..ccfa73b4e2 100644--- a/crates/engine/src/cmd/motion_analysis_tests.rs+++ b/crates/engine/src/cmd/motion_analysis_tests.rs@@ -201,6 +201,10 @@ fn motion_analysis_refuses_what_it_cannot_do() {("motion.interference", json!({"study": "Push", "occurrences": ["A"]})),("motion.interference", json!({"study": "Push", "occurrences": ["A", "B"], "contact_sets": true})),("motion.interference", json!({"study": "Push", "contact_sets": true})),+ ("motion.interference", json!({"study": "Push", "budget_s": 0})),+ ("motion.interference", json!({"study": "Push", "budget_s": -1})),+ ("motion.interference", json!({"study": "Push", "budget_s": 1e9})),+ ("motion.interference", json!({"study": "Push", "budget_s": "soon"})),];for (cmd, p) in refused {assert!(s.execute(cmd, &p).is_err(), "{cmd} {p}");diff --git a/docs/book/src/guide/assemblies.md b/docs/book/src/guide/assemblies.mdindex 98154f2d39..1f3420ef86 100644--- a/docs/book/src/guide/assemblies.md+++ b/docs/book/src/guide/assemblies.md@@ -323,7 +323,7 @@ stop it), each sample from the one before, on a copy: the design is not changed.accelerations are finite differences between samples, central inside and one-sided at the ends,so they are as smooth as the samples are dense (up to 1000, one per step by default). Angles areunwrapped, so a joint that turns on past half a turn keeps counting.-`motion.interference {study, occurrences?, against?, contact_sets?, samples?}` answers each+`motion.interference {study, occurrences?, against?, contact_sets?, samples?, budget_s?}` answers eachcolliding pair with its `first_step`, `last_step`, the `steps` ranges where they overlap, howfar into each other (`depth_mm`, the most at `deepest_step`) and their shared `volume_mm3`there (null when it is not cheap to work out). It plays the study as `motion.play` does, but@@ -332,7 +332,10 @@ through another between two samples is missed. Parts are told apart by occurrencsets tell them apart: an occurrence inside a sub-assembly placed twice is one part, so its twocopies are not checked against each other. A check takes at most 256 bodies; on a large design,list the `occurrences` to check (an arm, with `against` the parts it must miss). When the work-runs out it says `truncated` and the step it `checked_to`.+runs out it says `truncated` and the step it `checked_to`, and it is not `clear`, even when nothing+collided in the steps it checked. A mechanism with detailed parts, such as a gear train, can need+more than that fixed work budget: give it `budget_s` (seconds, at most 86400) and the check runs+until that time instead, looked at between samples.`joint.sweep {joint, from, to, index?, step?, refine?, occurrences?, against?, contact_sets?,report_gaps?, apply?}` drives one joint value from `from` toward `to` and answers how far it getsbefore parts touch: `stopped_at` (the last value clear of contact), `stopped_by` (the two partsdiff --git a/skills/solidcraft-mechanisms/SKILL.md b/skills/solidcraft-mechanisms/SKILL.mdindex 890b875a44..9e9fc6aec5 100644--- a/skills/solidcraft-mechanisms/SKILL.md+++ b/skills/solidcraft-mechanisms/SKILL.md@@ -58,7 +58,7 @@ Written against SolidCraft `main` after 0.11.1, which counts the degrees of free- **Play:** `motion.play {"study":..., "step":s}` sets the joints there, which changes the design, and answers every occurrence's pose (about 0.2 KB per occurrence). `motion.export {"study":..., "samples":n}` gives the poses at every step without changing the design.- **Trace:** `motion.trace {"occurrence":..., "point":[x,y,z], "joint":..., "from":0, "to":360}` (or `"study":...` instead of joint, from and to) answers the world path of a point of a part, such as a coupler curve, without changing the design. It ends at `stopped_at` where a loop or contact stops the motion. `motion.trace.keep` with the same params keeps it as a 3D sketch spline.- **Plot:** `motion.plot {"study":..., "joints":[...], "duration":seconds}` answers each joint value's `value`, `velocity` and `acceleration` per sample (finite differences; per step, or per second with a duration), and with `"occurrence"` and `"point"` a point's `position`, `velocity`, `acceleration`, `speed`. Check a follower's rate against the analytic one this way, without changing the design.-- **Collisions:** `motion.interference {"study":..., "occurrences":[...], "against":[...]}` plays the study (contact sets don't stop it) and lists each colliding pair with `first_step` and `steps` ranges; `clear: true` when none. It takes at most 256 bodies: on a big design list the moving part as `occurrences` and what it must miss as `against`. Parts joined at a knuckle often overlap by design and show up at every step.+- **Collisions:** `motion.interference {"study":..., "occurrences":[...], "against":[...]}` plays the study (contact sets don't stop it) and lists each colliding pair with `first_step` and `steps` ranges; `clear: true` when none and every step was checked (never while `truncated`: then it stopped at `checked_to`; give a gear train or other detailed parts more time with `budget_s`). It takes at most 256 bodies: on a big design list the moving part as `occurrences` and what it must miss as `against`. Parts joined at a knuckle often overlap by design and show up at every step.- **Sweep until contact:** `joint.sweep {"joint":..., "from":0, "to":120, "occurrences":[...], "against":[...], "report_gaps":true}` answers how far a hinge, door or linkage opens: `stopped_at` (last clear value, bisected to `refine` mm, default 0.01), `stopped_by` `{a, b, at}` (or `"loop"`, `"limit"`), per-sample `min_gap_mm` and the nearest each part came (`min_gap`). It runs on a copy; `"apply":true` leaves the design at the stop. Pairs touching at `from` (`touching_at_start`) stop it only once they pass into each other.## Verify