diff --git a/crates/engine/src/cmd/motion_analysis.rs b/crates/engine/src/cmd/motion_analysis.rs index ab3c51d3f..d10cc911b 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 j pub 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 Result { 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) -> Result { + 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| { - // Placing the meshes is work too, also where nothing comes near. - work = work.saturating_add(geometry.vertex_count()); - if work > MAX_WORK { + if deadline.is_some_and(|d| web_time::Instant::now() >= d) { truncated = true; return Ok(false); } - let hits: Vec<(Member, Member, f64)> = match geometry.hits(t, &mut work, MAX_WORK, true) { + // Placing the meshes is work too, also where nothing comes near. + work = work.saturating_add(geometry.vertex_count()); + if work > budget { + truncated = true; + return Ok(false); + } + 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 { })?; // 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 { "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 { 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.rs index 88c2cd41c..ccfa73b4e 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.md index 98154f2d3..1f3420ef8 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 are unwrapped, 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 each colliding pair with its `first_step`, `last_step`, the `steps` ranges where they overlap, how far 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 occurrenc sets tell them apart: an occurrence inside a sub-assembly placed twice is one part, so its two copies 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 gets before parts touch: `stopped_at` (the last value clear of contact), `stopped_by` (the two parts diff --git a/skills/solidcraft-mechanisms/SKILL.md b/skills/solidcraft-mechanisms/SKILL.md index 890b875a4..9e9fc6aec 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