SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Contracts and result types for the commands in `cmd/sketch_canvas.rs`: `canvas.insert`,
//! `canvas.decal`, `canvas.edit`, `canvas.calibrate` and `canvas.delete`.
//!
//! 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 an image can be read, a canvas exists
//! or a face is there stays the handler's to check. A call with several problems may get a
//! different one first in strict than with the check off (the check goes key by key, the handlers
//! in their own order).
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 super::check::whole;
use super::motion::require;
use super::types::{LengthExpr, Point2, Point3};
use crate::params;
/// Place an image on a plane as a reference to trace, kept in the design. Give the image as
/// `path` or as base64 `data`; only PNG and JPEG are taken, up to 16 MiB. The image goes into the
/// active component. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = image_required)]
pub struct CanvasInsertParams {
/// A PNG or JPEG file to read (not blank, under 4096 characters). Used when `data` is not
/// given.
#[serde(default)]
pub path: Option<String>,
/// The image itself, a PNG or JPEG, as base64. Wins over `path`.
#[serde(default)]
pub data: Option<String>,
/// The plane the image lies on. Default: XY. A picked face is read as `sketch.create` reads
/// one.
#[serde(default, deserialize_with = "super::present", skip_serializing_if = "Option::is_none")]
#[schemars(with = "CanvasPlane")]
pub plane: Option<CanvasPlane>,
/// Move the plane this far along its normal (mm or a length expression).
#[serde(default)]
pub offset: Option<LengthExpr>,
/// Where the image's centre is, on the plane, in mm. Default: `at`; else the picked point when
/// `plane` is a picked face; else the plane's origin.
#[serde(default)]
pub center: Option<Point2>,
/// A point [x, y, z] in mm, projected onto the plane, for the centre when `center` is not
/// given. Default: the picked point when `plane` is a picked face, else the plane's origin.
#[serde(default)]
pub at: Option<Point3>,
/// The image's width on the plane, in mm (above 0, below 1e7); its height follows the
/// image. Default: 100.
#[serde(default)]
pub width: Option<CanvasWidth>,
/// Its rotation on the plane, in degrees (a number of 1e9 or more is ignored). Default: 0.
#[serde(default)]
pub angle: Option<f64>,
/// Mirror it left to right. Default: false.
#[serde(default)]
pub flip: Option<bool>,
/// Its name. Default: "Canvas" and the first number no canvas's name has.
#[serde(default)]
pub name: Option<String>,
/// Its opacity, 0 (clear) to 1 (opaque); a value outside is clamped (a number of 1e9 or more is ignored, as if left out). Default: 0.5.
#[serde(default)]
pub opacity: Option<f64>,
}
/// Put an image on a planar face of the model, like a sticker, kept in the design. Give the image
/// as `path` or as base64 `data`; only PNG and JPEG are taken, up to 16 MiB. The image goes into
/// the active component. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = decal_required)]
pub struct CanvasDecalParams {
/// A PNG or JPEG file to read (not blank, under 4096 characters). Used when `data` is not
/// given.
#[serde(default)]
pub path: Option<String>,
/// The image itself, a PNG or JPEG, as base64. Wins over `path`.
#[serde(default)]
pub data: Option<String>,
// Optional in the type and required in the schema (`decal_required`): left out, the handler
// refuses it with its own message, not the check's "is required".
/// The face: a point [x, y, z] in mm on a planar face, where the image is centred, or a
/// picked face as `sketch.create`'s `plane` takes it: `{face: [x, y, z], body?, index?,
/// path?, fixed?}` (`body` and `index` go together).
#[serde(default, deserialize_with = "some", skip_serializing_if = "Option::is_none")]
#[schemars(with = "DecalFace")]
pub face: Option<DecalFace>,
/// Move the face's plane this far along its normal (mm or a length expression).
#[serde(default)]
pub offset: Option<LengthExpr>,
/// Where the image's centre is, on the face's plane, in mm. Default: `at`, or the picked
/// point.
#[serde(default)]
pub center: Option<Point2>,
/// A point [x, y, z] in mm, projected onto the plane, for the centre when `center` is not
/// given. Default: the picked point.
#[serde(default)]
pub at: Option<Point3>,
/// The image's width on the plane, in mm (above 0, below 1e7); its height follows the
/// image. Default: 100.
#[serde(default)]
pub width: Option<CanvasWidth>,
/// Its rotation on the plane, in degrees (a number of 1e9 or more is ignored). Default: 0.
#[serde(default)]
pub angle: Option<f64>,
/// Mirror it left to right. Default: false.
#[serde(default)]
pub flip: Option<bool>,
/// Its name. Default: "Decal" and the first number no canvas's name has.
#[serde(default)]
pub name: Option<String>,
/// Its opacity, 0 (clear) to 1 (opaque); a value outside is clamped (a number of 1e9 or more is ignored, as if left out). Default: 1.
#[serde(default)]
pub opacity: Option<f64>,
}
/// Change a canvas or decal: its place, size, angle, opacity, mirroring, visibility or name. Keys
/// left out stay as they are. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = canvas_required)]
pub struct CanvasEditParams {
/// The canvas, by id or name.
// Optional in the type and required in the schema, as `face` above.
#[serde(default, deserialize_with = "some", skip_serializing_if = "Option::is_none")]
#[schemars(with = "CanvasRef")]
pub canvas: Option<CanvasRef>,
/// The image's new centre on its plane, in mm.
#[serde(default)]
pub center: Option<Point2>,
/// Its new width, in mm (above 0, below 1e7); its height follows the image.
#[serde(default)]
pub width: Option<CanvasWidth>,
/// Its new rotation on the plane, in degrees (a number of 1e9 or more is ignored).
#[serde(default)]
pub angle: Option<f64>,
/// Its new opacity, 0 (clear) to 1 (opaque); a value outside is clamped (a number of 1e9 or more is ignored, as if left out).
#[serde(default)]
pub opacity: Option<f64>,
/// Mirror it left to right, or not.
#[serde(default)]
pub flip: Option<bool>,
/// Show it or hide it.
#[serde(default)]
pub visible: Option<bool>,
/// Its new name; blank text keeps the name.
#[serde(default)]
pub name: Option<String>,
/// Lock it or unlock it. A locked canvas refuses a new centre, width, angle or flip, Calibrate
/// and Delete until it is unlocked; its opacity, visibility and name can still change.
#[serde(default)]
pub locked: Option<bool>,
}
/// Scale a canvas so that two points on it are a known distance apart: the image is scaled about
/// the first point. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = calibrate_required)]
pub struct CanvasCalibrateParams {
/// The canvas, by id or name.
// Optional in the types and required in the schema (`calibrate_required`), as `face` above.
#[serde(default, deserialize_with = "some", skip_serializing_if = "Option::is_none")]
#[schemars(with = "CanvasRef")]
pub canvas: Option<CanvasRef>,
/// A point on the canvas's plane, in mm, [x, y]: the one the image is scaled about.
#[serde(default, deserialize_with = "some", skip_serializing_if = "Option::is_none")]
#[schemars(with = "CalibrationPoint")]
pub a: Option<CalibrationPoint>,
/// Another point on the plane, in mm, [x, y], not the same as `a`.
#[serde(default, deserialize_with = "some", skip_serializing_if = "Option::is_none")]
#[schemars(with = "CalibrationPoint")]
pub b: Option<CalibrationPoint>,
/// What the distance from `a` to `b` really is, in mm (above 0).
#[serde(default, deserialize_with = "some", skip_serializing_if = "Option::is_none")]
#[schemars(with = "Distance")]
pub distance: Option<Distance>,
}
/// Remove a canvas or decal from the design. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = canvas_required)]
pub struct CanvasDeleteParams {
/// The canvas, by id or name.
// Optional in the type and required in the schema, as `face` above.
#[serde(default, deserialize_with = "some", skip_serializing_if = "Option::is_none")]
#[schemars(with = "CanvasRef")]
pub canvas: Option<CanvasRef>,
}
/// A key that, once given (`null` included), must parse as `T`, as the handlers read it.
fn some<'de, D: Deserializer<'de>, T: Deserialize<'de>>(d: D) -> Result<Option<T>, D::Error> {
T::deserialize(d).map(Some)
}
/// A canvas by its id (a number) or its name, as `find` in `cmd/sketch_canvas.rs` reads it.
#[derive(Clone, Debug, PartialEq)]
pub struct CanvasRef(pub String);
impl<'de> Deserialize<'de> for CanvasRef {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
match Value::deserialize(d)? {
Value::Number(n) => Ok(CanvasRef(n.to_string())),
Value::String(s) => Ok(CanvasRef(s)),
_ => Err(D::Error::custom("must be an id or a name")),
}
}
}
impl JsonSchema for CanvasRef {
fn schema_name() -> Cow<'static, str> {
"CanvasRef".into()
}
fn json_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({"description": "A canvas's id (a number) or its name.", "type": ["number", "string"]})
}
}
/// An image width in mm: above 0 and below 1e7, as `cmd/sketch_canvas.rs` requires.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct CanvasWidth(pub f64);
impl<'de> Deserialize<'de> for CanvasWidth {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
match Value::deserialize(d)? {
Value::Number(n) => match n.as_f64() {
Some(w) if w > 1e-6 && w < 1e7 => Ok(CanvasWidth(w)),
_ => Err(D::Error::custom("must be positive")),
},
_ => Err(D::Error::custom("must be a number of mm")),
}
}
}
impl JsonSchema for CanvasWidth {
fn schema_name() -> Cow<'static, str> {
"CanvasWidth".into()
}
fn json_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({
"description": "A width in mm: more than 0.000001 and below 10 000 000.",
"type": "number", "exclusiveMinimum": 1e-6, "exclusiveMaximum": 1e7
})
}
}
/// `canvas.calibrate`'s `distance`: a number above 0 (and below 1e9), whatever else it is read
/// as `distance` must be positive.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Distance(pub f64);
impl<'de> Deserialize<'de> for Distance {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
let n = match Value::deserialize(d)? {
Value::Number(n) => n.as_f64().and_then(params::finite),
_ => None,
};
n.filter(|d| *d > 1e-9).map(Distance).ok_or_else(|| D::Error::custom("must be positive"))
}
}
impl JsonSchema for Distance {
fn schema_name() -> Cow<'static, str> {
"Distance".into()
}
fn json_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({
"description": "A distance in mm: above 0 (more than 0.000000001) and below 1 000 000 000.",
"type": "number", "exclusiveMinimum": 1e-9, "exclusiveMaximum": 1e9
})
}
}
/// A point of `canvas.calibrate`: `[x, y]` or `{x, y}` of numbers, with the handler's one message
/// for `a` and `b`.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct CalibrationPoint(pub solidcore_record::Vec2);
impl<'de> Deserialize<'de> for CalibrationPoint {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
params::vec2(&Value::deserialize(d)?).map(CalibrationPoint).ok_or_else(|| D::Error::custom(whole("`a` and `b` must be points [x,y]")))
}
}
impl JsonSchema for CalibrationPoint {
fn schema_name() -> Cow<'static, str> {
"CalibrationPoint".into()
}
fn inline_schema() -> bool {
true
}
fn json_schema(generator: &mut SchemaGenerator) -> Schema {
generator.subschema_for::<Point2>()
}
}
/// The plane of `canvas.insert`, as `sketch::plane_ref` reads it: an origin plane's name or alias,
/// a construction plane's name or feature id, a picked face `{face, …}`, or `{origin?, x_dir,
/// y_dir}`. Kept as given, for the handler. Whether a name or id names a plane is checked by the
/// handler, which has the design.
#[derive(Clone, Debug, PartialEq)]
pub struct CanvasPlane(pub Value);
impl<'de> Deserialize<'de> for CanvasPlane {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
let v = Value::deserialize(d)?;
let problem = match &v {
Value::String(_) => None,
Value::Number(n) if n.is_u64() => None,
Value::Number(_) => Some(format!("`plane` must be {}", crate::cmd::PLANE_FORMS)),
Value::Object(o) if o.contains_key("face") => crate::cmd::face_pick_form(&v).err().map(str::to_string),
Value::Object(_) => crate::cmd::custom_plane_form(&v).err().map(str::to_string),
_ => Some(crate::cmd::PLANE_REF_FORMS.to_string()),
};
match problem {
Some(why) => Err(D::Error::custom(whole(why))),
None => Ok(CanvasPlane(v)),
}
}
}
impl JsonSchema for CanvasPlane {
fn schema_name() -> Cow<'static, str> {
"CanvasPlane".into()
}
fn json_schema(generator: &mut SchemaGenerator) -> Schema {
let point = generator.subschema_for::<Point3>();
json_schema!({
"description": "A plane: XY, XZ or YZ (or Top, Front or Right; any case), a construction plane's name or feature id, a picked planar face {\"face\": [x, y, z], \"body\"?, \"index\"?, \"path\"?, \"fixed\"?}, or an explicit plane {\"origin\"?, \"x_dir\", \"y_dir\"}: two directions [x, y, z] that aren't parallel and an origin in mm, numbers only (default: the origin).",
"anyOf": [
{"type": "string"},
{"type": "integer", "minimum": 0, "maximum": u64::MAX},
face_pick(&point),
{
"type": "object",
"properties": {"origin": {"anyOf": [point, {"type": "null"}]}, "x_dir": point, "y_dir": point},
"required": ["x_dir", "y_dir"],
"not": {"required": ["face"]}
}
]
})
}
}
/// The face of `canvas.decal`, as the handler reads it: a point on the face, or a picked face
/// `{face, body?, index?, path?, fixed?}`. Kept as given, for the handler.
#[derive(Clone, Debug, PartialEq)]
pub struct DecalFace(pub Value);
impl<'de> Deserialize<'de> for DecalFace {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
let v = Value::deserialize(d)?;
// A point alone is made a pick, as the handler does.
let pick = if v.get("face").is_some() { v.clone() } else { json!({"face": v}) };
match crate::cmd::face_pick_form(&pick) {
Ok(_) => Ok(DecalFace(v)),
Err(why) => Err(D::Error::custom(whole(why))),
}
}
}
impl JsonSchema for DecalFace {
fn schema_name() -> Cow<'static, str> {
"DecalFace".into()
}
fn json_schema(generator: &mut SchemaGenerator) -> Schema {
let point = generator.subschema_for::<Point3>();
json_schema!({
"description": "A point [x, y, z] in mm on a planar face, or a picked face {\"face\": [x, y, z], \"body\"?, \"index\"?, \"path\"?, \"fixed\"?}: \"body\" (the picked body's world name) and \"index\" (the face's index in it) pick the face exactly and go together; \"path\" is the occurrence path of the body's placement (at most 64 nonzero ids); \"fixed\": true keeps the plane where the face is now.",
"anyOf": [point, face_pick(&point)]
})
}
}
/// A picked face, as `sketch::face::face_pick_form` reads it.
fn face_pick(point: &Schema) -> Value {
json!({
"type": "object",
"properties": {
"face": point,
"fixed": {"type": "boolean"},
"body": {"type": "string", "minLength": 1, "description": "Goes with `index`: give both or neither."},
"index": {"type": "integer", "minimum": 0, "description": "Goes with `body`: give both or neither."},
"path": {"type": "array", "items": {"type": "integer", "minimum": 1}, "maxItems": 64}
},
"required": ["face"]
})
}
/// `canvas.insert` and `canvas.decal` need `path` or `data`; the handler says so when both are
/// left out.
fn need_image(schema: &mut Schema) {
schema.insert("anyOf".into(), json!([{"required": ["data"]}, {"required": ["path"]}]));
}
fn image_required(schema: &mut Schema) {
need_image(schema);
}
fn decal_required(schema: &mut Schema) {
need_image(schema);
require(schema, "face");
}
fn canvas_required(schema: &mut Schema) {
require(schema, "canvas");
}
fn calibrate_required(schema: &mut Schema) {
for key in ["canvas", "a", "b", "distance"] {
require(schema, key);
}
}
/// What `canvas.insert` and `canvas.decal` return.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CanvasPlaced {
/// The new canvas's id.
pub canvas: u64,
/// Its name.
pub name: String,
/// The image's size in pixels, [width, height].
pub pixels: [u32; 2],
/// 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 `canvas.edit` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CanvasEdited {
/// The canvas's id.
pub canvas: 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 `canvas.calibrate` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CanvasCalibrated {
/// The canvas's id.
pub canvas: u64,
/// Its width now, in mm.
pub width: 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>,
}
/// What `canvas.delete` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CanvasDeleted {
/// The id the canvas had.
pub deleted: 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>,
}
#[cfg(test)]
#[path = "canvas_tests.rs"]
mod tests;