Skip to content

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

9.0 KB
Raw Blame
//! Contracts and result types for the commands in `cmd/parts.rs`: standard parts (#11003).

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;
use solidcore_record::Vec3;

use super::check::whole;
use super::types::Point3;
use crate::params;

/// List the standard part families, or one family's sizes with their dimensions (mm).
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct PartsLibraryParams {
    /// One family, as the list names it (default: every family).
    #[serde(default)]
    pub family: Option<String>,
}

/// Insert a standard part as a new component: seated in holes with a rigid joint each (`at`),
/// placed at a point (`point`), or at the origin. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct PartsInsertParams {
    /// The family, as `parts.library` lists it: socket_head_cap_screw, button_head_cap_screw,
    /// hex_bolt, hex_nut, washer, set_screw, dowel_pin, bearing, hex_cap_screw_inch,
    /// hex_nut_inch, washer_sae or washer_uss.
    #[serde(deserialize_with = "family")]
    pub family: String,
    /// The size, as `parts.library` lists it: `M6`, `608` for a bearing, `1/2-13 UNC` for an
    /// inch screw or nut, `1/2` for an inch washer.
    #[serde(deserialize_with = "size")]
    pub size: String,
    #[serde(default, deserialize_with = "length")]
    #[schemars(schema_with = "length_schema")]
    pub length: Option<f64>,
    #[serde(default)]
    pub at: Option<HolePicks>,
    /// Without `at`: where the part's origin goes, with no joint.
    #[serde(default)]
    pub point: Option<Point3>,
    /// With `point`: the direction the part's +Z turns to (default +Z), a non-zero `[x, y, z]`.
    #[serde(default)]
    pub direction: Option<Point3>,
    /// The component's name (default: the part's, such as `Socket Head Cap Screw M6x20`).
    #[serde(default)]
    pub name: Option<String>,
}

/// Change an inserted standard part's size or length, rebuilding it in place; its joints keep it
/// seated. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct PartsResizeParams {
    /// The part's component, by id or name.
    #[serde(deserialize_with = "component")]
    #[schemars(schema_with = "component_schema")]
    pub component: String,
    /// The new size (default: the part's).
    #[serde(default)]
    pub size: Option<String>,
    #[serde(default, deserialize_with = "length")]
    #[schemars(schema_with = "length_schema")]
    pub length: Option<f64>,
}

/// The family, with the handler's message for anything that isn't text.
fn family<'de, D: Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    match Value::deserialize(d)? {
        Value::String(s) => Ok(s),
        _ => Err(D::Error::custom(whole("`family` is required (parts.library)"))),
    }
}

/// The size, with the handler's message for anything that isn't text.
fn size<'de, D: Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    match Value::deserialize(d)? {
        Value::String(s) => Ok(s),
        _ => Err(D::Error::custom(whole("`size` is required"))),
    }
}

/// A part's length, as the handler reads it: `null` is the default, else above 0 and at most
/// 2000 mm.
fn length<'de, D: Deserializer<'de>>(d: D) -> Result<Option<f64>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        v => v
            .as_f64()
            .and_then(params::finite)
            .filter(|l| *l > 0.0 && *l <= 2000.0)
            .map(Some)
            .ok_or_else(|| D::Error::custom(whole("`length` must be 0…2000 mm"))),
    }
}

fn length_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({
        "description": "For screws, bolts, set screws and pins: the length in mm, inch parts too (default: a standard length near 2.5 diameters).",
        "type": ["number", "null"],
        "exclusiveMinimum": 0,
        "maximum": 2000
    })
}

/// A component's id or name, as the resize reads it, with its message.
fn component<'de, D: Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    match Value::deserialize(d)? {
        Value::Number(n) => Ok(n.to_string()),
        Value::String(s) => Ok(s),
        _ => Err(D::Error::custom("must be an id or a name")),
    }
}

fn component_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"description": "The part's component, by id or name.", "type": ["number", "string"]})
}

/// The most holes one insert seats a part in.
const MAX_HOLES: usize = 1000;

/// Points on the rims or walls of holes, as the insert reads them: one point, or a list of up to
/// 1000 (a list's first item is a list, or it is empty), with its messages. The part seats on
/// each hole's face with a rigid joint, placed once per hole as one component.
#[derive(Clone, Debug, PartialEq)]
pub struct HolePicks(pub Vec<Vec3>);

impl<'de> Deserialize<'de> for HolePicks {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let fail = || D::Error::custom(whole("`at` must be [x,y,z] or a list of them"));
        let one = |v: &Value| params::vec3(v).ok_or_else(fail);
        match Value::deserialize(d)? {
            Value::Array(list) if list.first().is_some_and(Value::is_array) || list.is_empty() => {
                if list.len() > MAX_HOLES {
                    return Err(D::Error::custom(whole(format!("`at` takes at most {MAX_HOLES} holes"))));
                }
                list.iter().map(one).collect::<Result<_, _>>().map(HolePicks)
            }
            v => Ok(HolePicks(vec![one(&v)?])),
        }
    }
}

impl JsonSchema for HolePicks {
    fn schema_name() -> Cow<'static, str> {
        "HolePicks".into()
    }
    fn inline_schema() -> bool {
        true
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let point = generator.subschema_for::<Point3>();
        json_schema!({
            "description": "A point on a hole's rim or wall, or a list of them (one per hole, at most 1000): the part seats on each hole's face with a rigid joint.",
            "anyOf": [point.clone(), {"type": "array", "prefixItems": [{"allOf": [{"type": "array"}, point.clone()]}], "items": point, "maxItems": MAX_HOLES}]
        })
    }
}

/// What `parts.library` returns: every family, or the one asked for.
#[derive(Debug, Serialize, JsonSchema)]
pub struct PartsLibrary {
    /// Without `family`: every family.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub families: Option<Vec<PartFamily>>,
    /// With `family`: that family.
    #[serde(flatten)]
    pub family: Option<PartFamily>,
    /// 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 standard part family.
#[derive(Debug, Serialize, JsonSchema)]
pub struct PartFamily {
    /// Its id, as `parts.insert` takes it.
    pub family: String,
    pub name: String,
    /// The standard its sizes follow.
    pub standard: String,
    /// `metric` or `inch`.
    pub system: String,
    /// Each size with its dimensions in mm (which depend on the family), and `default_length`
    /// where the part has a length.
    #[schemars(schema_with = "sizes_schema")]
    pub sizes: Vec<Value>,
    /// The standard lengths (mm), for the families that have one; else `null`.
    pub lengths: Option<Vec<f64>>,
}

fn sizes_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({"type": "array", "items": {"type": "object", "properties": {"size": {"type": "string"}}, "required": ["size"]}})
}

/// What `parts.insert` and `parts.fastener` return.
#[derive(Debug, Serialize, JsonSchema)]
pub struct InsertedPart {
    /// The new component's id.
    pub component: u64,
    /// Its first occurrence's id.
    pub occurrence: u64,
    /// The component's name.
    pub name: String,
    /// With `at`: the first hole's joint.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub joint: Option<u64>,
    /// With `at`: an occurrence per hole, in pick order.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub occurrences: Option<Vec<u64>>,
    /// With `at`: a joint per hole, in pick order.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub joints: Option<Vec<u64>>,
    /// 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 `parts.resize` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ResizedPart {
    pub component: u64,
    /// The component's new name.
    pub name: String,
    pub size: String,
    /// Its length (mm), for a part that has one; else `null`.
    pub length: Option<f64>,
    /// 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 = "parts_tests.rs"]
mod tests;