SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Agents and scripts: the render stage commands (Ground, Backdrop, Clear) describe their exact parameters and reply (#11455) (#11456)
austin62jake0fc4cd274739
diff --git a/crates/engine/src/cmd/render.rs b/crates/engine/src/cmd/render.rsindex 64001d6c02..1507342298 100644--- a/crates/engine/src/cmd/render.rs+++ b/crates/engine/src/cmd/render.rs@@ -91,11 +91,17 @@ CommandSpec::new("render.library.preview", "Inspect Original Surface Map", libra.params("id: SURF-*. Returns bounded hash-verified original base-color PNG bytes and source-map fidelity label, not a rendered material thumbnail. No external paths, rendering or document edits."),CommandSpec::new("render.library.physical.prepare", "Prepare Physical Reference", physical_library::prepare).icon("inspect").noundo().doc_only().params("id: named built-in physical profile, name: proposed new material label, acknowledge_reference:true. Read-only loss-aware creation plan using native ValidatedCard admission and one point density; returns source receipts, extended fields and omissions. Does not execute material.create, assign bodies or infer effective-part physics."),-CommandSpec::new("render.stage.ground", "Save Render Ground", staging::ground).icon("render_scene")+CommandSpec::new("render.stage.ground", "Save Render Ground", crate::checked!("render.stage.ground", staging::ground)).icon("render_scene")+ .contract(&staging::GROUND_CONTRACT)+ .output(crate::schema::output_schema_for::<crate::schema::render_stage::StageSaved>).params("name: typed raytrace setup, set?: setup patch, margin_fraction?:0.25, gap_mm?:0.1, reflectance_linear?:[0.18,0.18,0.18], replace_stage?:false. Fits one finite passive ground below the visible product once and saves its physical transforms in one undo. Product AABB separation is rechecked on every render."),-CommandSpec::new("render.stage.backdrop", "Save Physical Render Background", staging::backdrop).icon("render_scene").doc_only()+CommandSpec::new("render.stage.backdrop", "Save Physical Render Background", crate::checked!("render.stage.backdrop", staging::backdrop)).icon("render_scene").doc_only()+ .contract(&staging::BACKDROP_CONTRACT)+ .output(crate::schema::output_schema_for::<crate::schema::render_stage::StageSaved>).params("name: typed raytrace setup, set?: setup patch, kind: floor_wall or cyclorama, reflectance_linear?: [0.18,0.18,0.18], expected_revision: reviewed revision, replace_stage?:false. Fits a finite floor/wall or a 24-strip polygonal cyclorama behind the visible subject using the saved camera azimuth; world +Z up and a minimum one-mm stage envelope. Preserves subject geometry, lighting, output, pose and engineering materials; one undo and rechecked product separation. Not an infinite/analytically smooth/terrain background."),-CommandSpec::new("render.stage.clear", "Remove Render Stage", staging::clear).icon("render_scene").doc_only()+CommandSpec::new("render.stage.clear", "Remove Render Stage", crate::checked!("render.stage.clear", staging::clear)).icon("render_scene").doc_only()+ .contract(&staging::CLEAR_CONTRACT)+ .output(crate::schema::output_schema_for::<crate::schema::render_stage::StageSaved>).params("name: setup, set?: setup patch. Removes saved render-only panels atomically; CAD geometry and lighting are unchanged."),CommandSpec::new("render.library.surface.bind", "Save Surface Binding", surface_bindings::bind).icon("appearance").params("name: GPU setup; set?: setup patch; surface: same input as render.library.surface.prepare; replace?: false. Pins exact source hashes and definition/feature/occurrence identity with local-mm mapping in one undo. No paths, mesh ordinals or physical material changes."),diff --git a/crates/engine/src/cmd/render/staging.rs b/crates/engine/src/cmd/render/staging.rsindex 586434e238..4130f35765 100644--- a/crates/engine/src/cmd/render/staging.rs+++ b/crates/engine/src/cmd/render/staging.rs@@ -1,7 +1,8 @@//! Explicit saved render-only ground. Does not add engineering bodies or material cards.+use crate::schema::TypedContract;+use crate::schema::render_stage::{BackdropKind, BackdropParams, ClearParams, GroundParams, StageSaved};use crate::{Result, Session, params::bad};-use serde::Deserialize;-use serde_json::{Value, json};+use serde_json::Value;use solidcraft_doc::render_settings::{RenderJob, RenderSetup};use solidcraft_render::{ProductScene,@@ -9,49 +10,41 @@ use solidcraft_render::{stage::{Stage, StagePanel},};use std::sync::Arc;-fn patch() -> Value {- json!({})-}-fn margin() -> f64 {- 0.25-}-fn gap() -> f64 {- 0.1-}-fn reflectance() -> [f64; 3] {- [0.18; 3]-}-#[derive(Deserialize)]-#[serde(deny_unknown_fields)]-struct Ground {- name: String,- #[serde(default = "patch")]- set: Value,- #[serde(default = "margin")]- margin_fraction: f64,- #[serde(default = "gap")]- gap_mm: f64,- #[serde(default = "reflectance")]- reflectance_linear: [f64; 3],- #[serde(default)]- replace_stage: bool,-}++pub(super) const GROUND_CONTRACT: TypedContract<GroundParams> = TypedContract::new();+pub(super) const BACKDROP_CONTRACT: TypedContract<BackdropParams> = TypedContract::new();+pub(super) const CLEAR_CONTRACT: TypedContract<ClearParams> = TypedContract::new();+pub(super) fn apply(scene: &mut ProductScene, setup: &RenderSetup, command: &str) -> Result<()> {setup.stage.append_to(scene, &CancelToken::default()).map_err(|e| bad(command, e.to_string()))}-fn save(s: &mut Session, name: String, setup: RenderSetup, command: &str) -> Result<Value> {+fn save(s: &mut Session, name: String, setup: RenderSetup, command: &str) -> Result<StageSaved> {let mut settings = (*s.doc.render).clone();settings.setups.insert(name.clone(), setup.clone());settings.validate().map_err(|e| bad(command, e.to_string()))?;+ let setup = serde_json::to_value(&setup).map_err(|e| bad(command, e.to_string()))?;if settings != *s.doc.render {s.doc_mut().render = Arc::new(settings);}- Ok(json!({"name":name,"setup":setup,"engineering_geometry_unchanged":true,"stage_only":true,- "clearance":"conservative product AABB separation; not a B-rep collision proof"}))+ Ok(StageSaved {+ name,+ setup,+ engineering_geometry_unchanged: true,+ stage_only: true,+ clearance: "conservative product AABB separation; not a B-rep collision proof".into(),+ geometry_kind: None,+ light_transport: None,+ camera_preserved: None,+ limitations: None,+ param_warnings: Vec::new(),+ })+}+fn reply(command: &str, saved: StageSaved) -> Result<Value> {+ serde_json::to_value(saved).map_err(|e| bad(command, e.to_string()))}pub(super) fn ground(s: &mut Session, params: &Value) -> Result<Value> {let command = "render.stage.ground";- let input: Ground = serde_json::from_value(params.clone()).map_err(|e| bad(command, e.to_string()))?;+ let input: GroundParams = serde_json::from_value(params.clone()).map_err(|e| bad(command, e.to_string()))?;if !input.margin_fraction.is_finite()|| !(0.0..=10.0).contains(&input.margin_fraction)|| !input.gap_mm.is_finite()@@ -88,48 +81,22 @@ pub(super) fn ground(s: &mut Session, params: &Value) -> Result<Value> {}]).map_err(|e| bad(command, e.to_string()))?;apply(&mut scene, &setup, command)?;- save(s, input.name, setup, command)-}-#[derive(Deserialize)]-#[serde(deny_unknown_fields)]-struct Clear {- name: String,- #[serde(default = "patch")]- set: Value,+ reply(command, save(s, input.name, setup, command)?)}pub(super) fn clear(s: &mut Session, params: &Value) -> Result<Value> {let command = "render.stage.clear";- let input: Clear = serde_json::from_value(params.clone()).map_err(|e| bad(command, e.to_string()))?;+ let input: ClearParams = serde_json::from_value(params.clone()).map_err(|e| bad(command, e.to_string()))?;let mut setup = super::patched_settings(s, &input.name, &input.set, command)?;setup.stage = Stage::default();- save(s, input.name, setup, command)+ reply(command, save(s, input.name, setup, command)?)}-#[derive(Clone, Copy, Debug, Deserialize)]-#[serde(rename_all = "snake_case")]-enum BackdropKind {- FloorWall,- Cyclorama,-}-#[derive(Deserialize)]-#[serde(deny_unknown_fields)]-struct BackdropInput {- name: String,- #[serde(default = "patch")]- set: Value,- kind: BackdropKind,- #[serde(default = "reflectance")]- reflectance_linear: [f64; 3],- #[serde(default)]- replace_stage: bool,- expected_revision: u64,-}/// Original world-space stage derived from captured subject bounds and the chosen/// camera azimuth. Twenty-four explicit planar strips approximate the round cove;/// it is not an analytic smooth surface, terrain or engineering model operation.pub(super) fn backdrop(s: &mut Session, params: &Value) -> Result<Value> {let command = "render.stage.backdrop";- let input: BackdropInput = serde_json::from_value(params.clone()).map_err(|e| bad(command, e.to_string()))?;+ let input: BackdropParams = serde_json::from_value(params.clone()).map_err(|e| bad(command, e.to_string()))?;if input.expected_revision != s.revision {return Err(bad(command, "the design changed; review the stage again"));}@@ -204,17 +171,20 @@ pub(super) fn backdrop(s: &mut Session, params: &Value) -> Result<Value> {setup.stage = Stage::new(panels).map_err(|e| bad(command, e.to_string()))?;apply(&mut scene, &setup, command)?;let mut result = save(s, input.name, setup, command)?;- result["geometry_kind"] = json!(match input.kind {- BackdropKind::FloorWall => "finite_floor_and_wall",- BackdropKind::Cyclorama => "24_segment_polygonal_cyclorama",- });- result["light_transport"] =- json!("nonemissive world-space stage; receives native lighting and casts reflections/shadows supported by the selected executor");- result["camera_preserved"] = json!(true);- result["limitations"] = json!([- "Finite background, not an infinite floor or a terrain mesh.",- "Cyclorama is an explicit 24-strip polygonal approximation, not a smooth CAD face.",- "No change to HDR, light energy, subject optics, pose or engineering properties."+ result.geometry_kind = Some(+ match input.kind {+ BackdropKind::FloorWall => "finite_floor_and_wall",+ BackdropKind::Cyclorama => "24_segment_polygonal_cyclorama",+ }+ .into(),+ );+ result.light_transport =+ Some("nonemissive world-space stage; receives native lighting and casts reflections/shadows supported by the selected executor".into());+ result.camera_preserved = Some(true);+ result.limitations = Some(vec![+ "Finite background, not an infinite floor or a terrain mesh.".into(),+ "Cyclorama is an explicit 24-strip polygonal approximation, not a smooth CAD face.".into(),+ "No change to HDR, light energy, subject optics, pose or engineering properties.".into(),]);- Ok(result)+ reply(command, result)}diff --git a/crates/engine/src/schema/mod.rs b/crates/engine/src/schema/mod.rsindex a065bd650e..79dd9a7ea3 100644--- a/crates/engine/src/schema/mod.rs+++ b/crates/engine/src/schema/mod.rs@@ -76,6 +76,7 @@ pub mod panels;pub mod print_face;pub mod render;pub mod render_lights;+pub mod render_stage;pub mod render_ui;pub mod section;pub mod sheet;diff --git a/crates/engine/src/schema/render_stage.rs b/crates/engine/src/schema/render_stage.rsnew file mode 100644index 0000000000..2693820284--- /dev/null+++ b/crates/engine/src/schema/render_stage.rs@@ -0,0 +1,145 @@+//! Contracts and result type for the render stage commands in `cmd/render/staging.rs` (#11455).+//! A stage is a set of render-only panels saved with a render setup. The handlers read these+//! same parameter types, so each contract is exactly what its handler takes; like the handlers,+//! a contract refuses unknown keys.++use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};+use serde::{Deserialize, Serialize};+use serde_json::Value;++fn patch() -> Value {+ serde_json::json!({})+}++fn set_schema(_: &mut SchemaGenerator) -> Schema {+ json_schema!({"type": "object", "maxProperties": 13, "default": {}})+}++fn margin() -> f64 {+ 0.25+}++fn gap() -> f64 {+ 0.1+}++fn reflectance() -> [f64; 3] {+ [0.18; 3]+}++/// Fit one ground panel under the visible product, a little below its lowest point, and save+/// it with a render setup in one undo step. The setup must render with the CPU raytracer or the+/// GPU path tracer. The product's clearance from the panel is checked again on every render.+#[derive(Debug, Deserialize, JsonSchema)]+#[serde(deny_unknown_fields)]+pub struct GroundParams {+ /// The render setup, saved or new.+ pub name: String,+ /// Changes to the setup before the ground is fitted, as `render.settings.set` takes them:+ /// an object of at most 13 setup fields. Default: none.+ #[serde(default = "patch")]+ #[schemars(schema_with = "set_schema")]+ pub set: Value,+ /// How far the ground reaches past the product on each side, as a share of the product's+ /// largest size: 0 to 10. Default: 0.25.+ #[serde(default = "margin")]+ #[schemars(range(min = 0.0, max = 10.0))]+ pub margin_fraction: f64,+ /// The gap between the product's lowest point and the ground (mm): 0.0001 to 1000.+ /// Default: 0.1.+ #[serde(default = "gap")]+ #[schemars(range(min = 0.0001, max = 1000.0))]+ pub gap_mm: f64,+ /// How much light the ground reflects, as linear red, green and blue: each 0 to 1.+ /// Default: 0.18 each.+ #[serde(default = "reflectance")]+ pub reflectance_linear: [f64; 3],+ /// Replace a stage the setup already has. Without it, such a setup is refused.+ #[serde(default)]+ pub replace_stage: bool,+}++/// Fit a floor and a wall, or a curved cyclorama of 24 flat strips, behind the visible product,+/// facing the setup's camera, and save it with the render setup in one undo step. The setup+/// must render with the CPU raytracer or the GPU path tracer. World +Z is up. This is a finite+/// background, not an infinite floor or a smooth CAD face.+#[derive(Debug, Deserialize, JsonSchema)]+#[serde(deny_unknown_fields)]+pub struct BackdropParams {+ /// The render setup, saved or new.+ pub name: String,+ /// Changes to the setup before the backdrop is fitted, as `render.settings.set` takes them:+ /// an object of at most 13 setup fields. Default: none.+ #[serde(default = "patch")]+ #[schemars(schema_with = "set_schema")]+ pub set: Value,+ pub kind: BackdropKind,+ /// How much light the panels reflect, as linear red, green and blue: each 0 to 1.+ /// Default: 0.18 each.+ #[serde(default = "reflectance")]+ pub reflectance_linear: [f64; 3],+ /// Replace a stage the setup already has. Without it, such a setup is refused.+ #[serde(default)]+ pub replace_stage: bool,+ /// The design's revision when the caller last read it, as `document.inspect` gives it. If+ /// the design changed since, the call is refused: read it again and retry.+ pub expected_revision: u64,+}++/// The backdrop's shape.+#[derive(Clone, Copy, Debug, Deserialize, JsonSchema)]+#[serde(rename_all = "snake_case")]+pub enum BackdropKind {+ /// A floor and a flat wall.+ FloorWall,+ /// A floor that curves up into the wall, in 24 flat strips.+ Cyclorama,+}++/// Remove the stage from a render setup in one undo step. The design's geometry and the+/// setup's lighting stay as they are.+#[derive(Debug, Deserialize, JsonSchema)]+#[serde(deny_unknown_fields)]+pub struct ClearParams {+ /// The render setup, saved or new.+ pub name: String,+ /// Changes to the setup made with the removal, as `render.settings.set` takes them:+ /// an object of at most 13 setup fields. Default: none.+ #[serde(default = "patch")]+ #[schemars(schema_with = "set_schema")]+ pub set: Value,+}++/// What `render.stage.ground`, `render.stage.backdrop` and `render.stage.clear` return.+#[derive(Debug, Serialize, JsonSchema)]+pub struct StageSaved {+ /// The render setup.+ pub name: String,+ /// The setup as saved, as the render settings commands give it.+ pub setup: Value,+ /// Always true: the design's bodies don't change.+ pub engineering_geometry_unchanged: bool,+ /// Always true: the panels exist only in renders.+ pub stage_only: bool,+ /// How the product's clearance from the panels is checked.+ pub clearance: String,+ /// A backdrop's shape: `finite_floor_and_wall` or `24_segment_polygonal_cyclorama`.+ #[serde(skip_serializing_if = "Option::is_none")]+ pub geometry_kind: Option<String>,+ /// A backdrop's part in the lighting.+ #[serde(skip_serializing_if = "Option::is_none")]+ pub light_transport: Option<String>,+ /// A backdrop: always true, the setup's camera stays as it is.+ #[serde(skip_serializing_if = "Option::is_none")]+ pub camera_preserved: Option<bool>,+ /// A backdrop's limits, in sentences.+ #[serde(skip_serializing_if = "Option::is_none")]+ pub limitations: Option<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 = "render_stage_tests.rs"]+mod tests;diff --git a/crates/engine/src/schema/render_stage_tests.rs b/crates/engine/src/schema/render_stage_tests.rsnew file mode 100644index 0000000000..db14853e64--- /dev/null+++ b/crates/engine/src/schema/render_stage_tests.rs@@ -0,0 +1,99 @@+use serde_json::{Value, json};++use super::{BackdropParams, ClearParams, GroundParams, StageSaved};+use crate::Session;+use crate::schema::tests::{assert_keys, conforms};+use crate::schema::{ParamCheck, input_schema_for, output_schema_for};++/// A design with a box and a saved render setup, `Shot`, that renders with the GPU path tracer,+/// at the parameter-check level `level`.+fn with_a_shot(level: ParamCheck) -> Session {+ let mut s = Session { param_check: level, ..Session::default() };+ for (id, p) in [+ ("solid.box", json!({"length": 20, "width": 15, "height": 10, "body_name": "Subject"})),+ ("render.settings.set", json!({"name": "Shot", "set": {"width": 96, "height": 64, "job": {"method": "gpu_path", "options": {}}}})),+ ] {+ s.execute(id, &p).unwrap_or_else(|e| panic!("{id} {p}: {e}"));+ }+ s+}++#[test]+fn schemas_and_the_key_check_agree() {+ assert_keys(input_schema_for::<GroundParams>(), &["gap_mm", "margin_fraction", "name", "reflectance_linear", "replace_stage", "set"]);+ assert_keys(input_schema_for::<BackdropParams>(), &["expected_revision", "kind", "name", "reflectance_linear", "replace_stage", "set"]);+ assert_keys(input_schema_for::<ClearParams>(), &["name", "set"]);+}++/// The handlers refuse these calls after reading them; strict refuses them with their message.+/// They need a design with a body and a saved setup, and the design's revision, so the shared+/// helper, which has a sketch only, doesn't fit.+#[test]+fn strict_keeps_todays_errors() {+ let cases: [(&str, fn(u64) -> Value); 12] = [+ ("render.stage.ground", |_| json!({"name": "Shot", "margin_fraction": 11})),+ ("render.stage.ground", |_| json!({"name": "Shot", "gap_mm": 0})),+ ("render.stage.ground", |_| json!({"name": "Shot", "reflectance_linear": [2, 0, 0]})),+ ("render.stage.ground", |_| json!({"name": "Raster"})),+ ("render.stage.ground", |_| json!({"name": " Shot"})),+ ("render.stage.ground", |_| json!({"name": "Shot", "set": {"width": 0}})),+ ("render.stage.backdrop", |_| json!({"name": "Shot", "kind": "cyclorama", "expected_revision": 999_999})),+ ("render.stage.backdrop", |r| json!({"name": "Raster", "kind": "floor_wall", "expected_revision": r})),+ ("render.stage.backdrop", |r| json!({"name": "Shot", "kind": "floor_wall", "reflectance_linear": [0, -1, 0], "expected_revision": r})),+ ("render.stage.clear", |_| json!({"name": ""})),+ ("render.stage.clear", |_| json!({"name": "Shot", "set": {"width": 0}})),+ ("render.stage.clear", |_| json!({"name": "Shot", "set": 5})),+ ];+ for (id, p) in cases {+ let error = |level: ParamCheck| {+ let mut s = with_a_shot(level);+ let p = p(s.revision);+ s.execute(id, &p).err().map(|e| e.to_string())+ };+ let off = error(ParamCheck::Off);+ assert!(off.is_some(), "{id} {} should fail today", p(0));+ assert_eq!(error(ParamCheck::Strict), off, "{id} {}", p(0));+ }+ // A stage already there needs `replace_stage`, for a ground and a backdrop alike.+ for level in [ParamCheck::Off, ParamCheck::Strict] {+ let mut s = with_a_shot(level);+ s.execute("render.stage.ground", &json!({"name": "Shot"})).unwrap_or_else(|e| panic!("{e}"));+ let ground = s.execute("render.stage.ground", &json!({"name": "Shot"})).err().map(|e| e.to_string());+ let p = json!({"name": "Shot", "kind": "floor_wall", "expected_revision": s.revision});+ let backdrop = s.execute("render.stage.backdrop", &p).err().map(|e| e.to_string());+ for error in [ground, backdrop] {+ assert!(error.as_deref().is_some_and(|e| e.contains("replace_stage: true")), "{level:?}: {error:?}");+ }+ }+}++/// #11455: a ground, both backdrops and a clear reply as the output schema says, in Warn+/// without warnings; only a backdrop carries its shape and limits. Like the handlers, warn and+/// strict refuse a misspelt key.+#[test]+fn stage_commands_reply_with_their_schema() {+ let schema = output_schema_for::<StageSaved>();+ let schema = schema.as_value();+ let mut s = with_a_shot(ParamCheck::Warn);+ let run = |s: &mut Session, id: &str, p: Value| {+ let r = s.execute(id, &p).unwrap_or_else(|e| panic!("{id} {p}: {e}"));+ assert!(conforms(schema, schema, &r), "{r} doesn't match {schema}");+ assert!(r.get("param_warnings").is_none(), "{r}");+ r+ };+ let p = json!({"name": "Shot", "set": {}, "margin_fraction": 0.5, "gap_mm": 1, "reflectance_linear": [0.2, 0.2, 0.2], "replace_stage": false});+ let r = run(&mut s, "render.stage.ground", p);+ assert!(r["setup"].is_object() && r.get("geometry_kind").is_none(), "{r}");+ for kind in ["floor_wall", "cyclorama"] {+ let revision = s.revision;+ let p = json!({"name": "Shot", "kind": kind, "replace_stage": true, "expected_revision": revision});+ let r = run(&mut s, "render.stage.backdrop", p);+ assert!(r["geometry_kind"].is_string() && r["limitations"].is_array(), "{r}");+ }+ run(&mut s, "render.stage.clear", json!({"name": "Shot", "set": {}}));+ for level in [ParamCheck::Warn, ParamCheck::Strict] {+ let mut s = with_a_shot(level);+ let error = s.execute("render.stage.clear", &json!({"nme": "Shot"})).err().map(|e| e.to_string()).unwrap_or_default();+ assert!(error.contains("nme"), "{level:?}: {error}");+ }+}diff --git a/crates/engine/src/schema/unconverted.txt b/crates/engine/src/schema/unconverted.txtindex 46f048b6ec..5f1bf092bc 100644--- a/crates/engine/src/schema/unconverted.txt+++ b/crates/engine/src/schema/unconverted.txt@@ -181,9 +181,6 @@ render.settings.setrender.shot.duplicaterender.shot.removerender.shot.rename-render.stage.backdrop-render.stage.clear-render.stage.groundrender.startrender.statusselect.clear