Skip to content

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

Typed schemas for Appearance, Appearance Library and List Appearances (part of #2829) (#10976)

semmelrinde2741df36291f
diff --git a/crates/engine/src/cmd/inspect.rs b/crates/engine/src/cmd/inspect.rs
index 48fa4f6740..7a14270127 100644
--- a/crates/engine/src/cmd/inspect.rs
+++ b/crates/engine/src/cmd/inspect.rs
@@ -69,7 +69,13 @@ pub static COMMANDS: &[CommandSpec] = &[
.at("SOLID", "MODIFY")
.icon("material")
.params("bodies: [names]; material: name (Steel, Aluminum, ABS Plastic, …, or one made with material.create; `material.list`)"),
- CommandSpec::new("appearance.assign", "Appearance", appearance).at("SOLID", "MODIFY").icon("appearance").key("A").params(
+ CommandSpec::new("appearance.assign", "Appearance", crate::checked!("appearance.assign", appearance))
+ .at("SOLID", "MODIFY")
+ .icon("appearance")
+ .key("A")
+ .contract(&ASSIGN_CONTRACT)
+ .output(crate::schema::output_schema_for::<AppearanceAssignResult>)
+ .params(
"bodies?: [names]; faces?: [[x,y,z] on faces] (body?: which body, default the nearest); components?: [names or ids, or occurrence names]; \
appearance?: library name or stable starter.* ID (appearance.library) | color: \"#rrggbb\" or [r, g, b] (0–255), opacity? (0–1, default 1); \
name?: inert copied look label (requires color, mutually exclusive with appearance); pbr?: {metallic:0..1, roughness:0.045..1, dielectric_ior:1..3} (requires color/appearance and opacity 1); a starter ID or registered starter name resolves its recipe before color overrides; omitted pbr retains that response and pbr: null explicitly clears it. Unavailable glass recipes refuse through either selector. Other custom labels with an explicit color retain legacy scalar behavior. Neither appearance nor color (or color: null): clear, so the face follows its body, the body its component, the component its material",
@@ -86,11 +92,17 @@ pub static COMMANDS: &[CommandSpec] = &[
CommandSpec::new("appearance.replace", "Replace Appearance", appearance_chain::replace).icon("appearance").params(
"from: library name | saved look {name,color,opacity,pbr?} (copy appearance.list in_design); to: library name | assignment look {appearance? | color, name?, opacity?, pbr?} (appearance.assign rules; no clear). Matches the full look including name and PBR. scope?: {bodies?: [names], components?: [names or ids]} (a placed copy's name means the body or component it shows), at most 10000 targets; body scope includes face overrides, component scope selects only the component override. Omitted scope means all overrides, including hidden/suppressed ones; physical defaults are unchanged. Duplicate targets count once. Returns count of rewritten overrides; zero adds no history. One undo step, atomic; no dialogs. Designs above 100000 overrides refuse",
),
- CommandSpec::new("appearance.library", "Appearance Library", appearance_library).icon("library")
+ CommandSpec::new("appearance.library", "Appearance Library", crate::checked!("appearance.library", appearance_library))
+ .icon("library")
.noundo()
+ .contract(&LIBRARY_CONTRACT)
+ .output(crate::schema::output_schema_for::<AppearanceLibraryResult>)
.params("→ 20 legacy scalar appearances, six opaque PBR finishes and 40 starter recipes with IDs, categories, provenance, requirements and availability; six starter glass recipes are unavailable"),
- CommandSpec::new("appearance.list", "List Appearances", appearance_list).icon("list")
+ CommandSpec::new("appearance.list", "List Appearances", crate::checked!("appearance.list", appearance_list))
+ .icon("list")
.noundo()
+ .contract(&LIST_CONTRACT)
+ .output(crate::schema::output_schema_for::<AppearanceListResult>)
.params("body?: name (or a placed copy's, `KB (K:2)`: the body it shows) → assigned appearances; with body, its resolved look and its faces' (face index, look)"),
CommandSpec::new("material.list", "List Materials", material_list).icon("list")
.noundo()
@@ -531,7 +543,7 @@ fn physical_material(s: &mut Session, p: &Value) -> Result<Value> {
}
/// A colour parameter: `"#rrggbb"` or `[r, g, b]` (0–255).
-pub(super) fn color_param(v: &Value) -> Option<[u8; 3]> {
+pub(crate) fn color_param(v: &Value) -> Option<[u8; 3]> {
if let Some(t) = v.as_str() {
let h = t.trim().trim_start_matches('#');
if h.len() != 6 || !h.is_ascii() {
@@ -545,6 +557,21 @@ pub(super) fn color_param(v: &Value) -> Option<[u8; 3]> {
Some([c(0)?, c(1)?, c(2)?])
}
+use crate::schema::appearance::{
+ AppearanceAssignParams, AppearanceAssignResult, AppearanceLibraryParams, AppearanceLibraryResult, AppearanceListParams, AppearanceListResult,
+ BodyLooks, ComponentLookReply, FaceIndexLook, FaceLookReply, FaceSpot, LibraryAppearance, LookInDesign, LookReply, PbrReply, PlainAppearance,
+ StarterAppearance,
+};
+
+const ASSIGN_CONTRACT: TypedContract<AppearanceAssignParams> = TypedContract::new();
+const LIBRARY_CONTRACT: TypedContract<AppearanceLibraryParams> = TypedContract::new();
+const LIST_CONTRACT: TypedContract<AppearanceListParams> = TypedContract::new();
+
+/// An appearance command's reply, built from its schema's type so the two can't drift apart.
+fn appearance_reply(cmd: &str, r: impl serde::Serialize) -> Result<Value> {
+ serde_json::to_value(r).map_err(|e| bad(cmd, e.to_string()))
+}
+
pub(super) fn appearance(s: &mut Session, p: &Value) -> Result<Value> {
use solidcraft_doc::appearance::FaceLook;
let cmd = "appearance.assign";
@@ -639,12 +666,9 @@ pub(super) fn appearance(s: &mut Session, p: &Value) -> Result<Value> {
})
});
}
- Ok(json!({
- "bodies": bodies,
- "faces": faces.iter().map(|(b, p)| json!({"body": b, "point": p})).collect::<Vec<_>>(),
- "components": comps,
- "appearance": look.as_ref().map(look_json),
- }))
+ let faces = faces.iter().map(|(body, p)| FaceSpot { body: body.clone(), point: [p.x, p.y, p.z] }).collect();
+ let appearance = look.as_ref().map(LookReply::from);
+ appearance_reply(cmd, AppearanceAssignResult { bodies, faces, components: comps, appearance, param_warnings: Vec::new() })
}
/// Shared look parser for assignment and atomic replacement.
@@ -766,35 +790,45 @@ pub(super) fn attach_pbr(cmd: &str, params: &Value, look: &mut solidcraft_doc::a
}
fn appearance_library(_s: &mut Session, _p: &Value) -> Result<Value> {
- let mut list: Vec<Value> = solidcraft_doc::appearance::LIBRARY
+ let category = |name: &str| name.split(" - ").next().unwrap_or(name).to_string();
+ let mut list: Vec<LibraryAppearance> = solidcraft_doc::appearance::LIBRARY
.iter()
.map(|(n, c, o)| {
- let category = n.split(" - ").next().unwrap_or(n);
- json!({"name": n, "category": category, "color": format!("#{:02x}{:02x}{:02x}", c[0], c[1], c[2]), "opacity": o})
+ let look = LookReply { name: n.to_string(), color: format!("#{:02x}{:02x}{:02x}", c[0], c[1], c[2]), opacity: *o, pbr: None };
+ LibraryAppearance::Plain(PlainAppearance { look, category: category(n) })
})
.collect();
list.extend(solidcraft_doc::appearance::OPAQUE_FINISHES.iter().filter_map(|(name, ..)| {
let look = solidcraft_doc::appearance::library(name)?;
- let mut value = look_json(&look);
- value["category"] = json!(name.split(" - ").next().unwrap_or(name));
- Some(value)
+ Some(LibraryAppearance::Plain(PlainAppearance { look: LookReply::from(&look), category: category(name) }))
}));
for preset in solidcraft_doc::appearance_pack::STARTER_PACK {
let c = preset.preview_color();
- let pbr = preset.opaque_look().ok().and_then(|look| look.pbr);
- list.push(json!({"id":preset.id,"name":preset.name,"category":preset.category,"revision":preset.revision,
- "color":format!("#{:02x}{:02x}{:02x}",c[0],c[1],c[2]),"opacity":1.0,"pbr":pbr,
- "available":preset.is_opaque(),"requirements":preset.requirements,"provenance":preset.provenance,
- "recipe":preset.recipe,"preview_note":preset.preview_note,"future_texture_recipe":preset.future_texture_recipe}));
+ list.push(LibraryAppearance::Starter(StarterAppearance {
+ id: preset.id.to_string(),
+ name: preset.name.to_string(),
+ category: json!(preset.category),
+ revision: preset.revision,
+ color: format!("#{:02x}{:02x}{:02x}", c[0], c[1], c[2]),
+ opacity: 1.0,
+ pbr: preset.opaque_look().ok().and_then(|look| look.pbr).map(PbrReply::from),
+ available: preset.is_opaque(),
+ requirements: json!(preset.requirements),
+ provenance: json!(preset.provenance),
+ recipe: json!(preset.recipe),
+ preview_note: preset.preview_note.to_string(),
+ future_texture_recipe: json!(preset.future_texture_recipe),
+ }));
}
- Ok(json!({"appearances": list}))
+ appearance_reply("appearance.library", AppearanceLibraryResult { appearances: list, param_warnings: Vec::new() })
}
fn appearance_list(s: &mut Session, p: &Value) -> Result<Value> {
let a = &s.doc.appearances;
// "In this design": each look used, with where.
- let mut used: Vec<(solidcraft_doc::appearance::Look, Vec<Value>, Vec<Value>, Vec<Value>)> = Vec::new();
- fn slot(used: &mut Vec<(solidcraft_doc::appearance::Look, Vec<Value>, Vec<Value>, Vec<Value>)>, l: &solidcraft_doc::appearance::Look) -> usize {
+ type Used = Vec<(solidcraft_doc::appearance::Look, Vec<String>, Vec<FaceSpot>, Vec<u64>)>;
+ let mut used: Used = Vec::new();
+ fn slot(used: &mut Used, l: &solidcraft_doc::appearance::Look) -> usize {
match used.iter().position(|(u, ..)| u == l) {
Some(i) => i,
None => {
@@ -806,51 +840,49 @@ fn appearance_list(s: &mut Session, p: &Value) -> Result<Value> {
for (b, l) in &a.bodies {
let i = slot(&mut used, l);
if let Some(u) = used.get_mut(i) {
- u.1.push(json!(b));
+ u.1.push(b.clone());
}
}
for f in &a.faces {
let i = slot(&mut used, &f.look);
if let Some(u) = used.get_mut(i) {
- u.2.push(json!({"body": f.body, "point": f.point}));
+ u.2.push(FaceSpot { body: f.body.clone(), point: [f.point.x, f.point.y, f.point.z] });
}
}
for (c, l) in &a.components {
let i = slot(&mut used, l);
if let Some(u) = used.get_mut(i) {
- u.3.push(json!(c));
+ u.3.push(*c);
}
}
- let in_design: Vec<Value> = used
- .iter()
- .map(|(l, b, f, c)| {
- let mut value = look_json(l);
- value["bodies"] = json!(b);
- value["faces"] = json!(f);
- value["components"] = json!(c);
- value
- })
- .collect();
- let mut out = json!({
- "in_design": in_design,
- "bodies": a.bodies.iter().map(|(b, l)| (b.clone(), look_json(l))).collect::<serde_json::Map<_, _>>(),
- "faces": a.faces.iter().map(|f| json!({"body": f.body, "point": f.point, "appearance": look_json(&f.look)})).collect::<Vec<_>>(),
- "components": a.components.iter().map(|(c, l)| json!({"component": c, "appearance": look_json(l)})).collect::<Vec<_>>(),
- });
+ let in_design =
+ used.into_iter().map(|(l, bodies, faces, components)| LookInDesign { look: LookReply::from(&l), bodies, faces, components }).collect();
+ let mut out = AppearanceListResult {
+ in_design,
+ bodies: a.bodies.iter().map(|(b, l)| (b.clone(), LookReply::from(l))).collect(),
+ faces: a
+ .faces
+ .iter()
+ .map(|f| FaceLookReply { body: f.body.clone(), point: [f.point.x, f.point.y, f.point.z], appearance: LookReply::from(&f.look) })
+ .collect(),
+ components: a.components.iter().map(|(c, l)| ComponentLookReply { component: *c, appearance: LookReply::from(l) }).collect(),
+ body: None,
+ param_warnings: Vec::new(),
+ };
if let Some(name) = str_(p, "body") {
let st = s.model.state();
// A placed copy's name (`KB (K:2)`) means the body it shows, as appearance.assign takes
// it (#9740): the reply names that body.
let own = s.own_body_name(name);
let b = own.as_deref().and_then(|n| st.body(n)).ok_or_else(|| bad("appearance.list", format!("no body `{name}`")))?;
- out["body"] = json!({
- "name": b.name,
- "appearance": s.doc.model_body_look(b).map(|l| look_json(&l)),
- "color": s.doc.body_color(b),
- "faces": s.doc.face_colors(b).iter().map(|(i, l)| json!({"face": i, "appearance": look_json(l)})).collect::<Vec<_>>(),
+ out.body = Some(BodyLooks {
+ name: b.name.clone(),
+ appearance: s.doc.model_body_look(b).as_ref().map(LookReply::from),
+ color: s.doc.body_color(b),
+ faces: s.doc.face_colors(b).iter().map(|(i, l)| FaceIndexLook { face: *i, appearance: LookReply::from(l) }).collect(),
});
}
- Ok(out)
+ appearance_reply("appearance.list", out)
}
fn material_list(s: &mut Session, _p: &Value) -> Result<Value> {
diff --git a/crates/engine/src/schema/appearance.rs b/crates/engine/src/schema/appearance.rs
new file mode 100644
index 0000000000..ef18ad14f2
--- /dev/null
+++ b/crates/engine/src/schema/appearance.rs
@@ -0,0 +1,384 @@
+//! Contracts and result types for the appearance commands in `cmd/inspect.rs`:
+//! `appearance.assign`, `appearance.library` and `appearance.list`.
+
+use std::borrow::Cow;
+use std::collections::BTreeMap;
+
+use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
+use serde::de::Error as _;
+use serde::{Deserialize, Deserializer, Serialize};
+use serde_json::{Value, json};
+use solidcraft_doc::appearance::Look;
+use solidcraft_doc::pbr_appearance::PbrParameters;
+
+use super::check::whole;
+use super::types::{Point3, StringList};
+use crate::params;
+
+/// Give bodies, faces or components a look, or clear theirs: a library appearance or a starter
+/// recipe by `appearance`, or a `color`. With neither (or `color: null`) the targets' own looks
+/// are cleared, so a face follows its body, a body its component and a component its material.
+/// One undo step; no dialogs.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppearanceAssignParams {
+ /// Bodies, by name (a placed copy's name, `KB (K:2)`, means the body it shows).
+ #[serde(default)]
+ pub bodies: Option<StringList>,
+ /// Faces, by a point on each, at most 10000.
+ #[serde(default)]
+ pub faces: Option<FaceSpots>,
+ /// The body the `faces` points are on, for points that don't name one. Default: the
+ /// nearest body with a face there.
+ #[serde(default)]
+ pub body: Option<String>,
+ /// Components, by name or id, or a placement's name (`K:2`).
+ #[serde(default)]
+ pub components: Option<StringList>,
+ /// A library appearance's name or a starter recipe's name or stable `starter.*` id (see
+ /// `appearance.library`). With `color` too, that colour under this name. A recipe that
+ /// needs refraction (the glass ones) is refused.
+ #[serde(default)]
+ pub appearance: Option<String>,
+ /// The colour, `"#rrggbb"` or `[r, g, b]` (0–255); with `appearance`, it replaces the
+ /// recipe's colour. `null` (without `appearance`) clears the targets' looks.
+ #[serde(default)]
+ pub color: Option<ColorParam>,
+ /// 0 (clear) to 1 (opaque). Default: 1, or the appearance's own. With `color` alone it
+ /// must be within 0–1; with `appearance` it is clamped there.
+ #[serde(default)]
+ pub opacity: Option<f64>,
+ /// A label for a copied look: needs `color`, not with `appearance`.
+ #[serde(default)]
+ pub name: Option<LookLabel>,
+ /// The opaque PBR response (needs `color` or `appearance`, and opacity 1). Left out, a
+ /// recipe keeps its own; `null` clears it.
+ #[serde(default)]
+ pub pbr: Option<PbrParam>,
+}
+
+/// `appearance.assign`'s `faces`: at most 10000 points, each `[x, y, z]` (or `{x, y, z}`) or
+/// `{"point": [x, y, z], "body": name}`, read as the handler reads them.
+#[derive(Clone, Debug, PartialEq)]
+pub struct FaceSpots(pub Vec<Value>);
+
+impl<'de> Deserialize<'de> for FaceSpots {
+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ let fail = || D::Error::custom("must list points [x, y, z]");
+ let list = match Value::deserialize(d)? {
+ Value::Array(list) if list.len() <= 10_000 => list,
+ _ => return Err(fail()),
+ };
+ let point = |v: &Value| params::vec3(v).or_else(|| v.get("point").and_then(params::vec3));
+ if list.iter().all(|v| point(v).is_some()) { Ok(FaceSpots(list)) } else { Err(fail()) }
+ }
+}
+
+impl JsonSchema for FaceSpots {
+ fn schema_name() -> Cow<'static, str> {
+ "FaceSpots".into()
+ }
+ fn json_schema(generator: &mut SchemaGenerator) -> Schema {
+ let point = generator.subschema_for::<Point3>();
+ let on_body = json!({
+ "type": "object",
+ "properties": {"point": point, "body": {"type": "string"}},
+ "required": ["point"]
+ });
+ json_schema!({
+ "description": "Points in mm, one on each face: [x, y, z], or {\"point\": [x, y, z], \"body\": name} to say which body.",
+ "type": "array",
+ "items": {"anyOf": [point, on_body]},
+ "maxItems": 10000
+ })
+ }
+}
+
+/// A colour, `"#rrggbb"` (the `#` optional) or `[r, g, b]` of numbers 0–255, as
+/// `inspect::color_param` reads it.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct ColorParam(pub [u8; 3]);
+
+impl<'de> Deserialize<'de> for ColorParam {
+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ crate::cmd::inspect::color_param(&Value::deserialize(d)?)
+ .map(ColorParam)
+ .ok_or_else(|| D::Error::custom("must be \"#rrggbb\" or [r, g, b] with values 0–255"))
+ }
+}
+
+impl JsonSchema for ColorParam {
+ fn schema_name() -> Cow<'static, str> {
+ "Color".into()
+ }
+ fn json_schema(_: &mut SchemaGenerator) -> Schema {
+ let channel = json!({"type": "number", "minimum": 0, "maximum": 255});
+ json_schema!({
+ "description": "A colour: \"#rrggbb\" or [r, g, b] with values 0–255.",
+ "anyOf": [
+ {"type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$"},
+ {"type": "array", "items": channel, "minItems": 3, "maxItems": 3}
+ ]
+ })
+ }
+}
+
+/// A copied look's label: 1 to 128 characters, none of them a control character.
+#[derive(Clone, Debug, PartialEq)]
+pub struct LookLabel(pub String);
+
+impl<'de> Deserialize<'de> for LookLabel {
+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ match Value::deserialize(d)? {
+ Value::String(s) if !s.is_empty() && s.chars().count() <= 128 && !s.chars().any(char::is_control) => Ok(LookLabel(s)),
+ _ => Err(D::Error::custom("must be a nonempty label of at most 128 characters without controls")),
+ }
+ }
+}
+
+impl JsonSchema for LookLabel {
+ fn schema_name() -> Cow<'static, str> {
+ "LookLabel".into()
+ }
+ fn json_schema(_: &mut SchemaGenerator) -> Schema {
+ json_schema!({
+ "description": "A label for a copied look, without control characters.",
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 128
+ })
+ }
+}
+
+/// An opaque PBR response, exactly `metallic`, `roughness` and `dielectric_ior`, checked as
+/// the handler checks it (`attach_pbr`), with its messages.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct PbrParam(pub PbrParameters);
+
+impl<'de> Deserialize<'de> for PbrParam {
+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+ let value = Value::deserialize(d)?;
+ let object = value
+ .as_object()
+ .filter(|o| o.len() == 3 && o.keys().all(|k| matches!(k.as_str(), "metallic" | "roughness" | "dielectric_ior")))
+ .ok_or_else(|| D::Error::custom(whole("`pbr` requires exactly metallic, roughness and dielectric_ior")))?;
+ let number = |key: &str| {
+ object.get(key).and_then(Value::as_f64).ok_or_else(|| D::Error::custom(whole(format!("`pbr.{key}` must be a finite number"))))
+ };
+ PbrParameters::new(number("metallic")?, number("roughness")?, number("dielectric_ior")?).map(PbrParam).map_err(|e| D::Error::custom(whole(e)))
+ }
+}
+
+impl JsonSchema for PbrParam {
+ fn schema_name() -> Cow<'static, str> {
+ "PbrParameters".into()
+ }
+ fn json_schema(_: &mut SchemaGenerator) -> Schema {
+ json_schema!({
+ "description": "An opaque PBR response.",
+ "type": "object",
+ "properties": {
+ "metallic": {"type": "number", "minimum": 0, "maximum": 1},
+ "roughness": {"type": "number", "minimum": 0.045, "maximum": 1},
+ "dielectric_ior": {"type": "number", "minimum": 1, "maximum": 3}
+ },
+ "required": ["metallic", "roughness", "dielectric_ior"],
+ "additionalProperties": false
+ })
+ }
+}
+
+/// A look's PBR response, as the appearance commands report it.
+#[derive(Clone, Copy, Debug, Serialize, JsonSchema)]
+pub struct PbrReply {
+ pub metallic: f64,
+ pub roughness: f64,
+ pub dielectric_ior: f64,
+}
+
+impl From<PbrParameters> for PbrReply {
+ fn from(p: PbrParameters) -> Self {
+ PbrReply { metallic: p.metallic(), roughness: p.roughness(), dielectric_ior: p.dielectric_ior() }
+ }
+}
+
+/// A look, as the appearance commands report it.
+#[derive(Clone, Debug, Serialize, JsonSchema)]
+pub struct LookReply {
+ /// The library appearance's or recipe's name, or the look's label (`Custom` for a plain
+ /// colour).
+ pub name: String,
+ /// `"#rrggbb"`.
+ pub color: String,
+ /// 0 (clear) to 1 (opaque).
+ pub opacity: f64,
+ /// Its opaque PBR response, when it has one.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub pbr: Option<PbrReply>,
+}
+
+impl From<&Look> for LookReply {
+ fn from(l: &Look) -> Self {
+ LookReply { name: l.name.clone(), color: l.hex(), opacity: l.opacity, pbr: l.pbr.map(PbrReply::from) }
+ }
+}
+
+/// A face with a look of its own: its body and the point on it the look was given at.
+#[derive(Clone, Debug, Serialize, JsonSchema)]
+pub struct FaceSpot {
+ pub body: String,
+ /// `[x, y, z]` in mm.
+ pub point: [f64; 3],
+}
+
+/// What `appearance.assign` returns: the targets, and the look they got (`null`: cleared).
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct AppearanceAssignResult {
+ pub bodies: Vec<String>,
+ pub faces: Vec<FaceSpot>,
+ /// The components, by id.
+ pub components: Vec<u64>,
+ pub appearance: Option<LookReply>,
+ /// 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>,
+}
+
+/// `appearance.library` takes no parameters.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppearanceLibraryParams {}
+
+/// What `appearance.library` returns: every appearance `appearance.assign` takes by name.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct AppearanceLibraryResult {
+ pub appearances: Vec<LibraryAppearance>,
+ /// 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>,
+}
+
+/// One library entry: a plain appearance or finish, or a starter recipe.
+#[derive(Debug, Serialize, JsonSchema)]
+#[serde(untagged)]
+pub enum LibraryAppearance {
+ Plain(PlainAppearance),
+ Starter(StarterAppearance),
+}
+
+/// A legacy scalar appearance, or an opaque PBR finish (which has `pbr`).
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct PlainAppearance {
+ #[serde(flatten)]
+ pub look: LookReply,
+ /// The part of the name before ` - `, such as `Aluminum`.
+ pub category: String,
+}
+
+/// A starter recipe: its look, where it comes from and what showing it needs.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct StarterAppearance {
+ /// Its stable id, `starter.*`, which `appearance.assign` takes as `appearance`.
+ pub id: String,
+ pub name: String,
+ /// wood, metal, plastic, glass, solar or regolith.
+ pub category: Value,
+ pub revision: u32,
+ /// Its preview colour, `"#rrggbb"`.
+ pub color: String,
+ pub opacity: f64,
+ /// Its opaque PBR response; `null` for a recipe that has none (glass).
+ pub pbr: Option<PbrReply>,
+ /// False for a recipe this build can't show (the glass ones need refraction).
+ pub available: bool,
+ /// What showing it needs: opaque_pbr, refraction, certified_thin_or_closed.
+ pub requirements: Value,
+ /// Who made it and under which licence: {author, license, source, kind}.
+ pub provenance: Value,
+ /// Its optical recipe: {kind: opaque, color, metallic, roughness, dielectric_ior} or
+ /// {kind: glass, dielectric_ior, transmission_linear_rgb, reference_path_mm, boundary}.
+ pub recipe: Value,
+ pub preview_note: String,
+ /// The texture it is meant to get later ({id, repeat_mm, grain_axis}), or `null`.
+ pub future_texture_recipe: Value,
+}
+
+/// `appearance.list` takes one parameter, `body`, optional.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppearanceListParams {
+ /// A body (or a placed copy's name, `KB (K:2)`, for the body it shows): the reply adds
+ /// `body`, its resolved look and its faces' looks.
+ #[serde(default)]
+ pub body: Option<String>,
+}
+
+/// What `appearance.list` returns: the looks the design assigns, by look and by target.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct AppearanceListResult {
+ /// Each look the design uses, with where it is used.
+ pub in_design: Vec<LookInDesign>,
+ /// The bodies with a look of their own, by name.
+ pub bodies: BTreeMap<String, LookReply>,
+ /// The faces with a look of their own.
+ pub faces: Vec<FaceLookReply>,
+ /// The components with a look of their own.
+ pub components: Vec<ComponentLookReply>,
+ /// With `body`: that body's resolved look and its faces'.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub body: Option<BodyLooks>,
+ /// 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>,
+}
+
+/// A look the design uses, and the bodies, faces and components it is given to.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct LookInDesign {
+ #[serde(flatten)]
+ pub look: LookReply,
+ pub bodies: Vec<String>,
+ pub faces: Vec<FaceSpot>,
+ /// Components, by id.
+ pub components: Vec<u64>,
+}
+
+/// A face's own look.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct FaceLookReply {
+ pub body: String,
+ /// `[x, y, z]` in mm: the point the look was given at.
+ pub point: [f64; 3],
+ pub appearance: LookReply,
+}
+
+/// A component's own look.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct ComponentLookReply {
+ /// The component's id.
+ pub component: u64,
+ pub appearance: LookReply,
+}
+
+/// A body's resolved look and its faces' looks.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct BodyLooks {
+ pub name: String,
+ /// The look it shows (its own, else its component's, else its material's), or `null`.
+ pub appearance: Option<LookReply>,
+ /// The colour it is drawn in, `[r, g, b]` from 0 to 1, or `null` for the default.
+ pub color: Option<[f32; 3]>,
+ /// Its faces with a look (their own or imported), by face index.
+ pub faces: Vec<FaceIndexLook>,
+}
+
+/// A face's look, by the face's index in `model.faces`.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct FaceIndexLook {
+ pub face: usize,
+ pub appearance: LookReply,
+}
+
+#[cfg(test)]
+#[path = "appearance_tests.rs"]
+mod tests;
diff --git a/crates/engine/src/schema/appearance_tests.rs b/crates/engine/src/schema/appearance_tests.rs
new file mode 100644
index 0000000000..c25e7aa124
--- /dev/null
+++ b/crates/engine/src/schema/appearance_tests.rs
@@ -0,0 +1,82 @@
+use serde_json::{Value, json};
+
+use super::{
+ AppearanceAssignParams, AppearanceAssignResult, AppearanceLibraryParams, AppearanceLibraryResult, AppearanceListParams, AppearanceListResult,
+};
+use crate::Session;
+use crate::schema::tests::{assert_keys, assert_strict_keeps_todays_errors, conforms};
+use crate::schema::{ParamCheck, input_schema_for, output_schema_for};
+
+#[test]
+fn schemas_and_the_key_check_agree() {
+ assert_keys(
+ input_schema_for::<AppearanceAssignParams>(),
+ &["appearance", "bodies", "body", "color", "components", "faces", "name", "opacity", "pbr"],
+ );
+ assert_keys(input_schema_for::<AppearanceLibraryParams>(), &[]);
+ assert_keys(input_schema_for::<AppearanceListParams>(), &["body"]);
+}
+
+#[test]
+fn strict_keeps_todays_errors() {
+ assert_strict_keeps_todays_errors(&[
+ ("appearance.assign", json!({"faces": [[1, 2]]})),
+ ("appearance.assign", json!({"faces": [{"body": "Box1"}]})),
+ ("appearance.assign", json!({"color": "red"})),
+ ("appearance.assign", json!({"color": [0, 128, 300]})),
+ ("appearance.assign", json!({"color": "#ff0000", "name": ""})),
+ ("appearance.assign", json!({"color": "#ff0000", "pbr": {"metallic": 1}})),
+ ("appearance.assign", json!({"color": "#ff0000", "pbr": {"metallic": "1", "roughness": 0.5, "dielectric_ior": 1.5}})),
+ ("appearance.assign", json!({"color": "#ff0000", "pbr": {"metallic": 2, "roughness": 0.5, "dielectric_ior": 1.5}})),
+ ]);
+}
+
+/// A library look, a starter recipe, a colour with PBR on a face, a cleared body, the library
+/// and the list with and without `body`, in Warn: each reply matches its output schema and
+/// carries no warning; a misspelt key's warning still matches.
+#[test]
+fn replies_match_the_output_schema() {
+ let mut s = Session { param_check: ParamCheck::Warn, ..Session::default() };
+ let mut run = |id: &str, p: Value| s.execute(id, &p).unwrap_or_else(|e| panic!("{id} {p}: {e}"));
+ let matches = |schema: schemars::Schema, id: &str, reply: &Value| {
+ let schema = schema.as_value();
+ assert!(conforms(schema, schema, reply), "{id}: {reply} doesn't match {schema}");
+ };
+ let assigned = |reply: &Value| {
+ assert!(reply.get("param_warnings").is_none(), "{reply}");
+ matches(output_schema_for::<AppearanceAssignResult>(), "appearance.assign", reply);
+ };
+ let made = run("solid.box", json!({"length": 10, "width": 10, "height": 10, "corner": [0, 0, 0]}));
+ let body = made["created_bodies"][0].as_str().unwrap_or_default().to_string();
+ let library = run("appearance.library", json!({}));
+ assert!(library.get("param_warnings").is_none(), "{library}");
+ matches(output_schema_for::<AppearanceLibraryResult>(), "appearance.library", &library);
+ let entries = library["appearances"].as_array().cloned().unwrap_or_default();
+ let named = |pick: &dyn Fn(&Value) -> bool| entries.iter().find(|e| pick(e)).and_then(|e| e["name"].as_str()).unwrap_or_default().to_string();
+ let plain = named(&|e| e.get("id").is_none() && e.get("pbr").is_none());
+ let finish = named(&|e| e.get("id").is_none() && e.get("pbr").is_some());
+ let starter = entries.iter().find(|e| e["available"] == true).and_then(|e| e["id"].as_str()).unwrap_or_default().to_string();
+ assert!(!plain.is_empty() && !finish.is_empty() && !starter.is_empty(), "{library}");
+ assigned(&run("appearance.assign", json!({"bodies": [body], "appearance": plain, "opacity": 0.5})));
+ assigned(&run("appearance.assign", json!({"bodies": body, "appearance": finish})));
+ assigned(&run("appearance.assign", json!({"bodies": [body], "appearance": starter})));
+ let face = run(
+ "appearance.assign",
+ json!({"faces": [{"point": [5, 5, 10], "body": body}], "color": [200, 40, 40], "name": "Signal red",
+ "pbr": {"metallic": 0, "roughness": 0.4, "dielectric_ior": 1.5}}),
+ );
+ assert_eq!(face["faces"][0]["point"], json!([5.0, 5.0, 10.0]), "{face}");
+ assigned(&face);
+ let all = run("appearance.list", json!({}));
+ assert!(all.get("param_warnings").is_none() && all.get("body").is_none(), "{all}");
+ matches(output_schema_for::<AppearanceListResult>(), "appearance.list", &all);
+ let one = run("appearance.list", json!({"body": body}));
+ assert_eq!(one["body"]["faces"].as_array().map(Vec::len), Some(1), "{one}");
+ matches(output_schema_for::<AppearanceListResult>(), "appearance.list", &one);
+ let cleared = run("appearance.assign", json!({"bodies": [body]}));
+ assert!(cleared["appearance"].is_null(), "{cleared}");
+ assigned(&cleared);
+ let warned = run("appearance.list", json!({"bodyy": body}));
+ assert!(warned["param_warnings"].as_array().is_some_and(|w| !w.is_empty()), "{warned}");
+ matches(output_schema_for::<AppearanceListResult>(), "appearance.list", &warned);
+}
diff --git a/crates/engine/src/schema/mod.rs b/crates/engine/src/schema/mod.rs
index 655e62acb9..2981f17f74 100644
--- a/crates/engine/src/schema/mod.rs
+++ b/crates/engine/src/schema/mod.rs
@@ -54,6 +54,7 @@ mod coverage_tests;
mod tests;
// The contracts, by command file.
+pub mod appearance;
pub mod bom;
pub mod browser;
pub mod component;
diff --git a/crates/engine/src/schema/unconverted.txt b/crates/engine/src/schema/unconverted.txt
index f987993805..0d2ceb3497 100644
--- a/crates/engine/src/schema/unconverted.txt
+++ b/crates/engine/src/schema/unconverted.txt
@@ -2,9 +2,6 @@
# (coverage_tests.rs). This list only shrinks: when you give a command its contract and output
# type, remove its line. Never add one: a new command comes with both schemas. Sorted, one id
# per line.
-appearance.assign
-appearance.library
-appearance.list
body.rename
browser.collapse_all
browser.expand_all