SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Contracts and reply types for the commands in `cmd/plastic.rs`: the plastic rule commands
//! Manage, Assign and List Plastic Rules (#12313), and the plastic features Boss, Lip, Snap Fit
//! and Rest (#12622). A plastic rule holds a plastic part's design values, which the features
//! take as defaults.
//!
//! 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 rule, a body or a face exists, and
//! whether an expression evaluates and fits the part, stay the handlers' to check. Where a
//! handler ignores a key of the wrong type (a `delete` that isn't true or false, a rule value or
//! a feature's optional size that is neither a number nor text), the contract refuses it.
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::Value;
use solidcore_record::Vec3;
use solidcraft_doc::plastic::{PlasticRule, PlasticValues};
use solidcraft_geom::Vec3Geom as _;
use super::check::whole;
use super::config::NameList;
use super::types::{
AngleExpr, FeatureCommon, LengthExpr, LipSideParam, LipTypeParam, NumberExpr, Point3, TouchingParam, feature_common, not_blank_pattern, present,
};
/// The longest rule name, in bytes once trimmed, as `plastic.manage_rules` reads it.
const MAX_RULE_NAME_BYTES: usize = 128;
/// `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 name_required(schema: &mut Schema) {
require(schema, "name");
}
fn bodies_required(schema: &mut Schema) {
require(schema, "bodies");
}
/// Make or edit a plastic rule, make it the active rule (the one for bodies without a rule of
/// their own), or delete it. A new rule starts from `from`; an existing one keeps the values not
/// given. Each value is a number or an expression, and may use the design's parameters; in a
/// rule's other values, `Thickness` is that rule's thickness.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = name_required)]
pub struct ManageRulesParams {
/// The rule, by name: a library rule (to edit it in this design) or a new one. Trimmed,
/// 1 to 128 bytes.
// Optional in the type, required in the schema: left out, the handler refuses the call
// with its own message.
#[serde(default, deserialize_with = "rule_name")]
#[schemars(schema_with = "rule_name_schema", transform = drop_default)]
pub name: Option<String>,
/// For a new rule: the rule it starts from. Default: "ABS (1.5mm)".
pub from: Option<String>,
/// The material the rule is for, as a note (at most 128 characters are kept).
pub material: Option<String>,
/// The nominal wall thickness.
pub thickness: Option<LengthExpr>,
/// The nominal radius of rounds.
pub nominal_radius: Option<LengthExpr>,
/// The clearance between mating parts: a groove's gap when it gives none.
pub clearance: Option<LengthExpr>,
pub knife_edge: Option<LengthExpr>,
pub reveal_height: Option<LengthExpr>,
/// How much a wall's thickness may vary.
pub thickness_variation: Option<LengthExpr>,
/// The draft of plastic features when they give none.
pub draft: Option<AngleExpr>,
/// The thickest wall allowed.
pub max_thickness: Option<LengthExpr>,
/// The thinnest wall allowed.
pub min_thickness: Option<LengthExpr>,
/// The least draft allowed.
pub min_draft: Option<AngleExpr>,
/// True makes this the active rule; false stops it being the active rule.
pub active: Option<bool>,
/// True deletes the rule from the design (a library rule goes back to the library's
/// values). Default: false.
pub delete: Option<bool>,
}
/// A rule's name as `plastic.manage_rules` reads it: text that isn't blank, at most 128 bytes
/// once trimmed, and the handler's message for anything else.
fn rule_name<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
match Value::deserialize(d)? {
Value::String(name) if !name.trim().is_empty() && name.trim().len() <= MAX_RULE_NAME_BYTES => Ok(Some(name.trim().to_string())),
_ => Err(D::Error::custom(whole("`name` is required"))),
}
}
/// The pattern says "not blank"; at most 128 bytes once trimmed, which JSON Schema can't count,
/// is in the field's description and checked by [`rule_name`].
fn rule_name_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({"type": "string", "minLength": 1, "pattern": not_blank_pattern()})
}
/// Assign a plastic rule to bodies, or take theirs away. Plastic features on those bodies take
/// the rule's draft and clearance as defaults.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = bodies_required)]
pub struct AssignRuleParams {
/// The bodies, by name: 1 to 10 000.
// Optional in the type, required in the schema: left out, `null` or empty, the handler
// refuses the call with its own message, so the schema allows none of those.
#[serde(default)]
#[schemars(schema_with = "bodies_schema")]
pub bodies: Option<NameList>,
/// The rule, by name, as `plastic.rules` lists it. Empty or left out: the bodies have no
/// rule of their own, so the active rule applies.
pub rule: Option<String>,
}
/// `bodies` as `plastic.assign_rule` takes it: a name, or a list of 1 to 10 000 names. Not
/// `NameList`'s own schema, which allows the empty list the handler refuses.
fn bodies_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({
"anyOf": [
{"type": "string"},
{"type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": crate::params::MAX_STRING_LIST}
]
})
}
/// List the plastic rules (the library's and the design's), the active rule and the rules
/// assigned to bodies. No parameters.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct RulesParams {}
/// A rule's values as written: numbers or expressions, as text.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RuleExpressions {
pub thickness: String,
pub nominal_radius: String,
pub clearance: String,
pub knife_edge: String,
pub reveal_height: String,
pub thickness_variation: String,
pub draft: String,
pub max_thickness: String,
pub min_thickness: String,
pub min_draft: String,
}
impl From<&PlasticRule> for RuleExpressions {
fn from(r: &PlasticRule) -> Self {
Self {
thickness: r.thickness.clone(),
nominal_radius: r.nominal_radius.clone(),
clearance: r.clearance.clone(),
knife_edge: r.knife_edge.clone(),
reveal_height: r.reveal_height.clone(),
thickness_variation: r.thickness_variation.clone(),
draft: r.draft.clone(),
max_thickness: r.max_thickness.clone(),
min_thickness: r.min_thickness.clone(),
min_draft: r.min_draft.clone(),
}
}
}
/// A rule's values, evaluated: lengths in mm, angles in degrees.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RuleValues {
pub thickness: f64,
pub nominal_radius: f64,
pub clearance: f64,
pub knife_edge: f64,
pub reveal_height: f64,
pub thickness_variation: f64,
pub draft_deg: f64,
pub max_thickness: f64,
pub min_thickness: f64,
pub min_draft_deg: f64,
}
impl From<PlasticValues> for RuleValues {
fn from(v: PlasticValues) -> Self {
Self {
thickness: v.thickness,
nominal_radius: v.nominal_radius,
clearance: v.clearance,
knife_edge: v.knife_edge,
reveal_height: v.reveal_height,
thickness_variation: v.thickness_variation,
draft_deg: v.draft.to_degrees(),
max_thickness: v.max_thickness,
min_thickness: v.min_thickness,
min_draft_deg: v.min_draft.to_degrees(),
}
}
}
/// A rule's evaluated values, or why they don't evaluate (an expression naming a parameter the
/// design no longer has, say).
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum RuleValuesOrError {
Values(RuleValues),
Error { error: String },
}
/// A plastic rule, as the rule commands give it back.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RuleInfo {
pub name: String,
/// The material the rule is for, as a note; may be empty.
pub material: String,
/// Whether the rule is one of the library's (edited in this design, or not).
pub library: bool,
pub expressions: RuleExpressions,
pub values: RuleValuesOrError,
}
/// What `plastic.manage_rules` returns: the rule made or edited, with the active rule, or the
/// rule deleted.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum ManageRulesResult {
Changed {
rule: Box<RuleInfo>,
/// The active rule, if any.
active: Option<String>,
/// In the warn parameter-check mode: what the call's parameters got wrong.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
param_warnings: Vec<String>,
},
Deleted {
deleted: String,
/// In the warn parameter-check mode: what the call's parameters got wrong.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
param_warnings: Vec<String>,
},
}
/// What `plastic.assign_rule` returns: the bodies and the rule they now have, or `null` for
/// none.
#[derive(Debug, Serialize, JsonSchema)]
pub struct AssignRuleResult {
pub bodies: Vec<String>,
pub rule: 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 `plastic.rules` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RulesResult {
/// The library's rules, as this design has edited them, then the design's own.
pub rules: Vec<RuleInfo>,
/// The active rule, if any.
pub active: Option<String>,
/// Each body with a rule of its own: body name to rule name.
pub assigned: BTreeMap<String, 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>,
}
// ---- Plastic features (#12622) ----
//
// Each feature joins the body it stands on (a groove cuts it) and replies as every feature
// command does, with `FeatureResult`. The common keys (`name`, `body_name`, `body_names`,
// `participants`) are `FeatureCommon`'s; `touching` is declared here because the features join.
/// `v` as `params::vec3` reads it. With `direction`, it must also have a length, since the
/// handlers make it a unit vector and refuse a zero one.
fn vector(v: &Value, direction: bool) -> Option<Vec3> {
let p = crate::params::vec3(v)?;
if direction { p.normalized() } else { Some(p) }
}
/// A point or direction key of the plastic features: read as [`vector`] reads it, refused with
/// the handler's whole message, published as a [`Point3`] with the key's own description.
macro_rules! plastic_vector {
($(#[$doc:meta])* $name:ident, direction: $direction:literal, $message:literal, $description:literal) => {
$(#[$doc])*
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct $name(pub Vec3);
impl<'de> Deserialize<'de> for $name {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
vector(&Value::deserialize(d)?, $direction).map($name).ok_or_else(|| D::Error::custom(whole($message)))
}
}
impl JsonSchema for $name {
fn schema_name() -> Cow<'static, str> {
stringify!($name).into()
}
fn inline_schema() -> bool {
true
}
fn json_schema(generator: &mut SchemaGenerator) -> Schema {
let mut schema = generator.subschema_for::<Point3>();
schema.insert("description".into(), $description.into());
schema
}
}
};
}
plastic_vector!(
/// Boss, Snap Fit and Rest's `position`.
FacePosition,
direction: false,
"`position` must be a point [x, y, z] on a face",
"A point in mm on the face the feature stands on: [x, y, z] or {\"x\", \"y\", \"z\"}."
);
plastic_vector!(
/// Boss, Snap Fit and Rest's `direction`.
FaceDirection,
direction: true,
"`direction` must be a non-zero [x, y, z]",
"The direction the feature stands out of the face, not zero. Default: square out of the face at `position`, which must then be planar."
);
plastic_vector!(
/// Lip's `face`.
RimFace,
direction: false,
"`face` must be a point [x, y, z] on the rim face",
"A point in mm on the planar rim face of a shelled body, round its opening: [x, y, z] or {\"x\", \"y\", \"z\"}."
);
plastic_vector!(
/// Snap Fit's `hook`.
HookDirection,
direction: true,
"`hook` must be the catch's direction [x, y, z]",
"The direction the catch sticks out of the arm: across `direction`, not zero."
);
plastic_vector!(
/// Rest's `along`.
AlongDirection,
direction: true,
"`along` must be a direction across the face",
"The direction of a rectangular rest's `length`: across `direction`, not zero."
);
/// Add a boss: a round post standing on a face, for a screw, with an optional hole, draft, root
/// fillet and ribs. It joins the body it stands on. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct BossParams {
pub position: FacePosition,
#[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "FaceDirection")]
pub direction: Option<FaceDirection>,
/// The post's diameter at the face, at least 0.01 mm.
pub diameter: LengthExpr,
/// How far the post stands out of the face, at least 0.01 mm.
pub height: LengthExpr,
/// The screw hole's diameter, down from the post's top. Default: no hole.
#[serde(default)]
pub hole_diameter: Option<LengthExpr>,
/// How deep the hole goes from the post's top. Default: down to the face (the post's height).
#[serde(default)]
pub hole_depth: Option<LengthExpr>,
/// The post's draft: it narrows towards its top by this angle. Default: the body's plastic
/// rule's draft, or none.
#[serde(default)]
pub draft: Option<AngleExpr>,
/// The radius of the round where the post meets the face. Default: none.
#[serde(default)]
pub fillet: Option<LengthExpr>,
/// How many ribs brace the post, evenly round it: 0 to 64. Default: none.
#[serde(default)]
pub ribs: Option<NumberExpr>,
/// Each rib's thickness. Default: 0.3 times the post's radius.
#[serde(default)]
pub rib_thickness: Option<LengthExpr>,
/// How far each rib reaches out from the post's wall. Default: the post's radius.
#[serde(default)]
pub rib_length: Option<LengthExpr>,
/// How far below the post's top the ribs stop. Default: 0, the ribs reach the top.
#[serde(default)]
pub rib_offset: Option<LengthExpr>,
/// The body the boss joins, by name. Default: the body at `position`.
#[serde(default)]
pub body: Option<String>,
/// What a join makes of pieces that share no face. Default: separate.
#[serde(default)]
pub touching: Option<TouchingParam>,
#[serde(flatten, deserialize_with = "feature_common")]
pub common: FeatureCommon,
}
/// Add a lip or a groove: a band along one edge of a shelled body's rim face, raised for a lip
/// and cut for a groove, so two halves of a case fit together. A lip joins the body and a groove
/// cuts it. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct LipParams {
pub face: RimFace,
/// The band's width across the rim.
pub width: LengthExpr,
/// A lip's height above the rim, or a groove's depth into it.
pub height: LengthExpr,
#[serde(default, rename = "type")]
pub kind: Option<LipTypeParam>,
/// A groove's clearance: it is this much wider than `width`, at least 0. Default: the body's
/// plastic rule's clearance, or none. A lip doesn't use it.
#[serde(default)]
pub gap: Option<LengthExpr>,
#[serde(default)]
pub side: Option<LipSideParam>,
/// True: the band runs along the outside edge, as `side: outside` does. Default: false.
#[serde(default)]
pub outside: Option<bool>,
/// The shelled body, by name. Default: the body at `face`.
#[serde(default)]
pub body: Option<String>,
/// What a lip's join makes of pieces that share no face. Default: separate.
#[serde(default)]
pub touching: Option<TouchingParam>,
#[serde(flatten, deserialize_with = "feature_common")]
pub common: FeatureCommon,
}
/// Add a snap fit: a cantilever arm standing on a face with a catch at its tip, which clips into
/// another part. It joins the body it stands on, or makes a body of its own. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct SnapFitParams {
pub position: FacePosition,
#[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "FaceDirection")]
pub direction: Option<FaceDirection>,
pub hook: HookDirection,
/// The arm's length out of the face, at least 0.01 mm.
pub length: LengthExpr,
/// The arm's thickness, along `hook`, at least 0.01 mm.
pub thickness: LengthExpr,
/// The arm's width, across `hook`, at least 0.01 mm.
pub width: LengthExpr,
/// How far the catch sticks out of the arm, at least 0.01 mm.
pub catch_depth: LengthExpr,
/// The catch's length along the arm, at the arm's tip: at least 0.01 mm and shorter than
/// `length`.
pub catch_length: LengthExpr,
/// How far the arm's base reaches below the face, into the wall, at least 0.01 mm. Default:
/// none, the arm starts at the face.
#[serde(default)]
pub base_height: Option<LengthExpr>,
/// True: the snap fit is a body of its own instead of joining the body. Default: false.
#[serde(default)]
pub new_body: Option<bool>,
/// The body it stands on, by name. Default: the body at `position`.
#[serde(default)]
pub body: Option<String>,
/// What a join makes of pieces that share no face. Default: separate.
#[serde(default)]
pub touching: Option<TouchingParam>,
#[serde(flatten, deserialize_with = "feature_common")]
pub common: FeatureCommon,
}
/// Add a rest: a pad standing on a face for another part to rest on, round or rectangular, solid
/// or hollow. It joins the body it stands on. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct RestParams {
pub position: FacePosition,
#[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "FaceDirection")]
pub direction: Option<FaceDirection>,
/// The pad's width at the face: a round rest's diameter.
pub width: LengthExpr,
/// A rectangular rest's length, along `along`. Default: a round rest.
#[serde(default)]
pub length: Option<LengthExpr>,
#[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "AlongDirection")]
pub along: Option<AlongDirection>,
/// How far the pad stands out of the face, at least 0.01 mm.
pub height: LengthExpr,
/// The pad's draft, under 57°: it narrows towards its top by this angle. Default: the body's
/// plastic rule's draft, or none.
#[serde(default)]
pub draft: Option<AngleExpr>,
/// A hollow rest's wall thickness. Default: a solid rest.
#[serde(default)]
pub thickness: Option<LengthExpr>,
/// The body it stands on, by name. Default: the body at `position`.
#[serde(default)]
pub body: Option<String>,
/// What a join makes of pieces that share no face. Default: separate.
#[serde(default)]
pub touching: Option<TouchingParam>,
#[serde(flatten, deserialize_with = "feature_common")]
pub common: FeatureCommon,
}
#[cfg(test)]
#[path = "plastic_tests.rs"]
mod tests;