Skip to content

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

Merge remote-tracking branch 'origin/main' into feat/sketch-tools-return-ids

CypherNaugh_0xb93d4905acf2
diff --cc crates/engine/src/cmd/mod.rs
index 71c06ec682,8eec64ee0a..beddce9b5a
--- a/crates/engine/src/cmd/mod.rs
+++ b/crates/engine/src/cmd/mod.rs
@@@ -34,7 -29,7 +36,8 @@@ mod parameters
mod plastic;
mod sheet;
mod sketch;
+pub(crate) use sketch::created as sketch_created;
+ pub(crate) use sketch::author_path_for_rebind;
mod sketch_3d;
mod sketch_canvas;
mod sketch_constraints;
diff --cc crates/engine/src/cmd/sketch.rs
index 3ba23f845f,a3921e3b7f..ffdfd4783b
--- a/crates/engine/src/cmd/sketch.rs
+++ b/crates/engine/src/cmd/sketch.rs
@@@ -28,7 -34,10 +34,10 @@@ pub static COMMANDS: &[CommandSpec] = &
.icon("line")
.key("L")
.enabled(in_sketch)
- .params(concat!("points: [[x,y] | \"l1.end\" | {at, ref}…], closed?: bool, construction?: bool, ids?: [..], infer?: bool (add horizontal/vertical)", connect_doc!())),
+ .params(concat!("points: [[x,y] | \"l1.end\" | {at, ref}…], closed?: bool, construction?: bool, ids?: [..], infer?: bool (add horizontal/vertical)", connect_doc!(), created_doc!())),
+ CommandSpec::new("sketch.draw.dimensioned", "Draw Dimensioned Sketch Geometry", draw_dimensioned)
+ .enabled(in_sketch)
- .params("command: sketch creation command, params: object, dimensions: object of role to numeric or expression value; creates geometry and all driving dimensions atomically in one undo step"),
++ .params(concat!("command: sketch creation command, params: object, dimensions: object of role to numeric or expression value; creates geometry and all driving dimensions atomically in one undo step", created_doc!())),
CommandSpec::new("sketch.rectangle.two_point", "2-Point Rectangle", rect_two_point)
.at("SKETCH", "CREATE")
.icon("rect")
diff --cc crates/engine/src/cmd/sketch_create.rs
index a8cd427258,6b8948d2b9..92d61a9934
--- a/crates/engine/src/cmd/sketch_create.rs
+++ b/crates/engine/src/cmd/sketch_create.rs
@@@ -10,81 -10,83 +10,81 @@@ use super::{CommandSpec, in_sketch}
use crate::params::{bad, num, req_vec2, str_, string_list};
use crate::{Result, Session};
-pub static COMMANDS: &[CommandSpec] =
- &[
- CommandSpec::new("sketch.line.midpoint", "Midpoint Line", midpoint_line)
- .at("SKETCH", "CREATE")
- .icon("line_mid")
- .enabled(in_sketch)
- .params("mid: [x,y] or point ref, end: [x,y]; construction?"),
- CommandSpec::new("sketch.arc.tangent", "Tangent Arc", arc_tangent).at("SKETCH", "CREATE").icon("arc_tangent").enabled(in_sketch).params(
- "start: end point of a line or arc (\"l1.end\"), end: [x,y]; curve?: the curve to be tangent to (default: the one ending at start)",
- ),
- CommandSpec::new("sketch.circle.two_tangent", "2-Tangent Circle", circle_tan_tan)
- .at("SKETCH", "CREATE")
- .icon("circle_tt")
- .enabled(in_sketch)
- .params("curves: [two lines/circles/arcs], radius | diameter: expr, near: [x,y] (which of the solutions)"),
- CommandSpec::new("sketch.circle.three_tangent", "3-Tangent Circle", circle_three_tan)
- .at("SKETCH", "CREATE")
- .icon("circle_ttt")
- .enabled(in_sketch)
- .params("curves: [three lines/circles/arcs], near: [x,y] (which of the solutions)"),
- CommandSpec::new("sketch.slot.center_point", "Center Point Slot", slot_center_point)
- .at("SKETCH", "CREATE")
- .icon("slot")
- .enabled(in_sketch)
- .params("center: slot centre, end: one arc centre, width"),
- CommandSpec::new("sketch.slot.arc_three_point", "Three Point Arc Slot", arc_slot_three)
- .at("SKETCH", "CREATE")
- .icon("arc_slot")
- .enabled(in_sketch)
- .params("start, through, end: points on the centre arc, width"),
- CommandSpec::new("sketch.slot.arc_center", "Center Point Arc Slot", arc_slot_center)
- .at("SKETCH", "CREATE")
- .icon("arc_slot")
- .enabled(in_sketch)
- .params("center, start: centre arc start, end: direction of the centre arc end (counter-clockwise), width"),
- CommandSpec::new("sketch.ellipse", "Ellipse", ellipse)
- .at("SKETCH", "CREATE")
- .icon("ellipse")
- .enabled(in_sketch)
- .params("center, major: end of the major axis [x,y], minor: a point the ellipse passes through on the minor side [x,y] | minor_radius"),
- CommandSpec::new("sketch.spline.fit_point", "Fit Point Spline", spline_fit)
- .at("SKETCH", "CREATE")
- .icon("spline")
- .enabled(in_sketch)
- .params("points: [[x,y] or point refs…] (2…500), periodic?: boolean (default false); periodic cubic fit closes smoothly through at least 3 distinct samples"),
- CommandSpec::new("sketch.spline.control_point", "Control Point Spline", spline_cv3)
- .at("SKETCH", "CREATE")
- .icon("spline_cv")
- .enabled(in_sketch)
- .params("points: control points (2…500), cubic"),
- CommandSpec::new("sketch.spline.control_point_5", "Control Point Spline (Degree 5)", spline_cv5)
- .at("SKETCH", "CREATE")
- .icon("spline_cv")
- .enabled(in_sketch)
- .params("points: control points (2…500), degree 5"),
- CommandSpec::new("sketch.conic", "Conic Curve", conic)
- .at("SKETCH", "CREATE")
- .icon("conic")
- .enabled(in_sketch)
- .params("start, end, apex: [x,y] or point refs; rho?: 0…1 (default 0.5: parabola)"),
- CommandSpec::new("sketch.blend_curve", "Blend Curve", blend)
- .at("SKETCH", "MODIFY")
- .icon("blend")
- .enabled(in_sketch)
- .params("a, b: end points of two curves (\"l1.end\", \"a2.start\"): a smooth (tangent) spline joining them"),
- CommandSpec::new("sketch.centerline", "Centerline", centerline)
- .enabled(in_sketch)
- .params("curves: [line ids], value?: bool (default toggles): centerline line type (not in profiles; an axis)"),
- CommandSpec::new("sketch.text", "Text", text)
- .at("SKETCH", "CREATE")
- .icon("text")
- .enabled(in_sketch)
- .params("text: string (\\n breaks lines), at: baseline start [x,y], height?: capital height mm (default 5), angle?: deg"),
- CommandSpec::new("sketch.edit_text", "Edit Text", edit_text)
- .enabled(in_sketch)
- .params("link: the text's link id (or entity: one of its curves), text?, at?, height?, angle?: deg"),
- ];
+pub static COMMANDS: &[CommandSpec] = &[
+ CommandSpec::new("sketch.line.midpoint", "Midpoint Line", midpoint_line)
+ .at("SKETCH", "CREATE")
+ .icon("line_mid")
+ .enabled(in_sketch)
+ .params(concat!("mid: [x,y] or point ref, end: [x,y]; construction?", created_doc!())),
+ CommandSpec::new("sketch.arc.tangent", "Tangent Arc", arc_tangent).at("SKETCH", "CREATE").icon("arc_tangent").enabled(in_sketch).params(concat!(
+ "start: end point of a line or arc (\"l1.end\"), end: [x,y]; curve?: the curve to be tangent to (default: the one ending at start)",
+ created_doc!()
+ )),
+ CommandSpec::new("sketch.circle.two_tangent", "2-Tangent Circle", circle_tan_tan)
+ .at("SKETCH", "CREATE")
+ .icon("circle_tt")
+ .enabled(in_sketch)
+ .params(concat!("curves: [two lines/circles/arcs], radius | diameter: expr, near: [x,y] (which of the solutions)", created_doc!())),
+ CommandSpec::new("sketch.circle.three_tangent", "3-Tangent Circle", circle_three_tan)
+ .at("SKETCH", "CREATE")
+ .icon("circle_ttt")
+ .enabled(in_sketch)
+ .params(concat!("curves: [three lines/circles/arcs], near: [x,y] (which of the solutions)", created_doc!())),
+ CommandSpec::new("sketch.slot.center_point", "Center Point Slot", slot_center_point)
+ .at("SKETCH", "CREATE")
+ .icon("slot")
+ .enabled(in_sketch)
+ .params(concat!("center: slot centre, end: one arc centre, width", created_doc!())),
+ CommandSpec::new("sketch.slot.arc_three_point", "Three Point Arc Slot", arc_slot_three)
+ .at("SKETCH", "CREATE")
+ .icon("arc_slot")
+ .enabled(in_sketch)
+ .params(concat!("start, through, end: points on the centre arc, width", created_doc!())),
+ CommandSpec::new("sketch.slot.arc_center", "Center Point Arc Slot", arc_slot_center)
+ .at("SKETCH", "CREATE")
+ .icon("arc_slot")
+ .enabled(in_sketch)
+ .params(concat!("center, start: centre arc start, end: direction of the centre arc end (counter-clockwise), width", created_doc!())),
+ CommandSpec::new("sketch.ellipse", "Ellipse", ellipse).at("SKETCH", "CREATE").icon("ellipse").enabled(in_sketch).params(concat!(
+ "center, major: end of the major axis [x,y], minor: a point the ellipse passes through on the minor side [x,y] | minor_radius",
+ created_doc!()
+ )),
+ CommandSpec::new("sketch.spline.fit_point", "Fit Point Spline", spline_fit)
+ .at("SKETCH", "CREATE")
+ .icon("spline")
+ .enabled(in_sketch)
- .params(concat!("points: [[x,y] or point refs…] (2…500): the spline passes through them", created_doc!())),
++ .params(concat!("points: [[x,y] or point refs…] (2…500): the spline passes through them, periodic?: boolean (default false); periodic cubic fit closes smoothly through at least 3 distinct samples", created_doc!())),
+ CommandSpec::new("sketch.spline.control_point", "Control Point Spline", spline_cv3)
+ .at("SKETCH", "CREATE")
+ .icon("spline_cv")
+ .enabled(in_sketch)
+ .params(concat!("points: control points (2…500), cubic", created_doc!())),
+ CommandSpec::new("sketch.spline.control_point_5", "Control Point Spline (Degree 5)", spline_cv5)
+ .at("SKETCH", "CREATE")
+ .icon("spline_cv")
+ .enabled(in_sketch)
+ .params(concat!("points: control points (2…500), degree 5", created_doc!())),
+ CommandSpec::new("sketch.conic", "Conic Curve", conic)
+ .at("SKETCH", "CREATE")
+ .icon("conic")
+ .enabled(in_sketch)
+ .params(concat!("start, end, apex: [x,y] or point refs; rho?: 0…1 (default 0.5: parabola)", created_doc!())),
+ CommandSpec::new("sketch.blend_curve", "Blend Curve", blend)
+ .at("SKETCH", "MODIFY")
+ .icon("blend")
+ .enabled(in_sketch)
+ .params(concat!("a, b: end points of two curves (\"l1.end\", \"a2.start\"): a smooth (tangent) spline joining them", created_doc!())),
+ CommandSpec::new("sketch.centerline", "Centerline", centerline)
+ .enabled(in_sketch)
+ .params("curves: [line ids], value?: bool (default toggles): centerline line type (not in profiles; an axis)"),
+ CommandSpec::new("sketch.text", "Text", text).at("SKETCH", "CREATE").icon("text").enabled(in_sketch).params(concat!(
+ "text: string (\\n breaks lines), at: baseline start [x,y], height?: capital height mm (default 5), angle?: deg",
+ created_doc!()
+ )),
+ CommandSpec::new("sketch.edit_text", "Edit Text", edit_text)
+ .enabled(in_sketch)
+ .params(concat!("link: the text's link id (or entity: one of its curves), text?, at?, height?, angle?: deg", created_doc!())),
+];
fn text_source(p: &Value, cmd: &str, old: Option<(String, Vec2, f64, f64)>) -> Result<LinkSource> {
let (t0, at0, h0, a0) = old.unwrap_or((String::new(), Vec2::ZERO, 5.0, 0.0));
diff --cc crates/engine/src/cmd/sketch_ids_tests.rs
index 1d288385d3,0000000000..65063ba0ce
mode 100644,000000..100644
--- a/crates/engine/src/cmd/sketch_ids_tests.rs
+++ b/crates/engine/src/cmd/sketch_ids_tests.rs
@@@ -1,298 -1,0 +1,330 @@@
+//! Every command that adds sketch geometry returns `created: {points, curves, constraints,
+//! dimensions}` with the real ids of what it added, so a script can dimension and constrain the
+//! new geometry right away; ids are never reused after a delete.
+
+use serde_json::{Value, json};
+use solvecraft_sketch::{CurveKind, Sketch};
+
+use crate::Session;
+
+fn run(s: &mut Session, id: &str, p: Value) -> Value {
+ match s.execute(id, &p) {
+ Ok(v) => v,
+ Err(e) => panic!("{id} {p}: {e}"),
+ }
+}
+
+fn strs(v: &Value) -> Vec<String> {
+ v.as_array().map(|a| a.iter().filter_map(|x| x.as_str().map(str::to_string)).collect()).unwrap_or_default()
+}
+
+fn sketch(s: &Session) -> Sketch {
+ s.doc.sketch(s.active_sketch.unwrap()).unwrap().clone()
+}
+
+fn new_sketch() -> Session {
+ let mut s = Session::default();
+ run(&mut s, "sketch.create", json!({"plane": "XY"}));
+ s
+}
+
+/// The ids in `r.created` exist in the active sketch, and each curve and point takes a
+/// dimension (driven, so it never conflicts) and a fix right away. `before`: the sketch before
+/// the command. Returns `created`.
+fn check(s: &mut Session, cmd: &str, r: &Value, before: &Sketch) -> Value {
+ let c = r.get("created").cloned().unwrap_or_else(|| panic!("{cmd}: no `created` in {r}"));
+ for k in ["points", "curves", "constraints", "dimensions"] {
+ assert!(c[k].is_array(), "{cmd}: created.{k} in {c}");
+ }
+ let sk = sketch(s);
+ let curves = strs(&c["curves"]);
+ let points = strs(&c["points"]);
+ assert!(!curves.is_empty() || !points.is_empty() || c.get("wires").is_some(), "{cmd}: nothing created: {c}");
+ for id in &points {
+ assert!(sk.point_index(id).is_some(), "{cmd}: point {id} not in the sketch");
+ assert_ne!(id, "origin", "{cmd}");
+ }
+ for id in strs(&c["constraints"]).iter().chain(&strs(&c["dimensions"])) {
+ assert!(sk.constraints.iter().any(|k| &k.id == id), "{cmd}: constraint {id} not in the sketch");
+ }
+ for id in strs(&c["dimensions"]) {
+ assert!(sk.constraints.iter().any(|k| k.id == id && k.kind.is_dimension()), "{cmd}: {id} is not a dimension");
+ }
+ for id in strs(&c.get("wires").cloned().unwrap_or_default()) {
+ assert!(sk.wire_index(&id).is_some(), "{cmd}: wire {id} not in the sketch");
+ }
+ // The new curves in the command's own list (where it has one) are in `created`.
+ let wires = strs(&c.get("wires").cloned().unwrap_or_default());
+ for id in strs(&r["curves"]) {
+ let old = before.curve_index(&id).is_some() || before.wire_index(&id).is_some();
+ assert!(old || curves.contains(&id) || wires.contains(&id), "{cmd}: returned curve {id} missing from created {c}");
+ }
+ for id in curves.iter().chain(&points) {
+ assert!(before.curve_index(id).is_none() && before.point_index(id).is_none(), "{cmd}: {id} is not new");
+ }
+ for id in &curves {
+ let i = sk.curve_index(id).unwrap_or_else(|| panic!("{cmd}: curve {id} not in the sketch"));
+ let measurable = matches!(sk.curves[i].kind, CurveKind::Line { .. } | CurveKind::Circle { .. } | CurveKind::Arc { .. });
+ if measurable {
+ run(s, "sketch.dimension", json!({"entities": [id], "driven": true}));
+ }
+ run(s, "sketch.constraint.fix", json!({"entity": id, "fixed": true}));
+ run(s, "edit.undo", json!({}));
+ if measurable {
+ run(s, "edit.undo", json!({}));
+ }
+ }
+ for id in &points {
+ run(s, "sketch.dimension", json!({"entities": [id, "origin"], "driven": true}));
+ run(s, "edit.undo", json!({}));
+ }
+ c
+}
+
+/// Run `cmd` in `s` and check what it reports.
+fn made(s: &mut Session, cmd: &str, p: Value) -> Value {
+ let before = sketch(s);
+ let r = run(s, cmd, p);
+ check(s, cmd, &r, &before)
+}
+
+#[test]
+fn drawing_commands_return_the_ids_they_create() {
+ let cases: Vec<(&str, Value)> = vec![
+ ("sketch.line", json!({"points": [[0, 0], [10, 0], [10, 5]]})),
+ ("sketch.rectangle.two_point", json!({"p0": [1, 1], "p1": [21, 15]})),
+ ("sketch.rectangle.three_point", json!({"p0": [0, 0], "p1": [20, 5], "p2": [18, 15]})),
+ ("sketch.rectangle.center", json!({"center": [3, 2], "corner": [13, 9]})),
+ ("sketch.circle.center", json!({"center": [5, 5], "diameter": 8})),
+ ("sketch.circle.two_point", json!({"p0": [0, 0], "p1": [10, 0]})),
+ ("sketch.circle.three_point", json!({"p0": [0, 0], "p1": [10, 0], "p2": [5, 6]})),
+ ("sketch.arc.three_point", json!({"start": [0, 0], "end": [10, 0], "through": [5, 4]})),
+ ("sketch.arc.center_point", json!({"center": [0, 0], "start": [10, 0], "end": [0, 10]})),
+ ("sketch.polygon.inscribed", json!({"center": [0, 0], "radius": 10, "sides": 6})),
+ ("sketch.polygon.circumscribed", json!({"center": [0, 0], "radius": 10, "sides": 5})),
+ ("sketch.polygon.edge", json!({"p0": [0, 0], "p1": [10, 0], "sides": 4})),
+ ("sketch.slot.center_to_center", json!({"p0": [0, 0], "p1": [20, 0], "width": 6})),
+ ("sketch.slot.overall", json!({"p0": [0, 0], "p1": [20, 0], "width": 6})),
+ ("sketch.slot.center_point", json!({"center": [0, 0], "end": [10, 0], "width": 4})),
+ ("sketch.slot.arc_three_point", json!({"start": [0, 0], "through": [10, 5], "end": [20, 0], "width": 3})),
+ ("sketch.slot.arc_center", json!({"center": [0, 0], "start": [10, 0], "end": [0, 10], "width": 3})),
+ ("sketch.point", json!({"point": [3, 4]})),
+ ("sketch.line.midpoint", json!({"mid": [0, 0], "end": [10, 5]})),
+ ("sketch.ellipse", json!({"center": [0, 0], "major": [10, 0], "minor_radius": 4})),
+ ("sketch.spline.fit_point", json!({"points": [[0, 0], [5, 5], [10, 0]]})),
++ ("sketch.spline.fit_point", json!({"points": [[0, 0], [5, 5], [10, 0]], "periodic": true})),
+ ("sketch.spline.control_point", json!({"points": [[0, 0], [5, 5], [10, 0], [15, 5]]})),
+ ("sketch.spline.control_point_5", json!({"points": [[0, 0], [3, 5], [6, 0], [9, 5], [12, 0], [15, 5]]})),
+ ("sketch.conic", json!({"start": [0, 0], "end": [10, 0], "apex": [5, 6]})),
+ ("sketch.text", json!({"text": "IT", "at": [0, 0], "height": 10})),
+ ];
+ for (cmd, p) in cases {
+ let mut s = new_sketch();
+ made(&mut s, cmd, p);
+ }
+}
+
+#[test]
+fn drawn_ids_take_driving_dimensions_and_constraints() {
+ let mut s = new_sketch();
+ let c = made(&mut s, "sketch.line", json!({"points": [[0, 0], [10, 0]], "connect": false}));
+ let l = strs(&c["curves"]);
+ let pts = strs(&c["points"]);
+ assert_eq!((l.len(), pts.len()), (1, 2), "{c}");
+ run(&mut s, "sketch.constraint.coincident", json!({"a": pts[0], "b": "origin"}));
+ run(&mut s, "sketch.constraint.horizontal_vertical", json!({"line": l[0]}));
+ let d = run(&mut s, "sketch.dimension", json!({"entities": [l[0]], "value": 30}));
+ assert_eq!(strs(&d["created"]["dimensions"]).len(), 1, "{d}");
+ let sk = sketch(&s);
+ let end = sk.point(sk.point_index(&pts[1]).unwrap()).unwrap();
+ assert!((end.x - 30.0).abs() < 1e-6 && end.y.abs() < 1e-6, "{end:?}");
+
+ let c = made(&mut s, "sketch.circle.center", json!({"center": [50, 0], "radius": 4}));
+ let circle = strs(&c["curves"]);
+ run(&mut s, "sketch.dimension", json!({"entities": [circle[0]], "type": "diameter", "value": 12}));
+ let sk = sketch(&s);
+ let i = sk.curve_index(&circle[0]).unwrap();
+ assert!(matches!(sk.curves[i].kind, CurveKind::Circle { r, .. } if (r - 6.0).abs() < 1e-6));
+}
+
+#[test]
+fn modify_commands_return_the_ids_they_create() {
+ // Corner tools: an open L of two lines.
+ for (cmd, extra) in [
+ ("sketch.fillet", json!({"radius": 2})),
+ ("sketch.chamfer.equal_distance", json!({"distance": 2})),
+ ("sketch.chamfer.distance_angle", json!({"distance": 2, "angle": 40})),
+ ("sketch.chamfer.two_distance", json!({"distance": 2, "distance2": 3})),
+ ] {
+ let mut s = new_sketch();
+ let c = made(&mut s, "sketch.line", json!({"points": [[0, 10], [0, 0], [10, 0]]}));
+ let l = strs(&c["curves"]);
+ let mut p = extra;
+ p["point"] = json!(format!("{}.end", l[0]));
+ let c = made(&mut s, cmd, p);
+ assert!(!strs(&c["curves"]).is_empty(), "{cmd}: {c}");
+ }
+
+ let mut s = new_sketch();
+ let rect = strs(&made(&mut s, "sketch.rectangle.two_point", json!({"p0": [0, 0], "p1": [20, 10]}))["curves"]);
+ let c = made(&mut s, "sketch.offset", json!({"curves": [rect[0]], "distance": 2, "side": [10, 5]}));
+ assert_eq!(strs(&c["curves"]).len(), 4, "{c}");
+ made(&mut s, "sketch.move", json!({"entities": [rect[0]], "translate": [0, -20], "copy": true}));
+ made(&mut s, "sketch.pattern.rectangular", json!({"entities": [rect[2]], "count": 3, "spacing": 30}));
+ let circle = strs(&made(&mut s, "sketch.circle.center", json!({"center": [100, 0], "radius": 2}))["curves"]);
+ made(&mut s, "sketch.pattern.circular", json!({"entities": [circle[0]], "center": [90, 0], "count": 4}));
+ let axis = strs(&made(&mut s, "sketch.line", json!({"points": [[200, -10], [200, 10]]}))["curves"]);
+ let sm = strs(&made(&mut s, "sketch.circle.center", json!({"center": [190, 0], "radius": 2}))["curves"]);
+ made(&mut s, "sketch.mirror", json!({"entities": [sm[0]], "line": axis[0]}));
+
+ // Break and trim split a curve where another crosses it.
+ let mut s = new_sketch();
+ let h = strs(&made(&mut s, "sketch.line", json!({"points": [[0, 0], [20, 0]]}))["curves"]);
+ made(&mut s, "sketch.line", json!({"points": [[10, -5], [10, 5]]}));
+ made(&mut s, "sketch.break", json!({"curve": h[0], "at": [5, 0]}));
+ let mut s = new_sketch();
+ let h = strs(&made(&mut s, "sketch.line", json!({"points": [[0, 0], [30, 0]]}))["curves"]);
+ made(&mut s, "sketch.line", json!({"points": [[10, -5], [10, 5]]}));
+ made(&mut s, "sketch.line", json!({"points": [[20, -5], [20, 5]]}));
+ made(&mut s, "sketch.trim", json!({"curve": h[0], "at": [15, 0]}));
+
+ // Tangent tools and blends start from existing curves.
+ let mut s = new_sketch();
+ let l = strs(&made(&mut s, "sketch.line", json!({"points": [[0, 0], [10, 0]]}))["curves"]);
+ made(&mut s, "sketch.arc.tangent", json!({"start": format!("{}.end", l[0]), "end": [20, 10]}));
+ let a = strs(&made(&mut s, "sketch.line", json!({"points": [[0, 30], [10, 30]]}))["curves"]);
+ let b = strs(&made(&mut s, "sketch.line", json!({"points": [[20, 40], [30, 40]]}))["curves"]);
+ made(&mut s, "sketch.blend_curve", json!({"a": format!("{}.end", a[0]), "b": format!("{}.start", b[0])}));
+ let x = strs(&made(&mut s, "sketch.line", json!({"points": [[100, 0], [140, 0]], "connect": false}))["curves"]);
+ let y = strs(&made(&mut s, "sketch.line", json!({"points": [[100, 0], [100, 40]], "connect": false}))["curves"]);
+ made(&mut s, "sketch.circle.two_tangent", json!({"curves": [x[0], y[0]], "radius": 5, "near": [106, 4]}));
+ let z = strs(&made(&mut s, "sketch.line", json!({"points": [[100, 40], [140, 40]], "connect": false}))["curves"]);
+ made(&mut s, "sketch.circle.three_tangent", json!({"curves": [x[0], y[0], z[0]], "near": [120, 20]}));
+}
+
++#[test]
++fn dimensioned_drawing_reports_its_geometry_and_driving_dimensions() {
++ // The creator runs nested inside sketch.draw.dimensioned; `created` must still cover the
++ // dimensions the wrapper adds afterwards, not just the nested creator's geometry.
++ for (cmd, p, dims) in [
++ ("sketch.line", json!({"points": [[0, 0], [5, 5]]}), json!({"length": 10, "angle": 45})),
++ ("sketch.rectangle.two_point", json!({"p0": [0, 0], "p1": [20, 10]}), json!({"width": 30, "height": 15})),
++ ("sketch.circle.center", json!({"center": [0, 0], "radius": 3}), json!({"diameter": 12})),
++ ("sketch.polygon.inscribed", json!({"center": [0, 0], "radius": 10, "sides": 6}), json!({"radius": 8})),
++ ] {
++ let mut s = new_sketch();
++ let c = made(&mut s, "sketch.draw.dimensioned", json!({"command": cmd, "params": p, "dimensions": dims}));
++ let n = dims.as_object().map_or(0, |d| d.len());
++ assert_eq!(strs(&c["dimensions"]).len(), n, "{cmd}: {c}");
++ assert!(!strs(&c["curves"]).is_empty(), "{cmd}: {c}");
++ }
++}
++
++#[test]
++fn breaking_an_offset_association_creates_nothing() {
++ let mut s = new_sketch();
++ let e = strs(&made(&mut s, "sketch.ellipse", json!({"center": [0, 0], "major": [10, 0], "minor_radius": 5, "connect": false}))["curves"]);
++ let c = made(&mut s, "sketch.offset", json!({"curves": [e[0]], "distance": -1, "chain": false}));
++ let out = strs(&c["curves"]);
++ let r = run(&mut s, "sketch.offset.break", json!({"curve": out[0]}));
++ let c = &r["created"];
++ for k in ["points", "curves", "constraints", "dimensions"] {
++ assert_eq!(c[k], json!([]), "{r}");
++ }
++}
++
+#[test]
+fn text_edits_and_imports_return_the_ids_they_create() {
+ let mut s = new_sketch();
+ let r = run(&mut s, "sketch.text", json!({"text": "I", "at": [0, 0], "height": 10}));
+ check(&mut s, "sketch.text", &r, &Sketch::new());
+ let before = sketch(&s);
+ let link = r["link"].as_str().map(str::to_string).unwrap_or_else(|| panic!("{r}"));
+ let r = run(&mut s, "sketch.edit_text", json!({"link": link, "text": "II"}));
+ check(&mut s, "sketch.edit_text", &r, &before);
+
+ let svg = r#"<svg width="40mm" height="40mm" viewBox="0 0 40 40"><path d="M0 0 H40 V40 H0 Z"/></svg>"#;
+ let mut s = new_sketch();
+ let c = made(&mut s, "sketch.insert_svg", json!({"text": svg}));
+ assert_eq!(strs(&c["curves"]).len(), 4, "{c}");
+ let dxf = run(&mut s, "sketch.export_dxf", json!({}))["dxf"].as_str().unwrap_or_default().to_string();
+ let mut s = new_sketch();
+ let c = made(&mut s, "sketch.insert_dxf", json!({"text": dxf}));
+ assert_eq!(strs(&c["curves"]).len(), 4, "{c}");
+}
+
+#[test]
+fn projections_and_3d_curves_return_the_ids_they_create() {
+ let mut s = Session::default();
+ run(&mut s, "solid.box", json!({"corner": [0, 0, 0], "length": 20, "width": 20, "height": 10}));
+ let body = s.model.state().bodies.first().map(|b| b.name.clone()).unwrap_or_default();
+ run(&mut s, "sketch.create", json!({"plane": "XY", "offset": 5}));
+ made(&mut s, "sketch.project", json!({"refs": [{"edge": [10, 0, 10]}]}));
+ made(&mut s, "sketch.intersect", json!({"refs": [{"body": body}]}));
+ made(&mut s, "sketch.include_3d", json!({"refs": [{"edge": [20, 10, 10]}]}));
+ made(&mut s, "sketch.fit_curves_to_section", json!({"body": body}));
+ made(&mut s, "sketch.isoparametric_curve", json!({"face": [10, 10, 10]}));
+
+ let mut s = new_sketch();
+ run(&mut s, "sketch.options", json!({"sketch_3d": true}));
+ let c = made(&mut s, "sketch.line3d", json!({"points": [[0, 0, 0], [0, 0, 10], [10, 0, 10]]}));
+ assert_eq!(strs(&c["wires"]).len(), 2, "{c}");
+ made(&mut s, "sketch.spline3d", json!({"points": [[0, 0, 0], [5, 5, 5], [10, 0, 10]]}));
+ made(&mut s, "sketch.point3d", json!({"point": [5, 5, 5]}));
+}
+
+#[test]
+fn a_new_sketch_reports_its_projected_face_edges() {
+ let mut s = Session::default();
+ run(&mut s, "solid.box", json!({"corner": [0, 0, 0], "length": 20, "width": 20, "height": 10}));
+ let r = run(&mut s, "sketch.create", json!({"plane": {"face": [10, 10, 10]}}));
+ let c = check(&mut s, "sketch.create", &r, &Sketch::new());
+ assert_eq!(strs(&c["curves"]).len(), 4, "{c}");
+}
+
+#[test]
+fn ids_are_never_reused_after_a_delete() {
+ let mut s = new_sketch();
+ let first = made(&mut s, "sketch.line", json!({"points": [[0, 0], [10, 0]]}));
+ let circle = made(&mut s, "sketch.circle.center", json!({"center": [30, 0], "radius": 3}));
+ let dim = run(&mut s, "sketch.dimension", json!({"entities": [strs(&circle["curves"])[0]], "value": 8}));
+ let mut gone: Vec<String> = ["points", "curves"].iter().flat_map(|k| strs(&first[k]).into_iter().chain(strs(&circle[k]))).collect();
+ gone.extend(strs(&dim["created"]["dimensions"]));
+ // Deleting the curves takes their own end and centre points (and the dimension) with them.
+ run(&mut s, "sketch.delete", json!({"entities": strs(&first["curves"]).into_iter().chain(strs(&circle["curves"])).collect::<Vec<_>>()}));
+ let sk = sketch(&s);
+ assert!(sk.curves.is_empty() && sk.points.len() == 1 && sk.constraints.is_empty(), "{:?}", sk.curves);
+ // The same commands again: every id is new.
+ let again = made(&mut s, "sketch.line", json!({"points": [[0, 0], [10, 0]]}));
+ let circle2 = made(&mut s, "sketch.circle.center", json!({"center": [30, 0], "radius": 3}));
+ let dim2 = run(&mut s, "sketch.dimension", json!({"entities": [strs(&circle2["curves"])[0]], "value": 8}));
+ let mut fresh: Vec<String> = ["points", "curves"].iter().flat_map(|k| strs(&again[k]).into_iter().chain(strs(&circle2[k]))).collect();
+ fresh.extend(strs(&dim2["created"]["dimensions"]));
+ assert_eq!(fresh.len(), gone.len(), "{fresh:?} {gone:?}");
+ for id in &fresh {
+ assert!(!gone.contains(id), "id {id} reused: {gone:?} -> {fresh:?}");
+ }
+ // Undo of a delete brings the old ids back unchanged (they still name the same geometry).
+ let line = strs(&again["curves"])[0].clone();
+ run(&mut s, "sketch.delete", json!({"entities": [line]}));
+ run(&mut s, "edit.undo", json!({}));
+ assert!(sketch(&s).curve_index(&line).is_some());
+}
+
+/// The example in docs/control-protocol.md.
+#[test]
+fn documented_example_holds() {
+ let mut s = new_sketch();
+ let r = run(&mut s, "sketch.line", json!({"points": [[0, 0], [40, 0]]}));
+ assert_eq!(r["curves"], json!(["l1"]));
+ assert_eq!(r["created"], json!({"points": ["l1.start", "l1.end"], "curves": ["l1"], "constraints": ["k1"], "dimensions": []}));
+ run(&mut s, "sketch.dimension", json!({"entities": ["l1"], "value": 50}));
+}
+
+#[test]
+fn commands_that_add_nothing_report_empty_lists() {
+ let mut s = new_sketch();
+ let c = made(&mut s, "sketch.line", json!({"points": [[0, 0], [10, 5]]}));
+ let r = run(&mut s, "sketch.move_point", json!({"point": strs(&c["points"])[1], "to": [12, 6]}));
+ assert_eq!(r["created"], json!({"points": [], "curves": [], "constraints": [], "dimensions": []}), "{r}");
+}
diff --cc crates/engine/src/cmd/sketch_modify.rs
index d7b9872665,282f2def70..a43dd79154
--- a/crates/engine/src/cmd/sketch_modify.rs
+++ b/crates/engine/src/cmd/sketch_modify.rs
@@@ -38,7 -41,10 +41,10 @@@ pub static COMMANDS: &[CommandSpec] = &
.icon("offset")
.key("O")
.enabled(in_sketch)
- .params("curves: [ids], distance: number (positive = left of the chain, or toward `side`), side?: [x,y], chain?: bool (default true: the connected chain)"),
+ .params(concat!("curves: [ids], distance: number (positive = left of the chain, or toward `side`), side?: [x,y], chain?: bool (default true: the connected chain)", created_doc!())),
+ CommandSpec::new("sketch.offset.break", "Break Offset Association", break_offset)
+ .enabled(in_sketch)
+ .params("curve: derived offset curve id (retains geometry and makes its points editable)"),
CommandSpec::new("sketch.trim", "Trim", trim)
.at("SKETCH", "MODIFY")
.icon("trim")
@@@ -54,7 -60,7 +60,7 @@@
.at("SKETCH", "MODIFY")
.icon("break")
.enabled(in_sketch)
- .params(concat!("curve: id, at: [x,y] (split at the nearest intersections around it) | params: split at points: [[x,y]…]", created_doc!())),
- .params("curve: id, at: [x,y] (split at intersections) | points: [[x,y]…] (1…1000 positions projected onto the curve; duplicates are merged)"),
++ .params(concat!("curve: id, at: [x,y] (split at intersections) | points: [[x,y]…] (1…1000 positions projected onto the curve; duplicates are merged)", created_doc!())),
CommandSpec::new("sketch.scale", "Sketch Scale", scale)
.at("SKETCH", "MODIFY")
.icon("scale")
diff --cc crates/engine/src/lib.rs
index 540f8ffbd9,e371eb154b..1d157477c5
--- a/crates/engine/src/lib.rs
+++ b/crates/engine/src/lib.rs
@@@ -375,29 -419,7 +420,28 @@@ impl Session
}
}
+ /// A sketch command's result gets `created`: the ids of the points, curves, constraints and
+ /// dimensions it added to its sketch (the `sketch` param, else the active sketch), so every
- /// drawing and modify command reports them the same way (see `cmd::sketch_created`).
++ /// drawing and modify command reports them the same way (see `cmd::sketch_created`). A command
++ /// that runs another one (`sketch.draw.dimensioned`) gets the whole diff, replacing the nested
++ /// command's narrower `created`.
+ fn with_created(&self, id: &str, params: &Value, before: &Snapshot, mut v: Value) -> Value {
+ if !id.starts_with("sketch.") {
+ return v;
+ }
+ let Some(out) = v.as_object_mut() else { return v };
- if out.contains_key("created") {
- return v;
- }
+ let named = match params.get("sketch") {
+ Some(Value::Number(n)) => self.doc.find_feature(&n.to_string()).map(|f| f.id),
+ Some(Value::String(x)) => self.doc.find_feature(x).map(|f| f.id),
+ _ => None,
+ };
+ let Some(sk) = named.or(self.active_sketch).or(before.active_sketch) else { return v };
+ let Ok(after) = self.doc.sketch(sk) else { return v };
+ out.insert("created".into(), cmd::sketch_created(before.doc.sketch(sk).ok(), after));
+ v
+ }
+
- /// Remember the design, active sketch and undo history; returns the checkpoint's id.
+ /// Remember the design, active sketch, pending positions and undo history; returns the checkpoint's id.
pub fn checkpoint(&mut self) -> u64 {
let id = self.next_checkpoint;
self.next_checkpoint += 1;
diff --cc docs/book/src/guide/sketching.md
index 85c7c25ed1,de24f0d45e..b74d1e300c
--- a/docs/book/src/guide/sketching.md
+++ b/docs/book/src/guide/sketching.md
@@@ -15,11 -15,43 +15,48 @@@ fillet, chamfer, offset (O), mirror, pa
**Project** (P) and **Intersect** bring model edges into the sketch as linked geometry that
follows later changes. Sketching on a face projects its edges automatically.
+Run from a script or the control channel, every command that adds sketch geometry returns the
+ids of what it added (`created: {points, curves, constraints, dimensions}`). Ids are stable and
+never reused within a sketch, even after a delete, so a script can dimension or constrain the new
+geometry right away.
+
+ Extend finds intersections with exact ellipses, rational conics and spline spans. It keeps the
+ original line or circular support and extends only beyond the selected endpoint; conflicting
+ constraints or an ambiguous overlap leave the sketch unchanged.
+
+ Offsets of smooth ellipses, conics and splines follow their source after dimension changes,
+ dragging and reopening a design. Their stored cubic spline has a whole-span normal-distance
+ error bound of 0.002 mm. Singular tangents, curvature cusps, possible self-intersections and
+ excessive subdivisions are refused. Offset these curves individually: mixed chain junctions
+ currently require separate geometry. `sketch.offset.break` releases an offset for independent
+ editing, and undo restores its association. Older independently sampled offsets remain independent.
+ Smooth open and newly created smooth closed offsets can be offset again, including bounded
+ refinement after a source edit. New closed outputs use a periodic cubic fit with continuous
+ tangent and curvature at the seam. Break Offset Association preserves that interpolation,
+ and its closing point remains joined when dragged. Deleting an output also removes its
+ unused private fit points; deleting a source with a retained dependent is refused.
+
+ For explicit closed fit splines, `sketch.spline.fit_point` accepts `periodic: true` and at
+ least three distinct cyclic samples. It closes the loop automatically. Existing calls and
+ older saved closed splines retain natural interpolation; older associative closed offsets
+ also retain their saved natural fit. A legacy seam without a unique normal still refuses
+ another offset. Periodic intent is stored on each curve and survives save, reopen and Break.
+ While drawing a fit spline, click its starting point after three distinct samples to close
+ it smoothly. Right-click finishes an ordinary natural fit. Offset accepts both ellipse
+ handles and dense fitted curves; the second click sets the side and distance from the curve.
+
+ Enable **3D Sketch** in the Sketch Palette to draw lines, fit splines and points off the plane.
+ New 3D geometry follows its sketch's component placement, including the selected occurrence
+ and pending position changes. Click a drawn fit point to show its move triad; its arrows move
+ along world X, Y and Z. Scripts also supply world coordinates to `sketch.line3d`,
+ `sketch.spline3d`, `sketch.point3d` and `sketch.move3d`. Activate the desired occurrence before
+ editing an explicit sketch belonging to a component with multiple placements.
+
+ Older drawn or detached 3D wires keep their saved world positions. Included and surface-linked
+ wires with an explicit component marker keep that meaning after the link is broken. Old files
+ whose links became lost after an incorrectly scoped cross-component refresh may require a
+ fresh link once the source is available; their stored point values are preserved on opening.
+
## Constraints and dimensions
The solver is SolveCraft's own (damped Gauss–Newton with degree-of-freedom analysis). Constraints: