Skip to content

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

11.5 KB
Raw Blame
//! Contracts and reply types for the render camera commands in `cmd/render.rs` (#12288): Set,
//! Inspect and Frame Render Camera, and Apply Render Camera. They change only the camera in the
//! view, never the design.
//!
//! The handlers read their parameters from the raw JSON, so each key here reads as its handler
//! reads it and fails with the handler's message. Whether a saved setup exists, and whether the
//! product can be framed, stay the handlers' to check.

use std::borrow::Cow;

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::render_settings::{RenderSettings, RenderSetup};

use super::check::whole;
use super::types::not_blank_pattern;

/// The largest size a camera's target coordinates and distance may have, in mm, as a saved
/// render setup keeps them (`RenderSetup::validate`).
const MAX_LENGTH_MM: f64 = 1e9;
/// The largest size a camera's yaw, pitch and roll may have, in radians, likewise.
const MAX_ANGLE: f64 = 1e6;
/// The picture's width over its height that Frame Render Subject takes: the range a preview
/// frame can show (`frame_rect` in the Render workspace).
const MIN_ASPECT: f64 = 1e-6;
const MAX_ASPECT: f64 = 1e6;

/// A render camera, as a saved render setup keeps it: strict about its keys, with finite
/// lengths and angles within [`MAX_LENGTH_MM`] and [`MAX_ANGLE`], a positive distance and a
/// field of view in [0, π).
///
/// It is not the view commands' `types::CameraParam`: those read a camera more loosely and
/// refuse an explicit `up`, while a render camera keeps both `roll` and `up`.
#[derive(Clone, Copy, Debug, PartialEq, Serialize)]
#[serde(transparent)]
pub struct RenderCamera(pub solidcraft_render::Camera);

impl JsonSchema for RenderCamera {
    fn schema_name() -> Cow<'static, str> {
        "RenderCamera".into()
    }
    /// The size bounds are for a camera given (the input schema) only. A reply gives back the
    /// camera in the view, which Frame Render Subject may have moved beyond them (a picture far
    /// taller than wide moves it back that much) and the view commands don't bound, so the
    /// output schema has the camera's shape alone.
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let given = generator.contract().is_deserialize();
        // `schema` with a largest size of `limit` either way, in the input schema only.
        let sized = |mut schema: Value, limit: f64| {
            if given {
                schema["minimum"] = json!(-limit);
                schema["maximum"] = json!(limit);
            }
            schema
        };
        let angle = |description: &str| sized(json!({"description": description, "type": "number"}), MAX_ANGLE);
        let coordinate = sized(json!({"type": "number"}), MAX_LENGTH_MM);
        let mut roll = angle("Turn about the viewing direction; 0 keeps the up axis upright. Default: 0.");
        roll["default"] = json!(0.0);
        let mut distance = json!({"description": "From the target to the eye, in mm.", "type": "number", "exclusiveMinimum": 0});
        if given {
            distance["maximum"] = json!(MAX_LENGTH_MM);
        }
        let bounds = if given { " Lengths are at most 1e9 mm in size, and angles at most 1e6 radians." } else { "" };
        json_schema!({
            "description": format!("A render camera orbiting a target point. Lengths are in mm and angles in radians, measured in the frame of the up axis.{bounds}"),
            "type": "object",
            "properties": {
                "target": {
                    "description": "The point the camera looks at, in mm: [x, y, z].",
                    "type": "array",
                    "items": coordinate,
                    "minItems": 3,
                    "maxItems": 3
                },
                "yaw": angle("Turn about the up axis; 0 looks along +Y, from the front."),
                "pitch": angle("Elevation above the ground plane: π/2 looks straight down."),
                "roll": roll,
                "distance": distance,
                "fov": {"description": "Vertical field of view; 0 is orthographic.", "type": "number", "minimum": 0, "exclusiveMaximum": std::f64::consts::PI},
                "up": {"description": "The world's up axis. Default: z.", "enum": ["z", "y"], "default": "z"}
            },
            "required": ["target", "yaw", "pitch", "distance", "fov"],
            "additionalProperties": false
        })
    }
}

/// `serde(default)` makes schemars publish `"default": null` on a key; drop it from a key the
/// schema requires.
fn drop_default(schema: &mut Schema) {
    schema.remove("default");
}

/// Adds `key` to the schema's `required` list: for a key the type has optional so that the
/// handler, not the check, refuses it with its own message when it's left out.
/// (`#[schemars(required)]` doesn't do this for a key with `serde(default)`.)
fn require(schema: &mut Schema, key: &str) {
    match schema.get_mut("required") {
        Some(Value::Array(required)) => {
            if !required.iter().any(|k| k == key) {
                required.push(key.into());
            }
        }
        _ => {
            schema.insert("required".into(), Value::Array(vec![key.into()]));
        }
    }
}

fn camera_required(schema: &mut Schema) {
    require(schema, "camera");
}

fn name_required(schema: &mut Schema) {
    require(schema, "name");
}

/// Set the camera in the view from a complete camera snapshot. Nothing in the design changes,
/// and there is no undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = camera_required)]
pub struct SetParams {
    /// The camera: `target`, `yaw`, `pitch`, `distance` and `fov`, and optionally `roll` and
    /// `up`.
    // Optional in the type, required in the schema: left out, the handler refuses the call
    // with its own message.
    #[serde(default, deserialize_with = "render_camera")]
    #[schemars(with = "RenderCamera", transform = drop_default)]
    pub camera: Option<RenderCamera>,
}

/// A camera as `render.camera.set` reads it: a render setup holding only that camera, decoded
/// and checked as a saved one is, with the same messages.
fn render_camera<'de, D: Deserializer<'de>>(d: D) -> Result<Option<RenderCamera>, D::Error> {
    let setup: RenderSetup = serde_json::from_value(json!({"camera": Value::deserialize(d)?})).map_err(|e| D::Error::custom(whole(e)))?;
    setup.validate().map_err(|e| D::Error::custom(whole(e)))?;
    Ok(Some(RenderCamera(setup.camera)))
}

/// The camera set in the view, if any. No parameters.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct GetParams {}

/// Fit the camera in the view to the visible product, keeping its direction: for a picture
/// taller than wide it moves back, so the picture's sides hold the product too.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct FitParams {
    // `skip_serializing_if` keeps schemars from publishing `"default": null`, which the reader
    // refuses, over the schema's own default of 1.
    #[serde(default, deserialize_with = "aspect", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "aspect_schema")]
    pub aspect: Option<f64>,
}

/// `aspect`, with `render.camera.fit`'s message for anything outside its range, `null`
/// included.
fn aspect<'de, D: Deserializer<'de>>(d: D) -> Result<Option<f64>, D::Error> {
    match Value::deserialize(d)?.as_f64() {
        Some(a) if (MIN_ASPECT..=MAX_ASPECT).contains(&a) => Ok(Some(a)),
        _ => Err(D::Error::custom(whole("aspect must be a number from 0.000001 to 1000000: the picture's width over its height"))),
    }
}

fn aspect_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({
        "description": "The picture's width over its height: 0.000001 to 1000000. Default: 1.",
        "type": "number",
        "minimum": MIN_ASPECT,
        "maximum": MAX_ASPECT,
        "default": 1.0
    })
}

/// Put a saved render setup's camera, with its roll and up axis, in the view. Nothing in the
/// design changes, and there is no undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = name_required)]
pub struct ApplyParams {
    /// The saved render setup, by name: trimmed, at most 128 bytes, with no control characters.
    // Optional in the type, required in the schema: left out (or `null`), the handler refuses
    // the call with its own message.
    #[serde(default, deserialize_with = "setup_name")]
    #[schemars(schema_with = "setup_name_schema", transform = drop_default)]
    pub name: Option<String>,
}

/// A setup's name as `render.settings.apply` reads it: `null` is left out, other text than a
/// string gets serde's message, and a string must be a valid setup name.
pub(super) fn setup_name<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    let Some(name) = Option::<String>::deserialize(Value::deserialize(d)?).map_err(|e| D::Error::custom(whole(e)))? else {
        return Ok(None);
    };
    RenderSettings::validate_name(&name).map_err(|e| D::Error::custom(whole(e)))?;
    Ok(Some(name))
}

/// The pattern says "not blank"; trimmed, at most 128 bytes and free of control characters,
/// which JSON Schema can't count or class portably, are in the field's description and
/// checked by [`setup_name`].
pub(super) fn setup_name_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "pattern": not_blank_pattern()
    })
}

/// What `render.camera.set` returns: the camera now in the view.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CameraSet {
    pub camera: RenderCamera,
    /// Always false: the design doesn't change.
    pub document_changed: 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.camera.get` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CameraInfo {
    /// The camera set in the view, or `null` when none is.
    pub camera: Option<RenderCamera>,
    /// Whether a camera is set in the view.
    pub explicit_view: bool,
    /// Always false: the design doesn't change.
    pub document_changed: 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.camera.fit` returns: the fitted camera, now in the view.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CameraFitted {
    pub camera: RenderCamera,
    /// Whether nothing visible was there to frame. The camera then isn't moved: it stays the
    /// one set in the view, or the default camera when none was.
    pub empty: bool,
    /// Always false: the design doesn't change.
    pub document_changed: 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.settings.apply` returns: the setup and its camera, now in the view.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CameraApplied {
    pub name: String,
    pub camera: RenderCamera,
    /// 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_camera_tests.rs"]
mod tests;