Motion interference: a check cut short is not clear, and budget_s gives it time (#7855) (#7934)

* claim: #7855

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019FAWPuFoh9qxn2uS2j53QZ

* Motion interference: a check cut short by its work budget is not clear (#7855)

motion.interference stops when its work budget runs out (truncated) but
answered clear: collisions.is_empty(), so a check that reached only the first
steps read as a pass: a gear pair checked for 14 of 61 samples was "clear".
clear is now true only when every sample was checked and none collide.

The budget is an argument of interference_within, so a test can cut a check
short: B slides up to touching A, a full check is clear, and the least work
that checks a first step stops after 1 of 16 samples with clear: false (it
was clear: true before). The guide and the mechanisms skill say the same.

The issue's second request, a budget_s on motion.interference, is not here.

Refs #7855.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019FAWPuFoh9qxn2uS2j53QZ

* Motion interference: budget_s gives a check the time it needs (#7855)

The work budget is fixed, so a gear pair drawn in detail was cut short
after a few samples, or refused before its first one. motion.interference
now takes budget_s (seconds, above 0, at most 86400, as inspect.interference
allows): the check then runs until that time instead of the work budget,
looked at before each sample, and echoes budget_s in its answer. Without
budget_s nothing changes. The refusal before a first step now names the
budget that ran out and suggests budget_s.

Tests: given a time, the smallest work budget (which checks no step) no
longer stops the check, through motion.interference too; budget_s 0, -1,
1e9 and "soon" are refused.

Fixes #7855.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019FAWPuFoh9qxn2uS2j53QZ

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
austin62jake
2026-10-28 12:19:10 +00:00
committed by GitHub
parent 4d6664e4ca
commit 1e3cb3e36e
4 changed files with 107 additions and 14 deletions
+97 -11
View File
@@ -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<Contact
pub(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| {
// 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<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]
@@ -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}");
+5 -2
View File
@@ -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
+1 -1
View File
@@ -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