SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Boundary surfaces (`surface.boundary`, issue #763): one patch through two to four sketch
//! curves in loop order, or one surface through a network of curves in two directions (sketch
//! curves, 3D sketch curves, a body's edges, or a point for a three-sided patch). The kernel
//! builds the face; this is the command's parameters and its checks, so that what it cannot hold
//! is refused before anything is built.
use serde_json::Value;
use solidcraft_doc::{BodyName, FeatureKind, NetworkCurve, Operation, Position, SketchId};
use solidcraft_geom::prelude::*;
use solidcraft_kernel::{Construction, Continuity};
use super::CommandSpec;
use super::features::{add_feature, feature_sketch, sketch_id};
use crate::params::{bad, str_, string_list, vec3};
use crate::schema::features::FeatureResult;
use crate::schema::surface_boundary::{BoundaryParams, MAX_NETWORK_CURVES, MAX_SAMPLES, MIN_SAMPLES};
use crate::schema::{TypedContract, output_schema_for};
use crate::{Result, Session};
/// The stations a boundary carries by default (the patch's resolution along the loop).
const DEFAULT_SAMPLES: usize = solidcraft_doc::BOUNDARY_SAMPLES;
const CONTRACT: TypedContract<BoundaryParams> = TypedContract::new();
/// The most sketch curves one network curve may chain, and points picking one chain of edges
/// (the kernel's own caps).
use solidcraft_kernel::{MAX_CHAIN_CURVES as MAX_CHAIN, MAX_EDGE_PICKS as MAX_PICKS};
pub static COMMANDS: &[CommandSpec] = &[CommandSpec::new("surface.boundary", "Boundary Surface", crate::checked!("surface.boundary", boundary))
.at("SURFACE", "CREATE")
.icon("surface_boundary")
.contract(&CONTRACT)
.output(output_schema_for::<FeatureResult>)
.params(
"Either a loop of one sketch's curves — sketch?: id|name (default: the sketch being edited); curves: [2 to 4 sketch curve ids in loop order] (each one ends where the next begins and the last where the first does; two: the patch spans between them and leaves each boundary along the tangent across it; three or four: the flat patch of the loop, three collapsing the side opposite the first curve to the corner there); continuity?: g0|g1|g2|g3 | [one per curve] (default g1: how much of the surface across each boundary the patch repeats — a sketch curve's own plane, so g1 and up hold exactly and g0 lets the middle bow); crown?: number -0.9…3 (default 0: how full the middle is, without touching a boundary; two curves only); samples?: 8…512 stations per boundary (default 25) — or a curve network — u: [curve] (two or more one way: the surface lofts through them), v?: [curve] (crossing every u-curve once: two each way give a Coons patch, more a Gordon surface through every curve; a curve that misses another by more than 0.01 mm is refused, naming the pair), each curve \"id\" (a curve of `sketch`) | {sketch?: id|name, curves: [ids meeting end to end]} (planar or 3D sketch curves) | {body: name, edges: [[x,y,z]] (points on a chain of its edges), continuity?: g0|g1|g2 (default g0; g1 the surface leaves tangent to the face beside a surface's open edges, g2 with its curvature too; on curves of one direction only)} | {point: [x,y,z]} (a side collapsed to a point: a three-sided patch); operation?: new|join (default new; join sews the surface into the body of its first edge curve, a solid when it closes the gap). name?, body_name? (a surface body)",
)];
/// `surface.boundary`: a loop of sketch curves, or a network when `u` is given.
fn boundary(s: &mut Session, p: &Value) -> Result<Value> {
if p.get("u").is_some_and(|v| !v.is_null()) {
return network(s, p);
}
loop_patch(s, p)
}
/// `surface.boundary` with `curves`: one patch through two to four sketch curves in loop order.
fn loop_patch(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "surface.boundary";
if p.get("v").is_some_and(|v| !v.is_null()) || p.get("operation").is_some_and(|v| !v.is_null()) {
return Err(bad(cmd, "`v` and `operation` belong to a curve network: give its curves as `u` and `v`"));
}
let sketch = feature_sketch(s, p, cmd)?;
let curves = string_list(cmd, p, "curves")?;
if !(2..=4).contains(&curves.len()) {
return Err(bad(cmd, "`curves` must list 2 to 4 sketch curves in loop order (or give a network as `u` and `v`)"));
}
// The curves must be the sketch's own, and they must run on into one another: the last station
// of each is the first of the next, and the last boundary's end is the first one's start.
let state = s.model.state();
let sk = state.sketch(sketch).ok_or_else(|| bad(cmd, "the sketch has not been solved"))?;
let mut ends: Vec<(solidcore_record::Vec2, solidcore_record::Vec2)> = Vec::with_capacity(curves.len());
for id in &curves {
let ci = sk.sketch.curve_index(id).ok_or_else(|| bad(cmd, format!("no sketch curve `{id}`")))?;
let pieces = sk.sketch.exact_pieces(ci);
let (Some(first), Some(last)) = (pieces.first(), pieces.last()) else {
return Err(bad(cmd, format!("curve `{id}` has no exact geometry to build on")));
};
if last.end().dist(first.start()) < 1e-9 {
return Err(bad(cmd, format!("curve `{id}` is closed: a boundary must be one side of the loop")));
}
ends.push((first.start(), last.end()));
}
// Two boundaries are the two sides of a bridge, which do not meet; three or four run round a
// loop, so each has to end where the next begins.
let scale = ends.iter().map(|(a, b)| a.dist(*b)).fold(1.0_f64, f64::max);
let tol = scale * 1e-4 + 1e-9;
for i in 0..if curves.len() >= 3 { ends.len() } else { 0 } {
let next = (i + 1) % ends.len();
let (Some(end), Some(start)) = (ends.get(i).map(|e| e.1), ends.get(next).map(|e| e.0)) else {
return Err(bad(cmd, "a curve is missing its ends"));
};
let gap = end.dist(start);
if gap > tol {
return Err(bad(
cmd,
format!("curve `{}` ends {gap:.4} mm from where `{}` starts: list the curves in loop order", curves[i], curves[next]),
));
}
}
drop(state);
let orders = match p.get("continuity") {
None | Some(Value::Null) => vec![Continuity::G1; curves.len()],
Some(one @ Value::String(_)) => vec![crate::params::continuity(cmd, Some(one), "`continuity`", Construction::Bridge)?; curves.len()],
Some(v) => {
let list = v.as_array().filter(|a| a.len() == curves.len()).ok_or_else(|| bad(cmd, "`continuity` must be one word, or one per curve"))?;
let mut out = Vec::with_capacity(list.len());
for x in list {
out.push(crate::params::continuity(cmd, Some(x), "a `continuity` entry", Construction::Bridge)?);
}
out
}
};
let crown = match p.get("crown") {
None | Some(Value::Null) => 0.0,
Some(v) => v
.as_f64()
.filter(|x| x.is_finite() && (solidcraft_geom::fill::MIN_CROWN..=solidcraft_geom::fill::MAX_CROWN).contains(x))
.ok_or_else(|| bad(cmd, "`crown` must be a number between -0.9 and 3"))?,
};
let samples = match p.get("samples") {
None | Some(Value::Null) => DEFAULT_SAMPLES,
Some(v) => {
let n = v.as_f64().filter(|x| x.is_finite() && x.fract() == 0.0).map(|x| x as usize);
n.filter(|x| (MIN_SAMPLES..=MAX_SAMPLES).contains(x))
.ok_or_else(|| bad(cmd, format!("`samples` must be a whole number of stations between {MIN_SAMPLES} and {MAX_SAMPLES}")))?
}
};
if crown != 0.0 && curves.len() >= 3 {
return Err(bad(cmd, "not supported yet: `crown` on a patch through three or four curves (it is the flat patch of its sides)"));
}
add_feature(s, p, FeatureKind::SurfaceBoundary { sketch: SketchId(sketch), curves, orders, crown, samples })
}
/// `surface.boundary` with `u` (and `v`): one surface through a curve network.
fn network(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "surface.boundary";
for key in ["curves", "continuity", "crown", "samples"] {
if p.get(key).is_some_and(|v| !v.is_null()) {
return Err(bad(cmd, format!("`{key}` belongs to a loop of sketch curves: a network gives each curve its own continuity")));
}
}
let operation = super::features::operation(p, cmd)?;
if !matches!(operation, Operation::NewBody | Operation::Join) {
return Err(bad(cmd, "`operation` must be new or join"));
}
// The sketch a bare curve id belongs to, found only when one is used.
let mut default_sketch: Option<u64> = None;
let u = network_curves(s, p, "u", &mut default_sketch)?;
let v = network_curves(s, p, "v", &mut default_sketch)?;
if u.is_empty() {
return Err(bad(cmd, "`u` must list the curves of one direction"));
}
if u.len() + v.len() < 2 {
return Err(bad(cmd, "a boundary surface needs two curves in one direction, or crossing curves"));
}
if operation == Operation::Join && !u.iter().chain(&v).any(|c| c.body.is_some()) {
return Err(bad(cmd, "`operation` join needs a curve on a body's edges: the surface is sewn into that body"));
}
add_feature(s, p, FeatureKind::SurfaceNetwork { u, v, operation })
}
/// One direction of a network (`key` is `u` or `v`), checked: each curve sketch curves that exist
/// (planar or 3D), a body's edges with points on them, or a point; a continuity only on edges.
fn network_curves(s: &Session, p: &Value, key: &str, default_sketch: &mut Option<u64>) -> Result<Vec<NetworkCurve>> {
let cmd = "surface.boundary";
let list = match p.get(key) {
None | Some(Value::Null) => return Ok(Vec::new()),
Some(Value::Array(a)) => a,
Some(_) => return Err(bad(cmd, format!("`{key}` must list curves"))),
};
if list.len() > MAX_NETWORK_CURVES {
return Err(bad(cmd, format!("`{key}` may list at most {MAX_NETWORK_CURVES} curves")));
}
let mut out = Vec::with_capacity(list.len());
for (k, item) in list.iter().enumerate() {
let name = format!("{key}[{k}]");
let mut curve = NetworkCurve { sketch: None, curves: Vec::new(), body: None, edges: Vec::new(), point: None, continuity: Continuity::G0 };
let obj = match item {
Value::String(id) => {
curve.curves = vec![id.clone()];
None
}
Value::Object(_) => Some(item),
_ => return Err(bad(cmd, format!("{name} must be a curve id or {{sketch?, curves}}, {{body, edges}} or {{point}}"))),
};
if let Some(o) = obj {
let has = |k: &str| o.get(k).is_some_and(|v| !v.is_null());
let kinds = [has("curves"), has("body") || has("edges"), has("point")];
if kinds.iter().filter(|x| **x).count() != 1 {
return Err(bad(cmd, format!("{name} must be one of {{sketch?, curves}}, {{body, edges}} or {{point}}")));
}
if has("point") {
curve.point = Some(Position(o.get("point").and_then(vec3).ok_or_else(|| bad(cmd, format!("{name}.point must be [x, y, z]")))?));
} else if kinds[1] {
let body = str_(o, "body").ok_or_else(|| bad(cmd, format!("{name}.body must name a body")))?;
if s.model.state().body(body).is_none() {
return Err(bad(cmd, format!("no body `{body}`")));
}
let edges =
o.get("edges").and_then(Value::as_array).ok_or_else(|| bad(cmd, format!("{name}.edges must list points on the edges")))?;
if edges.is_empty() || edges.len() > MAX_PICKS {
return Err(bad(cmd, format!("{name}.edges must list 1 to {MAX_PICKS} points on a chain of edges")));
}
let pts: Vec<Position> = edges
.iter()
.map(|e| vec3(e).map(Position).ok_or_else(|| bad(cmd, format!("{name}.edges: a point must be [x, y, z]"))))
.collect::<Result<_>>()?;
curve.body = Some(BodyName::from(body.to_string()));
curve.edges = pts;
} else {
curve.curves = string_list(cmd, o, "curves")?;
if o.get("sketch").is_some_and(|v| !v.is_null()) {
curve.sketch = Some(SketchId(sketch_id(s, o.get("sketch"), cmd, &format!("{name}.sketch"))?));
}
}
if let Some(g) = o.get("continuity").filter(|v| !v.is_null()) {
let g = crate::params::continuity(cmd, Some(g), &format!("{name}.continuity"), Construction::Network)?;
if g != Continuity::G0 && curve.body.is_none() {
return Err(bad(cmd, format!("{name}: g1 and g2 apply to a curve on a body's edges (a surface's open edges)")));
}
curve.continuity = g;
}
}
if curve.point.is_none() && curve.body.is_none() {
if curve.curves.is_empty() || curve.curves.len() > MAX_CHAIN {
return Err(bad(cmd, format!("{name} must list 1 to {MAX_CHAIN} sketch curves")));
}
let sketch = match curve.sketch {
Some(id) => id.0,
None => match *default_sketch {
Some(id) => id,
None => {
let id = feature_sketch(s, p, cmd)?;
*default_sketch = Some(id);
id
}
},
};
let state = s.model.state();
let sk = state.sketch(sketch).ok_or_else(|| bad(cmd, "the sketch has not been solved"))?;
for id in &curve.curves {
if sk.sketch.curve_index(id).is_none() && sk.sketch.wire_index(id).is_none() {
return Err(bad(cmd, format!("{name}: no sketch curve `{id}`")));
}
}
curve.sketch = Some(SketchId(sketch));
}
out.push(curve);
}
Ok(out)
}
#[cfg(test)]
mod tests {
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 ids(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 new_sketch() -> Session {
let mut s = Session::default();
run(&mut s, "sketch.create", json!({"plane": "XY"}));
s
}
/// Two parallel 20 mm lines 10 mm apart, and the patch between them.
fn two_walls(s: &mut Session) -> Vec<String> {
let a = ids(&run(s, "sketch.line", json!({"points": [[0, 0], [20, 0]]}))["created"]["curves"])[0].clone();
let b = ids(&run(s, "sketch.line", json!({"points": [[0, 10], [20, 10]]}))["created"]["curves"])[0].clone();
vec![a, b]
}
#[test]
fn a_boundary_patch_between_two_sketch_curves_is_the_sheet_they_span() {
for continuity in [json!("g0"), json!("g1"), json!("g2"), json!(["g1", "g2"])] {
let mut s = new_sketch();
let curves = two_walls(&mut s);
let r = run(&mut s, "surface.boundary", json!({"curves": curves, "continuity": continuity}));
let body = ids(&r["created_bodies"])[0].clone();
// It is one face, its boundary is the two lines themselves, and it covers exactly the
// 20 × 10 sheet between them — all four frames lie in the sketch's plane.
let f = run(&mut s, "model.faces", json!({"body": body}));
let faces = f["faces"].as_array().cloned().unwrap_or_default();
assert_eq!(faces.len(), 1, "{continuity}: {f}");
assert!((faces[0]["area"].as_f64().unwrap_or(f64::NAN) - 200.0).abs() < 1e-4, "{continuity}: {f}");
let normal = faces[0]["plane_normal"].as_array().cloned().unwrap_or_default();
assert_eq!(normal.len(), 3, "{continuity}: the patch is planar: {f}");
assert!(normal[2].as_f64().unwrap_or(0.0).abs() > 1.0 - 1e-9, "{continuity}: it lies in the sketch's plane: {f}");
let m = run(&mut s, "inspect.measure", json!({}));
let area = m["total"]["area_mm2"].as_f64().unwrap_or(f64::NAN);
assert!((area - 200.0).abs() < 1e-4, "{continuity}: {area}");
}
}
#[test]
fn a_boundary_patch_refuses_values_it_cannot_hold() {
let mut s = new_sketch();
let curves = two_walls(&mut s);
let extra = ids(&run(&mut s, "sketch.line", json!({"points": [[30, 30], [40, 40]]}))["created"]["curves"])[0].clone();
// A loop of three: the crown is the bridge's, not the flat loop patch's.
let a = ids(&run(&mut s, "sketch.line", json!({"points": [[0, 0], [20, 0]]}))["created"]["curves"])[0].clone();
let b = ids(&run(&mut s, "sketch.line", json!({"points": [[20, 0], [10, 15]]}))["created"]["curves"])[0].clone();
let c = ids(&run(&mut s, "sketch.line", json!({"points": [[10, 15], [0, 0]]}))["created"]["curves"])[0].clone();
let e = s.execute("surface.boundary", &json!({"curves": [a, b, c], "crown": 1})).unwrap_err().to_string();
assert!(e.contains("not supported yet") && e.contains("crown"), "three boundaries with a crown: {e}");
// Curves out of loop order.
let e = s.execute("surface.boundary", &json!({"curves": [curves[0], curves[1], extra]})).unwrap_err().to_string();
assert!(e.contains("loop order"), "{e}");
// Parameters and curves that make no sense.
let cases: Vec<(Value, &str)> = vec![
(json!({"curves": [curves[0]]}), "2 to 4"),
(json!({"curves": [curves[0], curves[1], extra.clone(), extra.clone(), extra.clone()]}), "2 to 4"),
(json!({"curves": [curves[0], "nope"]}), "no sketch curve"),
(json!({"curves": curves, "continuity": "g9"}), "continuity"),
(json!({"curves": curves, "continuity": ["g1", "g2", "g3"]}), "continuity"),
(json!({"curves": curves, "crown": 5}), "crown"),
(json!({"curves": curves, "crown": "full"}), "crown"),
(json!({"curves": curves, "samples": 3}), "samples"),
(json!({"curves": curves, "samples": 2.5}), "samples"),
(json!({"curves": curves, "operation": "join"}), "network"),
];
for (params, want) in cases {
let e = s.execute("surface.boundary", ¶ms).unwrap_err().to_string();
assert!(e.contains(want), "{params}: {e}");
}
// Nothing was built by any of them.
assert!(s.model.state().bodies.is_empty(), "a refused patch left a body behind");
}
}
#[cfg(test)]
#[path = "surface_boundary_tests.rs"]
mod network_tests;