Skip to content

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

39.2 KB
Raw Blame
//! Contracts and result types for the commands in `cmd/inspect.rs`.
//!
//! 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 body, a sketch or a material exists
//! stays the handler's to check. A key the handler refuses when it is left out (`material.assign`'s
//! `bodies` and `material`) is optional in the type and required in the schema, so that the
//! handler's message, not the check's "is required", is what a caller sees (#12498).

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::{Map, Value, json};

use super::check::{located, whole};
use super::materials::MaterialReply;
use crate::params;

/// Which command to describe.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct DescribeParams {
    /// The command's id, such as `solid.extrude`.
    #[serde(deserialize_with = "command_id")]
    pub command: String,
}

/// A command id, with the `engine.describe` handler's message for anything else.
fn command_id<'de, D: serde::Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    match Value::deserialize(d)? {
        Value::String(s) => Ok(s),
        _ => Err(serde::de::Error::custom("must be a command id")),
    }
}

/// What `engine.describe` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct DescribeResult {
    pub id: String,
    pub label: String,
    /// The command's parameter documentation, as prose.
    pub params: String,
    /// The parameters' JSON Schema, or `null` when the command has no contract yet.
    pub input: Option<Value>,
    /// The successful result's JSON Schema, or `null` when not described yet.
    pub output: Option<Value>,
    /// 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>,
}

/// List a body's edges or faces, with what picks each one.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct BodyListParams {
    /// The body, by name.
    pub body: String,
}

/// List the design's cosmetic threads.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ModelThreadsParams {}

/// List the timeline features that built each body (#11945).
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct BodyFeaturesParams {
    /// One body, by name (a placed copy's name means the body it shows); every body when left out.
    #[serde(default)]
    pub body: Option<String>,
}

/// What `model.body_features` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ModelBodyFeatures {
    /// The bodies, in the model's order (the one asked for alone).
    pub bodies: Vec<BodyFeatures>,
    /// 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 body and the features that built it.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BodyFeatures {
    /// The body's name.
    pub body: String,
    /// In timeline order: the feature that created it, every later one that changed its
    /// geometry, and those of the bodies consumed into it (a Combine's tools, a body joined in).
    pub features: Vec<BodyFeature>,
}

/// A timeline feature.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BodyFeature {
    /// The feature's id.
    pub id: u64,
    /// Its name in the timeline.
    pub name: String,
}

/// What `model.edges` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ModelEdges {
    /// The body's name.
    pub body: String,
    /// Its edges, in the kernel's order.
    pub edges: Vec<ModelEdge>,
    /// 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 edge of a body.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ModelEdge {
    /// Its index, which changes when the body is rebuilt differently.
    pub index: usize,
    /// Its name, `<face A>|<face B>` from the faces it joins (numbered when repeated); `null`
    /// when it has none.
    pub name: Option<String>,
    /// The point halfway along it, which picks it.
    pub mid: [f64; 3],
    /// Its length (mm).
    pub length: f64,
    /// Where it starts; `null` for an edge with no points.
    pub start: Option<[f64; 3]>,
    /// Where it ends; `null` for an edge with no points.
    pub end: Option<[f64; 3]>,
}

/// What `model.faces` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ModelFaces {
    /// The body's name.
    pub body: String,
    /// Its faces, in the kernel's order.
    pub faces: Vec<ModelFace>,
    /// 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 face of a body.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ModelFace {
    /// Its index, which changes when the body is rebuilt differently.
    pub index: usize,
    /// Its name: what `face.delete`, `sheet.convert`'s `face`, `solid.shell` and others take in
    /// place of a point. `null` when it has none.
    pub name: Option<String>,
    /// Whether the name follows the face's exact history; `false` when it was worked out from
    /// the geometry, which an edit earlier in the timeline can fool.
    pub exact: bool,
    /// Its area (mm²).
    pub area: f64,
    /// Its centroid, which isn't always on the face.
    pub centroid: [f64; 3],
    /// Its outward unit normal if it is planar, else `null`.
    pub plane_normal: Option<[f64; 3]>,
    /// A point on the face that picks it; `null` when none was found.
    pub point: Option<[f64; 3]>,
    /// For a cylindrical face: its axis and radius.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cylinder: Option<FaceCylinder>,
    /// For a folded sheet's face: `sheet:<body>:<panel>:<side>`, where the panel is `base` or a
    /// flange's tag `F<feature>.<k>` and the side is `top`, `bottom`, `rim.<edge>`, `bend.inner`
    /// or `bend.outer`. It is taken wherever a face name is, and holds while sizes change and
    /// flanges come and go.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sheet_face: Option<String>,
}

/// A cylindrical face's axis and radius.
#[derive(Debug, Serialize, JsonSchema)]
pub struct FaceCylinder {
    /// A point on the axis.
    pub origin: [f64; 3],
    /// The axis direction, a unit vector.
    pub axis: [f64; 3],
    /// The radius (mm).
    pub radius: f64,
}

/// What `model.threads` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ModelThreads {
    /// The cosmetic threads, in timeline order.
    pub threads: Vec<ModelThread>,
    /// 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 cosmetic thread: on which cylinder, its size, and the threaded part of the axis.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ModelThread {
    /// The id of the thread feature.
    pub feature: u64,
    /// The body it is on.
    pub body: String,
    /// Its size, such as `M6x1`.
    pub designation: String,
    /// Its major diameter (mm).
    pub major_diameter: f64,
    /// The radius of the cylindrical face it is on (mm).
    pub radius: f64,
    /// Its pitch (mm).
    pub pitch: f64,
    /// Whether it is cut into a hole rather than on a shaft.
    pub internal: bool,
    /// Its form.
    pub form: ThreadForm,
    /// Which way it turns.
    pub hand: ThreadHand,
    /// How many starts it has.
    pub starts: u32,
    /// A point on the axis, which `start` and `end` are measured from.
    pub axis_point: [f64; 3],
    /// The axis direction, a unit vector.
    pub axis: [f64; 3],
    /// Where the threaded part starts along the axis from `axis_point` (mm).
    pub start: f64,
    /// Where it ends (mm).
    pub end: f64,
}

/// Which way a thread turns.
#[derive(Clone, Copy, Debug, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ThreadHand {
    Right,
    Left,
    /// A right- and a left-handed groove crossing on one face (a reversing screw).
    Both,
}

/// A thread form: ISO metric 60°, metric trapezoidal 30°, Acme 29°, metric buttress 3°/30°,
/// buttress inch 7°/45°, square, and the 55° and 60° pipe threads.
#[derive(Clone, Copy, Debug, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ThreadForm {
    Metric,
    Trapezoidal,
    Acme,
    Buttress,
    ButtressAsme,
    Square,
    Bspp,
    Rp,
    Bspt,
    Npt,
}

impl From<&solidcraft_doc::ThreadInfo> for ModelThread {
    fn from(t: &solidcraft_doc::ThreadInfo) -> Self {
        use solidcraft_doc::thread_forms::{ThreadForm as Form, ThreadHand as Hand};
        ModelThread {
            feature: t.feature,
            body: t.body.clone(),
            designation: t.designation.clone(),
            major_diameter: t.major_diameter,
            radius: t.radius,
            pitch: t.pitch,
            internal: t.internal,
            form: match t.form {
                Form::Metric => ThreadForm::Metric,
                Form::Trapezoidal => ThreadForm::Trapezoidal,
                Form::Acme => ThreadForm::Acme,
                Form::Buttress => ThreadForm::Buttress,
                Form::ButtressAsme => ThreadForm::ButtressAsme,
                Form::Square => ThreadForm::Square,
                Form::Bspp => ThreadForm::Bspp,
                Form::Rp => ThreadForm::Rp,
                Form::Bspt => ThreadForm::Bspt,
                Form::Npt => ThreadForm::Npt,
            },
            hand: match t.hand {
                Hand::Right => ThreadHand::Right,
                Hand::Left => ThreadHand::Left,
                Hand::Both => ThreadHand::Both,
            },
            starts: t.starts,
            axis_point: t.axis_point.into(),
            axis: solidcore_record::Vec3::from(t.axis).into(),
            start: t.start,
            end: t.end,
        }
    }
}

/// Adds `keys` to the schema's `required` list: for a key the type has optional so that the
/// handler, not the check, refuses it when it's left out.
fn require_keys(schema: &mut Schema, keys: &[&str]) {
    let mut required = match schema.get("required") {
        Some(Value::Array(required)) => required.clone(),
        _ => Vec::new(),
    };
    for key in keys {
        if !required.iter().any(|k| k == key) {
            required.push((*key).into());
        }
    }
    schema.insert("required".into(), Value::Array(required));
}

fn bodies_and_material_required(schema: &mut Schema) {
    require_keys(schema, &["bodies", "material"]);
}

/// The message of a handler's parameter error, for a reader the contract shares.
fn message(e: crate::EngineError) -> String {
    match e {
        crate::EngineError::BadParams { msg, .. } => msg,
        other => other.to_string(),
    }
}

/// `bodies`: a name or a list of names, read by `params::string_list` itself, with its messages
/// (`null` is no names).
fn body_names<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Vec<String>>, D::Error> {
    let v = Value::deserialize(d)?;
    params::string_list("inspect", &json!({ "bodies": v }), "bodies").map(Some).map_err(|e| D::Error::custom(whole(message(e))))
}

fn body_names_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}, "maxItems": params::MAX_STRING_LIST}, {"type": "null"}]})
}

/// Read the design: its name, units, properties, parameters, timeline, bodies and sketches, the
/// selection and the undo and redo depth. Read-only.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct DocumentInspectParams {
    /// Measure each body too (volume, area, centre of mass, box, counts, as `inspect.measure`
    /// does), in place of its feature. Default: false.
    #[serde(default)]
    pub measure: Option<bool>,
    /// Give each sketch also its plane and its number of points and constraints. Default: false.
    #[serde(default)]
    pub sketch_counts: Option<bool>,
}

/// What `document.inspect` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct DocumentInspectResult {
    /// The design's name.
    pub name: String,
    /// Its length unit.
    pub units: String,
    /// Its metadata object as saved, other tools' keys included.
    pub metadata: Map<String, Value>,
    /// The file it is saved in; `null` when it has none.
    pub path: Option<String>,
    /// Whether it has changes that are not saved.
    pub dirty: bool,
    /// How many times the session's design changed.
    pub revision: u64,
    /// The sketch being edited, by feature id; `null` when none.
    pub active_sketch: Option<u64>,
    /// The timeline marker: features from this index on are rolled back.
    pub marker: usize,
    /// The design's parameters.
    pub params: Vec<DocumentParam>,
    /// Its features, in timeline order.
    pub timeline: Vec<TimelineEntry>,
    /// Its bodies.
    pub bodies: Vec<DocumentBody>,
    /// Its sketches.
    pub sketches: Vec<DocumentSketch>,
    /// What is selected, each as the selection commands take it.
    #[schemars(with = "Vec<Map<String, Value>>")]
    pub selection: Value,
    /// How many undo steps there are.
    pub undo: usize,
    /// How many redo steps there are.
    pub redo: usize,
    /// The parts of the origin that are hidden, by name.
    pub hidden_origin: 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>,
}

/// A parameter of the design.
#[derive(Debug, Serialize, JsonSchema)]
pub struct DocumentParam {
    pub name: String,
    /// What it is defined as.
    pub expression: String,
    /// `mm`, `deg` or empty (no unit).
    pub unit: String,
    /// What the expression comes to; `null` when it doesn't evaluate.
    pub value: Option<f64>,
    /// Whether a dimension or feature made it, not the user.
    pub model: bool,
    pub comment: String,
    /// Why the expression doesn't evaluate; `null` when it does.
    pub error: Option<String>,
}

/// A feature of the timeline.
#[derive(Debug, Serialize, JsonSchema)]
pub struct TimelineEntry {
    pub id: u64,
    pub name: String,
    /// The feature's kind, such as `Extrude`.
    #[serde(rename = "type")]
    pub kind: String,
    pub suppressed: bool,
    /// Whether the timeline marker has rolled it back.
    pub rolled_back: bool,
    /// Why it failed; `null` when it did not.
    pub error: Option<String>,
    pub warning: Option<String>,
    /// How long it took to evaluate (ms); `null` when it has no result.
    pub ms: Option<f64>,
}

/// A body of the design: measured with `measure`, else with the feature that made it.
#[derive(Debug, Serialize, JsonSchema)]
pub struct DocumentBody {
    #[serde(flatten)]
    pub detail: DocumentBodyDetail,
    /// Whether it is shown.
    pub visible: bool,
    /// Present, and true, when the timeline is rolled back and the body is deleted further on.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub removed_later: Option<bool>,
}

/// What a body entry says of the body itself.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum DocumentBodyDetail {
    /// Without `measure`.
    Listed {
        name: String,
        /// The feature that made it, by id.
        feature: u64,
    },
    /// With `measure`.
    Measured(Box<BodyMeasurement>),
}

/// One body measured: its name and the measurement or why there is none.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BodyMeasurement {
    pub name: String,
    #[serde(flatten)]
    pub outcome: BodyOutcome,
}

/// A body's measurement.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum BodyOutcome {
    Measured(BodyFigures),
    Failed(BodyFailure),
}

/// The measurements of a body.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BodyFigures {
    /// Whether it encloses a volume.
    pub closed: bool,
    /// Its volume (mm³); `null` unless it is closed.
    pub volume_mm3: Option<f64>,
    /// Its surface area (mm²).
    pub area_mm2: f64,
    /// Its centre of mass at uniform density; `null` unless it is closed.
    pub center_of_mass: Option<[f64; 3]>,
    pub bbox: BoundingBox,
    /// Faces, with split pieces of one analytic surface counted once (a sheet metal body's in
    /// `inspect.measure`: with its round holes counted as the design shows them).
    pub faces: i64,
    pub edges: i64,
    pub vertices: i64,
    /// The merged faces by kind of surface.
    pub face_types: BTreeMap<String, usize>,
    /// The kernel's own counts, which split closed curves and surfaces.
    pub kernel: KernelCounts,
    /// What volume, area and centre come from: `smlib` (exact) or `mesh` (a mesh body's own
    /// triangles).
    pub measured_by: String,
    /// Anything the measurement says about itself.
    pub notes: Vec<String>,
}

/// Why a body has no measurement.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BodyFailure {
    pub error: String,
    /// `inspect.measure` only, for a sheet metal body: its hole-corrected count, which has
    /// nothing to correct.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub faces: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub edges: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub vertices: Option<i64>,
}

/// An axis-aligned box (mm).
#[derive(Debug, Serialize, JsonSchema)]
pub struct BoundingBox {
    pub min: [f64; 3],
    pub max: [f64; 3],
}

/// A body's topology counts as the kernel has them.
#[derive(Debug, Serialize, JsonSchema)]
pub struct KernelCounts {
    pub faces: usize,
    pub edges: usize,
    pub vertices: usize,
    pub shells: usize,
}

/// A sketch of the design, in short.
#[derive(Debug, Serialize, JsonSchema)]
pub struct DocumentSketch {
    /// Its feature id.
    pub id: u64,
    pub name: String,
    /// Its remaining degrees of freedom (0: fully constrained).
    pub dof: usize,
    pub status: SketchStatus,
    /// How many curves it has.
    pub curves: usize,
    /// How many profiles it closes.
    pub profiles: usize,
    /// Whether it is shown.
    pub visible: bool,
    /// With `sketch_counts`: where it lies.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<Map<String, Value>>")]
    pub plane: Option<Value>,
    /// With `sketch_counts`: how many points it has.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub points: Option<usize>,
    /// With `sketch_counts`: how many constraints it has.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub constraints: Option<usize>,
}

/// Whether a sketch's constraints solved.
#[derive(Clone, Copy, Debug, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum SketchStatus {
    Solved,
    Failed,
}

impl From<solidcraft_sketch::SolveStatus> for SketchStatus {
    fn from(s: solidcraft_sketch::SolveStatus) -> Self {
        match s {
            solidcraft_sketch::SolveStatus::Solved => SketchStatus::Solved,
            solidcraft_sketch::SolveStatus::Failed => SketchStatus::Failed,
        }
    }
}

/// How `inspect.measure` selects: bodies, or one or two picked items. With `items`, `bodies` and
/// `names_only` are not read, so the check leaves them alone.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct MeasureKeys {
    /// The bodies to measure, by name. Default: all. Not read with `items`.
    #[serde(default, deserialize_with = "body_names", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "body_names_schema")]
    pub bodies: Option<Vec<String>>,
    /// Give each body's name and its definition's and measure nothing. Default: false. Not read
    /// with `items`.
    #[serde(default)]
    pub names_only: Option<bool>,
    /// One or two selections to measure, instead of bodies: a face or edge `{type, body, point}`
    /// (`index` is optional), or a body, vertex, sketch curve or profile as `Sel` has it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "items_schema")]
    pub items: Option<Vec<Value>>,
}

fn items_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"type": "array", "items": {"type": "object"}, "minItems": 1, "maxItems": 1000})
}

/// `inspect.measure`'s parameters: [`MeasureKeys`], read as the handler reads them: with `items`
/// given (even as `null`) only `items` is read; without it, `bodies` and `names_only`.
#[derive(Debug)]
pub struct MeasureParams(pub MeasureKeys);

impl<'de> Deserialize<'de> for MeasureParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let value = Value::deserialize(d)?;
        if let Some(items) = value.get("items") {
            let list = items.as_array().ok_or_else(|| D::Error::custom(whole("`items` must be a list of selections")))?;
            if list.is_empty() || list.len() > 1000 {
                return Err(D::Error::custom(whole("measure one or two items")));
            }
            return Ok(MeasureParams(MeasureKeys { bodies: None, names_only: None, items: Some(list.clone()) }));
        }
        serde_path_to_error::deserialize(&value).map(MeasureParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

impl JsonSchema for MeasureParams {
    fn schema_name() -> Cow<'static, str> {
        "MeasureParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        MeasureKeys::json_schema(generator)
    }
}

/// What `inspect.measure` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MeasureResult {
    #[serde(flatten)]
    pub measured: Measured,
    /// 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>,
}

/// The shapes of `inspect.measure`'s reply.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum Measured {
    /// With `items`.
    Items(Box<MeasuredItems>),
    /// With `names_only`.
    Names(BodyNames),
    /// Bodies.
    Bodies(MeasuredBodies),
}

/// Each world body's name and its definition's.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BodyNames {
    pub body_count: usize,
    pub bodies: Vec<BodyName>,
}

/// A body by its name and its definition's.
#[derive(Debug, Serialize, JsonSchema)]
pub struct BodyName {
    pub name: String,
    pub definition: String,
}

/// The bodies measured, with their totals.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MeasuredBodies {
    pub body_count: usize,
    pub bodies: Vec<MeasuredBody>,
    pub total: MeasureTotal,
}

/// A body measured, with its material and mass.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MeasuredBody {
    #[serde(flatten)]
    pub measurement: BodyMeasurement,
    /// Its material's name.
    pub material: String,
    /// The material's density; only for a body with a volume.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub density_g_cm3: Option<f64>,
    /// Its mass (g); only for a body with a volume.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mass_g: Option<f64>,
    /// True for a sheet metal body, whose counts are its own, with round holes as the design
    /// shows them.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sheet_metal: Option<bool>,
}

/// The sum over the bodies measured.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MeasureTotal {
    /// How many bodies are left out of the volume and mass because they enclose none.
    pub open_bodies_skipped: usize,
    pub volume_mm3: f64,
    pub area_mm2: f64,
    pub mass_g: f64,
    pub faces: u64,
    pub edges: u64,
    pub vertices: u64,
}

/// One or two picked items measured: each item, then what its shape gives (for one item) or what
/// lies between the two.
#[derive(Debug, Default, Serialize, JsonSchema)]
pub struct MeasuredItems {
    /// Each item described: its kind, what it is and its own figures.
    pub items: Vec<Map<String, Value>>,
    /// One item that is round: its diameter (mm).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<f64>")]
    pub diameter: Option<Value>,
    /// Its radius (mm).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<f64>")]
    pub radius: Option<Value>,
    /// A full circle's circumference (mm).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<f64>")]
    pub circumference: Option<Value>,
    /// An arc's sweep in degrees; two items: the angle between them.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<f64>")]
    pub angle_deg: Option<Value>,
    /// An arc's length (mm).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<f64>")]
    pub arc_length: Option<Value>,
    /// One round item's centre.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<[f64; 3]>")]
    pub center: Option<Value>,
    /// One slot: its `width`, `center_distance`, `overall_length` and the two `centers`.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<Map<String, Value>>")]
    pub slot: Option<Value>,
    /// One slot: where its first end is centred; two items: the first item's centre.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub center_from: Option<[f64; 3]>,
    /// One slot: its second end's centre; two items: the second's.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub center_to: Option<[f64; 3]>,
    /// Two items: the closest distance between them (mm).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub distance_mm: Option<f64>,
    /// Two items: where it starts on the first. A coordinate is `null` where it isn't a number: two planes that meet have no
    /// such point to name (their distance is 0).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<[Option<f64>; 3]>")]
    pub from: Option<[f64; 3]>,
    /// Two items: where it ends on the second. A coordinate is `null` where it isn't a number: two planes that meet have no
    /// such point to name (their distance is 0).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<[Option<f64>; 3]>")]
    pub to: Option<[f64; 3]>,
    /// Two items: `to` minus `from`. A coordinate is `null` where it isn't a number: two planes that meet have no
    /// such point to name (their distance is 0).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<[Option<f64>; 3]>")]
    pub delta: Option<[f64; 3]>,
    /// Two items: the closest distance, as `distance_mm`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min: Option<f64>,
    /// Two items: the farthest distance (mm).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_from: Option<[f64; 3]>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_to: Option<[f64; 3]>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_delta: Option<[f64; 3]>,
    /// Two items: the distance between their centres (or from an axis) (mm).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub center_distance: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub center_delta: Option<[f64; 3]>,
    /// Two items: which distance is the one to read, `center` or `min`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub measure: Option<MeasureKind>,
}

/// Which of two items' distances is the one to read.
#[derive(Clone, Copy, Debug, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum MeasureKind {
    Center,
    Min,
}

/// List every command: its id, label, place on the toolbar, icon, shortcut, parameter prose and
/// whether it can run now.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct CommandsParams {}

/// One command of `engine.commands`' list.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CommandEntry {
    /// The command's id, such as `solid.extrude`.
    pub id: String,
    pub label: String,
    /// The toolbar tab it is on; empty when it is on none.
    pub tab: String,
    /// The panel of that tab.
    pub panel: String,
    pub icon: String,
    pub shortcut: Option<String>,
    /// The parameter documentation, as prose (`engine.describe` has the schemas).
    pub params: String,
    /// Whether it can run in the session's state now.
    pub enabled: bool,
    /// Why it can't; `null` when it can.
    pub disabled_reason: Option<String>,
    /// For a command that is planned and not built yet: what is planned.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub planned: Option<String>,
}

impl From<crate::cmd::CommandInfo> for CommandEntry {
    fn from(c: crate::cmd::CommandInfo) -> Self {
        CommandEntry {
            id: c.id.into(),
            label: c.label.into(),
            tab: c.tab.into(),
            panel: c.panel.into(),
            icon: c.icon.into(),
            shortcut: c.shortcut.map(Into::into),
            params: c.params.into(),
            enabled: c.enabled,
            disabled_reason: c.disabled_reason,
            planned: c.planned.map(Into::into),
        }
    }
}

/// `material.list` takes no parameters.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct MaterialListParams {}

/// What `material.list` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MaterialListResult {
    /// The built-in materials, then the design's own.
    pub materials: Vec<ListedMaterial>,
    /// 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 material in the list.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum ListedMaterial {
    /// A built-in material.
    BuiltIn {
        name: String,
        /// Its density (g/cm³).
        density_g_cm3: f64,
    },
    /// One this design defines, with `user` true, its look and its physical card when it has
    /// one.
    Design(Box<MaterialReply>),
}

/// A name as `material.assign` reads `material`: text, with the handler's message for anything
/// else, `null` included.
fn material_name<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    match Value::deserialize(d)? {
        Value::String(s) => Ok(Some(s)),
        _ => Err(D::Error::custom(whole("`material` must be a material name"))),
    }
}

/// Give bodies a physical material (a built-in one, or one made with `material.create`), which
/// their mass and density come from. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = bodies_and_material_required)]
pub struct MaterialAssignParams {
    // Optional in the type and required in the schema (`bodies_and_material_required`).
    /// The bodies, by name: one or a list, at least one, each an existing body.
    #[serde(default, deserialize_with = "body_names", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "material_bodies_schema")]
    pub bodies: Option<Vec<String>>,
    /// The material's name (Steel, Aluminum, ABS Plastic, …, or one made with `material.create`;
    /// `material.list` lists them). Letter case and spaces at either end don't matter.
    #[serde(default, deserialize_with = "material_name", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "material_schema")]
    pub material: Option<String>,
}

fn material_bodies_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": params::MAX_STRING_LIST}]})
}

fn material_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"type": "string"})
}

/// What `material.assign` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MaterialAssignResult {
    /// The bodies that got the material.
    pub bodies: Vec<String>,
    /// The material's name as the design has it.
    pub material: 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>,
}

/// A sketch by its feature id (a number) or its name, as `sketch.inspect` reads `sketch`.
#[derive(Clone, Debug, PartialEq)]
pub enum SketchTarget {
    Id(u64),
    Name(String),
}

impl<'de> Deserialize<'de> for SketchTarget {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Number(n) => n.as_u64().map(SketchTarget::Id),
            Value::String(s) => Some(SketchTarget::Name(s)),
            _ => None,
        }
        .ok_or_else(|| D::Error::custom(whole("`sketch` must be an id or a name")))
    }
}

impl JsonSchema for SketchTarget {
    fn schema_name() -> Cow<'static, str> {
        "SketchTarget".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "A sketch's feature id (a number, never a name) or its name.",
            "anyOf": [{"type": "integer", "minimum": 0, "maximum": u64::MAX}, {"type": "string"}]
        })
    }
}

/// Read a sketch: its curves, points, constraints, profiles, links and 3D curves, with what is
/// determined and what is not. Read-only.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct SketchInspectParams {
    /// The sketch. Default (also `null`): the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
}

/// What `sketch.inspect` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SketchInspected {
    /// The sketch's feature id.
    pub id: u64,
    pub name: String,
    /// Where it lies, as saved.
    #[schemars(with = "Map<String, Value>")]
    pub plane: Value,
    pub status: SketchStatus,
    /// Its remaining degrees of freedom (0: fully constrained).
    pub dof: usize,
    pub fully_constrained: bool,
    /// The constraints still violated after a failed solve.
    pub failing: Vec<String>,
    pub curves: Vec<SketchCurve>,
    pub points: Vec<SketchPoint>,
    pub constraints: Vec<SketchConstraint>,
    pub profiles: Vec<SketchProfile>,
    /// Links to geometry outside the sketch (projections, intersections, includes), as saved.
    #[schemars(with = "Vec<Map<String, Value>>")]
    pub links: Value,
    /// Its 3D curves.
    pub wires: Vec<SketchWire>,
    /// Whether it is shown.
    pub visible: 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 curve of a sketch: its id, what it is and how it is held.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SketchCurve {
    pub id: String,
    #[serde(flatten)]
    pub shape: CurveShape,
    pub construction: bool,
    /// Whether it is locked (fixed, or linked).
    pub fixed: bool,
    /// Whether everything that defines it is determined by constraints.
    pub fully_constrained: bool,
    /// For a linked curve: the link that owns it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub link: Option<String>,
}

/// A curve's kind and its points, by id and (`_at`) by position `[x, y]` in the sketch's plane.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum CurveShape {
    Line {
        start: String,
        end: String,
        start_at: Option<[f64; 2]>,
        end_at: Option<[f64; 2]>,
    },
    Circle {
        center: String,
        center_at: Option<[f64; 2]>,
        radius: f64,
    },
    Arc {
        center: String,
        start: String,
        end: String,
        center_at: Option<[f64; 2]>,
        start_at: Option<[f64; 2]>,
        end_at: Option<[f64; 2]>,
        radius: Option<f64>,
    },
    Ellipse {
        center: String,
        /// The end of the major axis.
        major: String,
        center_at: Option<[f64; 2]>,
        major_at: Option<[f64; 2]>,
        minor_radius: f64,
    },
    Spline {
        points: Vec<String>,
        points_at: Vec<Option<[f64; 2]>>,
        /// Whether `points` are control points of a B-spline, not fit points.
        control: bool,
        degree: u8,
        periodic: bool,
        /// A control spline with its own knots (a projected free-form edge).
        #[serde(skip_serializing_if = "Option::is_none")]
        knots: Option<Vec<f64>>,
        /// Its weights, when it has any.
        #[serde(skip_serializing_if = "Option::is_none")]
        weights: Option<Vec<f64>>,
    },
    Conic {
        start: String,
        end: String,
        apex: String,
        start_at: Option<[f64; 2]>,
        end_at: Option<[f64; 2]>,
        apex_at: Option<[f64; 2]>,
        rho: f64,
    },
}

/// A point of a sketch.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SketchPoint {
    pub id: String,
    /// Its position `[x, y]` in the sketch's plane (mm).
    pub at: [f64; 2],
    /// Where that is in the design (mm).
    pub world: [f64; 3],
    /// Whether it is locked (fixed, or linked).
    pub fixed: bool,
    /// For a linked point: the link that owns it; `null` otherwise.
    pub link: Option<String>,
    pub fully_constrained: bool,
}

/// A constraint or dimension: its id, its kind's name and the kind's own fields (`type`, then
/// the points and curves it ties, a value…), as saved.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SketchConstraint {
    pub id: String,
    /// The kind in short, such as `Horizontal`.
    pub name: String,
    /// For a dimension: the parameter that drives it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub param: Option<String>,
    /// With `param`: the parameter's expression; `null` when the design has no such parameter.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Option<String>")]
    pub expression: Option<Option<String>>,
    #[serde(flatten)]
    pub kind: Map<String, Value>,
}

/// A region the sketch closes.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SketchProfile {
    pub index: usize,
    pub area_mm2: f64,
    /// Its centroid `[x, y]` in the sketch's plane.
    pub centroid_sketch: [f64; 2],
    /// The curves of its outer loop, each once, in loop order.
    pub curves: Vec<String>,
    /// The curves of each hole's loop.
    pub holes: Vec<Vec<String>>,
}

/// A 3D curve a sketch carries.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SketchWire {
    pub id: String,
    /// How many points its polyline has.
    pub points: usize,
    pub start: Option<[f64; 3]>,
    pub end: Option<[f64; 3]>,
    /// For a linked curve: the link that owns it; `null` otherwise.
    pub link: Option<String>,
    /// For an exact circular arc: its geometry; `null` otherwise.
    pub arc: Option<WireArcInfo>,
}

/// An exact circular arc of a 3D curve.
#[derive(Debug, Serialize, JsonSchema)]
pub struct WireArcInfo {
    pub center: [f64; 3],
    pub radius: f64,
    pub start: [f64; 3],
    pub end: [f64; 3],
    /// Its sweep (degrees).
    pub sweep_deg: f64,
}

#[cfg(test)]
#[path = "inspect_tests.rs"]
mod tests;