SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Agents and scripts: the clearance check describes its exact parameters and reply (#11051) (#11052)
austin62jaked39a2d28dbfd
diff --git a/crates/engine/src/cmd/clearance.rs b/crates/engine/src/cmd/clearance.rsindex 762eadb55d..89ee1e357a 100644--- a/crates/engine/src/cmd/clearance.rs+++ b/crates/engine/src/cmd/clearance.rs@@ -9,7 +9,7 @@use std::collections::{BTreeMap, HashMap};use std::sync::Arc;-use serde_json::{Value, json};+use serde_json::Value;use solidcraft_geom::mesh_distance::box_gap;use solidcraft_geom::prelude::*;use solidcraft_geom::{Aabb3, Mesh};@@ -17,9 +17,20 @@ use solidcraft_kernel::{BodyDistance, DistanceShape};use super::CommandSpec;use crate::params::{bad, num, str_, string_list};+use crate::schema::clearance::{+ Clearance as ClearanceReply, ClearanceParams, MAX_CLEARANCE, MAX_NEAREST, NearPair, Neighbour, Overlap, OverlapBounds, Unchecked,+};+use crate::schema::{TypedContract, output_schema_for};use crate::{Result, Session};-pub static COMMANDS: &[CommandSpec] = &[CommandSpec::new("inspect.clearance", "Clearance", clearance).icon("interference").noundo().params(+const CONTRACT: TypedContract<ClearanceParams> = TypedContract::new();++pub static COMMANDS: &[CommandSpec] = &[CommandSpec::new("inspect.clearance", "Clearance", crate::checked!("inspect.clearance", clearance))+ .icon("interference")+ .noundo()+ .contract(&CONTRACT)+ .output(output_schema_for::<ClearanceReply>)+ .params("bodies?: [names] (default: every solid body, in world placement, but those in `against`; mesh bodies are not measured); against?: [names] (only pairs with one body in `bodies` and the other here); \min_volume?: mm³ (default 0.01: smaller overlaps count as contact); clearance?: mm (default 0: report pairs closer than this); \nearest?: n (each body of `bodies` gets its n nearest others); skip_within?: \"occurrence\" (pairs of bodies of one occurrence) | \@@ -34,10 +45,6 @@ pub static COMMANDS: &[CommandSpec] = &[CommandSpec::new("inspect.clearance", "Cconst MAX_BODIES: usize = 20_000;/// Most pairs whose grown boxes meet that one call measures.const MAX_PAIRS: usize = 200_000;-/// Most neighbours a body's `nearest` list holds.-const MAX_NEAREST: usize = 1000;-/// Largest clearance (mm).-const MAX_CLEARANCE: f64 = 1e6;#[derive(Clone, Copy, PartialEq, Eq)]enum SkipWithin {@@ -261,48 +268,56 @@ fn clearance(s: &mut Session, p: &Value) -> Result<Value> {for k in ["bodies", "against"] {asked.extend(string_list(cmd, p, k)?);}- let mut unchecked: Vec<Value> = mesh_bodies+ let mut unchecked: Vec<Unchecked> = mesh_bodies.iter().filter(|b| p.get("bodies").is_none_or(Value::is_null) || asked.contains(&b.name))- .map(|b| json!({"a": b.name, "b": null, "reason": super::interference::MESH_NOT_CHECKED}))+ .map(|b| Unchecked { a: b.name.clone(), b: None, reason: super::interference::MESH_NOT_CHECKED.to_string() }).collect();let name = |i: usize| solid.get(i).map_or("", |b| b.name.as_str());+ let pair = |i: usize, j: usize, reason: String| Unchecked { a: name(i).to_string(), b: Some(name(j).to_string()), reason };for (&(i, j), r) in close.iter().zip(results) {let r = match r {Ok(r) => r,Err(e) => {- unchecked.push(json!({"a": name(i), "b": name(j), "reason": e.to_string()}));+ unchecked.push(pair(i, j, e.to_string()));continue;}};if let Some(reason) = r.unchecked {- unchecked.push(json!({"a": name(i), "b": name(j), "reason": reason}));+ unchecked.push(pair(i, j, reason));continue;}if let Some((volume, area, bbox, center)) = r.overlap&& volume >= min_volume{- overlaps.push(json!({"a": name(i), "b": name(j), "volume_mm3": volume, "area_mm2": area,- "bbox": {"min": bbox.min, "max": bbox.max}, "center": center}));+ overlaps.push(Overlap {+ a: name(i).to_string(),+ b: name(j).to_string(),+ volume_mm3: volume,+ area_mm2: area,+ bbox: OverlapBounds { min: bbox.min.into(), max: bbox.max.into() },+ center: center.into(),+ });known.insert((i, j), 0.0);continue;}let Some(d) = r.distance else { continue };known.insert((i, j), d.distance);if d.distance < gap {- let mut e = json!({"a": name(i), "b": name(j), "distance_mm": d.distance, "from": d.from, "to": d.to});- if let Some((v, ..)) = r.overlap.filter(|o| o.0 > 0.0) {- e["overlap_mm3"] = json!(v);- }- if !d.exact {- e["exact"] = json!(false);- }- near.push(e);+ near.push(NearPair {+ a: name(i).to_string(),+ b: name(j).to_string(),+ distance_mm: d.distance,+ from: d.from.into(),+ to: d.to.into(),+ overlap_mm3: r.overlap.filter(|o| o.0 > 0.0).map(|o| o.0),+ exact: (!d.exact).then_some(false),+ });}}- near.sort_by(|x, y| x["distance_mm"].as_f64().unwrap_or(0.0).total_cmp(&y["distance_mm"].as_f64().unwrap_or(0.0)));+ near.sort_by(|x, y| x.distance_mm.total_cmp(&y.distance_mm));- let mut nearest_out = serde_json::Map::new();+ let mut nearest_out = BTreeMap::new();if nearest > 0 {let lists = nearest_lists(&subjects, n, nearest, &boxes, &allowed, &mut known, |pairs| {solidcraft_kernel::map_with_local_pools(pairs, usize::MAX, |&(i, j)| {@@ -311,23 +326,25 @@ fn clearance(s: &mut Session, p: &Value) -> Result<Value> {})});for (i, list) in lists {- let rows: Vec<Value> = list.iter().map(|&(j, d)| json!({"body": name(j), "distance_mm": d})).collect();- nearest_out.insert(name(i).to_string(), Value::Array(rows));+ let rows = list.iter().map(|&(j, d)| Neighbour { body: name(j).to_string(), distance_mm: d }).collect();+ nearest_out.insert(name(i).to_string(), rows);}}- Ok(json!({- "overlaps": overlaps,- "near": near,- "nearest": nearest_out,- "unchecked": unchecked,- "bodies": subjects.len(),- "pairs_checked": close.len(),- "pairs_reused": reused,- "pairs_pruned": total.saturating_sub(close.len()),- "truncated": truncated > 0,- "ms": started.elapsed().as_secs_f64() * 1000.0,- }))+ let reply = ClearanceReply {+ overlaps,+ near,+ nearest: nearest_out,+ unchecked,+ bodies: subjects.len(),+ pairs_checked: close.len(),+ pairs_reused: reused,+ pairs_pruned: total.saturating_sub(close.len()),+ truncated: truncated > 0,+ ms: started.elapsed().as_secs_f64() * 1000.0,+ param_warnings: Vec::new(),+ };+ serde_json::to_value(reply).map_err(|e| bad(cmd, e.to_string()))}/// One pair: its overlap when the meshes meet or one holds the other, otherwise its distancediff --git a/crates/engine/src/schema/clearance.rs b/crates/engine/src/schema/clearance.rsnew file mode 100644index 0000000000..f5e8ca1864--- /dev/null+++ b/crates/engine/src/schema/clearance.rs@@ -0,0 +1,197 @@+//! Contract and result types for `inspect.clearance` in `cmd/clearance.rs` (#11051).++use std::borrow::Cow;+use std::collections::BTreeMap;++use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};+use serde::de::Error as _;+use serde::{Deserialize, Deserializer, Serialize};+use serde_json::Value;++use super::check::whole;+use super::types::StringList;+use crate::params;++/// Most neighbours a body's `nearest` list holds.+pub const MAX_NEAREST: usize = 1000;+/// Largest clearance (mm).+pub const MAX_CLEARANCE: f64 = 1e6;++/// Find the solid bodies that overlap, and those closer than `clearance`, in world placement.+/// Distances are measured on the exact faces and edges; the meshes only rule pairs out. Mesh+/// bodies aren't measured: each is listed in `unchecked`.+#[derive(Debug, Deserialize, JsonSchema)]+#[schemars(deny_unknown_fields)]+pub struct ClearanceParams {+ /// The bodies to check (default: every solid body but those in `against`).+ #[serde(default)]+ pub bodies: Option<StringList>,+ /// Only pairs with one body in `bodies` and the other here.+ #[serde(default)]+ pub against: Option<StringList>,+ /// Smaller overlaps count as contact, in mm³ (default 0.01).+ #[serde(default, deserialize_with = "min_volume")]+ #[schemars(schema_with = "min_volume_schema")]+ pub min_volume: Option<f64>,+ /// Report pairs closer than this, in mm: 0 to 1 000 000 (default 0).+ #[serde(default, deserialize_with = "clearance")]+ #[schemars(schema_with = "clearance_schema")]+ pub clearance: Option<f64>,+ /// A gap below this is contact, 0, in mm: 0 to 1 (default 1e-6).+ #[serde(default, deserialize_with = "tolerance")]+ #[schemars(schema_with = "tolerance_schema")]+ pub tolerance: Option<f64>,+ /// Each body of `bodies` gets its this many nearest others, 0 to 1000 (default 0); a+ /// fraction is rounded down.+ #[serde(default, deserialize_with = "nearest")]+ #[schemars(schema_with = "nearest_schema")]+ pub nearest: Option<f64>,+ #[serde(default)]+ pub skip_within: Option<SkipWithin>,+}++/// A number from 0 to `max`, read as the handler reads it (`params::num`: finite, under 1e9 in+/// size), with its message; `null` is the default.+macro_rules! up_to {+ ($read:ident, $schema:ident, $key:literal, $max:expr) => {+ fn $read<'de, D: Deserializer<'de>>(d: D) -> Result<Option<f64>, D::Error> {+ match Value::deserialize(d)? {+ Value::Null => Ok(None),+ v => v+ .as_f64()+ .and_then(params::finite)+ .filter(|x| (0.0..=$max).contains(x))+ .map(Some)+ .ok_or_else(|| D::Error::custom(whole(format!("`{}` must be a number from 0 to {}", $key, $max)))),+ }+ }++ fn $schema(_: &mut SchemaGenerator) -> Schema {+ json_schema!({"type": ["number", "null"], "minimum": 0, "maximum": f64::min($max, 1e9), "exclusiveMaximum": 1e9})+ }+ };+}++up_to!(min_volume, min_volume_schema, "min_volume", f64::MAX);+up_to!(clearance, clearance_schema, "clearance", MAX_CLEARANCE);+up_to!(tolerance, tolerance_schema, "tolerance", 1.0);+up_to!(nearest, nearest_schema, "nearest", MAX_NEAREST as f64);++/// Pairs not to check: of bodies of one occurrence (`occurrence`), or inside one placed+/// component, its subcomponents included (`component`). `null` checks every pair.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum SkipWithin {+ Occurrence,+ Component,+}++impl<'de> Deserialize<'de> for SkipWithin {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ match Value::deserialize(d)?.as_str() {+ Some("occurrence") => Ok(SkipWithin::Occurrence),+ Some("component") => Ok(SkipWithin::Component),+ _ => Err(D::Error::custom(whole("`skip_within` must be \"occurrence\", \"component\" or null"))),+ }+ }+}++impl JsonSchema for SkipWithin {+ fn schema_name() -> Cow<'static, str> {+ "SkipWithin".into()+ }+ fn inline_schema() -> bool {+ true+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ json_schema!({+ "description": "Pairs not to check: of bodies of one occurrence (`occurrence`), or inside one placed component, its subcomponents included (`component`). null checks every pair.",+ "enum": ["occurrence", "component", null]+ })+ }+}++/// What `inspect.clearance` returns.+#[derive(Debug, Serialize, JsonSchema)]+pub struct Clearance {+ /// Pairs that share at least `min_volume`.+ pub overlaps: Vec<Overlap>,+ /// Pairs closer than `clearance`, nearest first; a pair in contact is at 0.+ pub near: Vec<NearPair>,+ /// With `nearest`: each body of `bodies`, with its nearest others.+ pub nearest: BTreeMap<String, Vec<Neighbour>>,+ /// Pairs whose overlap couldn't be worked out, and each mesh body, which isn't measured+ /// (`b` is then `null`).+ pub unchecked: Vec<Unchecked>,+ /// How many solid bodies were checked.+ pub bodies: usize,+ pub pairs_checked: usize,+ /// Of those, the pairs measured by an earlier call: neither body changed or moved since.+ pub pairs_reused: usize,+ /// Pairs ruled out by their boxes.+ pub pairs_pruned: usize,+ /// Whether there were more pairs than one call measures.+ pub truncated: bool,+ /// How long it took (ms).+ pub ms: f64,+ /// In the warn parameter-check mode: what the call's parameters got wrong.+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ pub param_warnings: Vec<String>,+}++/// Two bodies that overlap.+#[derive(Debug, Serialize, JsonSchema)]+pub struct Overlap {+ pub a: String,+ pub b: String,+ /// The volume they share (mm³).+ pub volume_mm3: f64,+ /// The area of the shared volume's surface (mm²).+ pub area_mm2: f64,+ pub bbox: OverlapBounds,+ pub center: [f64; 3],+}++/// A box, by its corners.+#[derive(Debug, Serialize, JsonSchema)]+pub struct OverlapBounds {+ pub min: [f64; 3],+ pub max: [f64; 3],+}++/// Two bodies closer than `clearance`.+#[derive(Debug, Serialize, JsonSchema)]+pub struct NearPair {+ pub a: String,+ pub b: String,+ pub distance_mm: f64,+ /// The nearest point on `a`.+ pub from: [f64; 3],+ /// The nearest point on `b`.+ pub to: [f64; 3],+ /// For a contact: the volume they share, below `min_volume` (mm³).+ #[serde(skip_serializing_if = "Option::is_none")]+ pub overlap_mm3: Option<f64>,+ /// `false` when measured on the meshes; absent when measured on the exact faces and edges.+ #[serde(skip_serializing_if = "Option::is_none")]+ pub exact: Option<bool>,+}++/// One of a body's nearest others.+#[derive(Debug, Serialize, JsonSchema)]+pub struct Neighbour {+ pub body: String,+ pub distance_mm: f64,+}++/// A pair, or a mesh body, that wasn't measured.+#[derive(Debug, Serialize, JsonSchema)]+pub struct Unchecked {+ pub a: String,+ /// The other body; `null` for a mesh body.+ pub b: Option<String>,+ pub reason: String,+}++#[cfg(test)]+#[path = "clearance_tests.rs"]+mod tests;diff --git a/crates/engine/src/schema/clearance_tests.rs b/crates/engine/src/schema/clearance_tests.rsnew file mode 100644index 0000000000..edce0c2058--- /dev/null+++ b/crates/engine/src/schema/clearance_tests.rs@@ -0,0 +1,62 @@+use serde_json::{Value, json};++use super::{Clearance, ClearanceParams};+use crate::Session;+use crate::schema::tests::{assert_keys, assert_strict_keeps_todays_errors, conforms};+use crate::schema::{ParamCheck, input_schema_for, output_schema_for};++fn run(s: &mut Session, id: &str, p: Value) -> Value {+ s.execute(id, &p).unwrap_or_else(|e| panic!("{id} {p}: {e}"))+}++#[test]+fn schemas_and_the_key_check_agree() {+ assert_keys(input_schema_for::<ClearanceParams>(), &["against", "bodies", "clearance", "min_volume", "nearest", "skip_within", "tolerance"]);+}++/// The handler reads the numbers and `skip_within` before the bodies, so each of these fails+/// the same way on a design with no bodies.+#[test]+fn strict_keeps_todays_errors() {+ assert_strict_keeps_todays_errors(&[+ ("inspect.clearance", json!({"min_volume": -1})),+ ("inspect.clearance", json!({"min_volume": "x"})),+ ("inspect.clearance", json!({"min_volume": 2e9})),+ ("inspect.clearance", json!({"clearance": 2e6})),+ ("inspect.clearance", json!({"tolerance": 2})),+ ("inspect.clearance", json!({"nearest": 1001})),+ ("inspect.clearance", json!({"skip_within": "x"})),+ ("inspect.clearance", json!({"skip_within": 5})),+ ("inspect.clearance", json!({"bodies": ["Nope"]})),+ ("inspect.clearance", json!({"against": "Nope"})),+ ]);+}++/// #11051: a clearance check replies as its output schema says, in Warn without warnings for+/// good calls and with them for a misspelt key: two overlapping boxes and a third 2 mm away,+/// checked with every key, and with `against` alone.+#[test]+fn a_clearance_check_replies_with_its_schema() {+ let schema = output_schema_for::<Clearance>();+ let matches = |r: &Value, warned: bool| {+ let schema = schema.as_value();+ assert!(conforms(schema, schema, r), "{r} doesn't match {schema}");+ assert_eq!(r.get("param_warnings").is_some(), warned, "{r}");+ };+ let mut s = Session { param_check: ParamCheck::Warn, ..Session::default() };+ run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10, "body_name": "A"}));+ run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10, "corner": [5, 5, 5], "body_name": "B", "operation": "new"}));+ run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10, "corner": [12, -20, 0], "body_name": "C", "operation": "new"}));+ let r = run(&mut s, "inspect.clearance", json!({}));+ matches(&r, false);+ assert_eq!(r["overlaps"].as_array().map(Vec::len), Some(1), "{r}");+ let r = run(+ &mut s,+ "inspect.clearance",+ json!({"bodies": ["A", "B"], "against": "C", "min_volume": 0.01, "clearance": 30, "tolerance": 1e-6, "nearest": 2, "skip_within": "occurrence"}),+ );+ matches(&r, false);+ assert!(r["near"].as_array().is_some_and(|n| !n.is_empty()) && r["nearest"]["A"].is_array(), "{r}");+ matches(&run(&mut s, "inspect.clearance", json!({"against": ["A"], "skip_within": null})), false);+ matches(&run(&mut s, "inspect.clearance", json!({"clearence": 3})), true);+}diff --git a/crates/engine/src/schema/mod.rs b/crates/engine/src/schema/mod.rsindex 2981f17f74..546cc80d87 100644--- a/crates/engine/src/schema/mod.rs+++ b/crates/engine/src/schema/mod.rs@@ -57,6 +57,7 @@ mod tests;pub mod appearance;pub mod bom;pub mod browser;+pub mod clearance;pub mod component;pub mod config;pub mod construct;diff --git a/crates/engine/src/schema/unconverted.txt b/crates/engine/src/schema/unconverted.txtindex a1d80a6892..46d93a58a3 100644--- a/crates/engine/src/schema/unconverted.txt+++ b/crates/engine/src/schema/unconverted.txt@@ -78,7 +78,6 @@ frame.memberframe.profile.insertframe.profile.listframe.profile.properties-inspect.clearanceinspect.compareinspect.interferenceinspect.measure