Skip to content

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

39.4 KB
Raw Blame
//! Contracts and result types for the drawing commands in `cmd/sketch.rs`: a line, a point, the
//! circles and the arcs (#12953), the rectangles and the polygons (#13196).

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 solidcore_record::Vec2;

use super::check::whole;
use super::sketch_ends::SketchTarget;
use super::types::{LengthExpr, Point2, Point3, present};
use crate::params;

/// What the coordinates of a point typed as text must be.
const POINT_MUST: &str = "a point's coordinates must be numbers or expressions over the design's parameters";
/// The most points a line takes.
const MAX_LINE_POINTS: usize = 10_000;

/// The forms of a point argument: [`SketchPoint`] and [`SnapPoint`] differ in the snaps.
fn point_arg_schema(generator: &mut SchemaGenerator, snaps: bool) -> Schema {
    let point = generator.subschema_for::<Point2>();
    let coordinate = generator.subschema_for::<LengthExpr>();
    let mut forms = vec![
        json!(point),
        json!({
            "description": "[x, y] where a coordinate may be an expression over the design's parameters, such as [\"w / 2\", 5]: a point that follows the parameters.",
            "type": "array", "items": coordinate, "minItems": 2, "maxItems": 2
        }),
        json!({"description": "An existing point's id such as \"l1.end\" or \"p3\", or a snap such as \"mid:l1\".", "type": "string"}),
        json!({"description": "An existing point by id.", "type": "object", "properties": {"ref": {"type": "string"}}, "required": ["ref"]}),
        json!({"description": "A point by place.", "type": "object", "properties": {"at": point}, "required": ["at"]}),
    ];
    let description = if snaps {
        let model = generator.subschema_for::<Point3>();
        forms.push(json!({"description": "A model vertex [x, y, z] in mm, projected into the sketch.", "type": "object", "properties": {"vertex": model}, "required": ["vertex"]}));
        forms.push(json!({"description": "A point on a model edge [x, y, z] in mm, projected into the sketch.", "type": "object", "properties": {"on_edge": model}, "required": ["on_edge"]}));
        "A sketch point: [x, y] in mm (a coordinate may be an expression), an existing point's id (\"l1.end\"), {ref} or {at}, a snap as text (\"mid:<line>\", \"on:<curve>:x,y\", \"x:<a>+<b>:x,y\", \"vertex:x,y,z\"), or a model {vertex} or {on_edge}."
    } else {
        "A sketch point: [x, y] in mm (a coordinate may be an expression over the design's parameters), an existing point's id such as \"l1.end\", or {ref} or {at}."
    };
    json_schema!({"description": description, "anyOf": forms})
}

/// A point argument as `sketch::parg` reads it: a place `[x, y]` (a coordinate may be an
/// expression), an existing point's id, `{ref}` or `{at}`. Kept as given, for the handler, which
/// has the design to find a point and evaluate an expression.
#[derive(Clone, Debug, PartialEq)]
pub struct SketchPoint(pub Value);

impl<'de> Deserialize<'de> for SketchPoint {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = Value::deserialize(d)?;
        crate::cmd::point_arg_form(&v, false).map(|()| SketchPoint(v)).map_err(|why| D::Error::custom(whole(why)))
    }
}

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

/// A point argument of a command that snaps its points (`sketch_project::snap_points`): a
/// [`SketchPoint`], or a model `{vertex}` or `{on_edge}`. Snaps given as text are text.
#[derive(Clone, Debug, PartialEq)]
pub struct SnapPoint(pub Value);

impl<'de> Deserialize<'de> for SnapPoint {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = Value::deserialize(d)?;
        crate::cmd::point_arg_form(&v, true).map(|()| SnapPoint(v)).map_err(|why| D::Error::custom(whole(why)))
    }
}

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

/// A point as `params::req_vec2` reads it: `[x, y]` or `{x, y}` of numbers, with no expression, id
/// or snap (the 2-point circle's `p0` and `p1`).
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PlainPoint(pub Vec2);

impl<'de> Deserialize<'de> for PlainPoint {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        params::vec2(&Value::deserialize(d)?).map(PlainPoint).ok_or_else(|| D::Error::custom("must be a point [x, y]"))
    }
}

impl JsonSchema for PlainPoint {
    fn schema_name() -> Cow<'static, str> {
        "PlainPoint".into()
    }
    fn inline_schema() -> bool {
        true
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        generator.subschema_for::<Point2>()
    }
}

/// The points of a line: a list of [`SnapPoint`]s, 2 to 10 000.
#[derive(Clone, Debug, PartialEq)]
pub struct LinePoints(pub Vec<Value>);

impl<'de> Deserialize<'de> for LinePoints {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let Value::Array(list) = Value::deserialize(d)? else {
            return Err(D::Error::custom(whole("`points` must be a list")));
        };
        if list.len() < 2 || list.len() > MAX_LINE_POINTS {
            return Err(D::Error::custom(whole("a line needs 2 or more points")));
        }
        for v in &list {
            crate::cmd::point_arg_form(v, true).map_err(|why| D::Error::custom(whole(why)))?;
        }
        Ok(LinePoints(list))
    }
}

impl JsonSchema for LinePoints {
    fn schema_name() -> Cow<'static, str> {
        "LinePoints".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let point = generator.subschema_for::<SnapPoint>();
        json_schema!({
            "description": "The points the line runs through, in order: 2 to 10 000. Each is a SnapPoint.",
            "type": "array", "items": point, "minItems": 2, "maxItems": MAX_LINE_POINTS
        })
    }
}

/// Whether `v` is a snap that `sketch.point` takes as one, and if so whether it is well formed
/// (what the design makes of it, such as a line that is not there, stays the handler's).
fn snap_form(v: &Value) -> Option<bool> {
    let text = v.as_str();
    let snapped =
        text.is_some_and(|t| ["mid:", "on:", "vertex:"].iter().any(|k| t.starts_with(k))) || v.get("vertex").is_some() || v.get("on_edge").is_some();
    if !snapped {
        return None;
    }
    let numbers = |t: &str| -> Vec<f64> { t.split(',').filter_map(|x| x.trim().parse().ok()).collect() };
    let finite3 = |n: &[f64]| matches!(n, [x, y, z] if x.is_finite() && y.is_finite() && z.is_finite());
    let vertex =
        v.get("vertex").and_then(params::vec3).is_some() || text.and_then(|t| t.strip_prefix("vertex:")).is_some_and(|t| finite3(&numbers(t)));
    let edge = v.get("on_edge").and_then(params::vec3).is_some();
    let mid = text.is_some_and(|t| t.starts_with("mid:"));
    let on = text
        .and_then(|t| t.strip_prefix("on:"))
        .and_then(|t| t.rsplit_once(':'))
        .is_some_and(|(_, xy)| matches!(numbers(xy)[..], [x, y] if x.is_finite() && y.is_finite()));
    Some(vertex || edge || mid || on)
}

/// `sketch.point`'s `point`: `[x, y]` (numbers, or text expressions over the design's parameters),
/// `{x, y}`, or a snap that makes the point. An existing point's id is not taken.
#[derive(Clone, Debug, PartialEq)]
pub struct PointOrSnap(pub Value);

impl<'de> Deserialize<'de> for PointOrSnap {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = Value::deserialize(d)?;
        match snap_form(&v) {
            Some(true) => return Ok(PointOrSnap(v)),
            Some(false) => {
                return Err(D::Error::custom(whole(format!(
                    "`point` {v} is not a snap it takes: \"mid:<line>\", \"on:<curve>:x,y\", \"vertex:x,y,z\", {{vertex: [x,y,z]}} or {{on_edge: [x,y,z]}}"
                ))));
            }
            None => {}
        }
        if let Some([x, y]) = v.as_array().map(Vec::as_slice)
            && (x.is_string() || y.is_string())
        {
            // The coordinates `sketch::expr_point` reads: a finite number, or text that isn't blank.
            let coordinate = |c: &Value| match c {
                Value::Number(n) => n.as_f64().and_then(params::finite).is_some(),
                Value::String(e) => !e.trim().is_empty() && e.len() <= 4096,
                _ => false,
            };
            return if coordinate(x) && coordinate(y) { Ok(PointOrSnap(v)) } else { Err(D::Error::custom(whole(POINT_MUST))) };
        }
        if params::vec2(&v).is_some() { Ok(PointOrSnap(v)) } else { Err(D::Error::custom("must be a point [x, y]")) }
    }
}

impl JsonSchema for PointOrSnap {
    fn schema_name() -> Cow<'static, str> {
        "PointOrSnap".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let point = generator.subschema_for::<Point2>();
        let coordinate = generator.subschema_for::<LengthExpr>();
        let model = generator.subschema_for::<Point3>();
        json_schema!({
            "description": "A point to make: [x, y] in mm (a coordinate may be an expression over the design's parameters: the point then follows them), or a snap that makes it and holds it: \"mid:<line>\" (the line's midpoint), \"on:<curve>:x,y\" (on the curve, near x,y), \"vertex:x,y,z\" or {vertex: [x,y,z]} (a model vertex, projected) or {on_edge: [x,y,z]} (a point on a model edge, projected). An existing point's id is not taken.",
            "anyOf": [
                point,
                {"type": "array", "items": coordinate, "minItems": 2, "maxItems": 2},
                {"type": "string", "pattern": "^(mid:|on:|vertex:)"},
                {"type": "object", "properties": {"vertex": model}, "required": ["vertex"]},
                {"type": "object", "properties": {"on_edge": model}, "required": ["on_edge"]}
            ]
        })
    }
}

/// An id a drawing command gives its curve or point, as `named_id` reads it: text that can be
/// written into a face name whole.
#[derive(Clone, Debug, PartialEq)]
pub struct DrawId(pub String);

/// `id`, or an entry of `ids`, as `named_id` refuses it (the entry's position is not named).
fn id_problem(id: &str) -> Option<String> {
    (!solidcraft_doc::persistent_name::text_fits_name(id))
        .then(|| format!("the id `{id}` cannot be written into a name whole; give an id without `|`, `,`, `~`, `#` or `]`"))
}

impl<'de> Deserialize<'de> for DrawId {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let Value::String(id) = Value::deserialize(d)? else {
            return Err(D::Error::custom("must be text"));
        };
        match id_problem(&id) {
            Some(why) => Err(D::Error::custom(whole(why))),
            None => Ok(DrawId(id)),
        }
    }
}

impl JsonSchema for DrawId {
    fn schema_name() -> Cow<'static, str> {
        "DrawId".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "An id for the new geometry, such as \"base\". It may not hold `|`, `,`, `~`, `#` or `]`, which a face name made from it would read as its own.",
            "type": "string"
        })
    }
}

/// A line's `ids`, as `params::string_list` and `named_id` read them: a list of ids (one id is a
/// list of one), at most 10 000.
#[derive(Clone, Debug, PartialEq)]
pub struct DrawIds(pub Vec<String>);

impl<'de> Deserialize<'de> for DrawIds {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = Value::deserialize(d)?;
        let ids = match params::string_list("", &json!({"ids": v}), "ids") {
            Ok(ids) => ids,
            Err(crate::EngineError::BadParams { msg, .. }) => return Err(D::Error::custom(whole(msg))),
            Err(e) => return Err(D::Error::custom(whole(e))),
        };
        if let Some(why) = ids.iter().find_map(|id| id_problem(id)) {
            return Err(D::Error::custom(whole(why)));
        }
        Ok(DrawIds(ids))
    }
}

impl JsonSchema for DrawIds {
    fn schema_name() -> Cow<'static, str> {
        "DrawIds".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "Ids for the lines, in order: the first for the first segment and so on. One id is a list of one. Segments past the end of the list get an id of the sketch's own. An id may not hold `|`, `,`, `~`, `#` or `]`.",
            "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}, "maxItems": 10000}]
        })
    }
}

/// A circle's `radius` or `diameter`, as `radius_arg` and `circle_size` read it: a number, or text
/// that is an expression over the design's parameters (a dimension driven by them). Whether it is
/// positive, and whether an expression evaluates, is the handler's to check.
fn size_form(v: &Value, key: &str) -> Result<(), String> {
    match v {
        Value::Number(n) if n.as_f64().and_then(params::finite).is_some() => Ok(()),
        Value::String(_) if params::expr(&json!({ "v": v }), "v").is_some() => Ok(()),
        Value::String(_) => Err(format!("`{key}` {}", params::expr_problem(Some(v)))),
        _ => Err(format!("`{key}` must be a number")),
    }
}

macro_rules! circle_size {
    ($name:ident, $key:literal, $doc:literal) => {
        #[doc = $doc]
        #[derive(Clone, Debug, PartialEq)]
        pub struct $name(pub Value);

        impl<'de> Deserialize<'de> for $name {
            fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
                let v = Value::deserialize(d)?;
                size_form(&v, $key).map(|()| $name(v)).map_err(|why| D::Error::custom(whole(why)))
            }
        }

        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 {
                generator.subschema_for::<LengthExpr>()
            }
        }
    };
}

circle_size!(CircleRadius, "radius", "A circle's `radius`: a number or an expression.");
circle_size!(CircleDiameter, "diameter", "A circle's `diameter`: a number or an expression.");

/// An arc's `sweep`, as `params::num` reads it: a number below 1e9 in size. That it is between
/// -360 and 360 and not 0 is the handler's to check.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Sweep(pub f64);

impl<'de> Deserialize<'de> for Sweep {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        Value::deserialize(d)?.as_f64().and_then(params::finite).map(Sweep).ok_or_else(|| D::Error::custom("must be a number of degrees"))
    }
}

impl JsonSchema for Sweep {
    fn schema_name() -> Cow<'static, str> {
        "Sweep".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "The angle the arc turns through, in degrees: positive counter-clockwise from `start`, negative clockwise. Not 0, and less than 360 in size.",
            "type": "number", "exclusiveMinimum": -360, "exclusiveMaximum": 360
        })
    }
}

/// Draw a line through two or more points, or a closed polyline.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct LineParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// The points to run through, in order: one segment between each two. A point that is an
    /// existing point's id (or `{ref}`) shares that point, so the line starts or ends there.
    pub points: LinePoints,
    /// Close the line with a segment from the last point back to the first. Default: false.
    #[serde(default)]
    pub closed: Option<bool>,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Ids for the segments, in order. Default: ids of the sketch's own.
    #[serde(default)]
    pub ids: Option<DrawIds>,
    /// Add a horizontal or vertical constraint to a segment that is drawn exactly so, and a
    /// tangent to the arc or a perpendicular to the line that it starts from. Default: false.
    #[serde(default)]
    pub infer: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Add a point to the sketch, or a point made by a snap that holds it.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct PointParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// Where the point goes, or the snap that makes it.
    pub point: PointOrSnap,
    /// An id for the point. Default: one of the sketch's own. Ignored when `point` is a snap.
    #[serde(default)]
    pub id: Option<DrawId>,
    /// Make the new point coincident with an existing point it lands exactly on (the origin
    /// too). Default: true. Ignored when `point` is a snap.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw a circle from its centre and its radius or diameter.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct CircleCenterParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// The centre. A point's id or `{ref}` makes that point the centre, so the circle follows it.
    pub center: SnapPoint,
    /// The radius, in mm: a number, or an expression over the design's parameters, which makes
    /// the radius a dimension driven by them. Wins over `diameter`. Give one of the two.
    #[serde(default)]
    pub radius: Option<CircleRadius>,
    /// The diameter, in mm, as `radius` is given. Used when `radius` is not.
    #[serde(default)]
    pub diameter: Option<CircleDiameter>,
    /// A point the circle passes through, kept on it. With a placed centre and an existing
    /// point, that point and `radius` both fix the radius.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SnapPoint")]
    pub through: Option<SnapPoint>,
    /// An id for the circle. Default: one of the sketch's own.
    #[serde(default)]
    pub id: Option<DrawId>,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw a circle from the two ends of a diameter.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct CircleTwoPointParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// One end of the diameter, as [x, y] or {x, y} in mm. An expression, a point's id or a
    /// snap is not taken.
    pub p0: PlainPoint,
    /// The other end of the diameter. Not the same point as `p0`.
    pub p1: PlainPoint,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw a circle through three points.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct CircleThreePointParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// A point on the circle. One that is an existing point's id stays on the circle.
    pub p0: SnapPoint,
    /// A second point on the circle.
    pub p1: SnapPoint,
    /// A third point on the circle. The three may not be in a line.
    pub p2: SnapPoint,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw an arc from its two ends and a point on it.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ArcThreePointParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// One end of the arc.
    pub start: SnapPoint,
    /// The other end of the arc.
    pub end: SnapPoint,
    /// A point the arc passes through, between the ends. One that is an existing point's id
    /// stays on the arc. The three may not be in a line.
    pub through: SnapPoint,
    /// An id for the arc. Default: one of the sketch's own.
    #[serde(default)]
    pub id: Option<DrawId>,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw an arc round a centre, from a start point to an end point or through a sweep.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ArcCenterPointParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// The centre of the arc.
    pub center: SnapPoint,
    /// Where the arc starts. Its distance from `center` is the radius.
    pub start: SnapPoint,
    /// A point in the direction of the arc's end from `center`: the arc ends on the ray through
    /// it, at the radius. Give `end` or `sweep`; `sweep` wins.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "SnapPoint")]
    pub end: Option<SnapPoint>,
    /// With `end`: go clockwise from `start` to `end`. Default: false, counter-clockwise.
    #[serde(default)]
    pub clockwise: Option<bool>,
    /// The angle to turn through from `start`, in degrees, instead of `end`.
    #[serde(default)]
    pub sweep: Option<Sweep>,
    /// An id for the arc. Default: one of the sketch's own.
    #[serde(default)]
    pub id: Option<DrawId>,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// What a command added to its sketch: the ids that the sketch has now and did not before.
#[derive(Debug, Default, Serialize, JsonSchema)]
pub struct Created {
    /// Point ids.
    pub points: Vec<String>,
    /// Curve ids.
    pub curves: Vec<String>,
    /// Constraint ids, dimensions not among them.
    pub constraints: Vec<String>,
    /// Dimension ids.
    pub dimensions: Vec<String>,
    /// The ids of 3D curves, when the command made any.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub wires: Vec<String>,
}

/// What a drawing command returns for a line, a circle or an arc.
#[derive(Debug, Serialize, JsonSchema)]
pub struct DrawResult {
    /// The ids of the curves drawn, in order.
    pub curves: Vec<String>,
    /// The ids of the constraints added besides the curves' own: a coincident for a point that
    /// landed on an existing one, a point on the curve for a point that was given by id, a radius
    /// for a size given as an expression, what `infer` added.
    pub constraints: Vec<String>,
    /// The sketch's solve: `{solved, dof}`.
    pub sketch: Value,
    /// Everything the call added to the sketch: `{points, curves, constraints, dimensions}`, and
    /// `wires` when there are any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<Created>,
    /// 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 `sketch.point` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct PointResult {
    /// The id of the point made.
    pub point: String,
    /// The ids of the constraints added: a coincident with the existing point it landed on.
    pub constraints: Vec<String>,
    /// The sketch's solve: `{solved, dof}`.
    pub sketch: Value,
    /// Everything the call added to the sketch: `{points, curves, constraints, dimensions}`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<Created>,
    /// 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 rectangle corner as `sketch::corner_arg` reads it: `[x, y]` or `{x, y}` of numbers, or
/// `[x, y]` with a coordinate typed as an expression over the design's parameters. Not a point's
/// id or a snap. Kept as given, for the handler, which evaluates the expressions.
#[derive(Clone, Debug, PartialEq)]
pub struct CornerPoint(pub Value);

impl<'de> Deserialize<'de> for CornerPoint {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = Value::deserialize(d)?;
        if params::vec2(&v).is_some() {
            return Ok(CornerPoint(v));
        }
        // `corner_arg` reads a pair with a coordinate typed as text as `sketch::expr_point` does,
        // which is `point_arg_form`'s expression branch; anything else as `params::req_vec2`.
        let typed = v.as_array().is_some_and(|a| a.len() == 2 && a.iter().any(Value::is_string));
        if typed {
            return crate::cmd::point_arg_form(&v, false).map(|()| CornerPoint(v)).map_err(|why| D::Error::custom(whole(why)));
        }
        Err(D::Error::custom("must be a point [x, y]"))
    }
}

impl JsonSchema for CornerPoint {
    fn schema_name() -> Cow<'static, str> {
        "CornerPoint".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        let point = generator.subschema_for::<Point2>();
        let coordinate = generator.subschema_for::<LengthExpr>();
        json_schema!({
            "description": "A corner: [x, y] or {x, y} in mm, or [x, y] where a coordinate is an expression over the design's parameters, such as [\"w / 2\", 5]: the corner then follows the parameters. Not a point's id or a snap.",
            "anyOf": [
                point,
                {"type": "array", "items": coordinate, "minItems": 2, "maxItems": 2}
            ]
        })
    }
}

/// A number as `params::num` reads it (a polygon's `radius`, `diameter`, `sides` and `angle`): a
/// finite number, never an expression.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PlainNumber(pub f64);

impl<'de> Deserialize<'de> for PlainNumber {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        Value::deserialize(d)?.as_f64().and_then(params::finite).map(PlainNumber).ok_or_else(|| D::Error::custom("must be a number"))
    }
}

impl JsonSchema for PlainNumber {
    fn schema_name() -> Cow<'static, str> {
        "PlainNumber".into()
    }
    fn inline_schema() -> bool {
        true
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"type": "number"})
    }
}

/// Draw an axis-aligned rectangle from two opposite corners.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct RectTwoPointParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// One corner. A coordinate typed as an expression holds the corner where the parameters put it.
    pub p0: CornerPoint,
    /// The opposite corner. It must differ from `p0` in both x and y.
    pub p1: CornerPoint,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw a rectangle from one edge and a point on the opposite edge, at any angle.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct RectThreePointParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// One end of the first edge, as [x, y] or {x, y} in mm. An expression, a point's id or a
    /// snap is not taken.
    pub p0: PlainPoint,
    /// The other end of the first edge. Not the same point as `p0`.
    pub p1: PlainPoint,
    /// A point on the opposite edge: its distance from the first edge is the rectangle's width.
    /// Not on the first edge's line.
    pub p2: PlainPoint,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw an axis-aligned rectangle from its centre and one corner, with construction diagonals
/// that hold the centre.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct RectCenterParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// The centre. A coordinate typed as an expression holds the centre where the parameters put it.
    pub center: CornerPoint,
    /// One corner, in any quadrant round the centre. It must differ from `center` in both x and y.
    pub corner: CornerPoint,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw an axis-aligned rectangle from two opposite corners, its four corners rounded alike, as
/// one undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct RectRoundedParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// One corner of the rectangle before rounding, as `sketch.rectangle.two_point` takes it.
    pub p0: CornerPoint,
    /// The opposite corner. It must differ from `p0` in both x and y.
    pub p1: CornerPoint,
    /// The corner radius, in mm: a number or an expression over the design's parameters. Positive
    /// and less than half the shorter side. One radius dimension holds it; the other arcs are
    /// equal to it.
    pub radius: LengthExpr,
    /// Draw construction geometry, which is not part of a profile. Default: false.
    #[serde(default)]
    pub construction: Option<bool>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw a regular polygon whose corners lie on a circle round its centre.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct PolygonInscribedParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// The centre, as [x, y] or {x, y} in mm. An expression, a point's id or a snap is not taken.
    pub center: PlainPoint,
    /// The distance from the centre to each corner, in mm. Positive. Wins over `diameter`. Give
    /// one of the two.
    #[serde(default)]
    pub radius: Option<PlainNumber>,
    /// Twice the distance from the centre to each corner, in mm. Used when `radius` is not.
    #[serde(default)]
    pub diameter: Option<PlainNumber>,
    /// The number of sides: a whole number from 3 to 200. Default: 6.
    #[serde(default)]
    pub sides: Option<PlainNumber>,
    /// The direction of the first corner from the centre, in degrees counter-clockwise from the
    /// sketch's x axis. Default: 90 (straight up).
    #[serde(default)]
    pub angle: Option<PlainNumber>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw a regular polygon whose sides touch a circle round its centre.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct PolygonCircumscribedParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// The centre, as [x, y] or {x, y} in mm. An expression, a point's id or a snap is not taken.
    pub center: PlainPoint,
    /// The distance from the centre to the middle of each side, in mm. Positive. Wins over
    /// `diameter`. Give one of the two.
    #[serde(default)]
    pub radius: Option<PlainNumber>,
    /// Twice the distance from the centre to the middle of each side (the width across flats), in
    /// mm. Used when `radius` is not.
    #[serde(default)]
    pub diameter: Option<PlainNumber>,
    /// The number of sides: a whole number from 3 to 200. Default: 6.
    #[serde(default)]
    pub sides: Option<PlainNumber>,
    /// The direction of the middle of the first side from the centre, in degrees counter-clockwise
    /// from the sketch's x axis. Default: 90 (straight up).
    #[serde(default)]
    pub angle: Option<PlainNumber>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// Draw a regular polygon from one of its sides: the polygon lies to the left of the side from
/// `p0` to `p1`.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct PolygonEdgeParams {
    /// The sketch to draw in: its feature id or name. Default: the one being edited.
    #[serde(default)]
    pub sketch: Option<SketchTarget>,
    /// One end of the side, as [x, y] or {x, y} in mm. An expression, a point's id or a snap is
    /// not taken.
    pub p0: PlainPoint,
    /// The other end of the side. Not the same point as `p0`.
    pub p1: PlainPoint,
    /// The number of sides: a whole number from 3 to 200. Default: 6.
    #[serde(default)]
    pub sides: Option<PlainNumber>,
    /// Make a new point that lands exactly on an existing point (the origin too) coincident with
    /// it. Default: true.
    #[serde(default)]
    pub connect: Option<bool>,
}

/// An axis-aligned rectangle's sides by place, as line ids.
#[derive(Debug, Default, Serialize, JsonSchema)]
pub struct RectSides {
    /// The bottom side (least y).
    pub bottom: Option<String>,
    /// The right side (greatest x).
    pub right: Option<String>,
    /// The top side (greatest y).
    pub top: Option<String>,
    /// The left side (least x).
    pub left: Option<String>,
}

/// An axis-aligned rectangle's corners by place, as point ids.
#[derive(Debug, Default, Serialize, JsonSchema)]
pub struct RectCorners {
    /// The corner with the least x and y.
    pub bottom_left: Option<String>,
    /// The corner with the greatest x and least y.
    pub bottom_right: Option<String>,
    /// The corner with the greatest x and y.
    pub top_right: Option<String>,
    /// The corner with the least x and greatest y.
    pub top_left: Option<String>,
}

/// What `sketch.rectangle.two_point` and `sketch.rectangle.center` return.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RectResult {
    /// The ids of the four sides, counter-clockwise from the bottom side.
    pub curves: Vec<String>,
    /// The ids of the constraints added: horizontal and vertical sides, a coincident for a corner
    /// that landed on an existing point, the centre rectangle's midpoint.
    pub constraints: Vec<String>,
    /// The sketch's solve: `{solved, dof}`.
    pub sketch: Value,
    /// The sides by place, so a caller can dimension them without inspecting the sketch.
    pub sides: RectSides,
    /// The corners by place.
    pub corners: RectCorners,
    /// Everything the call added to the sketch: `{points, curves, constraints, dimensions}`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<Created>,
    /// 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 `sketch.rectangle.rounded` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RoundedRectResult {
    /// The ids of the four sides, then the four corner arcs.
    pub curves: Vec<String>,
    /// The ids of the constraints added: the rectangle's, then the fillet's (tangencies and the
    /// arcs equal to the first).
    pub constraints: Vec<String>,
    /// The sketch's solve after the rounding: `{solved, dof}`.
    pub sketch: Value,
    /// The sides by place. They end at the arcs now; there are no sharp corners to name.
    pub sides: RectSides,
    /// The corner arcs: bottom-left, bottom-right, top-right, top-left.
    pub arcs: Vec<String>,
    /// The parameter that holds the corner radius.
    pub param: String,
    /// Everything the call added to the sketch: `{points, curves, constraints, dimensions}`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<Created>,
    /// 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 the polygon commands return.
#[derive(Debug, Serialize, JsonSchema)]
pub struct PolygonResult {
    /// The ids of the sides, in order round the polygon.
    pub curves: Vec<String>,
    /// The ids of the constraints added: equal sides, the corners on their construction circle
    /// (and, round a circumscribed polygon, its tangent side), a coincident for a corner that
    /// landed on an existing point.
    pub constraints: Vec<String>,
    /// The sketch's solve: `{solved, dof}`.
    pub sketch: Value,
    /// The id of the construction circle that holds the polygon to its centre: through the
    /// corners of an inscribed or edge polygon, touching the sides of a circumscribed one.
    pub support_circle: String,
    /// Everything the call added to the sketch: `{points, curves, constraints, dimensions}`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<Created>,
    /// 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 = "sketch_shapes_tests.rs"]
mod tests;