SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Contracts and result types for the render binding commands (#11741): a body of a render setup
//! bound to a library surface's maps (`cmd/render/surface_bindings.rs`) or to optical numbers
//! (`cmd/render/optical_bindings.rs`). The handlers read these same parameter types, so each
//! contract is exactly what its handler takes; like the handlers, a contract refuses unknown
//! keys.
//!
//! Three parameters keep their own readers, and their schemas here are written by hand:
//! - `target` and `optics` are the doc crate's `RenderBodyTarget` and `OpticalMaterial`, which
//! don't derive `JsonSchema` (the doc crate doesn't depend on schemars).
//! - `surface` is passed on whole to `render.library.surface.prepare`, which checks it.
use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use solidcraft_doc::render_optics::OpticalMaterial;
use solidcraft_doc::render_surface::RenderBodyTarget;
/// `set`'s default: no change to the setup.
fn no_change() -> Value {
serde_json::json!({})
}
/// `set`: changes to the setup, as `render.settings.set` takes them. `patched_settings` in
/// `cmd/render.rs` refuses anything but an object of at most 13 fields, with its own message.
/// The fields of a render setup, as `render.settings.get` gives them. A `set` patch may give up
/// to 13 of them; `patched_settings` reads the patched setup as a `RenderSetup`, which refuses any
/// other key.
const SETUP_FIELDS: &[&str] = &[
"backend",
"mode",
"camera",
"width",
"height",
"format",
"exposure_ev",
"environment_rotation",
"environment_intensity",
"background",
"job",
"surfaces",
"optics",
"stage",
];
/// Each setup field, without its own schema: `patched_settings` checks the values.
fn setup_properties() -> serde_json::Map<String, Value> {
SETUP_FIELDS.iter().map(|field| (field.to_string(), Value::Object(serde_json::Map::new()))).collect()
}
fn set_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({
"description": "Changes to the setup made with the binding, as `render.settings.set` takes them: at most 13 of the setup's fields. Default: none.",
"type": "object",
"properties": setup_properties(),
"additionalProperties": false,
"maxProperties": 13,
"default": {}
})
}
/// A body of the design, by the identity a render setup keeps for it: its definition, the
/// feature that made it, and the component occurrence it's in. The ids survive a rebuild, so a
/// binding follows the body, and never another body that took its place in the list.
fn target_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({
"description": "A body, by the identity a render setup keeps for it, as the setup's `surfaces` or `optics` list gives it. A component and its occurrence path are both 0 and empty for a body outside components.",
"type": "object",
"properties": {
"definition": {"description": "The design or component definition that holds the body: 1 to 1024 bytes, without control characters.", "type": "string"},
"feature": {"description": "The id of the feature that made the body: 1 or more.", "type": "integer", "minimum": 1},
"component": {"description": "The id of the component the body is in, or 0 outside components.", "type": "integer", "minimum": 0},
"occurrence_path": {"description": "The occurrence ids from the top of the design down to the body's occurrence, each 1 or more and none twice; empty outside components.", "type": "array", "items": {"type": "integer", "minimum": 1}}
},
"required": ["definition", "feature", "component", "occurrence_path"],
"additionalProperties": false
})
}
/// Optical numbers for a body, as `solidcraft_doc::render_optics::OpticalMaterial` reads them.
/// Every field has a default, so `{}` is clear glass with a refractive index of 1.5.
fn optics_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({
"description": "The body's optical numbers, for the CPU or GPU renderer. Each field has a default: `{}` is clear glass with a refractive index of 1.5. These are render-only numbers, not an engineering material.",
"type": "object",
"properties": {
"ior": {"description": "Refractive index. Default: 1.5.", "type": "number"},
"absorption_per_mm": {"description": "How much light the inside absorbs per mm, as linear red, green and blue: each 0 or more. Default: none.", "type": "array", "items": {"type": "number", "minimum": 0}, "minItems": 3, "maxItems": 3},
"boundary": {"description": "How the body's surface bounds the medium: `thin_sheet` (a sheet of `thickness_mm`), `closed_box` or `closed_mesh` (the thickness comes from the geometry). Default: closed_mesh.", "type": "string", "enum": ["thin_sheet", "closed_box", "closed_mesh"]},
"thickness_mm": {"description": "A thin sheet's thickness (mm); 0 for a closed boundary. Default: 0.", "type": "number", "minimum": 0},
"shadow_transmission": {"description": "Let light through for shadows too. Default: false.", "type": "boolean"},
"model": {
"description": "Advanced Glass interface. Default: null (no model). A model requires the interface IOR to stay in [1, 3], including the full 380 to 780 nm range when dispersion is enabled.",
"type": ["object", "null"],
"default": null,
"properties": {
"roughness": {
"description": "Isotropic roughness, from 0 (smooth) to 1. Very small positive values can exceed transport precision. Default: 0.",
"type": "number", "minimum": 0, "maximum": 1, "default": 0
},
"dispersion": {
"description": "Three-band chromatic dispersion. Default: null (no dispersion).",
"type": ["object", "null"],
"default": null,
"properties": {
"abbe_number": {"description": "Abbe number, from 5 to 200.", "type": "number", "minimum": 5, "maximum": 200}
},
"required": ["abbe_number"],
"additionalProperties": false
},
"thin_film": {
"description": "One lossless film. Default: null (no film).",
"type": ["object", "null"],
"default": null,
"properties": {
"ior": {"description": "Film refractive index, from 1 to 3.", "type": "number", "minimum": 1, "maximum": 3},
"thickness_nm": {"description": "Film thickness in nm, from 0 to 100000. Zero has no film effect.", "type": "number", "minimum": 0, "maximum": 100000}
},
"required": ["ior", "thickness_nm"],
"additionalProperties": false
}
},
"additionalProperties": false
},
"subsurface": {
"description": "Light scattering inside the body, as in wax or skin; `null` for none. Default: none.",
"anyOf": [
{
"type": "object",
"properties": {
"scattering_per_mm": {"description": "How often light scatters per mm: 0 to 100.", "type": "number", "minimum": 0, "maximum": 100},
"anisotropy": {"description": "Which way it scatters: -0.95 (back) to 0.95 (forward). Default: 0, every way alike.", "type": "number", "minimum": -0.95, "maximum": 0.95}
},
"required": ["scattering_per_mm"],
"additionalProperties": false
},
{"type": "null"}
]
}
},
"additionalProperties": false
})
}
/// `surface`: a library surface placed on a body, exactly as `render.library.surface.prepare`
/// takes it. That command isn't converted yet, so its keys are described here.
fn surface_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({
"description": "The library surface and where it goes on the body, as `render.library.surface.prepare` takes it.",
"type": "object",
"properties": {
"id": {"description": "The surface: `SURF-` and its number, as `render.library.list` gives it.", "type": "string"},
"body_index": {"description": "The body's place in the render scene, from 0, as `render.library.targets` gives it.", "type": "integer", "minimum": 0},
"body_name": {"description": "The body's name at that place, as `render.library.targets` gives it; a body that moved in the list is refused.", "type": "string"},
"origin": {"description": "Where the maps start, in mm, as [x, y, z]. Default: the centre of the body's bounding box.", "type": ["array", "null"], "items": {"type": "number"}, "minItems": 3, "maxItems": 3},
"plane": {"description": "The plane the maps lie in: `xy`, `yz` or `zx`. Default: xy.", "type": "string", "enum": ["xy", "yz", "zx"]},
"scale": {"description": "How much larger than authored the maps repeat: 0.001 to 1000. Default: 1.", "type": "number", "minimum": 0.001, "maximum": 1000}
},
"required": ["id", "body_index", "body_name"],
"additionalProperties": false
})
}
/// Bind a body of a render setup to a library surface's authored maps, for the CPU or GPU renderer,
/// in one undo step. The binding keeps the maps' exact source hashes and the body's identity,
/// mapped in the body's own millimetres, so it follows the body when it moves. Needs a build with
/// the bundled render library and a CPU or GPU setup.
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct SurfaceBindParams {
/// The render setup, saved or new.
pub name: String,
#[schemars(schema_with = "surface_schema")]
pub surface: Value,
#[serde(default = "no_change")]
#[schemars(schema_with = "set_schema")]
pub set: Value,
/// Replace a binding the body already has. Without it, such a body is refused.
#[serde(default)]
pub replace: bool,
}
/// Remove one body's surface binding from a render setup, in one undo step. The design's
/// geometry, and any render device, aren't needed.
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct SurfaceUnbindParams {
/// The render setup.
pub name: String,
#[schemars(schema_with = "target_schema")]
pub target: RenderBodyTarget,
#[serde(default = "no_change")]
#[schemars(schema_with = "set_schema")]
pub set: Value,
}
/// Bind a body of a render setup to optical numbers (glass, tinted media, subsurface
/// scattering), for the CPU or GPU renderer, in one undo step. The design's geometry and engineering
/// materials don't change. The setup may render on the CPU or GPU.
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct OpticsBindParams {
/// The render setup, saved or new.
pub name: String,
#[serde(default = "no_change")]
#[schemars(schema_with = "set_schema")]
pub set: Value,
/// The body's place in the render scene, from 0, as `render.library.targets` gives it.
pub body_index: usize,
/// The body's name at that place; a body that moved in the list is refused.
pub body_name: String,
#[schemars(schema_with = "optics_schema")]
pub optics: OpticalMaterial,
/// 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,
/// Replace optics the body already has. Without it, such a body is refused.
#[serde(default)]
pub replace: bool,
}
/// Remove one body's optical binding from a saved render setup, in one undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct OpticsUnbindParams {
/// The saved render setup.
pub name: String,
#[schemars(schema_with = "target_schema")]
pub target: RenderBodyTarget,
/// 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,
}
/// What `render.library.surface.bind` and `render.library.surface.unbind` return.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SurfaceBindingSaved {
/// The render setup.
pub name: String,
/// The setup as saved, as the render settings commands give it.
pub setup: Value,
/// Always `definition_local_mm`: the maps are placed in the body's own millimetres.
pub mapping_space: String,
/// Always true: the design's geometry and physical materials don't change.
pub geometry_and_physical_materials_unchanged: bool,
/// 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>,
}
/// What `render.optics.bind` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct OpticsBindingSaved {
/// 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 geometry and engineering data don't change.
pub geometry_and_engineering_unchanged: bool,
/// What the image producer checks before it draws the body: closed topology and nested
/// containment.
pub certification: 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>,
}
/// What `render.optics.unbind` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct OpticsUnbound {
/// The render setup.
pub name: String,
/// Whether the body had optics to remove; `false` leaves the setup as it was.
pub removed: bool,
/// 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_bindings_tests.rs"]
mod tests;