SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Physical material data cards
material.properties.validate {card} checks a caller-supplied candidate record,
without assigning it, saving it in the design, reading files, fetching sources or
changing history, selection, camera or live geometry. material.create/edit can
also keep a validated card in a design-owned physical material. Saved cards use
the same schema and validator; density used for mass and visual appearance remain
separate. This implements the persistence slice of #1060 under #923/#922/#785.
Validation means numerical and structural consistency. It does not authenticate
sources, approve redistribution, certify design values, provide a solver or enable
advanced rendering. The result reports analysis_solver_available: false and
rendering_properties_available: false. Missing properties remain unknown.
Design-owned cards
| Command | Engineering-card behavior |
|---|---|
material.create |
Accepts optional physical_card; omitted or null leaves engineering properties unspecified. density_g_cm3 remains required. |
material.edit |
An omitted physical_card retains the complete saved card; an object replaces it atomically; null clears it. |
material.inspect |
Takes material: name and returns one built-in or design-owned material, its density/default look and any saved card, validation and density comparison. Read-only. |
material.list |
Retains the 14 built-in density rows and includes engineering details for design-owned materials that have a card. Read-only. |
material.properties.validate |
Reviews a supplied candidate without saving or assigning it. |
The physical_card value is the schema-1 card object described below. Its typed
wrapper revalidates input during commands and deserialization. Invalid data refuses
before changes to the material name, body/configuration references, assigned
density, appearance or undo history. Renaming, optical edits and density-only
edits retain an omitted card. Undo/redo, native save and cold reopening preserve
source claims, per-property conditions and SI values.
Mass continues to use the material's density_g_cm3, including the existing
generic built-ins. A card density in kg_m3 never changes assigned density
implicitly. When both exist, inspection reports their values in kg/m³, their
absolute relative difference divided by the larger value, and whether that
difference is at most 1e-9. This is a consistency report, not a decision about
which density applies. Appearance/PBR changes do not change a card, and a card
does not supply optical properties or mechanical axes for a body.
New files declare the physical-material-cards pending format change. Older
designs without a card need no data migration and retain unspecified engineering
properties. The last released reader refuses the newer format; a pending build
without this descriptor refuses the unknown change. No historical format number
or previous migration is repurposed.
Engineering constants such as elastic moduli can exceed the geometry coordinate
bound. The separate SI admission path applies only to a root
user_materials[].physical_card; similarly named fields elsewhere do not bypass
geometry checks. Normal loading and commands both bound user-defined materials
to 1,000, in addition to the card limits below. Existing document metadata keeps
its separate handling.
The portable solidcraft-library/2 catalog preserves physical cards, their sources
and conditions, and independent PBR default appearances. The scalar v1 reader remains
supported; explicit v1 export refuses any card or PBR loss before writing, including
empty cards whose designation/source information matters. See local material
libraries for copy, collision, file and size contracts.
Contract (standalone card schema 1)
Candidate review window
Search for Validate Physical Material Data in the command palette (or use
ui.start with material.properties.validate) to open the candidate reviewer.
Paste a schema-1 card object and choose Review card. The existing engine
validator checks it; the window shows known properties in SI units, unknown
properties, per-property conditions and source claims as inert text. Material-local
axes do not assign a frame to a body. Isotropic G/K come from the engine report.
Editing the input clears the previous review. Invalid input shows its refusal without retaining a stale valid result. Input is capped at 262,144 characters and 256 KiB before JSON parsing; the validator's tighter structural and text budgets still apply. The window does not read files, fetch references, assign properties, replace density, modify history or save the candidate. Close discards it. Calling the engine's JSON command still returns its report without opening a dialog.
Saved cards can be reviewed and edited in the existing Physical Material assignment panel. Select a design-owned material and expand Properties to review it, or choose Edit to edit its fields. New starts a blank material; Duplicate copies the selected built-in or design-owned material into an independent user material. Built-ins remain immutable. Assigned density is shown separately in g/cm³ and controls mass; card density is in kg/m³ and does not change that assigned density.
The graphical draft has optional engineering properties, all nine property types, isotropic and orthotropic elasticity, material-local axes, source metadata and per-property temperature, moisture, strain rate and state. Numeric fields show SI units and accept scientific notation. Missing properties and empty optional conditions remain unknown. Adding a property leaves its required values blank; Save refuses incomplete or invalid constants rather than creating measured data. Source IDs remain stable in the form; source titles, type, license and reference are editable. Sources still in use cannot be removed. Changing elasticity model clears its numeric draft fields and requires explicit values for the new model.
Save runs one material.create or material.edit command and keeps that change
with normal undo/redo, without assigning the material to any selected body.
Cancel closes the panel and discards only an unsaved draft; it never rolls back
a previous Save. Discard leaves the panel open and drops the current draft.
While a draft is open, footer OK and assignment through Enter are blocked. After
saving or discarding, OK retains the existing explicit body-assignment behavior.
Edits omit unchanged fields, preserving every saved source, condition, anisotropic constant and visual appearance, including PBR. An unchanged Save creates no undo entry. A changed material is refused if another command altered it while the draft was open. Duplicates copy optical scalar/PBR values; their owned appearance name follows the new material name. No new window, JSON editor, persistent format, solver or measured material dataset is introduced by the graphical form.
Numerical validation is visible before Save and the engine validates again at commit. Source/license claims remain unverified. Runtime checks and real UI captures are required in the integration gate; this documentation does not imply that a numerical card is engineering certification.
Local file import remains a separate operation. No dataset or rendering capability is supplied by reviewing or saving a card.
A card has schema_version: 1, designation, family (wood, polymer, glass,
metal, other), sources and properties. Source IDs are exact, case-sensitive
local references. Each source has id, title, kind (user_supplied,
measurement, public_reference, illustrative), optional license and
reference strings. These strings are metadata supplied by the caller; even a
declared open license remains in source_review_required. Nothing is downloaded.
Every property has data, source_id and optional conditions. Conditions are
temperature_k, moisture_dry_basis_kg_kg, strain_rate_per_s and a free-text
state (grade, temper, processing or specimen condition). Conditions belong to
the property, not an assumed global room temperature. An elastic block represents
constants measured under the same conditions and source; mixed-condition curves
and independently sourced constants need a later representation.
data.kind |
Explicit SI fields |
|---|---|
density |
kg_m3 |
elasticity |
model, described below |
tensile_strength, compressive_strength, yield_strength, shear_strength |
pa |
thermal_conductivity |
w_m_k: [k1,k2,k3], axes |
thermal_expansion |
per_k: [a1,a2,a3], axes |
specific_heat |
j_kg_k |
Directional values use axes: material123 (material-local 1/2/3) or wood_lrt
(longitudinal/radial/tangential). These labels do not assign a frame to a body or
infer mechanical orientation from texture rotation. Equal directional values can
describe an isotropic thermal property. Thermal expansion may be zero or negative.
An isotropic elastic model has symmetry: isotropic, young_modulus_pa and
poisson_ratio. Stability requires E > 0 and -1 < nu < 0.5. Valid auxetic values
are accepted. The result derives G = E/[2(1+nu)] and K = E/[3(1-2nu)], in Pa.
An orthotropic model has symmetry: orthotropic, axes,
young_moduli_pa: [E1,E2,E3], shear_moduli_pa: [G12,G23,G31] and
poisson_ratios: [nu12,nu23,nu31]. Here nu_ij = -eps_j/eps_i under stress along i;
reciprocity supplies nu_ij/Ei = nu_ji/Ej. The normal compliance is symmetric with
diagonal 1/Ei and off-diagonal -nu_ij/Ei. Diagonal scaling produces unit diagonal;
Sylvester's criterion checks its positive definiteness. All three shear moduli
must be positive. General orthotropic Poisson ratios are not capped at 0.5.
Moduli whose reciprocals cannot be represented finitely are rejected; the
isotropic derived response and its reciprocals must also remain finite/positive.
Moisture is kg water / kg dry material and can exceed one. It is not a wet-mass
fraction. Unspecified temperature/state, wood moisture or polymer strain rate are
reported in unspecified_conditions; they are not guessed or replaced by zero.
The validation report also returns missing_condition_fields, a map from each
incomplete property kind to its exact absent field names. Temperature and state
apply to every family; wood additionally checks dry-basis moisture and polymers
strain rate, following the same reporting policy as unspecified_conditions.
For example, a wood density with temperature and state but no moisture reports
{"density":["moisture_dry_basis_kg_kg"]}. Complete properties are omitted;
an empty card returns an empty map, without inventing properties or conditions.
This detail is read-only and does not change admission or the saved card schema.
Older serialized validation reports without the map deserialize with an empty
map; regenerate validation from the card to obtain the missing-field detail.
The family label does not certify that a chosen constitutive model fits a material.
Scalar strengths are individual measurements, not a three-dimensional failure
envelope. Typed strength directions and test methods remain a separate extension.
Admission limits
Before cloning/deserializing JSON: at most 2,048 nodes, depth 12, 32 array entries or object fields and a 256 KiB conservative accounting budget (32 bytes per node plus string/key bytes). The typed record allows 32 sources and 16 properties; duplicate source IDs or property kinds and unknown fields are rejected.
Text limits in UTF-8 bytes: designation/title 256, source ID 128, license 512, reference 2,048 and state 1,024; controls and blank text are rejected. All numeric values must be finite. Positive-value upper admission limits are density 1e6 kg/m³, moduli/strengths 1e15 Pa, conductivity 1e9 W/(m K), heat capacity 1e9 J/(kg K), temperature 20,000 K and strain rate 1e12 /s. Expansion is within ±1 /K, dry-basis moisture within [0,1e6] (also accommodating highly hydrated polymers), orthotropic Poisson ratios within ±1e6 in addition to the compliance stability test. These are generous technical admission limits, not measured applicability ranges or a conditioning guarantee for a future solver.
Original synthetic example
These deliberately invented constants demonstrate validation, not a real grade:
{
"card": {
"schema_version": 1,
"designation": "Synthetic elastic example — not design data",
"family": "other",
"sources": [{
"id": "example",
"title": "Original synthetic example",
"kind": "illustrative",
"license": "MIT OR Apache-2.0"
}],
"properties": [{
"data": {
"kind": "elasticity",
"model": {"symmetry": "isotropic", "young_modulus_pa": 12000000000, "poisson_ratio": 0.25}
},
"source_id": "example"
}]
}
}
The result has G = 4.8e9 Pa, K = 8e9 Pa, unspecified conditions and source review still required. No assigned mass, saved material or appearance changes.
Next phases and references
Portable engineering-card catalog v2 copies the validated records above. Scalar v1 remains a strict compatibility format. Curves, uncertainty, hardness scales, viscoelasticity and failure criteria remain later work. Visual PBR/texture/environment consumption uses the renderer contract requested in #813, with #909/#837 input utilities; accepting physical data advertises none of those capabilities.
The USDA Wood Handbook, including chapter 4's dry-mass moisture definition, is a public scientific reference for moisture, mechanical behavior and the distinction between specimen properties and graded design values. No handbook data/table is bundled. The Khronos PBR material model is a reference for the separate optical track. No third-party code, engineering dataset or asset is added by this implementation.
Directional elasticity query
material.properties.directional {card, direction: [x,y,z]} reports Young's modulus
in Pa for a uniaxial, small-strain constitutive test along a material-local direction.
It returns the safely normalized direction, declared axes (null for isotropy), and
the full validation/source/condition report. It neither assigns axes to a body nor
predicts a part's displacement, failure, strength or safety factor. No solver or
render capability is enabled. Missing elasticity refuses instead of inventing data.
For orthotropy, let n=(x,y,z) be the unit direction. With engineering shear compliance 1/G and the reciprocal Poisson convention above:
1/E(n) = x^4/E1 + y^4/E2 + z^4/E3
+ x²y²(1/G12 - 2 nu12/E1)
+ y²z²(1/G23 - 2 nu23/E2)
+ z²x²(1/G31 - 2 nu31/E3).
This follows by applying stress sigma = n tensor n, computing strain with the symmetric compliance, then contracting n with strain and n. The implementation uses a Cholesky sum of squares for the normal contribution, avoiding cancellation between the positive diagonal and negative coupling terms. Shear contributions are also nonnegative. Isotropy returns E directly, independent of orientation.
Input directions must contain exactly three finite numbers and be nonzero; arbitrary magnitude is allowed. Max-component scaling avoids overflow or underflow while normalizing very large or tiny vectors. Unrepresentable compliance/modulus refuses; this finite-precision check does not establish a condition-number certificate. The card's test conditions still apply; changing direction does not extrapolate temperature, moisture, process, rate, damage or nonlinear behavior. Synthetic analytic tests cover principal axes, the isotropic limit and off-axis shear/coupling terms. No physical dataset or external implementation is included.
Design-owned persistence
material.create accepts an optional physical_card; omission or null means
unknown. material.edit retains an omitted card, validates and replaces a supplied
card, and clears it only with explicit null. Density-only, appearance-only and
rename edits retain the card. Assignment, configurations, undo/redo and Paste New
keep using the same design-owned material definition.
material.list reports the optional card, its validation report and a density
comparison. Assigned density in g/cm3 and recorded density in kg/m3 stay separate:
card data never silently changes the density used for mass. Source and condition
claims are preserved, not certified, and this does not add an analysis solver.
The single pending descriptor is material-engineering-cards.rs. The build
assigns the pending format automatically; no released number, history or migration
is edited. Older designs keep absent cards as unknown. Older readers refuse the
newer saved format rather than silently losing engineering records.
Only user_materials[].physical_card receives the typed SI admission needed for
elastic moduli above coordinate limits. Other numeric/depth limits, including the
second range check after integer-valued coordinates become typed floats, remain
unchanged. Normal loading admits at most 1000 design-owned materials.
Scalar catalog v1 refuses cards before creating or replacing an export file.
Rich catalog transport is the separate #1086 contribution. The synthetic example
examples/material-card.json uses an assigned density of 0.8 g/cm3, a recorded
700 kg/m3 and invented isotropic constants; it is not a real material dataset.