SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Assemblies: mass, centre of mass and inertia per occurrence and rigid group (#9715) (#9717)
PaddleStrokefd5d0e6738ca
diff --git a/assets/locales/pending/assembly-mass-properties.json b/assets/locales/pending/assembly-mass-properties.jsonnew file mode 100644index 0000000000..732b3398ac--- /dev/null+++ b/assets/locales/pending/assembly-mass-properties.json@@ -0,0 +1,32 @@+{+ "en": { "cmd.assembly_mass_properties": "Mass Properties" },+ "ar": { "cmd.assembly_mass_properties": "خصائص الكتلة" },+ "bs": { "cmd.assembly_mass_properties": "Svojstva mase" },+ "cs": { "cmd.assembly_mass_properties": "Hmotnostní vlastnosti" },+ "da": { "cmd.assembly_mass_properties": "Masseegenskaber" },+ "de": { "cmd.assembly_mass_properties": "Masseeigenschaften" },+ "es": { "cmd.assembly_mass_properties": "Propiedades de masa" },+ "fr": { "cmd.assembly_mass_properties": "Propriétés de masse" },+ "gl": { "cmd.assembly_mass_properties": "Propiedades de masa" },+ "he": { "cmd.assembly_mass_properties": "תכונות מסה" },+ "hr": { "cmd.assembly_mass_properties": "Svojstva mase" },+ "hu": { "cmd.assembly_mass_properties": "Tömegjellemzők" },+ "id": { "cmd.assembly_mass_properties": "Properti massa" },+ "it": { "cmd.assembly_mass_properties": "Proprietà di massa" },+ "ja": { "cmd.assembly_mass_properties": "質量特性" },+ "ko": { "cmd.assembly_mass_properties": "질량 특성" },+ "ms": { "cmd.assembly_mass_properties": "Sifat jisim" },+ "nb": { "cmd.assembly_mass_properties": "Masseegenskaper" },+ "nl": { "cmd.assembly_mass_properties": "Massa-eigenschappen" },+ "pl": { "cmd.assembly_mass_properties": "Właściwości masowe" },+ "pt-BR": { "cmd.assembly_mass_properties": "Propriedades de massa" },+ "ro": { "cmd.assembly_mass_properties": "Proprietăți de masă" },+ "ru": { "cmd.assembly_mass_properties": "Массовые характеристики" },+ "sr": { "cmd.assembly_mass_properties": "Својства масе" },+ "sv": { "cmd.assembly_mass_properties": "Massegenskaper" },+ "tr": { "cmd.assembly_mass_properties": "Kütle özellikleri" },+ "uk": { "cmd.assembly_mass_properties": "Масові характеристики" },+ "vi": { "cmd.assembly_mass_properties": "Thuộc tính khối lượng" },+ "zh": { "cmd.assembly_mass_properties": "质量属性" },+ "zh-TW": { "cmd.assembly_mass_properties": "質量屬性" }+}diff --git a/crates/engine/src/cmd/mass_properties.rs b/crates/engine/src/cmd/mass_properties.rsnew file mode 100644index 0000000000..2922ecf339--- /dev/null+++ b/crates/engine/src/cmd/mass_properties.rs@@ -0,0 +1,363 @@+//! Mass, centre of mass and inertia tensor per occurrence and per rigid group (#9715): what a+//! multibody dynamics solver needs of each moving part.+//!+//! Bodies are measured as `component.properties` measures them (docs/assembly-properties.md):+//! volume and centre from the kernel's measurement, the inertia from how the welded export mesh+//! spreads that volume (`solidcraft_geom::inertia`), at the body's material density (the default+//! material's when none is assigned). Each body is measured once however often it is placed;+//! each placement moves its centre and turns its tensor, and an occurrence's bodies combine by+//! the parallel-axis theorem. An open body adds no mass and is counted.+//!+//! Rigid groups are the occurrences that move as one body: those an unsuppressed rigid joint+//! ties together, and a nested occurrence that no joint places with the occurrence it sits in+//! (the joint solver leaves it where its parent puts it). A group holding the design itself or+//! a grounded occurrence is fixed. Occurrences are taken where the joint solver places them, so+//! an occurrence inside a subassembly placed more than once is listed at the subassembly's first+//! placement (a warning says so).++use std::collections::{BTreeMap, HashMap, HashSet};++use serde_json::Value;+use solidcraft_doc::joints::{self, JointKind, MAX_JOINTS};+use solidcraft_doc::{Document, IDENTITY, MAX_PLACEMENTS, Mat, ModelState, apply_point, mat_inverse, mat_mul};+use solidcraft_geom::Vec3;+use solidcraft_geom::inertia::{self, Tensor3};++use super::CommandSpec;+use crate::params::bad;+use crate::schema::mass_properties::{AssemblyMassParams, AssemblyMassResult, BodyMassEntry, MassFrame, OccurrenceMass, RigidGroupMass, RigidMass};+use crate::schema::{TypedContract, output_schema_for};+use crate::{EngineError, Result, Session};++const CMD: &str = "assembly.mass_properties";+const CONTRACT: TypedContract<AssemblyMassParams> = TypedContract::new();++pub static COMMANDS: &[CommandSpec] = &[CommandSpec::new(CMD, "Mass Properties", crate::checked!("assembly.mass_properties", run))+ .icon("measure")+ .noundo()+ .contract(&CONTRACT)+ .output(output_schema_for::<AssemblyMassResult>)+ .params(+ "no parameters → occurrences: [{occurrence (0: the design's own bodies), name, component, path, group, fixed, frame \+ {origin, x, y, z}, bodies: [{name, material, density_g_cm3, closed, volume_mm3, mass_kg}], open_bodies_skipped, mass}], \+ groups: [{group, occurrences, fixed, frame_occurrence, frame, mass}] (occurrences an unsuppressed rigid joint ties \+ together, and a nested occurrence no joint places with its parent; fixed: holds the design or a grounded occurrence), \+ warnings. mass: {mass_kg, center_of_mass_mm (world), center_of_mass_local_mm, inertia_world_kg_mm2, \+ inertia_local_kg_mm2 (about the centre of mass, in world and frame axes)} or null when massless. Read-only; pending \+ moves count; each body at its material's density (the default material's when none is assigned)",+ )];++/// One rigid body's mass properties: mass (kg), centre of mass (mm, world) and the inertia+/// tensor about it (kg·mm², world axes; `None` when a closed body's mesh did not close).+#[derive(Clone, Copy, Debug, Default, PartialEq)]+pub struct MassBody {+ pub mass: f64,+ pub center: Vec3,+ pub inertia: Option<Tensor3>,+}++impl MassBody {+ pub fn is_finite(&self) -> bool {+ self.mass.is_finite() && self.center.is_finite() && self.inertia.is_none_or(|i| i.iter().flatten().all(|x| x.is_finite()))+ }++ /// Bodies taken as one: the masses add, the centre is mass-weighted, and each tensor moves to+ /// the common centre by the parallel-axis theorem. The tensor is `None` when any part's is.+ /// `None` when the total mass is not positive or a value is not finite.+ pub fn combine(parts: &[MassBody]) -> Option<MassBody> {+ let mass: f64 = parts.iter().map(|p| p.mass).sum();+ if !(mass > 0.0 && mass.is_finite()) {+ return None;+ }+ let center = parts.iter().fold(Vec3::ZERO, |acc, p| acc + p.center * p.mass) * (1.0 / mass);+ let inertia = parts.iter().try_fold([[0.0f64; 3]; 3], |sum, p| {+ let i = inertia::shifted(&p.inertia?, p.mass, p.center - center);+ Some([0, 1, 2].map(|r| [0, 1, 2].map(|k| sum[r][k] + i[r][k])))+ });+ let out = MassBody { mass, center, inertia };+ out.is_finite().then_some(out)+ }+}++/// The 3 × 3 linear part of a placement, row by row (`Mat` is column-major).+fn linear(m: &Mat) -> Tensor3 {+ [0, 1, 2].map(|i| [0, 1, 2].map(|j| m[j][i]))+}++fn transpose(a: &Tensor3) -> Tensor3 {+ [0, 1, 2].map(|i| [0, 1, 2].map(|j| a[j][i]))+}++fn det3(a: &Tensor3) -> f64 {+ a[0][0] * (a[1][1] * a[2][2] - a[1][2] * a[2][1]) - a[0][1] * (a[1][0] * a[2][2] - a[1][2] * a[2][0])+ + a[0][2] * (a[1][0] * a[2][1] - a[1][1] * a[2][0])+}++/// The rotation (or reflection) a placement's axes make, when they are orthonormal.+fn rotation(m: &Mat) -> Option<Tensor3> {+ let a = linear(m);+ let ata = inertia::transformed(&[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]], &transpose(&a));+ let ok = (0..3).all(|i| (0..3).all(|j| (ata[i][j] - if i == j { 1.0 } else { 0.0 }).abs() <= 1e-9));+ ok.then_some(a)+}++fn xyz(v: Vec3) -> [f64; 3] {+ [v.x, v.y, v.z]+}++fn frame_of(m: &Mat) -> MassFrame {+ let axis = |k: usize| {+ let v = Vec3::new(m[k][0], m[k][1], m[k][2]);+ let len = v.len();+ xyz(if len > 0.0 && len.is_finite() { v * (1.0 / len) } else { v })+ };+ MassFrame { origin: [m[3][0], m[3][1], m[3][2]], x: axis(0), y: axis(1), z: axis(2) }+}++/// A world [`MassBody`] as the frame `m` sees it.+fn rigid_mass(b: &MassBody, m: &Mat) -> RigidMass {+ let local = mat_inverse(m).map(|inv| apply_point(&inv, b.center)).unwrap_or(b.center);+ RigidMass {+ mass_kg: b.mass,+ center_of_mass_mm: xyz(b.center),+ center_of_mass_local_mm: xyz(local),+ inertia_world_kg_mm2: b.inertia,+ // Rᵀ I R: the world tensor in the frame's axes.+ inertia_local_kg_mm2: b.inertia.zip(rotation(m)).map(|(i, r)| inertia::transformed(&i, &transpose(&r))),+ }+}++/// Union-find over occurrence indices; the lower index roots a group, so the design (index 0)+/// roots its own.+struct Groups(Vec<usize>);++impl Groups {+ fn root(&self, mut i: usize) -> usize {+ // Bounded: each step goes to a lower index.+ for _ in 0..self.0.len() {+ match self.0.get(i) {+ Some(&parent) if parent != i => i = parent,+ _ => break,+ }+ }+ i+ }+ fn join(&mut self, a: usize, b: usize) {+ let (ra, rb) = (self.root(a), self.root(b));+ if let Some(slot) = self.0.get_mut(ra.max(rb)) {+ *slot = ra.min(rb);+ }+ }+}++/// Occurrence ids from the top of the assembly down, as `joints::occurrence_world` walks them.+fn canonical_path(doc: &Document, occ: u64) -> Vec<u64> {+ let mut path = Vec::new();+ let mut cur = doc.occurrences.iter().find(|o| o.id == occ);+ for _ in 0..1000 {+ let Some(o) = cur else { break };+ path.push(o.id);+ if o.parent == 0 {+ break;+ }+ cur = doc.occurrence_of(o.parent);+ }+ path.reverse();+ path+}++fn out_of_range() -> EngineError {+ bad(CMD, "mass properties exceed supported numeric range")+}++impl Session {+ /// Mass, centre of mass and inertia of every occurrence and rigid group of the design, as+ /// `assembly.mass_properties` returns them (kg, mm, kg·mm²), pending moves included.+ pub fn mass_properties(&self) -> Result<AssemblyMassResult> {+ let mut doc = (*self.doc).clone();+ for occurrence in &mut doc.occurrences {+ if let Some(transform) = self.pending_moves.get(&occurrence.id) {+ occurrence.transform = *transform;+ }+ }+ let state = self.model.state();+ assembly(&doc, &state)+ }+}++/// A body measured once: closed, and if so its volume (mm³), centre (mm) and spread, all in its+/// component's frame before its offset.+struct Shape {+ closed: bool,+ volume: f64,+ centroid: Vec3,+ gyration: Option<Tensor3>,+}++/// [`Session::mass_properties`] of a document and its evaluated state.+pub fn assembly(doc: &Document, state: &ModelState) -> Result<AssemblyMassResult> {+ if doc.occurrences.len() >= MAX_PLACEMENTS {+ return Err(bad(CMD, format!("assembly exceeds {MAX_PLACEMENTS} occurrences")));+ }+ let mut warnings = Vec::new();+ // Index 0 is the design itself; then the occurrences by id.+ let mut ids: Vec<u64> = doc.occurrences.iter().map(|o| o.id).filter(|id| *id != 0).collect();+ ids.sort_unstable();+ ids.dedup();+ ids.insert(0, 0);+ let index: HashMap<u64, usize> = ids.iter().enumerate().map(|(i, id)| (*id, i)).collect();++ let mut groups = Groups((0..ids.len()).collect());+ let live: Vec<_> = doc.assembly.joints.iter().filter(|j| !j.suppressed).take(MAX_JOINTS).collect();+ let jointed: HashSet<u64> = live.iter().flat_map(|j| [j.a.occurrence, j.b.occurrence]).collect();+ for j in live.iter().filter(|j| j.kind == JointKind::Rigid) {+ if let (Some(&a), Some(&b)) = (index.get(&j.a.occurrence), index.get(&j.b.occurrence)) {+ groups.join(a, b);+ }+ }+ for o in doc.occurrences.iter().filter(|o| o.parent != 0 && !jointed.contains(&o.id)) {+ if let (Some(&child), Some(&parent)) = (index.get(&o.id), doc.occurrence_of(o.parent).and_then(|p| index.get(&p.id))) {+ groups.join(child, parent);+ }+ }+ for c in doc.components.iter().filter(|c| doc.occurrences.iter().any(|o| o.parent == c.id)) {+ let copies = doc.occurrences.iter().filter(|o| o.component == c.id).count();+ if copies > 1 {+ warnings.push(format!(+ "`{}` is placed {copies} times: the occurrences inside it are listed at its first placement only, where joints place them",+ c.name+ ));+ }+ }++ // Each placed body measured once, on worker threads.+ let owners = doc.model_body_components(state);+ let placed: HashSet<u64> =+ ids.iter().map(|id| if *id == 0 { 0 } else { doc.occurrences.iter().find(|o| o.id == *id).map_or(u64::MAX, |o| o.component) }).collect();+ let measured: Vec<usize> = (0..state.bodies.len()).filter(|i| owners.get(*i).is_some_and(|c| placed.contains(c))).collect();+ let shapes = solidcraft_kernel::map_on_threads(&measured, 16, |&i| -> Result<Shape> {+ let body = state.bodies.get(i).ok_or_else(|| EngineError::Other("body index out of range".into()))?;+ let closed = crate::cmd::inspect::encloses_volume(&body.body);+ if !closed {+ return Ok(Shape { closed, volume: 0.0, centroid: Vec3::ZERO, gyration: None });+ }+ let m = solidcraft_kernel::measure_mass(&body.body)?;+ let gyration = solidcraft_io::mass_properties(&body.body)?.and_then(|p| p.gyration());+ Ok(Shape { closed, volume: m.volume, centroid: m.centroid, gyration })+ });+ let mut shape: BTreeMap<usize, Shape> = BTreeMap::new();+ for (i, s) in measured.into_iter().zip(shapes) {+ shape.insert(i, s.ok_or_else(|| bad(CMD, "measuring a body failed"))??);+ }++ let mut occurrences = Vec::with_capacity(ids.len());+ let mut totals: Vec<Option<MassBody>> = Vec::with_capacity(ids.len());+ for (i, &id) in ids.iter().enumerate() {+ let (component, name, world, path, fixed) = if id == 0 {+ (0, doc.name.clone(), IDENTITY, Vec::new(), true)+ } else {+ // Every id came from `doc.occurrences`, so the occurrence is there.+ let o = doc.occurrences.iter().find(|o| o.id == id);+ let (component, name, grounded) = o.map_or((u64::MAX, String::new(), false), |o| (o.component, o.name.clone(), o.grounded));+ (component, name, joints::occurrence_world(doc, id), canonical_path(doc, id), grounded)+ };+ if world.iter().flatten().any(|x| !x.is_finite()) {+ return Err(out_of_range());+ }+ let (mut bodies, mut parts, mut skipped) = (Vec::new(), Vec::new(), 0);+ for (k, body) in state.bodies.iter().enumerate().filter(|(k, _)| owners.get(*k) == Some(&component)) {+ let Some(s) = shape.get(&k) else { continue };+ let density = doc.density(&body.name);+ let mut entry = BodyMassEntry {+ name: body.name.clone(),+ material: doc.body_material(&body.name),+ density_g_cm3: density,+ closed: s.closed,+ ..BodyMassEntry::default()+ };+ if s.closed {+ let at = doc.model_body_offset(body).map_or(world, |offset| mat_mul(&world, offset));+ let l = linear(&at);+ let volume = s.volume * det3(&l).abs();+ // g/cm³ × mm³ is mg; kg is 1e-6 of that.+ let mass = volume * density * 1e-6;+ let inertia = s.gyration.map(|g| inertia::from_gyration(&inertia::transformed(&g, &l), mass));+ let part = MassBody { mass, center: apply_point(&at, s.centroid), inertia };+ if !(part.is_finite() && volume.is_finite()) {+ return Err(out_of_range());+ }+ if inertia.is_none() {+ warnings.push(format!("body `{}`: its mesh does not close, so its inertia is unknown", body.name));+ }+ parts.push(part);+ entry.volume_mm3 = Some(volume);+ entry.mass_kg = Some(mass);+ } else {+ skipped += 1;+ warnings.push(format!("body `{}` is not a closed solid: it adds no mass", body.name));+ }+ bodies.push(entry);+ }+ let total = MassBody::combine(&parts);+ if total.is_none() && parts.iter().map(|p| p.mass).sum::<f64>() > 0.0 {+ return Err(out_of_range());+ }+ if total.is_some() && rotation(&world).is_none() {+ warnings.push(format!("`{name}` is scaled: its inertia in its own axes is left out"));+ }+ totals.push(total);+ occurrences.push(OccurrenceMass {+ occurrence: id,+ name,+ component,+ path,+ group: i,+ fixed,+ frame: frame_of(&world),+ bodies,+ open_bodies_skipped: skipped,+ mass: total.map(|t| rigid_mass(&t, &world)),+ });+ }++ // Groups in order of their lowest occurrence id (their union-find root).+ let mut by_root: BTreeMap<usize, Vec<usize>> = BTreeMap::new();+ for i in 0..occurrences.len() {+ by_root.entry(groups.root(i)).or_default().push(i);+ }+ let mut out_groups = Vec::with_capacity(by_root.len());+ for (g, members) in by_root.values().enumerate() {+ let fixed = members.iter().any(|&m| occurrences.get(m).is_some_and(|o| o.fixed));+ let frame_occurrence = members.first().and_then(|&m| ids.get(m)).copied().unwrap_or(0);+ let world = if frame_occurrence == 0 { IDENTITY } else { joints::occurrence_world(doc, frame_occurrence) };+ let parts: Vec<MassBody> = members.iter().filter_map(|&m| totals.get(m).copied().flatten()).collect();+ let total = MassBody::combine(&parts);+ if total.is_none() && !parts.is_empty() {+ return Err(out_of_range());+ }+ for &m in members {+ if let Some(o) = occurrences.get_mut(m) {+ o.group = g;+ }+ }+ out_groups.push(RigidGroupMass {+ group: g,+ occurrences: members.iter().filter_map(|&m| ids.get(m).copied()).collect(),+ fixed,+ frame_occurrence,+ frame: frame_of(&world),+ mass: total.map(|t| rigid_mass(&t, &world)),+ });+ }+ Ok(AssemblyMassResult { occurrences, groups: out_groups, warnings, param_warnings: Vec::new() })+}++fn run(s: &mut Session, _p: &Value) -> Result<Value> {+ let r = s.mass_properties()?;+ serde_json::to_value(r).map_err(|e| EngineError::Other(e.to_string()))+}++#[cfg(test)]+#[path = "mass_properties_tests.rs"]+#[allow(clippy::unwrap_used, clippy::expect_used)]+mod tests;diff --git a/crates/engine/src/cmd/mass_properties_tests.rs b/crates/engine/src/cmd/mass_properties_tests.rsnew file mode 100644index 0000000000..5dc671ed94--- /dev/null+++ b/crates/engine/src/cmd/mass_properties_tests.rs@@ -0,0 +1,269 @@+//! `assembly.mass_properties` against closed-form values: a box, a cylinder, two boxes apart+//! (parallel axis), a turned occurrence, a rigid group, and inputs that must not panic.++use std::f64::consts::PI;++use serde_json::{Value, json};++use super::MassBody;+use crate::Session;+use solidcraft_geom::Vec3;+use solidcraft_geom::inertia::Tensor3 as Tensor;++fn run(s: &mut Session, cmd: &str, params: Value) -> Value {+ s.execute(cmd, ¶ms).unwrap_or_else(|e| panic!("{cmd}: {e}"))+}++fn num(v: &Value) -> f64 {+ v.as_f64().unwrap_or_else(|| panic!("not a number: {v}"))+}++fn near(actual: f64, expected: f64, rel: f64) {+ assert!((actual - expected).abs() <= rel * expected.abs().max(1e-9), "{actual} != {expected} (rel {rel})");+}++fn tensor(v: &Value) -> Tensor {+ let mut t = [[0.0; 3]; 3];+ for (i, row) in t.iter_mut().enumerate() {+ for (j, cell) in row.iter_mut().enumerate() {+ *cell = num(&v[i][j]);+ }+ }+ t+}++fn diag(t: &Tensor, expected: [f64; 3], rel: f64) {+ let scale = expected.iter().fold(0.0f64, |a, b| a.max(b.abs()));+ for i in 0..3 {+ near(t[i][i], expected[i], rel);+ for j in 0..3 {+ if i != j {+ assert!(t[i][j].abs() <= rel * scale, "off-diagonal [{i}][{j}] = {} in {t:?}", t[i][j]);+ }+ }+ }+}++/// A new component (not grounded) holding a box; its occurrence id and the body's name.+fn part(s: &mut Session, name: &str, size: [f64; 3], material: &str) -> (u64, u64, String) {+ run(s, "component.activate", json!({"component": "root"}));+ let c = run(s, "component.create", json!({"name": name, "grounded": false}));+ run(s, "solid.box", json!({"length": size[0], "width": size[1], "height": size[2]}));+ let body = s.model.state().bodies.last().map(|b| b.name.clone()).unwrap_or_default();+ run(s, "material.assign", json!({"bodies": [body], "material": material}));+ (c["component"].as_u64().unwrap_or(0), c["occurrence"].as_u64().unwrap_or(0), body)+}++fn occurrence(r: &Value, id: u64) -> &Value {+ r["occurrences"].as_array().and_then(|a| a.iter().find(|o| o["occurrence"] == id)).unwrap_or_else(|| panic!("no occurrence {id} in {r}"))+}++/// Box `a × b × c` of mass `m` about its centre: `m/12 (b² + c²)` and so on.+fn box_inertia(m: f64, [a, b, c]: [f64; 3]) -> [f64; 3] {+ [m / 12.0 * (b * b + c * c), m / 12.0 * (a * a + c * c), m / 12.0 * (a * a + b * b)]+}++#[test]+fn a_box_has_its_closed_form_mass_centre_and_inertia() {+ let mut s = Session::default();+ let (_, occ, body) = part(&mut s, "Block", [10.0, 20.0, 30.0], "Steel");+ let rho = s.doc.density(&body);+ let m = 6000.0 * rho * 1e-6;+ let r = run(&mut s, "assembly.mass_properties", json!({}));+ let o = occurrence(&r, occ);+ assert_eq!(o["bodies"][0]["material"], "Steel");+ assert_eq!(o["bodies"][0]["closed"], true);+ near(num(&o["bodies"][0]["volume_mm3"]), 6000.0, 1e-9);+ let mass = &o["mass"];+ near(num(&mass["mass_kg"]), m, 1e-9);+ for (k, c) in [5.0, 10.0, 15.0].iter().enumerate() {+ near(num(&mass["center_of_mass_mm"][k]), *c, 1e-9);+ near(num(&mass["center_of_mass_local_mm"][k]), *c, 1e-9);+ }+ diag(&tensor(&mass["inertia_world_kg_mm2"]), box_inertia(m, [10.0, 20.0, 30.0]), 1e-9);+ diag(&tensor(&mass["inertia_local_kg_mm2"]), box_inertia(m, [10.0, 20.0, 30.0]), 1e-9);+ // The design itself is a fixed group of its own, without mass.+ assert_eq!(r["groups"][0]["occurrences"], json!([0]));+ assert_eq!(r["groups"][0]["fixed"], true);+ assert!(r["groups"][0]["mass"].is_null());+ let g = &r["groups"][o["group"].as_u64().unwrap_or(0) as usize];+ assert_eq!(g["occurrences"], json!([occ]));+ assert_eq!(g["fixed"], false);+ near(num(&g["mass"]["mass_kg"]), m, 1e-9);+}++#[test]+fn a_cylinder_matches_its_closed_form_within_the_tessellation() {+ let mut s = Session::default();+ run(&mut s, "component.create", json!({"name": "Shaft", "grounded": false}));+ run(&mut s, "solid.cylinder", json!({"radius": 10, "height": 40}));+ let body = s.model.state().bodies.last().map(|b| b.name.clone()).unwrap_or_default();+ let rho = s.doc.density(&body);+ let (r_, h) = (10.0f64, 40.0f64);+ let m = PI * r_ * r_ * h * rho * 1e-6;+ let r = run(&mut s, "assembly.mass_properties", json!({}));+ let o = &r["occurrences"][1];+ assert_eq!(o["bodies"][0]["material"], s.doc.body_material(&body));+ let mass = &o["mass"];+ near(num(&mass["mass_kg"]), m, 1e-3);+ near(num(&mass["center_of_mass_mm"][2]), 20.0, 1e-3);+ assert!(num(&mass["center_of_mass_mm"][0]).abs() < 1e-3);+ let side = m * (3.0 * r_ * r_ + h * h) / 12.0;+ diag(&tensor(&mass["inertia_world_kg_mm2"]), [side, side, m * r_ * r_ / 2.0], 2e-3);+}++#[test]+fn two_boxes_apart_combine_by_the_parallel_axis_theorem() {+ let mut s = Session::default();+ let (_, occ, body) = part(&mut s, "Pair", [10.0, 10.0, 10.0], "Aluminum");+ run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10, "corner": [30, 0, 0]}));+ let second = s.model.state().bodies.last().map(|b| b.name.clone()).unwrap_or_default();+ assert_ne!(second, body);+ let (r1, r2) = (s.doc.density(&body), s.doc.density(&second));+ let (m1, m2) = (1000.0 * r1 * 1e-6, 1000.0 * r2 * 1e-6);+ let m = m1 + m2;+ // Centres at x = 5 and x = 35.+ let cx = (5.0 * m1 + 35.0 * m2) / m;+ let r = run(&mut s, "assembly.mass_properties", json!({}));+ let mass = &occurrence(&r, occ)["mass"];+ near(num(&mass["mass_kg"]), m, 1e-9);+ near(num(&mass["center_of_mass_mm"][0]), cx, 1e-9);+ let own = |mi: f64| mi / 12.0 * 200.0;+ let shift = m1 * (cx - 5.0).powi(2) + m2 * (35.0 - cx).powi(2);+ diag(&tensor(&mass["inertia_world_kg_mm2"]), [own(m1) + own(m2), own(m1) + own(m2) + shift, own(m1) + own(m2) + shift], 1e-9);+}++#[test]+fn a_turned_occurrence_turns_its_world_tensor_but_not_its_own() {+ let mut s = Session::default();+ let (_, occ, body) = part(&mut s, "Block", [10.0, 20.0, 30.0], "Steel");+ let m = 6000.0 * s.doc.density(&body) * 1e-6;+ // A quarter turn about z, kept pending (pending moves count, as Properties shows them).+ run(&mut s, "occurrence.move", json!({"occurrence": occ, "axis": [0, 0, 1], "angle": "90 deg", "translate": [100, 0, 0], "capture": false}));+ let r = run(&mut s, "assembly.mass_properties", json!({}));+ let o = occurrence(&r, occ);+ let frame = &o["frame"];+ near(num(&frame["x"][1]), 1.0, 1e-9);+ near(num(&frame["y"][0]), -1.0, 1e-9);+ let mass = &o["mass"];+ let local = box_inertia(m, [10.0, 20.0, 30.0]);+ diag(&tensor(&mass["inertia_world_kg_mm2"]), [local[1], local[0], local[2]], 1e-9);+ diag(&tensor(&mass["inertia_local_kg_mm2"]), local, 1e-9);+ for (k, c) in [5.0, 10.0, 15.0].iter().enumerate() {+ near(num(&mass["center_of_mass_local_mm"][k]), *c, 1e-9);+ }+ // World centre: (5, 10, 15) turned about z then moved.+ let world: Vec<f64> = (0..3).map(|k| num(&mass["center_of_mass_mm"][k])).collect();+ let expected = [num(&frame["origin"][0]) - 10.0, num(&frame["origin"][1]) + 5.0, num(&frame["origin"][2]) + 15.0];+ for (a, e) in world.iter().zip(expected) {+ near(*a, e, 1e-9);+ }+}++#[test]+fn a_rigid_group_is_one_body_and_other_joints_keep_bodies_apart() {+ let mut s = Session::default();+ let (_, a, body_a) = part(&mut s, "Base", [10.0, 10.0, 10.0], "Steel");+ let (_, b, body_b) = part(&mut s, "Cap", [10.0, 10.0, 10.0], "Steel");+ run(&mut s, "occurrence.move", json!({"occurrence": b, "translate": [0, 0, 40]}));+ let (_, c, _) = part(&mut s, "Loose", [10.0, 10.0, 10.0], "Steel");+ run(&mut s, "occurrence.move", json!({"occurrence": c, "translate": [100, 0, 0]}));+ run(&mut s, "joint.rigid_group", json!({"occurrences": [a, b]}));+ let r = run(&mut s, "assembly.mass_properties", json!({}));+ let (ga, gb, gc) = (occurrence(&r, a)["group"].clone(), occurrence(&r, b)["group"].clone(), occurrence(&r, c)["group"].clone());+ assert_eq!(ga, gb);+ assert_ne!(ga, gc);+ let g = &r["groups"][ga.as_u64().unwrap_or(0) as usize];+ let mut held: Vec<u64> = vec![a, b];+ held.sort_unstable();+ assert_eq!(g["occurrences"], json!(held));+ assert_eq!(g["frame_occurrence"], json!(held[0]));+ let m1 = 1000.0 * s.doc.density(&body_a) * 1e-6;+ let m2 = 1000.0 * s.doc.density(&body_b) * 1e-6;+ let m = m1 + m2;+ let mass = &g["mass"];+ near(num(&mass["mass_kg"]), m, 1e-9);+ // Centres at z = 5 and z = 45: the common one halfway, each 20 mm off it.+ near(num(&mass["center_of_mass_mm"][2]), 25.0, 1e-9);+ let own = m1 / 12.0 * 200.0 + m2 / 12.0 * 200.0;+ let shift = m1 * 400.0 + m2 * 400.0;+ diag(&tensor(&mass["inertia_world_kg_mm2"]), [own + shift, own + shift, own], 1e-9);+}++#[test]+fn a_nested_occurrence_no_joint_places_moves_with_its_parent() {+ let mut s = Session::default();+ let outer = run(&mut s, "component.create", json!({"name": "Assembly", "grounded": false}));+ let inner = run(&mut s, "component.create", json!({"name": "Inner", "grounded": false}));+ run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10}));+ let r = run(&mut s, "assembly.mass_properties", json!({}));+ let (o, i) = (outer["occurrence"].as_u64().unwrap_or(0), inner["occurrence"].as_u64().unwrap_or(0));+ assert_eq!(occurrence(&r, o)["group"], occurrence(&r, i)["group"]);+ assert!(occurrence(&r, o)["mass"].is_null(), "the outer component has no bodies of its own");+ assert_eq!(occurrence(&r, i)["path"], json!([o, i]));+}++#[test]+fn hostile_and_degenerate_inputs_never_panic() {+ // An empty design: the design itself, without mass.+ let mut s = Session::default();+ let r = run(&mut s, "assembly.mass_properties", json!({}));+ assert_eq!(r["occurrences"].as_array().map(Vec::len), Some(1));+ assert!(r["occurrences"][0]["mass"].is_null());+ // A pending placement that is not finite is refused, not propagated.+ let (_, occ, _) = part(&mut s, "Block", [10.0, 10.0, 10.0], "Steel");+ let mut bad = solidcraft_doc::IDENTITY;+ bad[3][0] = f64::NAN;+ s.pending_moves.insert(occ, bad);+ assert!(s.execute("assembly.mass_properties", &json!({})).is_err());+ let mut huge = solidcraft_doc::IDENTITY;+ huge[0][0] = 1e200;+ huge[1][1] = 1e200;+ huge[2][2] = 1e200;+ s.pending_moves.insert(occ, huge);+ assert!(s.execute("assembly.mass_properties", &json!({})).is_err());+ // A flattening placement: no volume, so no mass, and no panic.+ let mut flat = solidcraft_doc::IDENTITY;+ flat[2][2] = 0.0;+ s.pending_moves.insert(occ, flat);+ let r = run(&mut s, "assembly.mass_properties", json!({}));+ assert!(occurrence(&r, occ)["mass"].is_null(), "{r}");+ // A rigid joint to an occurrence that is gone is ignored.+ s.pending_moves.clear();+ let mut doc = (*s.doc).clone();+ if let Some(j) = doc.assembly.joints.first_mut() {+ j.b.occurrence = 999_999;+ }+ s.doc = std::sync::Arc::new(doc);+ run(&mut s, "assembly.mass_properties", json!({}));++ // The combination itself.+ assert_eq!(MassBody::combine(&[]), None);+ let neg = MassBody { mass: -1.0, ..MassBody::default() };+ assert_eq!(MassBody::combine(&[neg]), None);+ let nan = MassBody { mass: 1.0, center: Vec3::new(f64::NAN, 0.0, 0.0), ..MassBody::default() };+ assert_eq!(MassBody::combine(&[nan]), None);+ let inf = MassBody { mass: f64::INFINITY, ..MassBody::default() };+ assert_eq!(MassBody::combine(&[inf]), None);+ // A part whose tensor is unknown leaves the total's unknown, not wrong.+ let known = MassBody { mass: 1.0, center: Vec3::ZERO, inertia: Some([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]) };+ let unknown = MassBody { mass: 1.0, center: Vec3::new(2.0, 0.0, 0.0), inertia: None };+ let both = MassBody::combine(&[known, unknown]).unwrap_or_else(|| panic!("positive mass"));+ assert_eq!(both.inertia, None);+ near(both.center.x, 1.0, 1e-12);+}++#[test]+fn combining_two_point_like_bodies_adds_the_parallel_axis_terms() {+ let unit: Tensor = [[1.0, 0.0, 0.0], [0.0, 2.0, 0.0], [0.0, 0.0, 3.0]];+ let a = MassBody { mass: 1.0, center: Vec3::new(0.0, 0.0, 0.0), inertia: Some(unit) };+ let b = MassBody { mass: 3.0, center: Vec3::new(4.0, 4.0, 0.0), inertia: Some(unit) };+ let t = MassBody::combine(&[a, b]).and_then(|t| t.inertia).unwrap_or_else(|| panic!("combines"));+ // Centre (3, 3, 0); a is (−3, −3) from it, b (1, 1): Σ m d² terms and −Σ m dx dy.+ let (sxx, sxy) = (1.0 * 9.0 + 3.0 * 1.0, 1.0 * 9.0 + 3.0 * 1.0);+ near(t[0][0], 2.0 + sxx, 1e-12);+ near(t[1][1], 4.0 + sxx, 1e-12);+ near(t[2][2], 6.0 + 2.0 * sxx, 1e-12);+ near(t[0][1], -sxy, 1e-12);+ near(t[1][0], -sxy, 1e-12);+}diff --git a/crates/engine/src/cmd/mod.rs b/crates/engine/src/cmd/mod.rsindex 4ec05544d0..a5d68769a5 100644--- a/crates/engine/src/cmd/mod.rs+++ b/crates/engine/src/cmd/mod.rs@@ -60,6 +60,7 @@ pub(crate) mod inspect;mod interference;pub(crate) mod joints;mod libraries;+pub mod mass_properties;mod material_properties;mod materials;mod measure_sel;@@ -326,6 +327,7 @@ pub fn command_specs() -> Vec<&'static CommandSpec> {v.extend(config::COMMANDS.iter());v.extend(parts::COMMANDS.iter());v.extend(bom::COMMANDS.iter());+ v.extend(mass_properties::COMMANDS.iter());v.extend(browser::COMMANDS.iter());v.extend(delete::COMMANDS.iter());v.extend(edit::COMMANDS.iter());diff --git a/crates/engine/src/schema/mass_properties.rs b/crates/engine/src/schema/mass_properties.rsnew file mode 100644index 0000000000..4775ab50e0--- /dev/null+++ b/crates/engine/src/schema/mass_properties.rs@@ -0,0 +1,114 @@+//! Contracts and result types for the commands in `cmd/mass_properties.rs`.+//!+//! The reply types are also the Rust API a dynamics solver reads (`Session::mass_properties`):+//! units are kg, mm and kg·mm² throughout.++use schemars::JsonSchema;+use serde::{Deserialize, Serialize};++/// Mass, centre of mass and inertia tensor of every occurrence of the design and of every rigid+/// group (occurrences joined by rigid joints, which move as one body), from each body's material+/// density. Read-only.+#[derive(Debug, Deserialize, JsonSchema)]+#[schemars(deny_unknown_fields)]+pub struct AssemblyMassParams {}++/// A placed coordinate frame in world coordinates (mm): its origin and its unit axes.+#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]+pub struct MassFrame {+ pub origin: [f64; 3],+ pub x: [f64; 3],+ pub y: [f64; 3],+ pub z: [f64; 3],+}++/// Mass, centre of mass and inertia tensor of one rigid body (or of several taken as one).+#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]+pub struct RigidMass {+ /// Mass in kg.+ pub mass_kg: f64,+ /// Centre of mass in world coordinates, mm.+ pub center_of_mass_mm: [f64; 3],+ /// Centre of mass in the frame's coordinates, mm.+ pub center_of_mass_local_mm: [f64; 3],+ /// Inertia tensor about the centre of mass, world axes, kg·mm², row by row: the moments on+ /// the diagonal (Ixx = ∫ (y² + z²) dm …), the negated products of inertia off it+ /// (−∫ x y dm …), as URDF and most dynamics libraries take it. `null` when a closed body's+ /// mesh does not close (a warning names it).+ pub inertia_world_kg_mm2: Option<[[f64; 3]; 3]>,+ /// The same tensor in the frame's axes, kg·mm². `null` as above, or when the frame is+ /// scaled (its axes are not a rotation).+ pub inertia_local_kg_mm2: Option<[[f64; 3]; 3]>,+}++/// One body of an occurrence.+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]+pub struct BodyMassEntry {+ pub name: String,+ /// Its physical material (the default material when none is assigned).+ pub material: String,+ pub density_g_cm3: f64,+ /// A closed solid: an open body (a surface) has no volume and adds no mass.+ pub closed: bool,+ /// Volume in mm³ and mass in kg, for a closed body only.+ pub volume_mm3: Option<f64>,+ pub mass_kg: Option<f64>,+}++/// One occurrence (0: the design's own bodies, which never move).+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]+pub struct OccurrenceMass {+ pub occurrence: u64,+ pub name: String,+ /// The component it places.+ pub component: u64,+ /// Occurrence ids from the top of the assembly down (empty for 0).+ pub path: Vec<u64>,+ /// Index of its rigid group in `groups`.+ pub group: usize,+ /// Grounded, or the design itself.+ pub fixed: bool,+ /// The occurrence's frame (its component's origin and axes as placed).+ pub frame: MassFrame,+ pub bodies: Vec<BodyMassEntry>,+ /// Bodies left out because they are not closed solids.+ pub open_bodies_skipped: usize,+ /// Its own bodies' totals in its frame; `null` when it holds no closed body.+ pub mass: Option<RigidMass>,+}++/// Occurrences that move as one body.+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]+pub struct RigidGroupMass {+ /// Its index in `groups`.+ pub group: usize,+ /// The occurrences it holds, ascending (0: the design's own bodies).+ pub occurrences: Vec<u64>,+ /// Holds the design itself or a grounded occurrence: it does not move.+ pub fixed: bool,+ /// The occurrence whose frame `frame` is: 0 (world) for a fixed group holding the design,+ /// else the group's lowest occurrence id.+ pub frame_occurrence: u64,+ pub frame: MassFrame,+ /// Totals of all its occurrences in `frame` (parallel-axis theorem); `null` when massless.+ pub mass: Option<RigidMass>,+}++/// What `assembly.mass_properties` returns.+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]+pub struct AssemblyMassResult {+ /// Every occurrence, the design's own bodies (0) first, then by occurrence id.+ pub occurrences: Vec<OccurrenceMass>,+ /// The rigid groups, in order of their lowest occurrence id.+ pub groups: Vec<RigidGroupMass>,+ /// Approximations made (open bodies, repeated subassemblies, scaled frames).+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ pub warnings: Vec<String>,+ /// 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>,+}++#[cfg(test)]+#[path = "mass_properties_tests.rs"]+mod tests;diff --git a/crates/engine/src/schema/mass_properties_tests.rs b/crates/engine/src/schema/mass_properties_tests.rsnew file mode 100644index 0000000000..6f42ba9653--- /dev/null+++ b/crates/engine/src/schema/mass_properties_tests.rs@@ -0,0 +1,28 @@+use serde_json::json;++use super::{AssemblyMassParams, AssemblyMassResult};+use crate::Session;+use crate::schema::tests::{assert_keys, conforms};+use crate::schema::{ParamCheck, input_schema_for, output_schema_for};++#[test]+fn schemas_and_the_key_check_agree() {+ assert_keys(input_schema_for::<AssemblyMassParams>(), &[]);+}++#[test]+fn replies_match_the_output_schema() {+ let schema = output_schema_for::<AssemblyMassResult>();+ let schema = schema.as_value();+ let mut s = Session { param_check: ParamCheck::Warn, ..Session::default() };+ let empty = s.execute("assembly.mass_properties", &json!({})).unwrap_or_else(|e| panic!("{e}"));+ assert!(conforms(schema, schema, &empty), "{empty} doesn't match {schema}");+ assert!(empty.get("param_warnings").is_none(), "{empty}");+ s.execute("component.create", &json!({"name": "Block"})).unwrap_or_else(|e| panic!("{e}"));+ s.execute("solid.box", &json!({"length": 10, "width": 10, "height": 10})).unwrap_or_else(|e| panic!("{e}"));+ let r = s.execute("assembly.mass_properties", &json!({"unknown_extra": 1})).unwrap_or_else(|e| panic!("{e}"));+ assert!(r.get("param_warnings").is_some(), "{r}");+ assert!(conforms(schema, schema, &r), "{r} doesn't match {schema}");+ s.param_check = ParamCheck::Strict;+ assert!(s.execute("assembly.mass_properties", &json!({"unknown_extra": 1})).is_err());+}diff --git a/crates/engine/src/schema/mod.rs b/crates/engine/src/schema/mod.rsindex 803f90b341..4896d91e16 100644--- a/crates/engine/src/schema/mod.rs+++ b/crates/engine/src/schema/mod.rs@@ -60,6 +60,7 @@ pub mod edit;pub mod features;pub mod inspect;pub mod joints;+pub mod mass_properties;pub mod print_face;pub mod render;pub mod render_lights;diff --git a/docs/assembly-properties.md b/docs/assembly-properties.mdindex 0358b336c1..79d9f574ed 100644--- a/docs/assembly-properties.md+++ b/docs/assembly-properties.md@@ -69,3 +69,32 @@ quality. Each body is tessellated once, however many times the assembly places iturns its tensor. A closed body whose mesh does not close has `inertia_g_mm2: null`, and so doesthe total. Open bodies have no volume, so they have no tensor either, and the total leaves themout.++## Per occurrence and per rigid group++`assembly.mass_properties` (no parameters) gives what a dynamics solver needs of each moving+part, measured as above, in kg, mm and kg·mm²:++```json+{"command":"assembly.mass_properties","params":{}}+```++- `occurrences`: the design's own bodies (`occurrence: 0`) and then every occurrence, each with+ its `frame` (origin and unit axes in world coordinates), its own bodies (material, density,+ volume and mass), and `mass`: its bodies' total `mass_kg`, `center_of_mass_mm` (world) and+ `center_of_mass_local_mm` (in its frame), and the tensor about that centre in world axes+ (`inertia_world_kg_mm2`) and in its frame's axes (`inertia_local_kg_mm2`). Only the bodies the+ occurrence's component owns count, not those of occurrences nested in it.+- `groups`: occurrences that move as one body, each with the occurrences it holds, the same+ `mass` totals (combined with the parallel-axis theorem) in the frame of its lowest+ occurrence (`frame_occurrence`; 0 is the world), and `fixed` when it holds the design itself+ or a grounded occurrence. An unsuppressed rigid joint (Rigid Group makes them) puts its two+ occurrences in one group, and a nested occurrence that no joint places goes with the+ occurrence it sits in, since the joint solver leaves it where its parent puts it.+- `warnings`: open bodies (no mass), closed bodies whose mesh does not close (`inertia_*: null`),+ scaled placements (no tensor in their own axes) and subassemblies placed more than once (the+ occurrences inside them are listed at the first placement, where joints place them).++A body without a material assignment has the default material's density, as Properties shows.+Pending occurrence moves count. Rust callers get the same numbers, typed, from+`Session::mass_properties()`.