SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Physical materials defined in a design (`material.create`, `material.edit`,
//! `material.delete`): a name, a density and optional visual and engineering records. They are assigned like the
//! built-in library's (`material.assign`), set masses (`component.properties`) and fill
//! configuration material cells. The design keeps them, so they are saved and undone like
//! features.
use serde_json::Value;
use solidcraft_doc::appearance::{Look, library};
use solidcraft_doc::config::Column;
use solidcraft_doc::{DEFAULT_MATERIAL, MATERIALS, MAX_USER_MATERIALS, UserMaterial, valid_density};
use super::CommandSpec;
use super::inspect::color_param;
use crate::params::{bad, str_};
use crate::schema::TypedContract;
use crate::schema::appearance::LookReply;
use crate::schema::materials::{
DensityComparison, MaterialCreateParams, MaterialDeleteParams, MaterialDeleted, MaterialEditParams, MaterialInspectParams, MaterialInspected,
MaterialReply,
};
use crate::schema::output_schema_for;
use crate::{Result, Session};
const CREATE_CONTRACT: TypedContract<MaterialCreateParams> = TypedContract::new();
const EDIT_CONTRACT: TypedContract<MaterialEditParams> = TypedContract::new();
const INSPECT_CONTRACT: TypedContract<MaterialInspectParams> = TypedContract::new();
const DELETE_CONTRACT: TypedContract<MaterialDeleteParams> = TypedContract::new();
pub static COMMANDS: &[CommandSpec] = &[
CommandSpec::new("material.create", "New Physical Material", crate::checked!("material.create", create))
.icon("material")
.contract(&CREATE_CONTRACT)
.output(output_schema_for::<MaterialReply>)
.params(
"name (not a built-in material's); density_g_cm3: (0, 1000]; appearance?: library name (appearance.library) | color?: \"#rrggbb\" or [r, g, b] (0–255), opacity? (0–1), pbr?: {metallic:0..1, roughness:0.045..1, dielectric_ior:1..3} (opaque only, needs color/appearance): the default look. A named appearance keeps its preset response when pbr is omitted; pbr: null selects scalar shading. Optical edits do not change density. physical_card?: validated SI candidate record (null/omitted means unknown); card density never changes assigned density. Assign it with material.assign",
),
CommandSpec::new("material.edit", "Edit Physical Material", crate::checked!("material.edit", edit))
.icon("material")
.enabled(has_user_materials)
.contract(&EDIT_CONTRACT)
.output(output_schema_for::<MaterialReply>)
.params(
"material: a material defined in this design; name? (bodies and configuration cells follow); density_g_cm3?; appearance? | color?, opacity?, pbr? (as material.create; color: null clears the look). physical_card?: validated SI candidate record (omitted retains, null clears). Omitted appearance/color retains the entire current look",
),
CommandSpec::new("material.inspect", "Inspect Physical Material", crate::checked!("material.inspect", inspect))
.icon("material")
.noundo()
.doc_only()
.contract(&INSPECT_CONTRACT)
.output(output_schema_for::<MaterialInspected>)
.params(
"material: built-in or design-owned name. Returns assigned density, default appearance, optional physical_card, validation and density comparison. Read-only; missing engineering data remains unknown and card density does not change mass",
),
CommandSpec::new("material.delete", "Delete Physical Material", crate::checked!("material.delete", delete))
.icon("delete")
.enabled(has_user_materials)
.contract(&DELETE_CONTRACT)
.output(output_schema_for::<MaterialDeleted>)
.params(
"material: a material defined in this design; replace?: material for the bodies and configuration cells that use it (without it, a material in use is refused)",
),
];
#[cfg(test)]
#[path = "material_card_persistence_tests.rs"]
mod persistence_tests;
fn has_user_materials(s: &Session) -> std::result::Result<(), String> {
if s.doc.user_materials.is_empty() { Err("the design defines no physical materials (material.create)".into()) } else { Ok(()) }
}
/// A new material name: 1–128 characters, not a built-in material's or another design
/// material's (`except`: the one being renamed).
fn new_name(s: &Session, cmd: &str, name: &str, except: Option<&str>) -> Result<String> {
let name = name.trim();
if name.is_empty() || name.chars().count() > 128 {
return Err(bad(cmd, "`name` must have 1–128 characters"));
}
if MATERIALS.iter().any(|(n, _)| n.eq_ignore_ascii_case(name)) {
return Err(bad(cmd, format!("`{name}` is a built-in material (material.list)")));
}
let taken = |m: &&UserMaterial| m.name.eq_ignore_ascii_case(name) && except.is_none_or(|e| !m.name.eq_ignore_ascii_case(e));
if s.doc.user_materials.iter().any(|m| taken(&m)) {
return Err(bad(cmd, format!("the design already has a material `{name}`")));
}
Ok(name.to_string())
}
fn density(cmd: &str, p: &Value) -> Result<f64> {
p.get("density_g_cm3")
.and_then(Value::as_f64)
.filter(|d| valid_density(*d))
.ok_or_else(|| bad(cmd, "`density_g_cm3` must be a number above 0 and at most 1000"))
}
/// The look `appearance` / `color` / `opacity` give: `None` when none is given, `Some(None)`
/// to clear it (`color: null`).
fn look(cmd: &str, p: &Value, material: &str) -> Result<Option<Option<Look>>> {
if p.get("pbr").is_some() && str_(p, "appearance").is_none() && p.get("color").is_none_or(Value::is_null) {
return Err(bad(cmd, "`pbr` requires an appearance or color"));
}
let opacity = match p.get("opacity") {
Some(o) => Some(o.as_f64().filter(|x| x.is_finite() && (0.0..=1.0).contains(x)).ok_or_else(|| bad(cmd, "`opacity` must be 0…1"))?),
None => None,
};
let mut l = match (str_(p, "appearance"), p.get("color")) {
(Some(_), Some(c)) if !c.is_null() => return Err(bad(cmd, "give `appearance` or `color`, not both")),
(Some(n), _) => library(n).ok_or_else(|| bad(cmd, format!("no appearance `{n}` in the library (appearance.library)")))?,
(None, Some(Value::Null)) => return Ok(Some(None)),
(None, Some(c)) => {
let mut l = Look::custom(color_param(c).ok_or_else(|| bad(cmd, "`color` must be \"#rrggbb\" or [r, g, b] with values 0–255"))?, 1.0);
l.name = material.to_string();
l
}
(None, None) if opacity.is_some() => return Err(bad(cmd, "`opacity` needs `appearance` or `color`")),
(None, None) => return Ok(None),
};
if let Some(o) = opacity {
l.opacity = o;
}
super::inspect::attach_pbr(cmd, p, &mut l)?;
Ok(Some(Some(l)))
}
/// A design material as `material.create` and `material.edit` report it: with its card, the
/// card's check and how the card's measured density compares, when it has a card.
fn material_reply(cmd: &str, m: &UserMaterial) -> Result<MaterialReply> {
let mut out = MaterialReply {
name: m.name.clone(),
density_g_cm3: m.density,
appearance: m.appearance.as_ref().map(LookReply::from),
user: true,
physical_card: None,
physical_validation: None,
density_comparison: None,
bodies: None,
param_warnings: Vec::new(),
};
if let Some(record) = &m.physical_card {
let card = record.card();
out.physical_card = Some(serde_json::to_value(record).map_err(|e| bad(cmd, e.to_string()))?);
out.physical_validation = Some(card.validate()?.into());
let measured = card.properties.iter().find_map(|p| match p.data {
solidcraft_doc::physical_material::PropertyData::Density { kg_m3 } => Some(kg_m3),
_ => None,
});
out.density_comparison = measured.map(|measured| {
let assigned = m.density * 1000.0;
let relative_difference = (assigned - measured).abs() / assigned.max(measured);
DensityComparison {
assigned_density_kg_m3: assigned,
card_density_kg_m3: measured,
relative_difference,
matches_within_relative_tolerance: relative_difference <= 1e-9,
relative_tolerance: 1e-9,
}
});
}
Ok(out)
}
/// [`material_reply`] for `material.list` (`cmd/inspect.rs`).
pub(super) fn listed_material(m: &UserMaterial) -> Result<MaterialReply> {
material_reply("material.list", m)
}
fn reply(cmd: &str, reply: impl serde::Serialize) -> Result<Value> {
serde_json::to_value(reply).map_err(|e| bad(cmd, e.to_string()))
}
fn physical_card(cmd: &str, p: &Value) -> Result<Option<Option<solidcraft_doc::physical_material::ValidatedCard>>> {
match p.get("physical_card") {
None => Ok(None),
Some(Value::Null) => Ok(Some(None)),
Some(value) => {
solidcraft_doc::physical_material::ValidatedCard::from_value(value).map(|card| Some(Some(card))).map_err(|e| bad(cmd, e.to_string()))
}
}
}
fn inspect(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "material.inspect";
let name = str_(p, "material").ok_or_else(|| bad(cmd, "`material` must be a material name"))?;
let canonical = s.doc.material_name(name).ok_or_else(|| bad(cmd, format!("unknown material `{name}` (see material.list)")))?;
// The look a material's bodies show: its own, or a built-in material's default.
let appearance = s.doc.material_look(&canonical).as_ref().map(LookReply::from);
let out = if let Some(material) = s.doc.user_materials.iter().find(|m| m.name == canonical) {
let own = material_reply(cmd, material)?;
MaterialInspected {
name: own.name,
density_g_cm3: own.density_g_cm3,
appearance,
user: true,
physical_card: own.physical_card,
physical_validation: own.physical_validation,
density_comparison: own.density_comparison,
param_warnings: Vec::new(),
}
} else {
let density = MATERIALS
.iter()
.find(|(n, _)| *n == canonical.as_str())
.map(|(_, density)| *density)
.ok_or_else(|| bad(cmd, "material is unavailable"))?;
MaterialInspected {
name: canonical,
density_g_cm3: density,
appearance,
user: false,
physical_card: None,
physical_validation: None,
density_comparison: None,
param_warnings: Vec::new(),
}
};
reply(cmd, out)
}
/// The index of the design material `material` names.
fn existing(s: &Session, cmd: &str, p: &Value) -> Result<usize> {
let name = str_(p, "material").ok_or_else(|| bad(cmd, "`material` must be a material name"))?;
s.doc
.user_materials
.iter()
.position(|m| m.name.eq_ignore_ascii_case(name.trim()))
.ok_or_else(|| bad(cmd, format!("the design defines no material `{name}` (built-in materials cannot be changed)")))
}
fn create(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "material.create";
let name = new_name(s, cmd, str_(p, "name").ok_or_else(|| bad(cmd, "`name` is required"))?, None)?;
if s.doc.user_materials.len() >= MAX_USER_MATERIALS {
return Err(bad(cmd, format!("a design defines at most {MAX_USER_MATERIALS} materials")));
}
let material =
UserMaterial { density: density(cmd, p)?, appearance: look(cmd, p, &name)?.flatten(), name, physical_card: physical_card(cmd, p)?.flatten() };
let out = reply(cmd, material_reply(cmd, &material)?)?;
s.doc_mut().user_materials.push(material);
Ok(out)
}
/// Which configuration columns hold materials.
fn material_columns(s: &Session) -> Vec<bool> {
s.doc.configs.columns.iter().map(|c| matches!(c, Column::Material(_))).collect()
}
/// Where material `name` is used: bodies, and configuration rows with a cell naming it.
fn uses(s: &Session, name: &str) -> (Vec<String>, Vec<String>) {
let bodies = s.doc.materials.iter().filter(|(_, m)| m.eq_ignore_ascii_case(name)).map(|(b, _)| b.clone()).collect();
let columns = material_columns(s);
let rows = s
.doc
.configs
.rows
.iter()
.filter(|r| r.cells.iter().zip(&columns).any(|(cell, material)| *material && cell.trim().eq_ignore_ascii_case(name)))
.map(|r| r.name.clone())
.collect();
(bodies, rows)
}
/// Point every use of material `from` (body assignments, configuration cells) at `to`
/// ([`DEFAULT_MATERIAL`] removes the body assignments).
fn move_uses(s: &mut Session, from: &str, to: &str) {
let columns = material_columns(s);
let d = s.doc_mut();
let bodies: Vec<String> = d.materials.iter().filter(|(_, m)| m.eq_ignore_ascii_case(from)).map(|(b, _)| b.clone()).collect();
for b in bodies {
if to == DEFAULT_MATERIAL {
d.materials.remove(&b);
} else {
d.materials.insert(b, to.to_string());
}
}
for row in &mut d.configs.rows {
for (cell, material) in row.cells.iter_mut().zip(&columns) {
if *material && cell.trim().eq_ignore_ascii_case(from) {
*cell = to.to_string();
}
}
}
}
fn edit(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "material.edit";
let i = existing(s, cmd, p)?;
let old = s.doc.user_materials.get(i).cloned().ok_or_else(|| bad(cmd, "no such material"))?;
let name = match str_(p, "name") {
Some(n) => new_name(s, cmd, n, Some(&old.name))?,
None => old.name.clone(),
};
let density = if p.get("density_g_cm3").is_some() { density(cmd, p)? } else { old.density };
let appearance = match look(cmd, p, &name)? {
Some(l) => l,
// A colour named after the material keeps following its name.
None => old.appearance.clone().map(|mut l| {
if l.name == old.name {
l.name = name.clone();
}
l
}),
};
let physical_card = physical_card(cmd, p)?.unwrap_or(old.physical_card);
let material = UserMaterial { name: name.clone(), density, appearance, physical_card };
let mut out = material_reply(cmd, &material)?;
if let Some(m) = s.doc_mut().user_materials.get_mut(i) {
*m = material;
}
if name != old.name {
move_uses(s, &old.name, &name);
}
out.bodies = Some(uses(s, &name).0);
reply(cmd, out)
}
fn delete(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "material.delete";
let i = existing(s, cmd, p)?;
let name = s.doc.user_materials.get(i).map(|m| m.name.clone()).ok_or_else(|| bad(cmd, "no such material"))?;
let (bodies, rows) = uses(s, &name);
let replace = match str_(p, "replace") {
Some(r) => {
let r = s.doc.material_name(r).ok_or_else(|| bad(cmd, format!("unknown material `{r}` (see material.list)")))?;
if r.eq_ignore_ascii_case(&name) {
return Err(bad(cmd, "`replace` must be another material"));
}
Some(r)
}
None if bodies.is_empty() && rows.is_empty() => None,
None => {
let mut used: Vec<String> =
bodies.iter().map(|b| format!("body `{b}`")).chain(rows.iter().map(|r| format!("configuration `{r}`"))).collect();
if used.len() > 10 {
let more = used.len() - 10;
used.truncate(10);
used.push(format!("{more} more"));
}
return Err(bad(cmd, format!("`{name}` is used by {}: give `replace` (a material for them)", used.join(", "))));
}
};
if let Some(r) = &replace {
move_uses(s, &name, r);
}
s.doc_mut().user_materials.remove(i);
reply(cmd, MaterialDeleted { deleted: name, replaced_by: replace, bodies, param_warnings: Vec::new() })
}