Skip to content

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

Command line: run --out exports meshes at a chosen quality with --quality fine or finest (#12270) (#12386)

Ahmad Khanb5a5412d486a
diff --git a/apps/solidcraft-cli/src/main.rs b/apps/solidcraft-cli/src/main.rs
index 676caf1072..2e168007db 100644
--- a/apps/solidcraft-cli/src/main.rs
+++ b/apps/solidcraft-cli/src/main.rs
@@ -62,7 +62,7 @@ struct Command {
}
/// `run`'s lines in the usage.
-const USAGE_RUN: &str = " solidcraft-cli run <script.json|design.sc|part.step> [--in design.sc|part.step] [--out FILE]... [--save FILE] [--quiet] [--results] [--timings] [--profile] [--profile-out trace.json] [--json-out FILE] [--allow-errors] [--validation each_step|each_feature|off]\n [--param-check off|warn|strict]\n solidcraft-cli run --in <design.sc|part.step> [--out FILE]...\n (a timeline feature that fails fails the run and nothing is written; --allow-errors writes anyway)\n (--validation: when SMLib's full check runs on the features computed (diagnostics.validation), default each_feature)\n (--param-check checks each step against its command's contract: warn reports on stderr, strict stops the run)\n (--timings prints {timings: [{index, command, ms}], total_ms} for a script, with --results its results too;\n --profile adds each command's profile: {boolean_ms, tessellate_ms, other_ms}, the kernel's share)\n (--profile also records where the time goes, SMLib's calls, kernel operations, features, commands and import stages,\n and prints the table to stderr: count, total, self time and longest per span; --profile-out FILE writes the spans\n as a Chrome trace for chrome://tracing or ui.perfetto.dev; SOLIDCRAFT_PROFILE=1 does the same for any command)\n";
+const USAGE_RUN: &str = " solidcraft-cli run <script.json|design.sc|part.step> [--in design.sc|part.step] [--out FILE]... [--save FILE] [--quiet] [--results] [--timings] [--profile] [--profile-out trace.json] [--json-out FILE] [--allow-errors] [--validation each_step|each_feature|off]\n [--param-check off|warn|strict] [--quality standard|fine|finest]\n solidcraft-cli run --in <design.sc|part.step> [--out FILE]...\n (a timeline feature that fails fails the run and nothing is written; --allow-errors writes anyway)\n (--quality: how closely an STL, OBJ or 3MF --out follows curved faces, as file.export's quality: a chord of\n 2e-4, 5e-5 or 1e-5 of each body's size, never under 1 µm, default standard)\n (--validation: when SMLib's full check runs on the features computed (diagnostics.validation), default each_feature)\n (--param-check checks each step against its command's contract: warn reports on stderr, strict stops the run)\n (--timings prints {timings: [{index, command, ms}], total_ms} for a script, with --results its results too;\n --profile adds each command's profile: {boolean_ms, tessellate_ms, other_ms}, the kernel's share)\n (--profile also records where the time goes, SMLib's calls, kernel operations, features, commands and import stages,\n and prints the table to stderr: count, total, self time and longest per span; --profile-out FILE writes the spans\n as a Chrome trace for chrome://tracing or ui.perfetto.dev; SOLIDCRAFT_PROFILE=1 does the same for any command)\n";
/// `eval`'s lines in the usage.
const USAGE_EVAL: &str = " solidcraft-cli eval <script.json|design.sc|part.step> [--in design.sc|part.step] [--json-out FILE] [--profile] [--profile-out trace.json] [--validation each_step|each_feature|off] (alias: inspect)\n solidcraft-cli eval --in <script.json|design.sc|part.step> [--json-out FILE]\n (with both inputs, runs the positional script on --in before measuring; does not automatically save the modified design)\n (--json-out FILE writes the JSON that run (with --results, else the measurement) and eval print to FILE instead of stdout,\n as plain UTF-8: a shell's > can re-encode it, e.g. Windows PowerShell adds a byte-order mark)\n (--profile, --profile-out and --validation as for run)\n";
/// `script`'s lines in the usage.
@@ -451,11 +451,12 @@ fn cmd_run(args: &[String]) -> Result<(), String> {
known_args(
"run",
args,
- &["--in", "--out", "--save", "--json-out", "--param-check", "--profile-out", "--validation"],
+ &["--in", "--out", "--save", "--json-out", "--param-check", "--profile-out", "--validation", "--quality"],
&["--quiet", "--results", "--timings", "--profile", "--allow-errors"],
true,
)?;
let validation = validation_flag("run", args)?;
+ let quality = export_quality("run", args)?;
let base = flag(args, "--in");
let path = positional(args);
if path.is_none() && base.is_none() {
@@ -503,7 +504,11 @@ fn cmd_run(args: &[String]) -> Result<(), String> {
timeline_ok(&s, flags(args, "--out").is_empty())?;
}
for out in flags(args, "--out") {
- s.execute("file.export", &json!({"path": out})).map_err(|e| e.to_string())?;
+ let mut params = json!({"path": out});
+ if let Some(q) = quality {
+ params["quality"] = json!(q);
+ }
+ s.execute("file.export", &params).map_err(|e| e.to_string())?;
}
if let Some(p) = flag(args, "--save") {
s.execute("file.save_as", &json!({"path": p})).map_err(|e| e.to_string())?;
@@ -544,6 +549,20 @@ fn open_validating(
}
}
+/// `--quality standard|fine|finest`: how closely the meshes `--out` writes (STL, OBJ, 3MF)
+/// follow curved faces, as `file.export`'s `quality` (#12270). Checked before anything runs;
+/// given twice it is refused, since only one quality can apply.
+fn export_quality<'a>(cmd: &str, args: &'a [String]) -> Result<Option<&'a str>, String> {
+ if flags(args, "--quality").len() > 1 {
+ return Err(format!("{cmd}: --quality is given more than once"));
+ }
+ match flag(args, "--quality") {
+ Some(q) if solidcraft_engine::io::MeshQuality::from_name(q).is_some() => Ok(Some(q)),
+ Some(q) => Err(format!("{cmd}: --quality must be standard, fine or finest, not `{q}`")),
+ None => Ok(None),
+ }
+}
+
/// `--validation MODE` (`diagnostics.validation`): the default, each_feature, when not given.
fn validation_flag(cmd: &str, args: &[String]) -> Result<solidcraft_engine::kernel::Validation, String> {
match flag(args, "--validation") {
diff --git a/apps/solidcraft-cli/tests/run_results.rs b/apps/solidcraft-cli/tests/run_results.rs
index 797af68e0c..88d7415e5f 100644
--- a/apps/solidcraft-cli/tests/run_results.rs
+++ b/apps/solidcraft-cli/tests/run_results.rs
@@ -67,6 +67,9 @@ fn run_rejects_invalid_options_before_script_execution_or_output_writes() {
(&["--out", "--quiet"][..], "--out needs a value"),
(&["--ouut", "part.step"][..], "doesn't take --ouut"),
(&["--unknown"][..], "doesn't take --unknown"),
+ (&["--quality"][..], "--quality needs a value"),
+ (&["--quality", "best"][..], "--quality must be standard, fine or finest, not `best`"),
+ (&["--quality", "standard", "--quality", "best"][..], "--quality is given more than once"),
];
for existing in [false, true] {
let saved = dir.0.join(format!("{existing}.solidcraft"));
@@ -288,6 +291,38 @@ fn results_still_save_and_export_the_script_once() {
}
}
+/// The triangles of a binary STL: the count after its 80-byte header.
+fn stl_triangles(path: &Path) -> u32 {
+ let bytes = std::fs::read(path).unwrap();
+ u32::from_le_bytes(bytes[80..84].try_into().unwrap())
+}
+
+/// #12270: `run --out part.stl --quality fine` writes the mesh at that quality, as
+/// `file.export`'s `quality` does, without a script to say so.
+#[test]
+fn run_exports_meshes_at_the_quality_asked_for() {
+ let dir = Scratch::new();
+ let script = dir.0.join("cylinder.json");
+ std::fs::write(&script, json!({"commands": [{"command": "solid.cylinder", "params": {"diameter": 40, "height": 10}}]}).to_string()).unwrap();
+ let export = |name: &str, quality: Option<&str>| {
+ let stl = dir.0.join(name);
+ let mut command = cli();
+ command.arg("run").arg(&script).arg("--quiet").arg("--out").arg(&stl);
+ if let Some(q) = quality {
+ command.args(["--quality", q]);
+ }
+ let output = command.output().unwrap();
+ assert!(output.status.success(), "{quality:?}: {}", String::from_utf8_lossy(&output.stderr));
+ stl_triangles(&stl)
+ };
+ let default = export("default.stl", None);
+ let standard = export("standard.stl", Some("standard"));
+ let fine = export("fine.stl", Some("fine"));
+ let finest = export("finest.stl", Some("finest"));
+ assert_eq!(default, standard);
+ assert!(standard < fine && fine < finest, "standard {standard}, fine {fine}, finest {finest}");
+}
+
#[test]
fn results_with_base_design_and_quiet_still_report_and_save() {
let dir = Scratch::new();
diff --git a/docs/book/src/guide/getting-started.md b/docs/book/src/guide/getting-started.md
index 4934a6fa2b..a3c8d9e3b4 100644
--- a/docs/book/src/guide/getting-started.md
+++ b/docs/book/src/guide/getting-started.md
@@ -352,6 +352,15 @@ rebuilds it; `run` then exits with status 1, lists the failing features and writ
its `--out` and `--save` files, because the bodies lack what those features should have made.
`--allow-errors` writes them anyway.
+`--quality standard|fine|finest` sets how closely an STL, OBJ or 3MF written by `--out`
+follows curved faces, as `file.export`'s `quality` does: a chord tolerance of 2e-4, 5e-5 or
+1e-5 of each body's size, though never under 1 µm, so on a small body `fine` and `finest`
+can come out the same. The default is `standard`.
+
+```sh
+solidcraft-cli run --in part.sc --out part.stl --quality fine
+```
+
`--param-check warn|strict` checks each step against its command's parameter contract, for the
commands that have one (`describe_command` in the MCP server shows them); the default, `off`,
checks nothing. A misspelt optional key, such as `operaton` for `solid.box`'s `operation`, is