SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Render shell requests. The UI applies validated echoes without design edits.
use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::{Value, json};
use std::borrow::Cow;
use super::check::whole;
use solidcore_record::{Vec2, Vec3};
use solidcraft_geom::Vec3Geom;
use super::types::{CameraParam, present};
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RenderDock {
pub panel: RenderPanel,
pub side: DockSide,
}
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum RenderPanel {
Inspector,
Browser,
}
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum DockSide {
Left,
Right,
}
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RenderFocus {
/// Hide the Render docks while retaining their layout and the current camera.
pub on: bool,
}
/// Pause or resume the current document's live Render preview without saving a setup.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RenderLive {
/// True pauses refinement; false resumes it using the current visual settings.
pub paused: bool,
}
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RenderBrowser {
/// Open the floating Browser card in a narrow Render window.
pub open: bool,
}
/// Latch or release the viewport's Zoom tool. With no flag, the UI toggles it.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ZoomTool {
#[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "bool")]
pub on: Option<bool>,
}
/// Empty input for the read-only viewport effect query.
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct StatusItemsParams {}
/// Show or hide the View angles readout under the orientation gizmo (#6032): the view's pitch, yaw
/// and roll in degrees (the angles of `view.apply`'s camera, which takes them in radians) and Ortho
/// or Persp for the projection. A display setting the app keeps: not saved with the design, not an
/// undo step, and it never opens a dialog.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct AngleReadoutParams {
/// True shows the readout, false hides it.
#[serde(deserialize_with = "enabled_flag")]
pub enabled: bool,
}
/// A boolean, with the `view.angle_readout` handler's message for anything else.
fn enabled_flag<'de, D: serde::Deserializer<'de>>(d: D) -> Result<bool, D::Error> {
match Value::deserialize(d)? {
Value::Bool(b) => Ok(b),
_ => Err(serde::de::Error::custom("must be a boolean")),
}
}
/// What `view.angle_readout` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct AngleReadoutResult {
/// Whether the readout is shown now.
pub enabled: 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>,
}
/// Turn the view to the command's standard orientation (front, back, left, right, top, bottom
/// or isometric), as the view cube does, keeping the camera's target, distance, projection and
/// up axis. Display only: the design isn't changed and nothing is added to undo.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct StandardViewParams {
/// The camera to turn. Default: the session's camera, or the home view when there is none.
#[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "CameraParam")]
pub camera: Option<CameraParam>,
}
/// Look straight at the first selected planar face or plane, centred on the point it was picked
/// at (a plane: its origin); asked again while already facing it, look from the other side.
/// Keeps the camera's distance, projection and up axis. Needs a planar face or plane in the
/// selection. Display only: the design isn't changed and nothing is added to undo.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct NormalToParams {
/// The camera to turn. Default: the session's camera, or the home view when there is none.
/// Its yaw and roll must also be within ±1e6 and its pitch within ±π/2.
#[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "CameraParam")]
pub camera: Option<CameraParam>,
}
/// What the standard views and `view.normal_to` return: the camera after the turn, which the
/// session keeps as its view.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CameraReply {
/// The camera now.
#[schemars(with = "CameraParam")]
pub camera: solidcraft_render::Camera,
/// 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>,
}
/// `view.next_tab` and `view.previous_tab` take no parameters (#8565).
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct TabStepParams {}
/// What `view.next_tab` and `view.previous_tab` return. The window shows the design tab `step`
/// places along the strip, going round at either end; the design is not changed and nothing is
/// added to undo.
#[derive(Debug, Serialize, JsonSchema)]
pub struct TabStep {
/// 1: the tab to the right; -1: the tab to the left.
pub step: i8,
/// 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>,
}
/// `view.ribbon_tabs_only`: fold the ribbon to its tab row, or show it whole (#10112).
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RibbonTabsOnlyParams {
/// True folds the ribbon to its tab row, false shows it whole; omitted switches between the two.
#[serde(default)]
pub on: Option<bool>,
}
/// What `view.ribbon_tabs_only` returns: the request echoed. The window applies it to its
/// preference; the design is not changed and nothing is added to undo.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RibbonTabsOnly {
/// The requested state; absent when the call asked to switch.
#[serde(skip_serializing_if = "Option::is_none")]
pub on: Option<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>,
}
/// Validated request and echoed result of `view.render_select`.
#[derive(Debug, Serialize)]
pub struct RenderSelect {
pub kind: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub id: Option<String>,
}
impl<'de> Deserialize<'de> for RenderSelect {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Request {
kind: String,
id: Option<String>,
}
let request = Request::deserialize(d)?;
let identified = matches!(request.kind.as_str(), "light" | "shot");
if !matches!(
request.kind.as_str(),
"nothing" | "environment" | "lighting" | "light" | "shot" | "output" | "wear" | "sampling" | "effects" | "check"
) || identified != request.id.is_some()
|| request.id.as_ref().is_some_and(|id| id.trim().is_empty() || id.len() > 1024)
{
return Err(serde::de::Error::custom("expected a Browser kind and an id only for light or shot"));
}
Ok(Self { kind: request.kind, id: request.id })
}
}
impl JsonSchema for RenderSelect {
fn schema_name() -> Cow<'static, str> {
"RenderSelect".into()
}
fn json_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({
"oneOf": [
{
"type": "object",
"properties": {
"kind": {"type": "string", "enum": ["nothing", "environment", "lighting", "output", "wear", "sampling", "effects", "check"]},
"id": {"type": "null"}
},
"required": ["kind"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {"type": "string", "enum": ["light", "shot"]},
"id": {"type": "string", "minLength": 1, "maxLength": 1024, "pattern": super::types::not_blank_pattern(),
"description": "A nonblank identity, at most 1024 UTF-8 bytes."}
},
"required": ["kind", "id"],
"additionalProperties": false
}
]
})
}
}
#[derive(Clone, Copy, Debug, Deserialize, Serialize, JsonSchema)]
pub enum FrameAspect {
#[serde(rename = "16:9")]
Wide,
#[serde(rename = "3:2")]
Photo,
#[serde(rename = "1:1")]
Square,
#[serde(rename = "4:5")]
Portrait,
#[serde(rename = "9:16")]
Tall,
#[serde(rename = "custom")]
Custom,
}
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RenderFrame {
/// Overlay aspect selection only; output dimensions require render.settings.set.
#[serde(default, deserialize_with = "super::types::present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "FrameAspect")]
pub aspect: Option<FrameAspect>,
#[serde(default, deserialize_with = "super::types::present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "bool")]
pub thirds: Option<bool>,
#[serde(default, deserialize_with = "super::types::present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "bool")]
pub safe_area: Option<bool>,
#[serde(default, deserialize_with = "super::types::present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "bool")]
pub centre_mark: Option<bool>,
}
/// Set the view navigator at the view's corner: its type, and for the custom one the body it
/// draws, its texture and the controls around it. The navigator is the app's, kept with the
/// preferences and settings profiles, never in the design; without an app the call only checks
/// its parameters. Never opens a dialog.
#[derive(Debug, Default, Deserialize, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct NavigatorParams {
/// The navigator: signed axes, the cube, or a custom body (the cube until a body is
/// chosen). Default: unchanged.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub style: Option<NavigatorStyle>,
/// A body of the open design for the custom navigator to draw; the app keeps a snapshot of
/// it, so it stays when the design closes. `null`: no body (the cube again). A body over
/// 10,000 triangles, or whose thinnest width is under a fifth of its widest, is refused.
/// Default: unchanged.
#[serde(default, deserialize_with = "nullable", skip_serializing_if = "Option::is_none")]
#[schemars(with = "Option<String>")]
pub body: Option<Option<String>>,
/// The custom navigator's colours: the cube's (`themed`) or the body's own appearance and
/// edge colour (`modeled`). Default: unchanged.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub texture: Option<NavigatorTexture>,
/// The cube's orbit and roll arrows around the custom navigator. Default: unchanged.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub arrows: Option<bool>,
/// The cube's Home button beside the custom navigator. Default: unchanged.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub home: Option<bool>,
}
/// A view navigator type.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum NavigatorStyle {
Axes,
Cube,
Custom,
}
/// How the custom view navigator colours its body.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum NavigatorTexture {
Themed,
Modeled,
}
/// A key that may be given as `null` (`Some(None)`), apart from absent (`None`).
fn nullable<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Option<String>>, D::Error> {
Option::<String>::deserialize(d).map(Some)
}
/// A key's value as its handler reads it: `read` takes the raw JSON value, and anything it
/// refuses gets the handler's own message, whole (no key put in front).
pub(super) fn read_with<'de, D: Deserializer<'de>, T>(d: D, message: &str, read: impl FnOnce(&Value) -> Option<T>) -> Result<Option<T>, D::Error> {
let value = Value::deserialize(d)?;
read(&value).map(Some).ok_or_else(|| serde::de::Error::custom(whole(message)))
}
/// A value `T` deserializes from, or the handler's message.
pub(super) fn read_as<'de, D: Deserializer<'de>, T: serde::de::DeserializeOwned>(d: D, message: &str) -> Result<Option<T>, D::Error> {
read_with(d, message, |v| serde_json::from_value(v.clone()).ok())
}
/// A deserializer for a key, with the handler's message for a value it refuses.
macro_rules! reads {
($name:ident -> $ty:ty, $message:literal) => {
fn $name<'de, D: Deserializer<'de>>(d: D) -> Result<Option<$ty>, D::Error> {
read_as(d, $message)
}
};
($name:ident -> $ty:ty, $message:literal, $read:expr) => {
fn $name<'de, D: Deserializer<'de>>(d: D) -> Result<Option<$ty>, D::Error> {
read_with(d, $message, $read)
}
};
}
/// A key the handlers refuse when it is left out, with their message: optional in the type, so
/// the check leaves the refusal to the handler, and required in the schema.
fn require(schema: &mut Schema, key: &str) {
super::motion::require(schema, key);
}
fn mode_required(schema: &mut Schema) {
require(schema, "mode");
}
fn preset_required(schema: &mut Schema) {
require(schema, "preset");
}
fn enabled_required(schema: &mut Schema) {
require(schema, "enabled");
}
fn camera_required(schema: &mut Schema) {
require(schema, "camera");
}
/// How the workspace is drawn.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum LayoutMode {
Floating,
Compact,
}
reads!(layout_mode -> LayoutMode, "mode must be floating or compact");
/// `view.layout`: the workspace layout, floating or compact. A display preference the app keeps;
/// the design, the camera and the active tool are not changed, and it never opens a dialog.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = mode_required)]
pub struct LayoutParams {
// Optional in the type and required in the schema (`mode_required`): left out, the handler
// refuses it with its own message.
/// `floating` or `compact`.
#[serde(default, deserialize_with = "layout_mode", skip_serializing_if = "Option::is_none")]
#[schemars(with = "LayoutMode")]
pub mode: Option<LayoutMode>,
}
/// What `view.layout` returns: the layout asked for.
#[derive(Debug, Serialize, JsonSchema)]
pub struct LayoutResult {
pub mode: LayoutMode,
/// 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>,
}
/// Where the history sits.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum HistoryDock {
Bottom,
Left,
UnderBrowser,
/// The history in the browser, with no timeline.
Browser,
}
reads!(history_width -> f64, "width must be finite and within 1..1000000", |v| v.as_f64().filter(|w| w.is_finite() && (1.0..=1_000_000.0).contains(w)));
reads!(history_dock -> HistoryDock, "dock must be bottom, left, under_browser or browser");
reads!(history_collapsed -> bool, "collapsed must be a boolean");
/// `view.history_layout`: the history's width, dock and whether it is collapsed; each given
/// key is checked and echoed, and a key left out stays as it is. A display preference the app
/// keeps; the design is not changed and it never opens a dialog.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct HistoryLayoutParams {
/// The history's width, 1 to 1000000.
#[serde(default, deserialize_with = "history_width", skip_serializing_if = "Option::is_none")]
#[schemars(with = "f64", range(min = 1.0, max = 1000000.0))]
pub width: Option<f64>,
/// Where the history sits.
#[serde(default, deserialize_with = "history_dock", skip_serializing_if = "Option::is_none")]
#[schemars(with = "HistoryDock")]
pub dock: Option<HistoryDock>,
/// True collapses the history, false opens it.
#[serde(default, deserialize_with = "history_collapsed", skip_serializing_if = "Option::is_none")]
#[schemars(with = "bool")]
pub collapsed: Option<bool>,
}
/// What `view.history_layout` returns: the keys given, checked.
#[derive(Debug, Serialize, JsonSchema)]
pub struct HistoryLayoutResult {
#[serde(skip_serializing_if = "Option::is_none")]
pub width: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub dock: Option<HistoryDock>,
#[serde(skip_serializing_if = "Option::is_none")]
pub collapsed: Option<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>,
}
/// A graphics preset.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum GraphicsPreset {
Performance,
Quality,
}
/// The tessellation a graphics preset asks for.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum PresetQuality {
Fine,
Normal,
}
reads!(graphics_preset_value -> GraphicsPreset, "preset must be performance or quality");
/// `view.graphics_preset`: one preset for ambient occlusion, tessellation and supersampling.
/// Quality: ambient occlusion on, Fine, adaptive 2x supersampling. Performance: no ambient
/// occlusion, Normal, no supersampling. MSAA stays independent. A display setting the app keeps;
/// the design is not changed.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = preset_required)]
pub struct GraphicsPresetParams {
// Optional in the type and required in the schema (`preset_required`), as `mode` above.
/// `performance` or `quality`.
#[serde(default, deserialize_with = "graphics_preset_value", skip_serializing_if = "Option::is_none")]
#[schemars(with = "GraphicsPreset")]
pub preset: Option<GraphicsPreset>,
}
/// What `view.graphics_preset` returns: the preset and the settings it stands for.
#[derive(Debug, Serialize, JsonSchema)]
pub struct GraphicsPresetResult {
pub preset: GraphicsPreset,
/// Ambient occlusion on or off.
pub enabled: bool,
pub display_quality: PresetQuality,
/// The supersampling factor: 2 for Quality, 1 for Performance.
pub supersampling: f64,
pub supersampling_adaptive: 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>,
}
reads!(ambient_occlusion_enabled -> bool, "enabled must be a boolean");
/// `view.ambient_occlusion`: soft contact shading in the GPU viewport, on or off. A display
/// setting the app keeps; the design is not changed.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = enabled_required)]
pub struct AmbientOcclusionParams {
// Optional in the type and required in the schema (`enabled_required`), as `mode` above.
/// True turns it on, false off.
#[serde(default, deserialize_with = "ambient_occlusion_enabled", skip_serializing_if = "Option::is_none")]
#[schemars(with = "bool")]
pub enabled: Option<bool>,
}
/// What `view.ambient_occlusion` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct AmbientOcclusionResult {
/// Whether it is on now.
pub enabled: 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 a navigation turns the camera by.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum NavigateAction {
Left,
Right,
Up,
Down,
Clockwise,
Counterclockwise,
/// The isometric view, framed on the whole model.
Home,
/// Frame the whole model.
Fit,
}
/// A direct manipulation of the camera.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum NavigateMotion {
Pan,
Orbit,
Zoom,
}
/// A point of finite numbers, `[x, y]` or `[x, y, z]` (or an object with those keys), each
/// within `lo..=hi`.
fn bounded_point(keys: &[&str], lo: f64, hi: f64) -> Schema {
let n = keys.len();
// `params::finite` takes numbers below 1e9 in size; the others' bounds are inclusive.
let number = if hi >= 1e9 {
json!({"type": "number", "exclusiveMinimum": lo, "exclusiveMaximum": hi})
} else {
json!({"type": "number", "minimum": lo, "maximum": hi})
};
let properties: serde_json::Map<String, Value> = keys.iter().map(|k| ((*k).to_string(), number.clone())).collect();
json_schema!({
"anyOf": [
{"type": "array", "items": number, "minItems": n, "maxItems": n},
{"type": "object", "properties": properties, "required": keys}
]
})
}
fn degrees_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({"description": "Degrees, above 0 and at most 180.", "type": "number", "exclusiveMinimum": 0, "maximum": 180})
}
fn point3_schema(_: &mut SchemaGenerator) -> Schema {
let mut s = bounded_point(&["x", "y", "z"], -1e9, 1e9);
s.insert("description".into(), "A point [x, y, z] or {\"x\", \"y\", \"z\"}, of numbers.".into());
s
}
fn delta_schema(_: &mut SchemaGenerator) -> Schema {
let mut s = bounded_point(&["x", "y"], -1e4, 1e4);
s.insert("description".into(), "Pixels [dx, dy] (or {\"x\", \"y\"}), each within ±10000.".into());
s
}
fn viewport_schema(_: &mut SchemaGenerator) -> Schema {
let mut s = bounded_point(&["x", "y"], 1.0, 1e6);
s.insert("description".into(), "The viewport's size in pixels [width, height] (or {\"x\", \"y\"}), each 1 to 1000000.".into());
s
}
/// The camera `view.navigate` turns: as the other view commands read it, and also with yaw and
/// roll within ±1e6 and pitch within ±π/2 (else "invalid camera"). Read before anything else.
fn navigate_camera<'de, D: Deserializer<'de>>(d: D) -> Result<Option<CameraParam>, D::Error> {
read_with(d, "invalid camera", |v| {
crate::cmd::camera_form(v)
.filter(|c| c.yaw.abs() <= 1e6 && c.roll.abs() <= 1e6 && c.pitch.abs() <= std::f64::consts::FRAC_PI_2)
.map(CameraParam)
})
}
reads!(navigate_fit -> bool, "fit must be a boolean");
reads!(
navigate_direction -> Vec3,
"direction must be a finite nonzero vector of length at most 2",
|v| crate::params::vec3(v).filter(|v| v.is_finite() && v.len() <= 2.0 && v.normalized().is_some())
);
reads!(navigate_action -> NavigateAction, "unknown navigation action");
reads!(
navigate_degrees -> f64,
"degrees must be a number above 0 and at most 180",
|v| v.as_f64().filter(|d| d.is_finite() && *d > 0.0 && *d <= 180.0)
);
reads!(navigate_motion -> NavigateMotion, "unknown navigation motion");
reads!(navigate_free_orbit -> bool, "free_orbit must be a boolean");
/// A pan or orbit's `delta` and an orbit's `viewport` are read in two steps, as the handler
/// does: a point, then its bounds, each with its own message.
fn bounded_point_key<'de, D: Deserializer<'de>>(d: D, key: &str, in_bounds: fn(Vec2) -> bool, out_of_bounds: &str) -> Result<Option<Vec2>, D::Error> {
let point = read_with(d, &format!("`{key}` must be a point [x, y]"), crate::params::vec2)?;
match point {
Some(p) if !in_bounds(p) => Err(serde::de::Error::custom(whole(out_of_bounds))),
point => Ok(point),
}
}
fn navigate_delta<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Vec2>, D::Error> {
bounded_point_key(d, "delta", |p| p.x.abs() <= 1e4 && p.y.abs() <= 1e4, "motion deltas must be within ±10000 pixels")
}
fn navigate_viewport<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Vec2>, D::Error> {
bounded_point_key(d, "viewport", |p| (1.0..=1e6).contains(&p.x) && (1.0..=1e6).contains(&p.y), "viewport dimensions must be in 1..1000000")
}
reads!(navigate_pivot -> Vec3, "`pivot` must be a point [x, y, z]", crate::params::vec3);
reads!(navigate_anchor -> Vec3, "`anchor` must be a point [x, y, z]", crate::params::vec3);
reads!(
navigate_factor -> f64,
"factor must be in 0.05..20",
|v| v.as_f64().filter(|f| f.is_finite() && f.abs() < 1e9 && (0.05..=20.0).contains(f))
);
/// `view.navigate`: turn, pan, orbit or zoom a camera without changing the design or adding to
/// undo. `camera` is always needed, and then one of three: `direction` (look from it), `action`
/// (a turn, a roll, home or fit) or `motion` (direct manipulation, which wins when given and
/// does not take `fit`). Keys of the other forms are not used.
// Deserialize is written out below rather than derived: the handler reads only the keys of the
// form it takes, so a key of another form is neither read nor checked.
#[derive(Debug, JsonSchema)]
#[schemars(deny_unknown_fields, transform = camera_required)]
pub struct NavigateParams {
// Optional in the type and required in the schema (`camera_required`), as `mode` above.
/// The camera to move, as `ui.inspect` gives it. Its yaw and roll must also be within ±1e6
/// and its pitch within ±π/2.
#[serde(default, deserialize_with = "navigate_camera", skip_serializing_if = "Option::is_none")]
#[schemars(with = "CameraParam")]
pub camera: Option<CameraParam>,
/// Also frame the whole model from the new direction, as home does. Not with `motion`.
/// Default: false.
#[serde(default, deserialize_with = "navigate_fit", skip_serializing_if = "Option::is_none")]
#[schemars(with = "bool")]
pub fit: Option<bool>,
/// Look from this direction, in the camera's up-axis frame: a finite nonzero vector of
/// length at most 2.
#[serde(default, deserialize_with = "navigate_direction", skip_serializing_if = "Option::is_none")]
#[schemars(schema_with = "point3_schema")]
pub direction: Option<Vec3>,
/// A turn without `direction`: left, right, up or down turn the view `degrees`, clockwise and
/// counterclockwise roll it a quarter turn, home shows the isometric view framed, fit frames
/// the model.
#[serde(default, deserialize_with = "navigate_action", skip_serializing_if = "Option::is_none")]
#[schemars(with = "NavigateAction")]
pub action: Option<NavigateAction>,
/// How far left, right, up or down turn the view, above 0 and at most 180. Default: 90.
#[serde(default, deserialize_with = "navigate_degrees", skip_serializing_if = "Option::is_none")]
#[schemars(schema_with = "degrees_schema")]
pub degrees: Option<f64>,
/// Direct manipulation: pan and orbit need `delta`, pan and an orbit about a `pivot` need
/// `viewport`, zoom needs `factor`.
#[serde(default, deserialize_with = "navigate_motion", skip_serializing_if = "Option::is_none")]
#[schemars(with = "NavigateMotion")]
pub motion: Option<NavigateMotion>,
/// Pan or orbit by this many pixels.
#[serde(default, deserialize_with = "navigate_delta", skip_serializing_if = "Option::is_none")]
#[schemars(schema_with = "delta_schema")]
pub delta: Option<Vec2>,
/// Orbit through the poles. Default: false.
#[serde(default, deserialize_with = "navigate_free_orbit", skip_serializing_if = "Option::is_none")]
#[schemars(with = "bool")]
pub free_orbit: Option<bool>,
/// The viewport's size in pixels, for a pan or an orbit about a pivot.
#[serde(default, deserialize_with = "navigate_viewport", skip_serializing_if = "Option::is_none")]
#[schemars(schema_with = "viewport_schema")]
pub viewport: Option<Vec2>,
/// Orbit about this point (mm) rather than the camera's target.
#[serde(default, deserialize_with = "navigate_pivot", skip_serializing_if = "Option::is_none")]
#[schemars(schema_with = "point3_schema")]
pub pivot: Option<Vec3>,
/// The zoom factor, 0.05 to 20.
#[serde(default, deserialize_with = "navigate_factor", skip_serializing_if = "Option::is_none")]
#[schemars(with = "f64", range(min = 0.05, max = 20.0))]
pub factor: Option<f64>,
/// Zoom towards this point (mm). Default: the camera's target.
#[serde(default, deserialize_with = "navigate_anchor", skip_serializing_if = "Option::is_none")]
#[schemars(schema_with = "point3_schema")]
pub anchor: Option<Vec3>,
}
impl<'de> Deserialize<'de> for NavigateParams {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
let p = serde_json::Map::<String, Value>::deserialize(d)?;
navigate_form(&p).map_err(serde::de::Error::custom)
}
}
/// A key's value through its reader, or `None` when the key is left out.
fn navigate_key<'a, T>(
p: &'a serde_json::Map<String, Value>,
key: &str,
read: impl FnOnce(&'a Value) -> Result<Option<T>, serde_json::Error>,
) -> Result<Option<T>, serde_json::Error> {
p.get(key).map_or(Ok(None), read)
}
/// The keys `view.navigate`'s handler reads, in its order: the camera and `fit`, then those of
/// a motion (each motion its own), of a direction, or of an action.
fn navigate_form(p: &serde_json::Map<String, Value>) -> Result<NavigateParams, serde_json::Error> {
let mut form = NavigateParams {
camera: navigate_key(p, "camera", navigate_camera)?,
fit: navigate_key(p, "fit", navigate_fit)?,
direction: None,
action: None,
degrees: None,
motion: None,
delta: None,
free_orbit: None,
viewport: None,
pivot: None,
factor: None,
anchor: None,
};
if p.contains_key("motion") {
form.free_orbit = navigate_key(p, "free_orbit", navigate_free_orbit)?;
form.motion = navigate_key(p, "motion", navigate_motion)?;
match form.motion {
Some(NavigateMotion::Pan) => {
form.delta = navigate_key(p, "delta", navigate_delta)?;
form.viewport = navigate_key(p, "viewport", navigate_viewport)?;
}
Some(NavigateMotion::Orbit) => {
form.delta = navigate_key(p, "delta", navigate_delta)?;
// An orbit needs the viewport only about a pivot.
if p.contains_key("pivot") {
form.pivot = navigate_key(p, "pivot", navigate_pivot)?;
form.viewport = navigate_key(p, "viewport", navigate_viewport)?;
}
}
Some(NavigateMotion::Zoom) => {
form.factor = navigate_key(p, "factor", navigate_factor)?;
form.anchor = navigate_key(p, "anchor", navigate_anchor)?;
}
None => {}
}
} else if p.contains_key("direction") {
form.direction = navigate_key(p, "direction", navigate_direction)?;
} else {
form.degrees = navigate_key(p, "degrees", navigate_degrees)?;
form.action = navigate_key(p, "action", navigate_action)?;
}
Ok(form)
}
/// What `view.navigate` returns: the camera after the move, and whether the window should also
/// frame the whole model. The window applies both; the design is not changed.
#[derive(Debug, Serialize, JsonSchema)]
pub struct NavigateResult {
/// The camera now.
#[schemars(with = "CameraParam")]
pub camera: solidcraft_render::Camera,
/// Frame the whole model from the new direction.
pub fit: bool,
/// True for a `motion`; absent for a turn.
#[serde(skip_serializing_if = "Option::is_none")]
pub continuous: Option<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 = "view_navigation_tests.rs"]
mod tests;