Pattern on Path (PatternOnPath: spacing or first-to-last distance, flip, identical or path orientation; instance k moves by path(k·d) − path(0)), rectangular/circular/path patterns of bodies; recipes: path_pattern (oracle 53 passes)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AS5Tn3xieewUSg3uxrMVdL

crates/engine/src/cmd/features.rs

@@ -37,11 +37,15 @@ pub static COMMANDS: &[CommandSpec] = &[
     CommandSpec::new("PatternRectangular", "Rectangular Pattern", pattern_rect)
         .at("SOLID", "CREATE")
         .icon("pattern_rect")
-        .params("features: [names]; dir1: [x,y,z]; count1; spacing1; dir2?, count2?, spacing2?"),
+        .params("features: [names] | bodies: [names]; dir1: [x,y,z]; count1; spacing1; dir2?, count2?, spacing2?"),
     CommandSpec::new("PatternCircular", "Circular Pattern", pattern_circ)
         .at("SOLID", "CREATE")
         .icon("pattern_circ")
-        .params("features: [names]; axis: X|Y|Z | {origin, dir}; count; angle? (default 360 deg)"),
+        .params("features: [names] | bodies: [names]; axis: X|Y|Z | {origin, dir}; count; angle? (default 360 deg)"),
+    CommandSpec::new("PatternOnPath", "Pattern on Path", pattern_path)
+        .at("SOLID", "CREATE")
+        .icon("pattern_rect")
+        .params("features: [names] | bodies: [names]; path_sketch: sketch; path: [curve ids in order]; count; spacing (between instances) | distance (first to last); orientation?: identical|path; flip?: bool"),
     CommandSpec::new("MirrorCommand", "Mirror", mirror).at("SOLID", "CREATE").icon("mirror").params("features: [names] | bodies: [names] (combine?: join with the original); plane: XY|XZ|YZ | {origin, x_dir, y_dir}"),
     CommandSpec::new("FusionHoleCommand", "Hole", hole)
         .at("SOLID", "CREATE")
@@ -518,9 +522,22 @@ fn axis_line(p: &Value, cmd: &str) -> Result<(Vec3, Vec3)> {
     }
 }
 
+/// What a pattern copies: features (replayed), or bodies (`bodies: [names]`).
+fn pattern_sources(s: &Session, p: &Value, cmd: &str) -> Result<(Vec<String>, Vec<String>)> {
+    let bodies = string_list(p, "bodies");
+    if bodies.is_empty() {
+        return Ok((source_features(s, p, cmd)?, Vec::new()));
+    }
+    let st = s.model.state();
+    if let Some(b) = bodies.iter().find(|b| st.body(b).is_none()) {
+        return Err(bad(cmd, format!("no body `{b}`")));
+    }
+    Ok((Vec::new(), bodies))
+}
+
 fn pattern_rect(s: &mut Session, p: &Value) -> Result<Value> {
     let cmd = "PatternRectangular";
-    let features = source_features(s, p, cmd)?;
+    let (features, bodies) = pattern_sources(s, p, cmd)?;
     let dir1 = p.get("dir1").and_then(vec3).ok_or_else(|| bad(cmd, "`dir1` must be [x, y, z]"))?;
     let count1 = req_expr(cmd, p, "count1")?;
     let spacing1 = req_expr(cmd, p, "spacing1")?;
@@ -535,19 +552,45 @@ fn pattern_rect(s: &mut Session, p: &Value) -> Result<Value> {
         check_expr(s, c, Kind::Length, cmd, "spacing2")?;
     }
     let pattern = solvecraft_doc::PatternKind::Rectangular { dir1, count1, spacing1, dir2, count2, spacing2 };
-    add_feature(s, p, FeatureKind::Pattern { features, pattern })
+    add_feature(s, p, FeatureKind::Pattern { features, pattern, bodies })
 }
 
 fn pattern_circ(s: &mut Session, p: &Value) -> Result<Value> {
     let cmd = "PatternCircular";
-    let features = source_features(s, p, cmd)?;
+    let (features, bodies) = pattern_sources(s, p, cmd)?;
     let (origin, axis) = axis_line(p, cmd)?;
     let count = req_expr(cmd, p, "count")?;
     check_expr(s, &count, Kind::Unitless, cmd, "count")?;
     let angle = expr(p, "angle").unwrap_or_else(|| "360 deg".into());
     check_expr(s, &angle, Kind::Angle, cmd, "angle")?;
     let pattern = solvecraft_doc::PatternKind::Circular { origin, axis, count, angle };
-    add_feature(s, p, FeatureKind::Pattern { features, pattern })
+    add_feature(s, p, FeatureKind::Pattern { features, pattern, bodies })
+}
+
+fn pattern_path(s: &mut Session, p: &Value) -> Result<Value> {
+    let cmd = "PatternOnPath";
+    let (features, bodies) = pattern_sources(s, p, cmd)?;
+    let path_sketch = sketch_id(s, p.get("path_sketch").or_else(|| p.get("sketch")), cmd, "path_sketch")?;
+    let path = string_list(p, "path");
+    if path.is_empty() || path.len() > 1000 {
+        return Err(bad(cmd, "`path` must list 1…1000 curve ids"));
+    }
+    let count = req_expr(cmd, p, "count")?;
+    check_expr(s, &count, Kind::Unitless, cmd, "count")?;
+    let (spacing, extent) = match (expr(p, "spacing"), expr(p, "distance")) {
+        (Some(x), _) => (x, false),
+        (None, Some(x)) => (x, true),
+        (None, None) => return Err(bad(cmd, "give `spacing` (between instances) or `distance` (first to last)")),
+    };
+    check_expr(s, &spacing, Kind::Length, cmd, "spacing")?;
+    let orient = match str_(p, "orientation") {
+        None | Some("identical") => false,
+        Some("path" | "path_direction" | "along_path") => true,
+        Some(o) => return Err(bad(cmd, format!("unknown orientation `{o}` (identical or path)"))),
+    };
+    let flip = bool_(p, "flip").unwrap_or(false);
+    let pattern = solvecraft_doc::PatternKind::Path { path_sketch, path, count, spacing, extent, flip, orient };
+    add_feature(s, p, FeatureKind::Pattern { features, pattern, bodies })
 }
 
 fn mirror(s: &mut Session, p: &Value) -> Result<Value> {
@@ -863,3 +906,7 @@ fn offset_face(s: &mut Session, p: &Value) -> Result<Value> {
     check_expr(s, &distance, Kind::Length, cmd, "distance")?;
     add_feature(s, p, FeatureKind::OffsetFace { faces, distance, body: str_(p, "body").map(str::to_string) })
 }
+
+#[cfg(test)]
+#[path = "patterns_tests.rs"]
+mod patterns_tests;

crates/engine/src/cmd/patterns_tests.rs

@@ -0,0 +1,75 @@
+use std::f64::consts::PI;
+
+use serde_json::{Value, json};
+
+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 volume(s: &mut Session) -> f64 {
+    run(s, "MeasureCommand", json!({}))["total"]["volume_mm3"].as_f64().unwrap_or(f64::NAN)
+}
+
+fn rel(a: f64, b: f64) -> f64 {
+    (a - b).abs() / b.abs().max(1e-12)
+}
+
+/// A 100 x 50 x 5 plate with a hole at the start of a straight path (10,10) → (90,10).
+fn plate_with_hole() -> Session {
+    let mut s = Session::default();
+    run(&mut s, "PrimitiveBox", json!({"length": 100, "width": 50, "height": 5, "corner": [0, 0, 0]}));
+    run(&mut s, "SketchCreate", json!({"plane": "XY", "name": "Path"}));
+    run(&mut s, "DrawPolyline", json!({"points": [[10, 10], [90, 10]], "ids": ["l1"]}));
+    run(&mut s, "CircleCenterRadius", json!({"center": [10, 10], "radius": 2, "id": "c1"}));
+    run(&mut s, "SketchStop", json!({}));
+    run(&mut s, "Extrude", json!({"sketch": "Path", "through_all": true, "operation": "cut", "name": "Hole1"}));
+    s
+}
+
+const PLATE: f64 = 100.0 * 50.0 * 5.0;
+const HOLE: f64 = PI * 4.0 * 5.0;
+
+#[test]
+fn pattern_on_path_spacing_extent_and_flip() {
+    let mut s = plate_with_hole();
+    assert!(rel(volume(&mut s), PLATE - HOLE) < 1e-4);
+    run(&mut s, "PatternOnPath", json!({"features": ["Hole1"], "path_sketch": "Path", "path": ["l1"], "count": 5, "spacing": 20}));
+    assert!(rel(volume(&mut s), PLATE - 5.0 * HOLE) < 1e-4);
+    // The count is a parameter like any other input.
+    let n = s.doc.features.last().and_then(|f| f.param_names.first().cloned()).unwrap_or_default();
+    run(&mut s, "ChangeParameterCommand", json!({"name": n, "expression": "3"}));
+    assert!(rel(volume(&mut s), PLATE - 3.0 * HOLE) < 1e-4);
+    // Instances past the end of the path are an error.
+    run(&mut s, "ChangeParameterCommand", json!({"name": n, "expression": "6"}));
+    let err = s.model.results.last().and_then(|r| r.error.clone()).unwrap_or_default();
+    assert!(err.contains("past the end of the path"), "{err}");
+
+    // Distance = first to last instance.
+    let mut s = plate_with_hole();
+    run(&mut s, "PatternOnPath", json!({"features": ["Hole1"], "path_sketch": "Path", "path": ["l1"], "count": 3, "distance": 80}));
+    assert!(rel(volume(&mut s), PLATE - 3.0 * HOLE) < 1e-4);
+
+    // Flipped, the path runs from (90,10) back toward (10,10).
+    let mut s = plate_with_hole();
+    run(&mut s, "PatternOnPath", json!({"features": ["Hole1"], "path_sketch": "Path", "path": ["l1"], "count": 2, "spacing": 30, "flip": true}));
+    // The copy moves by path(30) − path(0) = (60,10) − (90,10) = −30: off the plate side → only 1 hole.
+    assert!(rel(volume(&mut s), PLATE - HOLE) < 1e-4);
+}
+
+#[test]
+fn patterns_of_bodies() {
+    let mut s = Session::default();
+    run(&mut s, "PrimitiveBox", json!({"length": 10, "width": 10, "height": 10, "corner": [20, 0, 0], "body_name": "Cube"}));
+    run(&mut s, "PatternCircular", json!({"bodies": ["Cube"], "axis": "Z", "count": 4}));
+    let m = run(&mut s, "MeasureCommand", json!({}));
+    assert_eq!(m["body_count"], 4, "{m}");
+    assert!(rel(volume(&mut s), 4000.0) < 1e-4);
+    run(&mut s, "PatternRectangular", json!({"bodies": ["Cube"], "dir1": [0, 0, 1], "count1": 3, "spacing1": 20}));
+    assert!(rel(volume(&mut s), 6000.0) < 1e-4);
+    assert!(s.execute("PatternRectangular", &json!({"bodies": ["Nope"], "dir1": [1, 0, 0], "count1": 2, "spacing1": 5})).is_err());
+}