SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Assembly: place an occurrence or an inserted STEP file by a matrix (#1890) (#1901)
NOWN-DEV57d210130c5f
diff --git a/crates/engine/src/cmd/component.rs b/crates/engine/src/cmd/component.rsindex 76733d610f..847737fc41 100644--- a/crates/engine/src/cmd/component.rs+++ b/crates/engine/src/cmd/component.rs@@ -11,6 +11,8 @@ use super::CommandSpec;use crate::params::{bad, bool_, str_, string_list, vec3};use crate::{Result, Session};+#[path = "component_matrix.rs"]+pub(super) mod matrix;#[path = "component_properties.rs"]pub(super) mod properties;#[path = "component_transfer.rs"]@@ -52,7 +54,7 @@ pub static COMMANDS: &[CommandSpec] = &[.params("component (or occurrence): what to place again; path?: validates selected occurrence; parent?: component (default: the same parent); translate?: [x,y,z]. Copies the selected effective transform, including pending moves"),CommandSpec::new("component.paste_new", "Paste New", paste_new).icon("paste").params("component: independently copy its nested definition graph and history, materials and styles; occurrence?, path?: selected source placement; translate?: [x,y,z]. Reassigned external bodies become base geometry; retained external links and omitted boundary joints are reported"),CommandSpec::new("occurrence.move", "Move Occurrence", move_occurrence).icon("move")- .params("occurrence; path?: exact placement; space?: local|world (default local); translate?: [x,y,z]; axis?: [x,y,z], angle?: radians or \"30 deg\", origin?: [x,y,z]; capture?: bool (default true; false keeps it pending until Capture Position). Nested occurrence definitions remain shared"),+ .params("occurrence; path?: exact placement; space?: local|world (default local); translate?: [x,y,z]; axis?: [x,y,z], angle?: radians or \"30 deg\", origin?: [x,y,z]; matrix?: [12 or 16 numbers] (instead of translate/axis/angle/origin: a rigid move as a row-major 3x4 rotation-and-translation or 4x4 matrix, flat or as rows; one that is a rotation only up to rounding is orthonormalised, a scale, shear or mirror is refused); tolerance?: largest accepted |RᵀR − I| (default 1e-9, at most 1e-3); capture?: bool (default true; false keeps it pending until Capture Position). Nested occurrence definitions remain shared"),CommandSpec::new("occurrence.ground", "Ground", ground).icon("ground").params("occurrence; grounded?: bool (default toggles)"),CommandSpec::new("component.capture_position", "Capture Position", capture).at("SOLID", "POSITION").icon("capture").params("keeps pending occurrence moves"),CommandSpec::new("component.revert_position", "Revert Position", revert).at("SOLID", "POSITION").icon("revert").noundo().params("occurrences?: [ids] (default all); drops selected pending occurrence moves"),@@ -416,21 +418,28 @@ fn move_occurrence(s: &mut Session, p: &Value) -> Result<Value> {let name = s.doc.components.iter().find(|c| c.id == group).map(|c| c.name.clone()).unwrap_or_default();return Err(bad(cmd, format!("{} is held in {name} by a rigid group: move {name}, or Unlock Contents (component.unlock) first", o.name)));}- let t = move_vector(p, "translate", Vec3::ZERO, true, cmd)?;- let axis = move_vector(p, "axis", Vec3::Z, false, cmd)?;- let angle = match p.get("angle") {- Some(Value::String(e)) => s.doc.eval(e, solidcraft_doc::expr::Kind::Angle).map_err(|e| bad(cmd, e.to_string()))?,- None => 0.0,- Some(value) => value.as_f64().ok_or_else(|| bad(cmd, "angle must be a number or angle expression"))?,+ let delta = if let Some(m) = p.get("matrix") {+ if let Some(k) = ["translate", "axis", "angle", "origin"].into_iter().find(|k| p.get(*k).is_some()) {+ return Err(bad(cmd, format!("give either matrix or {k}, not both")));+ }+ matrix::rigid(m, matrix::tolerance(p, cmd)?, cmd)?+ } else {+ let t = move_vector(p, "translate", Vec3::ZERO, true, cmd)?;+ let axis = move_vector(p, "axis", Vec3::Z, false, cmd)?;+ let angle = match p.get("angle") {+ Some(Value::String(e)) => s.doc.eval(e, solidcraft_doc::expr::Kind::Angle).map_err(|e| bad(cmd, e.to_string()))?,+ None => 0.0,+ Some(value) => value.as_f64().ok_or_else(|| bad(cmd, "angle must be a number or angle expression"))?,+ };+ if !(t.is_finite() && axis.is_finite() && angle.is_finite()) {+ return Err(bad(cmd, "non-finite move"));+ }+ if angle != 0.0 && axis.normalized().is_none() {+ return Err(bad(cmd, "rotation axis must have a finite nonzero length"));+ }+ let origin = move_vector(p, "origin", Vec3::ZERO, true, cmd)?;+ solidcraft_doc::rigid(t, origin, axis, angle)};- if !(t.is_finite() && axis.is_finite() && angle.is_finite()) {- return Err(bad(cmd, "non-finite move"));- }- if angle != 0.0 && axis.normalized().is_none() {- return Err(bad(cmd, "rotation axis must have a finite nonzero length"));- }- let origin = move_vector(p, "origin", Vec3::ZERO, true, cmd)?;- let delta = solidcraft_doc::rigid(t, origin, axis, angle);let space = match p.get("space") {None => "local",Some(Value::String(space)) => space.as_str(),diff --git a/crates/engine/src/cmd/component_matrix.rs b/crates/engine/src/cmd/component_matrix.rsnew file mode 100644index 0000000000..b005c820c0--- /dev/null+++ b/crates/engine/src/cmd/component_matrix.rs@@ -0,0 +1,121 @@+//! Placement given as a matrix: a script's 3×4 (rotation rows and a translation column) or+//! 4×4 transform, read as a rigid move. A rotation that is one only up to rounding is+//! orthonormalised; a scale, shear or mirror is refused with the reason (a mirror is+//! `solid.mirror`'s, not a placement's).++use serde_json::Value;+use solidcraft_doc::{IDENTITY, Mat};++use crate::Result;+use crate::params::bad;++/// The default largest departure from a rotation a matrix may show: |RᵀR − I| per entry.+pub const TOLERANCE: f64 = 1e-9;+/// The loosest tolerance a caller may ask for.+const MAX_TOLERANCE: f64 = 1e-3;++/// The `tolerance` parameter: the default, or a finite positive number no looser than 1e-3.+pub fn tolerance(p: &Value, cmd: &str) -> Result<f64> {+ match p.get("tolerance") {+ None | Some(Value::Null) => Ok(TOLERANCE),+ Some(v) => v+ .as_f64()+ .filter(|t| t.is_finite() && *t > 0.0 && *t <= MAX_TOLERANCE)+ .ok_or_else(|| bad(cmd, format!("tolerance must be a number above 0 and at most {MAX_TOLERANCE}"))),+ }+}++/// Read `matrix` as a rigid transform. It is row-major: 12 numbers (three rows of rotation+/// and translation, `[r00, r01, r02, tx, r10, …, tz]`) or 16 (a fourth row `0, 0, 0, 1`), flat+/// or as rows.+pub fn rigid(v: &Value, tolerance: f64, cmd: &str) -> Result<Mat> {+ let numbers = numbers(v).ok_or_else(|| bad(cmd, "matrix must be 12 numbers (3x4, row by row) or 16 (4x4), flat or as rows"))?;+ if numbers.iter().any(|x| !x.is_finite()) {+ return Err(bad(cmd, "matrix must contain finite numbers"));+ }+ let at = |row: usize, col: usize| numbers.get(row * 4 + col).copied().unwrap_or(0.0);+ if numbers.len() == 16 {+ let last = [at(3, 0), at(3, 1), at(3, 2), at(3, 3) - 1.0];+ if last.iter().any(|x| x.abs() > tolerance) {+ return Err(bad(cmd, "matrix is not affine: its fourth row must be 0, 0, 0, 1 (a projective transform is not a placement)"));+ }+ }+ if (0..3).any(|r| at(r, 3).abs() > 1e9) {+ return Err(bad(cmd, "matrix translation exceeds supported numeric range"));+ }+ // r[row][col], then |RᵀR − I| measures how far it is from a rotation.+ let r: [[f64; 3]; 3] = std::array::from_fn(|row| std::array::from_fn(|col| at(row, col)));+ let deviation = (0..3)+ .flat_map(|i| (0..3).map(move |j| (i, j)))+ .map(|(i, j)| {+ let dot: f64 = (0..3).map(|k| r[k][i] * r[k][j]).sum();+ (dot - if i == j { 1.0 } else { 0.0 }).abs()+ })+ .fold(0.0, f64::max);+ let det = r[0][0] * (r[1][1] * r[2][2] - r[1][2] * r[2][1]) - r[0][1] * (r[1][0] * r[2][2] - r[1][2] * r[2][0])+ + r[0][2] * (r[1][0] * r[2][1] - r[1][1] * r[2][0]);+ if det < 0.0 {+ return Err(bad(cmd, "matrix mirrors (its determinant is negative): a placement only turns and moves; mirror bodies with solid.mirror"));+ }+ if !deviation.is_finite() || deviation > tolerance {+ return Err(bad(+ cmd,+ format!("matrix is not rigid: it scales or shears by {deviation:.3e} (|RᵀR − I|), above the tolerance {tolerance:.0e}"),+ ));+ }+ let rot = orthonormal(r);+ let mut m = IDENTITY;+ for (col, column) in m.iter_mut().enumerate().take(3) {+ for (row, cell) in column.iter_mut().enumerate().take(3) {+ *cell = rot[row][col];+ }+ }+ m[3] = [at(0, 3), at(1, 3), at(2, 3), 1.0];+ Ok(m)+}++/// The matrix's numbers, row by row: 12 or 16 of them, flat or nested as 3 or 4 rows of 4.+fn numbers(v: &Value) -> Option<Vec<f64>> {+ let a = v.as_array()?;+ let flat: Vec<f64> = if a.iter().all(Value::is_array) {+ if !matches!(a.len(), 3 | 4) {+ return None;+ }+ let mut out = Vec::with_capacity(16);+ for row in a {+ let row = row.as_array().filter(|r| r.len() == 4)?;+ for x in row {+ out.push(x.as_f64()?);+ }+ }+ out+ } else {+ a.iter().map(Value::as_f64).collect::<Option<_>>()?+ };+ matches!(flat.len(), 12 | 16).then_some(flat)+}++/// The rotation nearest to `r` (its polar factor), by Newton's iteration R ← (R + R⁻ᵀ) / 2,+/// which converges quadratically from a near-rotation; a few rounds reach machine precision.+fn orthonormal(mut r: [[f64; 3]; 3]) -> [[f64; 3]; 3] {+ for _ in 0..4 {+ let Some(inv_t) = inverse_transpose(&r) else { break };+ for (row, inv_row) in r.iter_mut().zip(inv_t) {+ for (x, y) in row.iter_mut().zip(inv_row) {+ *x = 0.5 * (*x + y);+ }+ }+ }+ r+}++/// (R⁻¹)ᵀ: the cofactor matrix over the determinant.+fn inverse_transpose(r: &[[f64; 3]; 3]) -> Option<[[f64; 3]; 3]> {+ let a = |i: usize, j: usize| r[i % 3][j % 3];+ let cof: [[f64; 3]; 3] = std::array::from_fn(|i| std::array::from_fn(|j| a(i + 1, j + 1) * a(i + 2, j + 2) - a(i + 1, j + 2) * a(i + 2, j + 1)));+ let det: f64 = (0..3).map(|j| r[0][j] * cof[0][j]).sum();+ if !det.is_finite() || det.abs() < 1e-12 {+ return None;+ }+ Some(cof.map(|row| row.map(|x| x / det)))+}diff --git a/crates/engine/src/cmd/file.rs b/crates/engine/src/cmd/file.rsindex 3ccca6b5bc..efc83fda11 100644--- a/crates/engine/src/cmd/file.rs+++ b/crates/engine/src/cmd/file.rs@@ -24,7 +24,7 @@ pub static COMMANDS: &[CommandSpec] = &[CommandSpec::new("file.insert_step", "Insert STEP", insert_step).at("SOLID", "INSERT").icon("import")- .params("path: STEP, IGES, FreeCAD .FCStd or Rhino .3dm file (its bodies join the design as an Import base feature in a new component named after the file, placed in the active component; an assembly's products become nested components, a repeated part one component with an occurrence per placement, all held as one rigid group until component.unlock → component, component_name, occurrence, subcomponents?, rigid_joints?); name? (the feature's and the component's); up?: z|y (default z: the file's axes are kept; y: the file has Y up, so the import's component is turned a quarter turn about X, Y becoming Z → stand_up: its occurrence); names?: solid|product|instance (what the bodies are named after: the solid's own name, else the product's (default); the name of the product (part) that holds the body; the name of the assembly occurrence (instance), else the product's)"),+ .params("path: STEP, IGES, FreeCAD .FCStd or Rhino .3dm file (its bodies join the design as an Import base feature in a new component named after the file, placed in the active component; an assembly's products become nested components, a repeated part one component with an occurrence per placement, all held as one rigid group until component.unlock → component, component_name, occurrence, subcomponents?, rigid_joints?); name? (the feature's and the component's); up?: z|y (default z: the file's axes are kept; y: the file has Y up, so the import's component is turned a quarter turn about X, Y becoming Z → stand_up: its occurrence); names?: solid|product|instance (what the bodies are named after: the solid's own name, else the product's (default); the name of the product (part) that holds the body; the name of the assembly occurrence (instance), else the product's); matrix?: [12 or 16 numbers] (where the new component's occurrence sits in the active component, after `up`: a rigid row-major 3x4 rotation-and-translation or 4x4 matrix, flat or as rows, as occurrence.move takes it; a scale, shear or mirror is refused before the file is read); tolerance? (see occurrence.move)"),CommandSpec::new("file.insert_mesh", "Insert Mesh", insert_mesh).at("SOLID", "INSERT").icon("import")@@ -218,7 +218,20 @@ fn insert_step(s: &mut Session, p: &Value) -> Result<Value> {return Err(bad(cmd, "only STEP, IGES, FreeCAD and Rhino files (.step, .stp, .igs, .iges, .fcstd, .3dm) can be inserted"));}let options = step_options(p, cmd)?;- add_step(s, path, str_(p, "name"), &options)+ let placement = match p.get("matrix") {+ None | Some(Value::Null) => None,+ Some(m) => Some(super::component::matrix::rigid(m, super::component::matrix::tolerance(p, cmd)?, cmd)?),+ };+ let mut out = add_step(s, path, str_(p, "name"), &options)?;+ if let Some(m) = placement {+ let occ = out["occurrence"].as_u64().ok_or_else(|| EngineError::Other("the import has no placement to move".into()))?;+ if let Some(o) = s.doc_mut().occurrences.iter_mut().find(|o| o.id == occ) {+ o.transform = solidcraft_doc::mat_mul(&m, &o.transform);+ out["transform"] = json!(o.transform);+ }+ s.refresh();+ }+ Ok(out)}fn open(s: &mut Session, p: &Value) -> Result<Value> {diff --git a/crates/engine/src/cmd/occurrence_tests.rs b/crates/engine/src/cmd/occurrence_tests.rsindex c88c7f8c22..310a6e8f1e 100644--- a/crates/engine/src/cmd/occurrence_tests.rs+++ b/crates/engine/src/cmd/occurrence_tests.rs@@ -580,3 +580,85 @@ fn compact_component_list_counts_and_skips_identity_transforms() {// Body names on request.assert_eq!(block(&run(&mut s, "component.list", json!({"compact": true, "bodies": true})))["bodies"], json!(["Cube"]));}++/// A script's 3x4 placement matrix (rotation rows, then the translation column) moves an+/// occurrence exactly as the same turn and move given as an axis, an angle and a translation.+#[test]+fn matrix_move_turns_a_quarter_and_moves() {+ let mut s = Session::default();+ let (_, occ) = created(&mut s, "Block");+ run(&mut s, "solid.box", json!({"length": 2, "width": 1, "height": 1}));+ // 90 degrees about Z, then (10, 20, 30): (x, y, z) goes to (10 - y, 20 + x, 30 + z).+ let r = run(&mut s, "occurrence.move", json!({"occurrence": occ, "matrix": [0, -1, 0, 10, 1, 0, 0, 20, 0, 0, 1, 30]}));+ let t = &r["transform"];+ for (col, expected) in [[0.0, 1.0, 0.0, 0.0], [-1.0, 0.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [10.0, 20.0, 30.0, 1.0]].iter().enumerate() {+ for (row, x) in expected.iter().enumerate() {+ near(&t[col][row], *x);+ }+ }+ // The box's centre (1, 0.5, 0.5) lands at (9.5, 21, 30.5).+ let props = run(&mut s, "occurrence.properties", json!({"occurrence": occ}));+ for (i, x) in [9.5, 21.0, 30.5].into_iter().enumerate() {+ near(&props["total"]["center_of_mass"][i], x);+ }+ // The same as axis/angle/translate, and the 4x4 form as rows says the same.+ let mut other = Session::default();+ let (_, o2) = created(&mut other, "Block");+ let r2 = run(&mut other, "occurrence.move", json!({"occurrence": o2, "axis": [0, 0, 1], "angle": "90 deg", "translate": [10, 20, 30]}));+ let mut rows = Session::default();+ let (_, o3) = created(&mut rows, "Block");+ let r3 = run(&mut rows, "occurrence.move", json!({"occurrence": o3, "matrix": [[0, -1, 0, 10], [1, 0, 0, 20], [0, 0, 1, 30], [0, 0, 0, 1]]}));+ for col in 0..4 {+ for row in 0..4 {+ near(&r2["transform"][col][row], t[col][row].as_f64().unwrap());+ near(&r3["transform"][col][row], t[col][row].as_f64().unwrap());+ }+ }+}++/// A rotation that is one only up to rounding is orthonormalised; a scale, a shear or a mirror+/// is refused with the reason, and the occurrence stays where it was.+#[test]+fn matrix_move_orthonormalises_rounding_and_refuses_what_is_not_rigid() {+ let mut s = Session::default();+ let (_, occ) = created(&mut s, "Block");+ let (sin, cos) = 30f64.to_radians().sin_cos();+ let e = 3e-10;+ let nearly = json!([cos + e, -sin, 0, 5, sin, cos - e, e, 0, 0, -e, 1.0 + e, 0]);+ let r = run(&mut s, "occurrence.move", json!({"occurrence": occ, "matrix": nearly, "space": "world"}));+ let m: solidcraft_doc::Mat = serde_json::from_value(r["transform"].clone()).unwrap();+ for i in 0..3 {+ for j in 0..3 {+ let dot: f64 = (0..3).map(|k| m[i][k] * m[j][k]).sum();+ assert!((dot - f64::from(u8::from(i == j))).abs() < 1e-15, "column {i}·{j} = {dot}");+ }+ }+ assert!((m[0][0] - cos).abs() < 1e-9 && (m[0][1] - sin).abs() < 1e-9 && (m[3][0] - 5.0).abs() < 1e-12, "{m:?}");++ let before = s.doc.occurrences.iter().find(|o| o.id == occ).unwrap().transform;+ let refused = |s: &mut Session, p: Value| s.execute("occurrence.move", &p).unwrap_err().to_string();+ let scaled = refused(&mut s, json!({"occurrence": occ, "matrix": [1.001, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]}));+ assert!(scaled.contains("not rigid") && scaled.contains("2.00"), "{scaled}");+ let sheared = refused(&mut s, json!({"occurrence": occ, "matrix": [1, 0.01, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]}));+ assert!(sheared.contains("not rigid"), "{sheared}");+ let mirrored = refused(&mut s, json!({"occurrence": occ, "matrix": [-1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]}));+ assert!(mirrored.contains("solid.mirror"), "{mirrored}");+ let projective = refused(&mut s, json!({"occurrence": occ, "matrix": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0.5, 0, 0, 1]}));+ assert!(projective.contains("fourth row"), "{projective}");+ // A looser tolerance is the caller's to ask for, up to 1e-3.+ let rounded = json!([0.866, -0.5, 0, 0, 0.5, 0.866, 0, 0, 0, 0, 1, 0]);+ assert!(refused(&mut s, json!({"occurrence": occ, "matrix": rounded})).contains("not rigid"));+ for p in [+ json!({"occurrence": occ, "matrix": rounded, "tolerance": 1}),+ json!({"occurrence": occ, "matrix": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], "translate": [1, 0, 0]}),+ json!({"occurrence": occ, "matrix": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0], "translate": [1, 0, 0]}),+ json!({"occurrence": occ, "matrix": [1, 0, 0, 1e12, 0, 1, 0, 0, 0, 0, 1, 0]}),+ json!({"occurrence": occ, "matrix": [[1, 0, 0, 0], [0, 1, 0, 0]]}),+ json!({"occurrence": occ, "matrix": "identity"}),+ json!({"occurrence": occ, "matrix": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]}),+ ] {+ assert!(s.execute("occurrence.move", &p).is_err(), "{p}");+ }+ assert_eq!(s.doc.occurrences.iter().find(|o| o.id == occ).unwrap().transform, before);+ run(&mut s, "occurrence.move", json!({"occurrence": occ, "matrix": rounded, "tolerance": 1e-3}));+}diff --git a/crates/engine/src/tests/step_import_options.rs b/crates/engine/src/tests/step_import_options.rsindex 435c4d7244..9f59137473 100644--- a/crates/engine/src/tests/step_import_options.rs+++ b/crates/engine/src/tests/step_import_options.rs@@ -202,3 +202,29 @@ fn the_bodies_are_named_after_the_solid_the_product_or_the_instance() {run(&mut again, "solid.move", json!({"bodies": ["Post-1"], "translate": [0, 0, 5]}));assert_eq!(body_names(&again), ["Plate-1", "Post-1"]);}++/// `matrix` places the inserted file's component, after `up`, in the same command (one undo+/// step); a matrix that is not rigid is refused before anything is added.+#[test]+fn a_step_file_can_be_inserted_at_a_matrix() {+ let path = frame_file("matrix");+ let quarter = json!([0, -1, 0, 100, 1, 0, 0, 0, 0, 0, 1, 0]);+ let mut s = Session::default();+ let r = run(&mut s, "file.insert_step", json!({"path": path, "matrix": quarter}));+ // (x, y, z) goes to (100 - y, x, z): the frame (0..40, 0..34, 0..20) spans x 66..100, y 0..40.+ let (lo, hi) = extent(&s);+ assert!(near(lo, [66.0, 0.0, 0.0]) && near(hi, [100.0, 40.0, 20.0]), "{lo:?} {hi:?} {r}");+ assert_eq!(r["transform"][3][0], json!(100.0), "{r}");+ assert_eq!(s.undo.len(), 1);++ // Stood up first ((0..40, -20..0, 0..34)), then turned and moved.+ let mut d = Session::default();+ run(&mut d, "file.insert_step", json!({"path": path, "up": "y", "matrix": quarter}));+ let (lo, hi) = extent(&d);+ assert!(near(lo, [100.0, 0.0, 0.0]) && near(hi, [120.0, 40.0, 34.0]), "{lo:?} {hi:?}");++ let mut d = Session::default();+ let e = d.execute("file.insert_step", &json!({"path": path, "matrix": [2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0]})).unwrap_err().to_string();+ assert!(e.contains("not rigid"), "{e}");+ assert!(d.doc.features.is_empty() && d.doc.occurrences.is_empty());+}