Skip to content

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

34.9 KB
Raw Blame
//! Contracts and result types for the commands in `cmd/motion.rs`.

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_geom::Vec3Geom as _;

use super::check::{located, whole};

/// Find where each value of a joint can go before the parts it moves touch another body. The
/// design is not changed.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct FindLimitsParams {
    pub joint: JointRef,
    /// Which value (0 for a revolute's angle). Default: every value of the joint.
    #[serde(default)]
    pub index: Option<u64>,
    /// mm: each stop is bisected until no part moves more than this between the last clear value
    /// and the touching one (above 0, at most 1000). Default: 0.01.
    #[serde(default)]
    pub refine: Option<f64>,
    /// Between samples, in the value's unit (degrees for angles, mm for distances; above 0).
    /// Default: fine enough that no part passes through another between two.
    #[serde(default)]
    pub step: Option<f64>,
    /// The parts checked against each other. Default: every occurrence.
    #[serde(default, deserialize_with = "super::present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "Vec<PartRef>")]
    pub occurrences: Option<Vec<PartRef>>,
    /// The parts that stay: each of `occurrences` is checked only against these.
    #[serde(default)]
    pub against: Option<Vec<PartRef>>,
    /// Check the pairs of the design's contact sets instead (not with `occurrences`).
    #[serde(default)]
    pub contact_sets: Option<bool>,
}

/// A joint by its id (a number) or its name.
#[derive(Debug)]
pub struct JointRef;

impl<'de> Deserialize<'de> for JointRef {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Number(_) | Value::String(_) => Ok(JointRef),
            _ => Err(D::Error::custom("must be an id or a name")),
        }
    }
}

impl JsonSchema for JointRef {
    fn schema_name() -> Cow<'static, str> {
        "JointRef".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "A joint's id (a number) or its name.", "type": ["number", "string"]})
    }
}

/// An occurrence by its id (a number) or its name.
#[derive(Debug)]
pub struct PartRef;

impl<'de> Deserialize<'de> for PartRef {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Number(_) | Value::String(_) => Ok(PartRef),
            _ => Err(D::Error::custom("an occurrence must be an id or a name")),
        }
    }
}

impl JsonSchema for PartRef {
    fn schema_name() -> Cow<'static, str> {
        "PartRef".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "An occurrence's id (a number) or its name.", "type": ["number", "string"]})
    }
}

/// What stopped one side of a sweep.
#[derive(Clone, Debug, PartialEq, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum Stop {
    /// Two parts touch.
    Contact {
        a: String,
        b: String,
        /// Where they touch (world, mm).
        at: [f64; 3],
    },
    /// `loop`: a closed loop can no longer close; `limit`: the limit of another of the joint's
    /// values, or of another joint through a motion link; `turn`: no contact within one turn, so the side is a turn from the other;
    /// `range`: no contact within the parts' reach (a distance), so the side has no limit.
    Other(Why),
}

/// Why a side stopped short of contact.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum Why {
    Loop,
    Limit,
    Turn,
    Range,
}

/// One value's limits.
#[derive(Debug, Serialize, JsonSchema)]
pub struct FoundLimits {
    /// Which value of the joint.
    pub index: usize,
    /// Its name (angle, distance, …).
    pub dof: String,
    /// `deg` or `mm`.
    pub unit: String,
    /// Where it is now, which the search starts from.
    pub value: f64,
    /// The lowest value clear of contact, or `null` (`min_by` is `range`).
    pub min: Option<f64>,
    /// The highest value clear of contact, or `null` (`max_by` is `range`).
    pub max: Option<f64>,
    pub min_by: Stop,
    pub max_by: Stop,
    /// How far each way the search went: a turn (360) for an angle, the parts' reach for a
    /// distance.
    pub range: f64,
}

/// Two parts already passing into each other where the search starts.
#[derive(Debug, Serialize, JsonSchema)]
pub struct Overlap {
    pub a: String,
    pub b: String,
    /// How deep (mm).
    pub depth_mm: f64,
}

/// What `joint.find_limits` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct FindLimitsResult {
    pub joint: u64,
    pub name: String,
    pub values: Vec<FoundLimits>,
    pub refine_mm: f64,
    /// `mesh`: distances between the parts' tessellations.
    pub gap_method: String,
    /// How far those can be off: 0 when every face is flat.
    pub gap_tolerance_mm: f64,
    /// How many pairs of parts are checked.
    pub pairs: usize,
    /// Pairs of parts touching where the search starts: they stop it only once they pass into
    /// each other deeper than they start.
    pub touching_at_start: Vec<[String; 2]>,
    /// Pairs of those already passing into each other, deeper than a touch.
    pub overlapping_at_start: Vec<Overlap>,
    /// 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>,
}

// ---- Contact (#11949) ----
//
// The contact 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 the occurrences and the set
// exist stays the handler's to check.

/// The most occurrences a contact set's list may name, as `cmd/motion.rs`'s `MAX_ITEMS`.
const MAX_OCCURRENCES: usize = 10_000;

/// Turn contact sets on or off: while on, driving a joint or playing a motion study stops where
/// bodies in one contact set would pass through each other. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ContactEnableParams {
    /// Whether contact sets are on. Default: true.
    #[serde(default)]
    pub enabled: Option<bool>,
}

/// No parameters: `contact.enable_all` (every occurrence takes part in contact, as one set),
/// `contact.disable_all` (contact off), `contact.list` and `contact.check` (read only).
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ContactNoParams {}

/// Make a contact set: occurrences whose bodies may touch but not pass through each other while
/// joints move. Contact sets are turned on. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = occurrences_required)]
pub struct ContactCreateParams {
    // Optional in the type and required in the schema (`occurrences_required`): left out, the
    // handler refuses it with its own message, not the check's "is required".
    #[serde(default, deserialize_with = "some_occurrences", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "OccurrenceKeys")]
    pub occurrences: Option<OccurrenceKeys>,
    /// The set's name. Default: "Contact Set" and the first number no set's name has.
    #[serde(default)]
    pub name: Option<String>,
}

/// Change a contact set: its occurrences, its name, or whether it's suppressed; or delete it. One
/// undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = set_required)]
pub struct ContactEditParams {
    // Required in the schema (`set_required`), optional in the type, as `occurrences` above.
    #[serde(default, deserialize_with = "contact_set", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "contact_set_schema")]
    pub set: Option<Value>,
    /// The set's new occurrences, replacing them all.
    #[serde(default, deserialize_with = "some_occurrences", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "OccurrenceKeys")]
    pub occurrences: Option<OccurrenceKeys>,
    /// The set's new name; blank text keeps the name.
    #[serde(default)]
    pub name: Option<String>,
    /// Suppress the set (it stops nothing) or not.
    #[serde(default)]
    pub suppressed: Option<bool>,
    /// Delete the set instead; the other keys are then not used. Default: false.
    #[serde(default)]
    pub delete: Option<bool>,
}

/// A contact set's occurrences, as `cmd/motion.rs`'s `occurrences` reads them: a list of ids or
/// names, with its messages. An occurrence named twice counts once.
#[derive(Clone, Debug, PartialEq)]
pub struct OccurrenceKeys(pub Vec<Value>);

impl<'de> Deserialize<'de> for OccurrenceKeys {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Array(list) if list.len() > MAX_OCCURRENCES => Err(D::Error::custom(whole("too many occurrences"))),
            Value::Array(list) if list.iter().all(|v| v.is_number() || v.is_string()) => Ok(OccurrenceKeys(list)),
            Value::Array(_) => Err(D::Error::custom(whole("an occurrence must be an id or a name"))),
            _ => Err(D::Error::custom(whole("`occurrences` must list occurrences"))),
        }
    }
}

impl JsonSchema for OccurrenceKeys {
    fn schema_name() -> Cow<'static, str> {
        "OccurrenceKeys".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "Two or more occurrences, each by id (a number) or name; not the root.",
            "type": "array",
            "items": {"type": ["number", "string"]},
            "minItems": 2,
            "maxItems": MAX_OCCURRENCES
        })
    }
}

/// `occurrences`: given, `null` included, it must be [`OccurrenceKeys`], as the handlers read it
/// whenever the key is there.
fn some_occurrences<'de, D: Deserializer<'de>>(d: D) -> Result<Option<OccurrenceKeys>, D::Error> {
    OccurrenceKeys::deserialize(d).map(Some)
}

/// `set`: an id or a name, with the handler's message for anything else, `null` included.
fn contact_set<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Value>, D::Error> {
    match Value::deserialize(d)? {
        v @ (Value::Number(_) | Value::String(_)) => Ok(Some(v)),
        _ => Err(D::Error::custom(whole("`set` must be an id or a name"))),
    }
}

fn contact_set_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"description": "The contact set, by id (a number) or name.", "type": ["number", "string"]})
}

/// Adds `key` 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.
pub(super) 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 occurrences_required(schema: &mut Schema) {
    require(schema, "occurrences");
}

fn set_required(schema: &mut Schema) {
    require(schema, "set");
}

/// What `contact.enable_sets`, `contact.enable_all` and `contact.disable_all` return.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ContactSwitch {
    /// Whether contact is on.
    pub enabled: bool,
    /// From `contact.enable_all`: always true, every occurrence takes part.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub all: 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>,
}

/// What `contact.create` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ContactSetCreated {
    /// The new set's id.
    pub set: u64,
    pub name: 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 `contact.edit` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ContactSetEdited {
    #[serde(flatten)]
    pub change: ContactSetChange,
    /// 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 an edit did to the set.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum ContactSetChange {
    /// The set was deleted.
    Deleted {
        /// Always true.
        deleted: bool,
    },
    /// The set was changed.
    Changed {
        /// The set's id.
        set: u64,
    },
}

/// What `contact.list` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ContactSets {
    /// Whether contact is on.
    pub enabled: bool,
    /// Whether every occurrence takes part, as one set, instead of `sets`.
    pub all: bool,
    pub sets: Vec<ContactSetInfo>,
    /// 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 contact set, as the design saves it.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ContactSetInfo {
    pub id: u64,
    pub name: String,
    /// Its occurrences' ids.
    pub occurrences: Vec<u64>,
    /// Present, and true, when the set is suppressed.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub suppressed: bool,
}

impl From<&solidcraft_doc::motion::ContactSet> for ContactSetInfo {
    fn from(set: &solidcraft_doc::motion::ContactSet) -> Self {
        ContactSetInfo { id: set.id, name: set.name.clone(), occurrences: set.occurrences.clone(), suppressed: set.suppressed }
    }
}

/// What `contact.check` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ContactCheck {
    /// The pairs of occurrences in one contact set whose bodies pass through each other now;
    /// none while contact is off.
    pub collisions: Vec<ContactCollision>,
    /// 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>,
}

/// Two occurrences whose bodies pass through each other.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ContactCollision {
    /// The occurrences' names.
    pub a: String,
    pub b: String,
    /// How deep (mm).
    pub depth_mm: f64,
}

// ---- Motion studies (#12155) ----
//
// `motion.study` reads its parameters from the raw JSON, so each key here reads as the handler
// reads it and fails with its message. Whether the study and each key's joint exist, whether the
// joint has that value, and whether an expression evaluates stay the handler's to check.

/// The most keys a motion study takes, and the most points one key takes.
const MAX_STUDY_KEYS: usize = 1000;
const MAX_KEY_POINTS: usize = 10_000;
/// A point's step, and a value given as a number, are read only while smaller than this in size.
const MAX_POINT_MAGNITUDE: f64 = 1e9;

/// Make a motion study, which drives joints along a timeline of steps: each key gives one value of
/// one joint at some steps, linear in between and held before the first and after the last. With
/// `study`, change that study instead. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct MotionStudyParams {
    /// A study to change, by id (a number) or name; left out, a new one is made.
    #[serde(default, deserialize_with = "some_study", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "study_ref_schema")]
    pub study: Option<Value>,
    /// The study's name; blank text keeps it. Default for a new one: "Motion Study" and the first
    /// number no study's name has.
    #[serde(default)]
    pub name: Option<String>,
    /// How many steps the timeline has: 1 to 100 000 (a fraction rounds). Default for a new one: 100.
    #[serde(default, deserialize_with = "study_steps", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "f64", range(min = 1, max = 100_000))]
    pub steps: Option<f64>,
    #[serde(default, deserialize_with = "study_keys", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "study_keys_schema")]
    pub keys: Option<Vec<Value>>,
}

/// List the design's motion studies, each with its keys in the units `motion.study` takes, and its
/// associative traces. Nothing is changed.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct MotionListParams {}

/// Delete a motion study. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = study_required)]
pub struct MotionStudyDeleteParams {
    // Required in the schema (`study_required`), optional in the type: left out, the handler
    // refuses it with its own message, not the check's "is required".
    #[serde(default, deserialize_with = "some_study", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "study_ref_schema")]
    pub study: Option<Value>,
}

/// `study`: an id or a name, with the handler's message for anything else, `null` included.
pub(super) fn some_study<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Value>, D::Error> {
    match Value::deserialize(d)? {
        v @ (Value::Number(_) | Value::String(_)) => Ok(Some(v)),
        _ => Err(D::Error::custom(whole("`study` must be an id or a name"))),
    }
}

pub(super) fn study_ref_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({
        "description": "The motion study, by id (a number) or name. A number is looked up as an id first, text as a name first.",
        "type": ["number", "string"]
    })
}

fn study_required(schema: &mut Schema) {
    require(schema, "study");
}

/// `steps`: a number from 1 to 100 000, with the handler's message for anything else, `null`
/// included.
fn study_steps<'de, D: Deserializer<'de>>(d: D) -> Result<Option<f64>, D::Error> {
    Value::deserialize(d)?
        .as_f64()
        .filter(|n| n.is_finite() && (1.0..=100_000.0).contains(n))
        .map(Some)
        .ok_or_else(|| D::Error::custom(whole("`steps` must be 1…100000")))
}

/// Why the handler refuses `key`'s shape before looking at the design: its joint, value index,
/// points and values, with the handler's messages.
fn study_key_problem(key: &Value) -> Option<String> {
    if !matches!(key.get("joint"), Some(Value::Number(_) | Value::String(_))) {
        return Some("`joint` must be an id or a name".into());
    }
    // The handler reads an index that isn't a whole number as 0; the contract refuses it.
    if key.get("index").is_some_and(|i| i.as_u64().is_none()) {
        return Some("a key's `index` must be a whole number of 0 or more".into());
    }
    let Some(points) = key.get("points").and_then(Value::as_array) else {
        return Some("each key needs `points`: [[step, value], …]".into());
    };
    if points.is_empty() || points.len() > MAX_KEY_POINTS {
        return Some("a key needs 1…10000 points".into());
    }
    for point in points {
        let step = point.get(0).and_then(Value::as_f64).filter(|x| x.is_finite() && x.abs() < MAX_POINT_MAGNITUDE);
        let Some(value) = point.get(1).filter(|_| step.is_some()) else {
            return Some("points are [step, value]".into());
        };
        let readable = match value {
            Value::Number(n) => n.as_f64().is_some_and(|x| x.is_finite() && x.abs() < MAX_POINT_MAGNITUDE),
            Value::String(_) => true,
            _ => false,
        };
        if !readable {
            return Some(format!("a joint value {}", crate::params::expr_problem(Some(value))));
        }
    }
    None
}

/// `keys`: a list of at most 1000 keys, each checked as [`study_key_problem`] says. Given, `null`
/// included, it must be a list, as the handler reads it.
fn study_keys<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Vec<Value>>, D::Error> {
    let Value::Array(keys) = Value::deserialize(d)? else {
        return Err(D::Error::custom(whole("`keys` must be a list")));
    };
    if keys.len() > MAX_STUDY_KEYS {
        return Err(D::Error::custom(whole("too many keys")));
    }
    if let Some(problem) = keys.iter().find_map(study_key_problem) {
        return Err(D::Error::custom(whole(problem)));
    }
    Ok(Some(keys))
}

/// The schema of `motion.study`'s `keys`. A point's two elements are typed apart
/// (`prefixItems`): the step must be a number, while the value may be a number or an
/// expression. Elements after those two are ignored by the handler, so they are left free.
fn study_keys_schema(_: &mut SchemaGenerator) -> Schema {
    let number = json!({"type": "number", "exclusiveMinimum": -MAX_POINT_MAGNITUDE, "exclusiveMaximum": MAX_POINT_MAGNITUDE});
    json_schema!({
        "description": "The study's keys, replacing any it has (at most 1000). Each drives one value of one joint: `joint` by id or name, `index` the value (0 for a revolute's angle; default 0), and `points` as [step, value] pairs (1 to 10 000), a value being degrees for an angle and mm for a distance, or an expression.",
        "type": "array",
        "maxItems": MAX_STUDY_KEYS,
        "items": {
            "type": "object",
            "required": ["joint", "points"],
            "properties": {
                "joint": {"type": ["number", "string"]},
                "index": {"type": "integer", "minimum": 0},
                "points": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": MAX_KEY_POINTS,
                    "items": {
                        "type": "array",
                        "minItems": 2,
                        "prefixItems": [
                            number.clone(),
                            {"anyOf": [number, {"type": "string"}]}
                        ]
                    }
                }
            }
        }
    })
}

/// What `motion.study` returns: the study made or changed.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MotionStudySaved {
    /// The study's id.
    pub study: u64,
    pub name: String,
    pub steps: u32,
    /// How many keys it has.
    pub keys: usize,
    /// 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 `motion.list` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MotionStudies {
    pub studies: Vec<MotionStudyInfo>,
    /// The design's associative traces, each `{sketch, motion, samples, error}`: the sketch
    /// (by id) the trace draws into, the motion it follows (a joint's range or a study), how many
    /// samples it takes (`null`: automatic), and why it last failed (`null` when it didn't).
    #[schemars(with = "Vec<serde_json::Map<String, Value>>")]
    pub traces: Vec<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>,
}

/// A motion study, in the form `motion.study` takes it back unchanged.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MotionStudyInfo {
    pub id: u64,
    pub name: String,
    pub steps: u32,
    pub keys: Vec<MotionStudyKeyInfo>,
}

/// One key of a study.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MotionStudyKeyInfo {
    /// The joint's id.
    pub joint: u64,
    /// Its name; its id, as text, when the joint is gone.
    pub joint_name: String,
    /// Which of its values.
    pub index: usize,
    /// `deg` for an angle, `mm` for a distance: the unit of the points' values.
    pub unit: String,
    /// [step, value] pairs.
    pub points: Vec<[f64; 2]>,
}

/// What `motion.delete` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct MotionStudyDeleted {
    /// The deleted study's name.
    pub deleted: 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>,
}

// ---- Exploded views (#12501) ----
//
// The exploded view handlers read their parameters from the raw JSON, so each key here reads as
// its handler reads it and fails with its message. Whether an occurrence or a view exists stays
// the handler's to check.

/// Make an exploded view: occurrences moved apart, shown with `explode.show`. The design keeps
/// its placements. One undo step. With `moves`, each occurrence moves as given; without, every
/// top-level occurrence is pushed away from the assembly's centre by `scale` times its offset.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ExplodeCreateKeys {
    /// The view's name. Default: "Exploded View" and the first number no view's name has.
    #[serde(default)]
    pub name: Option<String>,
    /// For the automatic view: how far each occurrence is pushed away from the assembly's
    /// centre, as a multiple of its offset from it (a number from -100 to 100). Default: 1.
    /// Not read, and so not checked, when `moves` is given.
    #[serde(default, deserialize_with = "explode_scale", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "explode_scale_schema")]
    pub scale: Option<f64>,
    /// The moves, instead of the automatic view (at most 10 000): each an `occurrence` (by id or
    /// name, or a component's name for its first occurrence) and its `translate`, in mm, as
    /// [x, y, z] or {x, y, z}, less than 1e7 in length. An occurrence named twice is moved by
    /// the last.
    #[serde(default, deserialize_with = "explode_moves", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "explode_moves_schema")]
    pub moves: Option<Vec<Value>>,
}

/// `explode.create`'s parameters: [`ExplodeCreateKeys`], where `scale` is read only without
/// `moves`, as the handler does.
#[derive(Debug)]
pub struct ExplodeCreateParams(pub ExplodeCreateKeys);

impl<'de> Deserialize<'de> for ExplodeCreateParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut value = Value::deserialize(d)?;
        // `moves`, even `null`, is what the handler goes by: it never reads `scale` then.
        if let Some(keys) = value.as_object_mut()
            && keys.contains_key("moves")
        {
            keys.remove("scale");
        }
        serde_path_to_error::deserialize(&value).map(ExplodeCreateParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

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

/// `scale`: a number of at most 100 in size, with the handler's message for anything else,
/// `null` included.
fn explode_scale<'de, D: Deserializer<'de>>(d: D) -> Result<Option<f64>, D::Error> {
    Value::deserialize(d)?
        .as_f64()
        .filter(|x| x.is_finite() && x.abs() <= 100.0)
        .map(Some)
        .ok_or_else(|| D::Error::custom(whole("`scale` must be a number up to 100")))
}

fn explode_scale_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({
        "description": "For the automatic view: how far each occurrence is pushed away from the assembly's centre, as a multiple of its offset from it (a number from -100 to 100). Default: 1. Not read, and so not checked, when `moves` is given.",
        "type": "number",
        "minimum": -100,
        "maximum": 100
    })
}

/// Why the handler refuses `item`, one of `moves`, before looking at the design.
/// The handler also looks each occurrence up as it goes, so a call with an unknown occurrence in
/// an earlier move and a malformed later one gets the handler's "no occurrence" message with the
/// check off and this shape message in strict; both refuse the call.
fn explode_move_problem(item: &Value) -> Option<&'static str> {
    if !matches!(item.get("occurrence"), Some(Value::Number(_) | Value::String(_))) {
        return Some("an occurrence must be an id or a name");
    }
    let translate = item.get("translate").and_then(crate::params::vec3).filter(|v| v.len() < 1e7);
    translate.is_none().then_some("each move needs `translate`: [x, y, z]")
}

/// `moves`: a list of at most 10 000 moves, each checked as [`explode_move_problem`] says. Given,
/// `null` included, it must be a list, as the handler reads it.
fn explode_moves<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Vec<Value>>, D::Error> {
    let Value::Array(moves) = Value::deserialize(d)? else {
        return Err(D::Error::custom(whole("`moves` must be a list")));
    };
    if moves.len() > MAX_EXPLODE_ITEMS {
        return Err(D::Error::custom(whole("too many moves")));
    }
    if let Some(problem) = moves.iter().find_map(explode_move_problem) {
        return Err(D::Error::custom(whole(problem)));
    }
    Ok(Some(moves))
}

/// The most moves a view takes, and the most views a design has, as `cmd/motion.rs`'s `MAX_ITEMS`.
const MAX_EXPLODE_ITEMS: usize = 10_000;

fn explode_moves_schema(_: &mut SchemaGenerator) -> Schema {
    let c = json!({"type": "number", "exclusiveMinimum": -1e7, "exclusiveMaximum": 1e7});
    json_schema!({
        "description": "The moves, instead of the automatic view (at most 10 000): each an `occurrence` (by id or name, or a component's name for its first occurrence) and its `translate`, in mm, as [x, y, z] or {x, y, z}, less than 1e7 in length. An occurrence named twice is moved by the last.",
        "type": "array",
        "maxItems": MAX_EXPLODE_ITEMS,
        "items": {
            "type": "object",
            "required": ["occurrence", "translate"],
            "properties": {
                "occurrence": {"type": ["number", "string"]},
                "translate": {
                    "anyOf": [
                        {"type": "array", "items": c, "minItems": 3, "maxItems": 3},
                        {"type": "object", "properties": {"x": c, "y": c, "z": c}, "required": ["x", "y", "z"]}
                    ]
                }
            }
        }
    })
}

/// An exploded view by its id (a number) or its name.
#[derive(Clone, Debug, PartialEq)]
pub struct ViewRef(pub Value);

impl<'de> Deserialize<'de> for ViewRef {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            v @ (Value::Number(_) | Value::String(_)) => Ok(ViewRef(v)),
            _ => Err(D::Error::custom(whole("`view` must be an id or a name"))),
        }
    }
}

impl JsonSchema for ViewRef {
    fn schema_name() -> Cow<'static, str> {
        "ViewRef".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "An exploded view's id (a number) or its name.", "type": ["number", "string"]})
    }
}

/// Show an exploded view in the model: the occurrences are drawn moved apart, and the design
/// keeps its placements. Without a view (or `none`), show the assembled placement again.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ExplodeShowParams {
    /// The view to show, by id (a number) or name. Default: none, which shows the assembled
    /// placement; `null` and the text `none` (in any case) mean the same.
    #[serde(default)]
    pub view: Option<ViewRef>,
}

/// List the design's exploded views. Nothing is changed.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ExplodeListParams {}

/// Delete an exploded view. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = view_required)]
pub struct ExplodeDeleteParams {
    // Required in the schema (`view_required`), optional in the type: left out, the handler
    // refuses it with its own message, not the check's "is required". `null` is refused too.
    /// The view to delete, by id (a number) or name.
    #[serde(default, deserialize_with = "some_view", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ViewRef")]
    pub view: Option<ViewRef>,
}

/// `view`: an id or a name, with the handler's message for anything else, `null` included.
fn some_view<'de, D: Deserializer<'de>>(d: D) -> Result<Option<ViewRef>, D::Error> {
    ViewRef::deserialize(d).map(Some)
}

fn view_required(schema: &mut Schema) {
    require(schema, "view");
}

/// One move of an exploded view.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ExplodeMoveInfo {
    /// The occurrence, by id.
    pub occurrence: u64,
    /// How far it moves, in mm (world).
    pub translate: [f64; 3],
}

impl From<&(u64, solidcore_record::Vec3)> for ExplodeMoveInfo {
    fn from((occurrence, t): &(u64, solidcore_record::Vec3)) -> Self {
        ExplodeMoveInfo { occurrence: *occurrence, translate: [t.x, t.y, t.z] }
    }
}

/// What `explode.create` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ExplodeCreated {
    /// The new view's id.
    pub view: u64,
    pub name: String,
    pub moves: Vec<ExplodeMoveInfo>,
    /// 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 `explode.show` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ExplodeShown {
    /// The view shown, by id; `null` when the assembled placement is shown.
    pub view: Option<u64>,
    /// The view's name; not there when the assembled placement is shown.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<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 `explode.list` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ExplodeViews {
    pub views: Vec<ExplodedViewInfo>,
    /// 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>,
}

/// An exploded view, as the design saves it.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ExplodedViewInfo {
    pub id: u64,
    pub name: String,
    /// [occurrence id, translation in mm] pairs.
    pub moves: Vec<(u64, [f64; 3])>,
}

impl From<&solidcraft_doc::motion::ExplodedView> for ExplodedViewInfo {
    fn from(view: &solidcraft_doc::motion::ExplodedView) -> Self {
        let moves = view.moves.iter().map(|(o, t)| (*o, [t.x, t.y, t.z])).collect();
        ExplodedViewInfo { id: view.id, name: view.name.clone(), moves }
    }
}

/// What `explode.delete` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ExplodeDeleted {
    /// The deleted view's name.
    pub deleted: String,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

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