Skip to content

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

OBJ export: the body colours travel with the file (#4451) (#6693)

Homero Thompson31d6873f7d83
diff --git a/crates/engine/src/cmd/file.rs b/crates/engine/src/cmd/file.rs
index 0cf82a8600..be67ca9a22 100644
--- a/crates/engine/src/cmd/file.rs
+++ b/crates/engine/src/cmd/file.rs
@@ -56,7 +56,7 @@ pub static COMMANDS: &[CommandSpec] = &[
CommandSpec::new("file.export", "Export", export)
.icon("export")
.noundo()
- .params("path; format?: stl|stla|obj|step|3mf|3mf-tagged|urdf|json (default from extension; 3mf-tagged: 3MF whose triangles carry their B-rep face, at full precision, for meshing and analysis tools; docs/formats/3mf-face-tags.md; urdf: the whole assembly as a robot, with STL meshes written next to it; docs/urdf.md); bodies?: [names] (JSON and URDF export the complete design); urdf only: mesh_prefix? (before each mesh file name, e.g. package://robot/meshes/), effort? (default 1000), velocity? (default 10); quality?: standard|fine|finest (STL, OBJ and 3MF: how closely the mesh follows curved faces, a chord tolerance of 2e-4, 5e-5 or 1e-5 of each body's size; default standard)"),
+ .params("path; format?: stl|stla|obj|step|3mf|3mf-tagged|urdf|json (default from extension; 3mf-tagged: 3MF whose triangles carry their B-rep face, at full precision, for meshing and analysis tools; docs/formats/3mf-face-tags.md; obj: the colours of the bodies go in a material library (`.mtl`) written next to the mesh file; urdf: the whole assembly as a robot, with STL meshes written next to it; docs/urdf.md); bodies?: [names] (JSON and URDF export the complete design); urdf only: mesh_prefix? (before each mesh file name, e.g. package://robot/meshes/), effort? (default 1000), velocity? (default 10); quality?: standard|fine|finest (STL, OBJ and 3MF: how closely the mesh follows curved faces, a chord tolerance of 2e-4, 5e-5 or 1e-5 of each body's size; default standard)"),
CommandSpec::new("file.save_mesh", "Save As Mesh", save_mesh)
.at("INSERT", "FILES")
.icon("mesh_export")
@@ -601,6 +601,10 @@ fn mesh_quality(p: &Value, cmd: &str) -> Result<solidcraft_io::MeshQuality> {
}
fn export_to(s: &Session, path: &str, format: Format, bodies: &[String], quality: solidcraft_io::MeshQuality) -> Result<Value> {
+ if format == Format::Obj {
+ // The colours of the bodies go in a material library beside the mesh file.
+ return export_obj(s, path, bodies, quality);
+ }
let name = std::path::Path::new(path).file_stem().map(|x| x.to_string_lossy().to_string()).unwrap_or_else(|| s.doc.name.clone());
// A design with components exports as a STEP assembly; otherwise bodies as placed.
let bytes = if format == Format::Design {
@@ -629,6 +633,32 @@ fn export(s: &mut Session, p: &Value) -> Result<Value> {
export_to(s, path, format, &string_list(p, "bodies"), quality)
}
+/// The OBJ export: the mesh file and the material library beside it, with the colours of the
+/// bodies. Every path is checked before anything is written; the library goes first and the
+/// mesh file last, so a mesh file never names a library that is not there.
+fn export_obj(s: &Session, path: &str, bodies: &[String], quality: solidcraft_io::MeshQuality) -> Result<Value> {
+ let mtl_path = std::path::Path::new(path).with_extension("mtl");
+ let mtl_name = mtl_path.file_name().map(|x| x.to_string_lossy().to_string()).unwrap_or_else(|| String::from("model.mtl"));
+ let files = solidcraft_io::export_obj(&s.doc.painted(&s.world_state()), bodies, &mtl_name, quality)?;
+ let mut targets: Vec<(String, &[u8])> = Vec::new();
+ if !files.mtl.is_empty() {
+ targets.push((mtl_path.to_string_lossy().to_string(), files.mtl.as_bytes()));
+ }
+ targets.push((path.to_string(), files.obj.as_bytes()));
+ for (t, _) in &targets {
+ solidcraft_io::vfs::check(t).map_err(|e| EngineError::Other(format!("{t}: {e}")))?;
+ }
+ let mut written: Vec<String> = Vec::new();
+ for (t, bytes) in &targets {
+ if let Err(e) = solidcraft_io::vfs::write(t, bytes) {
+ let before = if written.is_empty() { "none".to_string() } else { written.join(", ") };
+ return Err(EngineError::Other(format!("{t}: {e} (this file may be incomplete; written before it: {before})")));
+ }
+ written.push(t.clone());
+ }
+ Ok(json!({"path": path, "bytes": files.obj.len(), "format": format!("{:?}", Format::Obj), "files": written}))
+}
+
/// The assembly as a URDF and its meshes next to it (docs/urdf.md). Every path is checked before
/// anything is written; the meshes go first and the `.urdf` last.
fn export_urdf(s: &Session, path: &str, p: &Value) -> Result<Value> {
diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index 2d1b892dee..0b2625834a 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -2119,6 +2119,25 @@ fn material_and_appearance_colours_export_to_step() {
check(&step_round_trip(&mut s2, "colours2"));
}
+/// The OBJ export carries the colours of the bodies: the mesh file names a material library
+/// beside it, and the library holds a material per body.
+#[test]
+fn obj_export_writes_the_colours_of_the_bodies() {
+ let mut s = Session::default();
+ run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10, "body_name": "Red Box"}));
+ run(&mut s, "appearance.assign", json!({"bodies": ["Red Box"], "color": "#d03030"}));
+ let dir = std::env::temp_dir().join(format!("solidcraft-objcolours-{}", std::process::id()));
+ std::fs::create_dir_all(&dir).unwrap();
+ let obj = dir.join("part.obj");
+ run(&mut s, "file.export", json!({"path": obj.to_string_lossy(), "format": "obj"}));
+ let text = std::fs::read_to_string(&obj).unwrap();
+ assert!(text.contains("\nmtllib part.mtl\n"), "{text}");
+ let mtl = std::fs::read_to_string(dir.join("part.mtl")).unwrap();
+ assert!(mtl.contains("\nnewmtl Red_Box\n"), "{mtl}");
+ assert!(mtl.contains("Kd 0.816 0.188 0.188"), "{mtl}");
+ let _ = std::fs::remove_dir_all(&dir);
+}
+
/// Face appearances and see-through bodies export: STEP styles on the faces with a
/// transparency, read back as face colours.
#[test]
diff --git a/crates/io/src/lib.rs b/crates/io/src/lib.rs
index 271046f8e6..fa5a5786b2 100644
--- a/crates/io/src/lib.rs
+++ b/crates/io/src/lib.rs
@@ -459,57 +459,171 @@ pub fn stl_ascii(meshes: &[Mesh], name: &str) -> String {
s
}
-/// Wavefront OBJ, one object per body. Positions and normals are each written once per
-/// distinct value, so a face's vertices are shared while the normals keep edges between
-/// faces sharp. Names are written as they are (OBJ takes the rest of the line).
+/// A body in an OBJ export: the name it is written with, its mesh and the colour it is shown
+/// in.
+pub struct ObjBody<'a> {
+ /// The body's name, written in the `o` line.
+ pub name: &'a str,
+ /// The body's mesh.
+ pub mesh: &'a Mesh,
+ /// The colour of the body, when the design gives it one. The colours of its faces and its
+ /// transparency are not carried.
+ pub color: Option<[f32; 3]>,
+}
+
+/// The files of an OBJ export: the mesh file and the material library that goes with it.
+pub struct ObjFiles {
+ /// The mesh file.
+ pub obj: String,
+ /// The material library; empty when no body has a colour.
+ pub mtl: String,
+}
+
+/// Wavefront OBJ, one object per body, without materials.
pub fn obj(meshes: &[(String, Mesh)]) -> String {
- use std::collections::HashMap;
- let mut s = String::from("# SolidCraft OBJ export (mm)\n");
+ let bodies: Vec<ObjBody<'_>> = meshes.iter().map(|(name, mesh)| ObjBody { name: name.as_str(), mesh, color: None }).collect();
+ obj_files(&bodies, "").obj
+}
+
+/// Wavefront OBJ with the colours of the bodies: the mesh file and the material library that
+/// goes with it. `mtl_name` is the name the `mtllib` line writes (the library's file name
+/// beside the mesh file); an empty name writes no materials at all, as there is no library to
+/// name.
+///
+/// Only the colour of the body travels: the colours of single faces and the transparency of a
+/// body are left out, as a face colour needs material groups inside one object.
+///
+/// Positions and normals are each written once per distinct value, so a face's vertices are
+/// shared while the normals keep edges between faces sharp. Names are written as they are (OBJ
+/// takes the rest of the line); the material of a body takes its name with the characters a
+/// material name cannot hold replaced by an underscore.
+pub fn obj_files(bodies: &[ObjBody<'_>], mtl_name: &str) -> ObjFiles {
+ let materials = material_names(bodies);
+ let mut obj = String::from("# SolidCraft OBJ export (mm)\n");
+ let mut mtl = String::new();
+ if materials.iter().any(|m| m.is_some()) {
+ obj += &format!("mtllib {mtl_name}\n");
+ mtl = String::from("# SolidCraft material library\n");
+ }
let (mut vbase, mut nbase) = (1usize, 1usize);
- for (name, m) in meshes {
- let name: String = name.chars().map(|c| if c.is_control() { ' ' } else { c }).collect();
- s += &format!("o {name}\n");
- // `+ 0.0` turns -0 into 0, so both merge.
- let key = |x: f64, y: f64, z: f64| [x + 0.0, y + 0.0, z + 0.0].map(f64::to_bits);
- let mut vmap: HashMap<[u64; 3], usize> = HashMap::new();
- let mut nmap: HashMap<[u64; 3], usize> = HashMap::new();
- let vi: Vec<usize> = m
- .positions
- .iter()
- .map(|p| {
- let next = vmap.len();
- *vmap.entry(key(p.x, p.y, p.z)).or_insert_with(|| {
- s += &format!("v {} {} {}\n", p.x, p.y, p.z);
- next
- })
+ for (i, b) in bodies.iter().enumerate() {
+ let name: String = b.name.chars().map(|c| if c.is_control() { ' ' } else { c }).collect();
+ obj += &format!("o {name}\n");
+ if let (Some(material), Some(color)) = (materials.get(i).and_then(|m| m.as_deref()), b.color) {
+ obj += &format!("usemtl {material}\n");
+ mtl += &format!("newmtl {material}\nKd {}\n", kd(color));
+ }
+ let (text, vb, nb) = mesh_text(b.mesh, vbase, nbase);
+ obj += &text;
+ vbase = vb;
+ nbase = nb;
+ }
+ ObjFiles { obj, mtl }
+}
+
+/// The mesh of a body: its vertices and normals, each written once per distinct value, and the
+/// faces that use them. Returns the text and the bases the next body carries on from.
+fn mesh_text(mesh: &Mesh, vbase: usize, nbase: usize) -> (String, usize, usize) {
+ use std::collections::HashMap;
+ let mut s = String::new();
+ // `+ 0.0` turns -0 into 0, so both merge.
+ let key = |x: f64, y: f64, z: f64| [x + 0.0, y + 0.0, z + 0.0].map(f64::to_bits);
+ let mut vmap: HashMap<[u64; 3], usize> = HashMap::new();
+ let mut nmap: HashMap<[u64; 3], usize> = HashMap::new();
+ let vi: Vec<usize> = mesh
+ .positions
+ .iter()
+ .map(|p| {
+ let next = vmap.len();
+ *vmap.entry(key(p.x, p.y, p.z)).or_insert_with(|| {
+ s += &format!("v {} {} {}\n", p.x, p.y, p.z);
+ next
})
- .collect();
- let ni: Vec<usize> = m
- .normals
- .iter()
- .map(|n| {
- let next = nmap.len();
- *nmap.entry(key(n.x, n.y, n.z)).or_insert_with(|| {
- s += &format!("vn {} {} {}\n", n.x, n.y, n.z);
- next
- })
+ })
+ .collect();
+ let ni: Vec<usize> = mesh
+ .normals
+ .iter()
+ .map(|n| {
+ let next = nmap.len();
+ *nmap.entry(key(n.x, n.y, n.z)).or_insert_with(|| {
+ s += &format!("vn {} {} {}\n", n.x, n.y, n.z);
+ next
})
- .collect();
- for t in &m.triangles {
- let (Some(a), Some(b), Some(c)) = (vi.get(t[0] as usize), vi.get(t[1] as usize), vi.get(t[2] as usize)) else { continue };
- let (a, b, c) = (a + vbase, b + vbase, c + vbase);
- match (ni.get(t[0] as usize), ni.get(t[1] as usize), ni.get(t[2] as usize)) {
- (Some(na), Some(nb), Some(nc)) => {
- let (na, nb, nc) = (na + nbase, nb + nbase, nc + nbase);
- s += &format!("f {a}//{na} {b}//{nb} {c}//{nc}\n");
- }
- _ => s += &format!("f {a} {b} {c}\n"),
+ })
+ .collect();
+ for t in &mesh.triangles {
+ let (Some(a), Some(b), Some(c)) = (vi.get(t[0] as usize), vi.get(t[1] as usize), vi.get(t[2] as usize)) else { continue };
+ let (a, b, c) = (a + vbase, b + vbase, c + vbase);
+ match (ni.get(t[0] as usize), ni.get(t[1] as usize), ni.get(t[2] as usize)) {
+ (Some(na), Some(nb), Some(nc)) => {
+ let (na, nb, nc) = (na + nbase, nb + nbase, nc + nbase);
+ s += &format!("f {a}//{na} {b}//{nb} {c}//{nc}\n");
}
+ _ => s += &format!("f {a} {b} {c}\n"),
}
- vbase += vmap.len();
- nbase += nmap.len();
}
- s
+ (s, vbase + vmap.len(), nbase + nmap.len())
+}
+
+/// The material of each body: its name, safe to write in a material library and unique among
+/// the bodies. A body without a colour has no material.
+fn material_names(bodies: &[ObjBody<'_>]) -> Vec<Option<String>> {
+ let mut taken: std::collections::HashSet<String> = std::collections::HashSet::new();
+ let mut out: Vec<Option<String>> = Vec::with_capacity(bodies.len());
+ for b in bodies {
+ if b.color.is_none() {
+ out.push(None);
+ continue;
+ }
+ let base = safe_name(b.name);
+ let base = if base.is_empty() { String::from("body") } else { base };
+ let mut name = base.clone();
+ let mut n = 2;
+ while !taken.insert(name.clone()) {
+ name = format!("{base}_{n}");
+ n += 1;
+ }
+ out.push(Some(name));
+ }
+ out
+}
+
+/// A name a material library can hold: the body's name with every character that is not a
+/// letter, a digit or an underscore replaced by one, and the name cut short when it is longer
+/// than a material name needs to be.
+fn safe_name(name: &str) -> String {
+ name.chars().map(|c| if c.is_ascii_alphanumeric() || c == '_' { c } else { '_' }).take(64).collect()
+}
+
+/// The diffuse colour of a material: three fractions between 0 and 1, as the OBJ convention
+/// writes them.
+fn kd(color: [f32; 3]) -> String {
+ let [r, g, b] = color.map(|v| if v.is_finite() { v.clamp(0.0, 1.0) } else { 0.0 });
+ format!("{r:.3} {g:.3} {b:.3}")
+}
+
+/// The bodies of a model an export takes (all when `bodies` is empty).
+fn selected<'a>(state: &'a ModelState, bodies: &[String]) -> Result<Vec<&'a solidcraft_doc::ModelBody>> {
+ let sel: Vec<&solidcraft_doc::ModelBody> = state.bodies.iter().filter(|b| bodies.is_empty() || bodies.contains(&b.name)).collect();
+ if sel.is_empty() {
+ return Err(IoError::Empty);
+ }
+ Ok(sel)
+}
+
+/// The OBJ export of the given bodies of a model (all when `bodies` is empty): the mesh file
+/// and the material library beside it, with the colour of each body. `mtl_name` is the name
+/// the `mtllib` line writes (the library's file name beside the mesh file).
+pub fn export_obj(state: &ModelState, bodies: &[String], mtl_name: &str, quality: MeshQuality) -> Result<ObjFiles> {
+ obj_export(&selected(state, bodies)?, mtl_name, quality)
+}
+
+/// The OBJ export of the given bodies: the mesh file and the material library beside it.
+fn obj_export(sel: &[&solidcraft_doc::ModelBody], mtl_name: &str, quality: MeshQuality) -> Result<ObjFiles> {
+ let meshes: Vec<Mesh> = sel.iter().map(|b| export_mesh_at(&b.body, quality)).collect::<Result<_>>()?;
+ let bodies: Vec<ObjBody<'_>> = sel.iter().zip(&meshes).map(|(b, mesh)| ObjBody { name: b.name.as_str(), mesh, color: b.body.color() }).collect();
+ Ok(obj_files(&bodies, mtl_name))
}
/// Export the given bodies of a model (all when `bodies` is empty) in a format.
@@ -551,6 +665,10 @@ pub fn export_with_metadata(state: &ModelState, bodies: &[String], format: Forma
}
/// [`export_with_metadata`], meshing STL, OBJ and 3MF at `quality`.
+///
+/// The OBJ export of this function carries no materials: it writes one file, so it names no
+/// material library it could not write. [`export_obj`] returns the mesh file and the material
+/// library with the colours of the bodies.
pub fn export_with_quality(
state: &ModelState,
bodies: &[String],
@@ -559,10 +677,7 @@ pub fn export_with_quality(
meta: &Metadata,
quality: MeshQuality,
) -> Result<Vec<u8>> {
- let sel: Vec<&solidcraft_doc::ModelBody> = state.bodies.iter().filter(|b| bodies.is_empty() || bodies.contains(&b.name)).collect();
- if sel.is_empty() {
- return Err(IoError::Empty);
- }
+ let sel = selected(state, bodies)?;
Ok(match format {
Format::StlBinary | Format::StlAscii => {
// Each body welded on its own (as for 3MF), so shared vertices are written identically
@@ -578,6 +693,8 @@ pub fn export_with_quality(
if format == Format::StlBinary { stl_binary(&meshes, name) } else { stl_ascii(&meshes, name).into_bytes() }
}
Format::Obj => {
+ // One file, so no material library: a mesh file that names a library nobody wrote
+ // would come out in the reader's default grey.
let meshes: Vec<(String, Mesh)> = sel.iter().map(|b| Ok((b.name.clone(), export_mesh_at(&b.body, quality)?))).collect::<Result<_>>()?;
obj(&meshes).into_bytes()
}
@@ -873,6 +990,23 @@ mod tests {
assert!(ids.iter().all(|i| (1..=8).contains(i) || (1..=6).contains(i)));
}
+ /// The OBJ export carries the colours of the bodies: the mesh file names the material
+ /// library beside it and every body with a colour gets a material in it.
+ #[test]
+ fn obj_export_writes_the_colours_of_the_bodies() {
+ let (_, m) = model();
+ let mut st = (*m.state()).clone();
+ st.bodies[0].body = st.bodies[0].body.clone().with_color(Some([208.0 / 255.0, 48.0 / 255.0, 48.0 / 255.0]));
+ let files = export_obj(&st, &[], "part.mtl", MeshQuality::default()).unwrap();
+ assert!(files.obj.contains("\nmtllib part.mtl\n"), "{}", files.obj);
+ assert!(files.obj.contains("\nusemtl Body1\n"), "{}", files.obj);
+ assert!(files.mtl.contains("\nnewmtl Body1\n"), "{}", files.mtl);
+ assert!(files.mtl.contains("Kd 0.816 0.188 0.188"), "{}", files.mtl);
+ // The export that writes one file names no material library it cannot write.
+ let o = String::from_utf8(export(&st, &[], Format::Obj, "part").unwrap()).unwrap();
+ assert!(!o.contains("mtllib"), "{o}");
+ }
+
/// The design properties land in each format's own metadata (#1015): STEP and IGES headers,
/// 3MF model metadata. Other tools' keys never leave the design file.
#[test]