Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

17.4 KB
Raw Blame
//! Physical properties of an assembly placement, with original body material assignments.
use solidcraft_geom::prelude::*;
use std::collections::{BTreeMap, BTreeSet};

use serde_json::Value;
use solidcore_record::Vec3;
use solidcraft_doc::{Document, Mat};
use solidcraft_geom::Aabb3;
use solidcraft_geom::inertia::{self, Tensor3};

use crate::params::bad;
use crate::schema::component::{
    BodyProperties, BoundingBox, InertiaAbout, OccurrencePropertiesResult, PhysicalProperties, PropertiesResult, TotalProperties,
};
use crate::{Result, Session};

fn descendants(p: &Value, cmd: &str) -> Result<bool> {
    match p.get("descendants") {
        None => Ok(true),
        Some(Value::Bool(v)) => Ok(*v),
        Some(_) => Err(bad(cmd, "`descendants` must be a boolean")),
    }
}

/// Principal moments this close (a share of the largest) count as equal: a round body's
/// tessellation tells its two equal moments apart by about 1e-4, which turns their axes at random.
const EQUAL_MOMENTS: f64 = 1e-3;

/// The point `about` asks for the inertia tensor about, if any.
fn about(p: &Value, cmd: &str) -> Result<Option<Vec3>> {
    match p.get("about") {
        None | Some(Value::Null) => Ok(None),
        Some(v) => crate::params::vec3(v).map(Some).ok_or_else(|| bad(cmd, "`about` must be a point [x, y, z] in mm")),
    }
}

/// The 3 × 3 linear part of a placement, row by row: its turn, and any scale or mirror.
fn linear(m: &Mat) -> Tensor3 {
    [0, 1, 2].map(|i| [0, 1, 2].map(|j| m[j][i]))
}

fn placed_doc(s: &Session) -> Document {
    s.design_document().into_owned()
}

/// A property total must cover the entire assembly. The display traversal intentionally
/// truncates hostile designs, so use an explicit error instead of accepting its prefix.
pub(in crate::cmd) fn placements(doc: &Document, cmd: &str) -> Result<Vec<(u64, Vec<u64>, Mat)>> {
    subtree(doc, (0, Vec::new(), solidcraft_doc::IDENTITY), true, cmd)
}

/// `root` and, with `descendants`, every placement under it, each with its world transform.
/// The occurrences are grouped by parent once: searching all of them at every placement made a
/// large assembly's traversal quadratic.
fn subtree(doc: &Document, root: (u64, Vec<u64>, Mat), descendants: bool, cmd: &str) -> Result<Vec<(u64, Vec<u64>, Mat)>> {
    let mut out = vec![root.clone()];
    if !descendants {
        return Ok(out);
    }
    let mut stack = vec![root];
    let mut children: std::collections::BTreeMap<u64, Vec<_>> = std::collections::BTreeMap::new();
    for occurrence in &doc.occurrences {
        children.entry(occurrence.parent).or_default().push(occurrence);
    }
    while let Some((component, path, transform)) = stack.pop() {
        for occurrence in children.get(&component).into_iter().flatten() {
            if path.len() >= 64 || out.len() >= 100_000 {
                return Err(bad(cmd, "assembly exceeds physical-properties traversal limits (64 levels or 100000 placements)"));
            }
            let mut child_path = path.clone();
            child_path.push(occurrence.id);
            let world = solidcraft_doc::mat_mul(&transform, &occurrence.transform);
            out.push((occurrence.component, child_path.clone(), world));
            stack.push((occurrence.component, child_path, world));
        }
    }
    Ok(out)
}

pub(super) fn component(s: &mut Session, p: &Value) -> Result<Value> {
    let cmd = "component.properties";
    let id = if p.get("component").is_some() { super::component(s, p, "component", cmd)? } else { s.active_component };
    let doc = placed_doc(s);
    let path = doc.first_path(id);
    let name = if id == 0 {
        doc.name.clone()
    } else {
        doc.components.iter().find(|c| c.id == id).map(|c| c.name.clone()).ok_or_else(|| bad(cmd, "no active component"))?
    };
    let properties = measure(s, &doc, &path, descendants(p, cmd)?, about(p, cmd)?, cmd)?;
    super::reply(PropertiesResult { component: id, name, properties, param_warnings: Vec::new() })
}

pub(super) fn occurrence(s: &mut Session, p: &Value) -> Result<Value> {
    let cmd = "occurrence.properties";
    let id = super::occurrence(s, p, cmd)?;
    let doc = placed_doc(s);
    let path = if p.get("path").is_some() {
        super::occurrence_path(s, p, id, cmd)?
    } else {
        let paths: Vec<Vec<u64>> =
            placements(&doc, cmd)?.into_iter().filter(|(_, path, _)| path.last() == Some(&id)).map(|(_, path, _)| path).collect();
        match paths.as_slice() {
            [path] => path.clone(),
            [] => return Err(bad(cmd, "occurrence has no placement")),
            _ => return Err(bad(cmd, "occurrence has multiple placements; supply its `path`")),
        }
    };
    let properties = measure(s, &doc, &path, descendants(p, cmd)?, about(p, cmd)?, cmd)?;
    let name = doc.occurrences.iter().find(|o| o.id == id).map(|o| o.name.clone());
    super::reply(OccurrencePropertiesResult { occurrence: id, name, properties, param_warnings: Vec::new() })
}

/// The linear part of `m` is a rotation (no scale, shear or mirror), to rounding.
fn proper_rotation(m: &Mat) -> bool {
    let column = |i: usize| m.get(i).map_or(Vec3::ZERO, |c| Vec3::new(c[0], c[1], c[2]));
    let (x, y, z) = (column(0), column(1), column(2));
    m.iter().flatten().all(|v| v.is_finite())
        && [x, y, z].iter().all(|a| (a.dot(*a) - 1.0).abs() < 1e-9)
        && x.dot(y).abs() < 1e-9
        && x.dot(z).abs() < 1e-9
        && y.dot(z).abs() < 1e-9
        && x.cross(y).dot(z) > 0.0
}

/// Every axis of `m` goes to an axis (a quarter turn, or none): a box turned so stays a box.
fn square_to_axes(m: &Mat) -> bool {
    m.iter().take(3).all(|c| c.iter().take(3).filter(|v| v.abs() > 1e-12).count() == 1)
}

/// The box around the corners of `b` placed by `m`.
fn placed_box(m: &Mat, b: &Aabb3) -> Aabb3 {
    let mut out = Aabb3::EMPTY;
    if b.is_empty() {
        return out;
    }
    for i in 0..8 {
        let pick = |bit: usize, lo: f64, hi: f64| if i & bit == 0 { lo } else { hi };
        out.add(solidcraft_doc::apply_point(m, Vec3::new(pick(1, b.min.x, b.max.x), pick(2, b.min.y, b.max.y), pick(4, b.min.z, b.max.z))));
    }
    out
}

/// A body's measurements where a placement puts it.
struct Placed {
    volume: f64,
    area: f64,
    centroid: Vec3,
    bbox: Aabb3,
    closed: bool,
    faces: usize,
    edges: usize,
    vertices: usize,
}

/// `body` measured where `transform` places it. A rigid placement moves nothing but the centre
/// and the box: the body's own measurement (worked out once and shared by every placement of it,
/// [`solidcraft_doc::ModelBody::measure`]) is reused, where measuring each placed copy again took
/// three fine tessellations per copy and made Properties of a large assembly take minutes
/// (#8706). A placement that turns the body off the axes takes its box from the body's mesh
/// placed there (shared with the display). Any other placement (scaled or mirrored) is measured
/// as placed, as before.
fn measure_placed(body: &solidcraft_doc::ModelBody, transform: Mat) -> Result<Placed> {
    if proper_rotation(&transform) {
        let m = body.measure()?;
        let bbox = if square_to_axes(&transform) {
            placed_box(&transform, &m.bbox)
        } else {
            let mesh = body.mesh();
            let mut b = Aabb3::EMPTY;
            for p in &mesh.positions {
                b.add(solidcraft_doc::apply_point(&transform, *p));
            }
            if b.is_empty() { placed_box(&transform, &m.bbox) } else { b }
        };
        return Ok(Placed {
            volume: m.volume,
            area: m.area,
            centroid: solidcraft_doc::apply_point(&transform, m.centroid),
            bbox,
            closed: crate::cmd::inspect::encloses_volume(&body.body),
            faces: m.merged.faces,
            edges: m.merged.edges,
            vertices: m.merged.vertices,
        });
    }
    #[cfg(test)]
    work::count(|w| w.placed_measures += 1);
    let placed = solidcraft_kernel::transform_matrix(&body.body, transform)?;
    let m = solidcraft_kernel::measure(&placed)?;
    Ok(Placed {
        volume: m.volume,
        area: m.area,
        centroid: m.centroid,
        bbox: m.bbox,
        closed: crate::cmd::inspect::encloses_volume(&placed),
        faces: m.merged.faces,
        edges: m.merged.edges,
        vertices: m.merged.vertices,
    })
}

fn measure(s: &Session, doc: &Document, selected: &[u64], descendants: bool, about: Option<Vec3>, cmd: &str) -> Result<PhysicalProperties> {
    let state = s.model.state();
    let mut bodies = Vec::new();
    let (mut volume, mut area, mut mass) = (0.0, 0.0, 0.0);
    let mut moment = Vec3::ZERO;
    let mut bounds = Aabb3::EMPTY;
    let (mut faces, mut edges, mut vertices) = (0, 0, 0);
    let mut placement_count = 0;
    let mut skipped = 0;
    let selected_placements = if selected.is_empty() {
        subtree(doc, (0, Vec::new(), solidcraft_doc::IDENTITY), descendants, cmd)?
    } else {
        let placement = s.occurrence_placement_with(selected, &s.uncaptured_moves()).map_err(|e| bad(cmd, e.to_string()))?;
        subtree(doc, (placement.component, selected.to_vec(), placement.world), descendants, cmd)?
    };
    // Each component's bodies (with their index in the model), the timeline looked up once rather
    // than for every body at every placement.
    let mut by_component: std::collections::HashMap<u64, Vec<(usize, &solidcraft_doc::ModelBody)>> = std::collections::HashMap::new();
    for (index, (body, component)) in state.bodies.iter().zip(doc.model_body_components(&state)).enumerate() {
        by_component.entry(component).or_default().push((index, body));
    }
    // How each closed body's volume spreads about its centre of mass (#8095): one tessellation
    // however often it is placed, which each placement then turns.
    let components: BTreeSet<u64> = selected_placements.iter().map(|(component, _, _)| *component).collect();
    let spread_bodies: Vec<usize> = components
        .iter()
        .filter_map(|c| by_component.get(c))
        .flatten()
        .filter(|(_, b)| crate::cmd::inspect::encloses_volume(&b.body))
        .map(|(i, _)| *i)
        .collect();
    #[cfg(test)]
    work::count(|w| w.spreads += spread_bodies.len());
    let spreads = solidcraft_kernel::map_on_threads(&spread_bodies, 16, |&i| {
        let body = state.bodies.get(i)?;
        let mut measured = solidcraft_io::mass_properties(&body.body).ok().flatten()?;
        if let Some(sheet) = state.sheets.iter().find(|sheet| sheet.body == body.definition_name()) {
            sheet.correct_perforation_mass_properties(&mut measured, &solidcraft_doc::IDENTITY).ok()?;
        }
        measured.gyration()
    });
    let spread: BTreeMap<usize, Tensor3> = spread_bodies.into_iter().zip(spreads).filter_map(|(i, g)| Some((i, g.flatten()?))).collect();
    // A window waiting for the result (the Properties window) sees how far it is and can stop it.
    let watch = solidcraft_kernel::watch::current();
    let total_bodies: usize = selected_placements.iter().map(|(c, _, _)| by_component.get(c).map_or(0, Vec::len)).sum();
    let mut done = 0;
    // Closed bodies' (mass, centre of mass, inertia about it), all in world axes.
    let mut parts: Vec<(f64, Vec3, Option<Tensor3>)> = Vec::new();
    for (component, path, transform) in selected_placements {
        placement_count += 1;
        for &(index, body) in by_component.get(&component).into_iter().flatten() {
            if let Some(w) = &watch {
                if w.cancelled() {
                    return Err(bad(cmd, "cancelled"));
                }
                w.progress("measuring", done, total_bodies);
            }
            done += 1;
            let transform: Mat = doc.model_body_offset(body).map(|offset| solidcraft_doc::mat_mul(&transform, offset)).unwrap_or(transform);
            let mut measured = measure_placed(body, transform)?;
            if let Some(sheet) = state.sheets.iter().find(|sheet| sheet.body == body.definition_name() && !sheet.perforations.is_empty()) {
                let mut corrected = body.measure()?;
                corrected.volume = measured.volume;
                corrected.area = measured.area;
                corrected.centroid = measured.centroid;
                sheet.correct_perforation_properties(&mut corrected, &transform)?;
                measured.volume = corrected.volume;
                measured.area = corrected.area;
                measured.centroid = corrected.centroid;
            }
            let density = doc.density(&body.name);
            let body_mass = measured.volume * density / 1000.0;
            let closed = measured.closed;
            // The mesh's spread with the exact mass, so the tensor agrees with the mass shown.
            let body_inertia = spread
                .get(&index)
                .filter(|_| closed)
                .map(|g| inertia::from_gyration(&inertia::transformed(g, &linear(&transform)), body_mass))
                .filter(|i| i.iter().flatten().all(|x| x.is_finite()));
            if closed {
                volume += measured.volume;
                mass += body_mass;
                moment += measured.centroid * body_mass;
                parts.push((body_mass, measured.centroid, body_inertia));
            } else {
                skipped += 1;
            }
            area += measured.area;
            bounds = bounds.union(&measured.bbox);
            faces += measured.faces;
            edges += measured.edges;
            vertices += measured.vertices;
            bodies.push(BodyProperties {
                name: body.name.to_string(),
                component,
                path: path.clone(),
                material: doc.body_material(&body.name),
                closed,
                density_g_cm3: closed.then_some(density),
                mass_g: closed.then_some(body_mass),
                volume_mm3: closed.then_some(measured.volume),
                area_mm2: measured.area,
                center_of_mass: closed.then_some(measured.centroid),
                inertia_g_mm2: body_inertia,
                bbox: BoundingBox { min: measured.bbox.min, max: measured.bbox.max },
            });
        }
    }
    if let Some(w) = &watch {
        w.progress("measuring", done, total_bodies);
    }
    if !(volume.is_finite() && area.is_finite() && mass.is_finite() && moment.is_finite()) {
        return Err(bad(cmd, "physical properties exceed supported numeric range"));
    }
    let centroid = if mass > 0.0 { Some(moment / mass) } else { None };
    if centroid.is_some_and(|point| !point.is_finite()) {
        return Err(bad(cmd, "center of mass exceeds supported numeric range"));
    }
    // About the centre of mass: each body's own tensor, plus its mass at its distance from that
    // centre (parallel axes). Unknown when any closed body's mesh did not close.
    let at_centre = centroid.and_then(|c| {
        parts.iter().try_fold([[0.0f64; 3]; 3], |sum, (m, at, i)| {
            let i = inertia::shifted(&(*i)?, *m, *at - c);
            Some([0, 1, 2].map(|r| [0, 1, 2].map(|k| sum[r][k] + i[r][k])))
        })
    });
    let at_centre = at_centre.filter(|i| i.iter().flatten().all(|x| x.is_finite()));
    let principal = at_centre.and_then(|i| inertia::principal(&i, EQUAL_MOMENTS));
    let bbox = (!bodies.is_empty()).then_some(BoundingBox { min: bounds.min, max: bounds.max });
    let inertia_about = about.map(|point| {
        let shifted =
            centroid.zip(at_centre).map(|(c, i)| inertia::shifted(&i, mass, point - c)).filter(|i| i.iter().flatten().all(|x| x.is_finite()));
        InertiaAbout { point, inertia_g_mm2: shifted }
    });
    Ok(PhysicalProperties {
        path: selected.to_vec(),
        coordinate_frame: "world".to_string(),
        descendants,
        placement_count,
        body_count: bodies.len(),
        bodies,
        total: TotalProperties {
            open_bodies_skipped: skipped,
            volume_mm3: volume,
            area_mm2: area,
            mass_g: mass,
            center_of_mass: centroid,
            first_moment_g_mm: moment,
            inertia_g_mm2: at_centre,
            principal_moments_g_mm2: principal.map(|(moments, _)| moments),
            principal_axes: principal.map(|(_, axes)| axes),
            bbox,
            faces,
            edges,
            vertices,
            inertia_about,
        },
    })
}

/// The tessellating work a properties command did on this thread, for tests: placed copies
/// measured afresh (transformed, then tessellated) and bodies whose inertia spread was
/// tessellated. Counted where the work is asked for, on the command's own thread.
#[cfg(test)]
pub(super) mod work {
    use std::cell::Cell;

    #[derive(Clone, Copy, Debug, Default, PartialEq)]
    pub struct Work {
        pub placed_measures: usize,
        pub spreads: usize,
    }

    thread_local! {
        static WORK: Cell<Work> = const { Cell::new(Work { placed_measures: 0, spreads: 0 }) };
    }

    pub(super) fn count(f: impl FnOnce(&mut Work)) {
        WORK.with(|w| {
            let mut work = w.get();
            f(&mut work);
            w.set(work);
        });
    }

    /// `f`'s result and the work it did.
    pub fn capture<T>(f: impl FnOnce() -> T) -> (T, Work) {
        let before = WORK.with(Cell::get);
        let out = f();
        let after = WORK.with(Cell::get);
        (
            out,
            Work {
                placed_measures: after.placed_measures.saturating_sub(before.placed_measures),
                spreads: after.spreads.saturating_sub(before.spreads),
            },
        )
    }
}

#[cfg(test)]
#[path = "component_properties_tests.rs"]
mod tests;