#![cfg(feature = "stl")]
use crate::geom3::mesh::algorithms::normals::compute_face_normal;
use crate::geom3::mesh::{MeshData3, MeshView3};
use crate::{Point3, Result};
use std::fs::File;
use std::io::{BufReader, BufWriter, Read, Seek, Write};
use std::path::Path;
pub fn load_stl_mesh_data(path: &Path) -> Result<MeshData3> {
let mut file = BufReader::new(File::open(path)?);
read_stl_mesh_data(&mut file)
}
pub fn read_stl_mesh_data<R: Read + Seek>(source: &mut R) -> Result<MeshData3> {
let raw = stl_io::read_stl(source)?;
let points = raw
.vertices
.iter()
.map(|v| Point3::new(v[0] as f64, v[1] as f64, v[2] as f64))
.collect::<Vec<_>>();
let faces = raw
.faces
.iter()
.map(|f| {
[
f.vertices[0] as u32,
f.vertices[1] as u32,
f.vertices[2] as u32,
]
})
.collect::<Vec<_>>();
MeshData3::new(points, faces)
}
#[non_exhaustive]
#[derive(Debug, Clone)]
pub struct StlWriteOpts {
pub allow_attribute_loss: bool,
pub binary: bool,
pub header: Option<String>,
}
impl Default for StlWriteOpts {
fn default() -> Self {
Self {
allow_attribute_loss: false,
binary: true,
header: None,
}
}
}
const BINARY_HEADER_LEN: usize = 80;
pub fn write_stl_mesh<'a>(
path: &Path,
mesh: impl Into<MeshView3<'a>>,
opts: &StlWriteOpts,
) -> Result<()> {
let mut file = BufWriter::new(File::create(path)?);
write_stl_to(&mut file, mesh, opts)?;
file.flush()?;
Ok(())
}
pub fn write_stl_to<'a, W: Write>(
out: &mut W,
mesh: impl Into<MeshView3<'a>>,
opts: &StlWriteOpts,
) -> Result<()> {
let mesh = mesh.into();
mesh.check_attribute_loss("STL", opts.allow_attribute_loss)?;
if mesh.face_count() > u32::MAX as usize {
return Err(format!(
"This mesh has {} faces, but the binary STL facet count is a 32 bit value",
mesh.face_count()
)
.into());
}
let header = validated_header(opts.header.as_deref())?;
if opts.binary {
write_binary(out, mesh, header)
} else {
write_ascii(out, mesh, header)
}
}
const DEFAULT_HEADER: &str = "engeom";
fn validated_header(header: Option<&str>) -> Result<&str> {
let text = header.unwrap_or("").trim_start();
let head = &text.as_bytes()[..text.len().min(5)];
if head.eq_ignore_ascii_case(b"solid") {
return Err(
"An STL header may not begin with the word 'solid', because it makes the \
file look like ascii to a naive format detector"
.into(),
);
}
if text.is_empty() {
return Ok(DEFAULT_HEADER);
}
Ok(text)
}
fn face_points(mesh: MeshView3<'_>, face: &[u32; 3]) -> [Point3; 3] {
[
mesh.points()[face[0] as usize],
mesh.points()[face[1] as usize],
mesh.points()[face[2] as usize],
]
}
fn facet_normal(p: &[Point3; 3]) -> [f32; 3] {
match compute_face_normal(p) {
Some(n) => [n.x as f32, n.y as f32, n.z as f32],
None => [0.0, 0.0, 0.0],
}
}
fn write_binary<W: Write>(out: &mut W, mesh: MeshView3<'_>, header: &str) -> Result<()> {
let mut header_bytes = [0u8; BINARY_HEADER_LEN];
let source = header.as_bytes();
let mut take = source.len().min(BINARY_HEADER_LEN);
while take > 0 && !header.is_char_boundary(take) {
take -= 1;
}
header_bytes[..take].copy_from_slice(&source[..take]);
out.write_all(&header_bytes)?;
out.write_all(&(mesh.face_count() as u32).to_le_bytes())?;
for f in mesh.faces() {
let p = face_points(mesh, f);
let n = facet_normal(&p);
for c in n.iter() {
out.write_all(&c.to_le_bytes())?;
}
for v in p.iter() {
out.write_all(&(v.x as f32).to_le_bytes())?;
out.write_all(&(v.y as f32).to_le_bytes())?;
out.write_all(&(v.z as f32).to_le_bytes())?;
}
out.write_all(&0u16.to_le_bytes())?;
}
Ok(())
}
fn write_ascii<W: Write>(out: &mut W, mesh: MeshView3<'_>, header: &str) -> Result<()> {
writeln!(out, "solid {}", header)?;
for f in mesh.faces() {
let p = face_points(mesh, f);
let n = facet_normal(&p);
writeln!(out, "facet normal {} {} {}", n[0], n[1], n[2])?;
writeln!(out, " outer loop")?;
for v in p.iter() {
writeln!(
out,
" vertex {} {} {}",
v.x as f32, v.y as f32, v.z as f32
)?;
}
writeln!(out, " endloop")?;
writeln!(out, "endfacet")?;
}
writeln!(out, "endsolid {}", header)?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::geom3::Attr3;
use crate::tests::get_test_file_path;
use crate::{UnitVec3, Vector3};
use std::io::Cursor;
fn simple() -> MeshData3 {
MeshData3::new(
vec![
Point3::new(0.0, 0.0, 0.0),
Point3::new(1.0, 0.0, 0.0),
Point3::new(1.0, 2.0, 0.0),
Point3::new(0.0, 2.0, 0.5),
],
vec![[0, 1, 2], [0, 2, 3]],
)
.unwrap()
}
fn round_trip(mesh: &MeshData3, opts: &StlWriteOpts) -> Result<MeshData3> {
let mut buf = Vec::new();
write_stl_to(&mut buf, mesh, opts)?;
read_stl_mesh_data(&mut Cursor::new(buf))
}
fn triangle_set(mesh: &MeshData3) -> Vec<[[u32; 3]; 3]> {
let mut out = mesh
.faces()
.iter()
.map(|f| {
let mut corners = face_points(mesh.view(), f).map(|p| {
[
(p.x as f32).to_bits(),
(p.y as f32).to_bits(),
(p.z as f32).to_bits(),
]
});
corners.sort();
corners
})
.collect::<Vec<_>>();
out.sort();
out
}
#[test]
fn a_mesh_round_trips_through_the_binary_encoding() -> Result<()> {
let mesh = simple();
let back = round_trip(&mesh, &StlWriteOpts::default())?;
assert_eq!(back.face_count(), mesh.face_count());
assert_eq!(back.point_count(), mesh.point_count());
assert_eq!(triangle_set(&back), triangle_set(&mesh));
Ok(())
}
#[test]
fn a_mesh_round_trips_through_the_ascii_encoding() -> Result<()> {
let mesh = simple();
let opts = StlWriteOpts {
binary: false,
..Default::default()
};
let back = round_trip(&mesh, &opts)?;
assert_eq!(back.face_count(), mesh.face_count());
assert_eq!(triangle_set(&back), triangle_set(&mesh));
Ok(())
}
#[test]
fn the_two_encodings_agree() -> Result<()> {
let mesh = load_ply_fixture()?;
let binary = round_trip(
&mesh,
&StlWriteOpts {
allow_attribute_loss: true,
..Default::default()
},
)?;
let ascii = round_trip(
&mesh,
&StlWriteOpts {
binary: false,
allow_attribute_loss: true,
..Default::default()
},
)?;
assert_eq!(binary.point_count(), ascii.point_count());
assert_eq!(binary.face_count(), ascii.face_count());
assert_eq!(triangle_set(&binary), triangle_set(&ascii));
Ok(())
}
fn load_ply_fixture() -> Result<MeshData3> {
crate::io::load_ply_mesh_data(&get_test_file_path("bun_zipper_res4.ply"))
}
#[test]
fn a_real_mesh_round_trips_with_its_topology_intact() -> Result<()> {
let mesh = load_ply_fixture()?;
assert_eq!(mesh.point_count(), 453);
assert_eq!(mesh.face_count(), 948);
let back = round_trip(
&mesh,
&StlWriteOpts {
allow_attribute_loss: true,
..Default::default()
},
)?;
assert_eq!(back.point_count(), 453);
assert_eq!(back.face_count(), 948);
assert_eq!(triangle_set(&back), triangle_set(&mesh));
assert!(!back.has_attrs());
Ok(())
}
#[test]
fn a_mesh_with_attributes_is_refused_by_default() {
let mut mesh = simple();
mesh.set_point_stdev(Some(vec![0.01, 0.02, 0.03, 0.04]))
.unwrap();
let mut buf = Vec::new();
let err = write_stl_to(&mut buf, &mesh, &StlWriteOpts::default())
.expect_err("writing a mesh with attributes must fail by default");
let message = err.to_string();
assert!(message.contains("point_stdev"), "message was: {}", message);
assert!(message.contains("allow_attribute_loss"));
assert!(buf.is_empty());
}
#[test]
fn the_refusal_names_every_attribute_that_would_be_lost() {
let mut mesh = simple();
mesh.set_point_normals(Some(vec![UnitVec3::new_normalize(Vector3::z()); 4]))
.unwrap();
mesh.set_face_labels(Some(vec![7, 9])).unwrap();
mesh.insert_point_attr("intensity", Attr3::Scalar(vec![1.0, 2.0, 3.0, 4.0]))
.unwrap();
let mut buf = Vec::new();
let message = write_stl_to(&mut buf, &mesh, &StlWriteOpts::default())
.expect_err("must fail")
.to_string();
for name in ["point_normals", "face_labels", "intensity"] {
assert!(message.contains(name), "{} missing from: {}", name, message);
}
}
#[test]
fn accepting_the_loss_writes_the_geometry() -> Result<()> {
let mut mesh = simple();
mesh.set_point_stdev(Some(vec![0.01, 0.02, 0.03, 0.04]))?;
let back = round_trip(
&mesh,
&StlWriteOpts {
allow_attribute_loss: true,
..Default::default()
},
)?;
assert_eq!(triangle_set(&back), triangle_set(&mesh));
assert!(back.point_stdev().is_none());
Ok(())
}
#[test]
fn a_mesh_with_no_attributes_needs_no_flag() -> Result<()> {
let mut buf = Vec::new();
write_stl_to(&mut buf, &simple(), &StlWriteOpts::default())?;
assert!(!buf.is_empty());
Ok(())
}
#[test]
fn a_degenerate_face_is_written_rather_than_skipped() -> Result<()> {
let mesh = MeshData3::new(
vec![
Point3::new(0.0, 0.0, 0.0),
Point3::new(1.0, 0.0, 0.0),
Point3::new(2.0, 0.0, 0.0), Point3::new(0.0, 1.0, 0.0),
],
vec![[0, 1, 2], [0, 1, 3]],
)?;
let mut buf = Vec::new();
write_stl_to(&mut buf, &mesh, &StlWriteOpts::default())?;
assert_eq!(buf.len(), 80 + 4 + 50 * 2);
assert_eq!(u32::from_le_bytes(buf[80..84].try_into().unwrap()), 2);
let normal = &buf[84..96];
assert!(normal.iter().all(|b| *b == 0));
Ok(())
}
#[test]
fn the_header_is_written_into_the_binary_file() -> Result<()> {
let opts = StlWriteOpts {
header: Some("engeom test part".to_string()),
..Default::default()
};
let mut buf = Vec::new();
write_stl_to(&mut buf, &simple(), &opts)?;
assert_eq!(&buf[..16], b"engeom test part");
assert!(buf[16..80].iter().all(|b| *b == 0));
Ok(())
}
#[test]
fn a_default_header_is_written_when_none_is_given() -> Result<()> {
let mut binary = Vec::new();
write_stl_to(&mut binary, &simple(), &StlWriteOpts::default())?;
assert_eq!(&binary[..6], b"engeom");
let mut ascii = Vec::new();
write_stl_to(
&mut ascii,
&simple(),
&StlWriteOpts {
binary: false,
..Default::default()
},
)?;
assert!(String::from_utf8(ascii)?.starts_with("solid engeom\n"));
Ok(())
}
#[test]
fn the_header_becomes_the_solid_name_in_ascii() -> Result<()> {
let opts = StlWriteOpts {
binary: false,
header: Some("engeom test part".to_string()),
..Default::default()
};
let mut buf = Vec::new();
write_stl_to(&mut buf, &simple(), &opts)?;
let text = String::from_utf8(buf)?;
assert!(text.starts_with("solid engeom test part\n"));
assert!(text.trim_end().ends_with("endsolid engeom test part"));
Ok(())
}
#[test]
fn a_header_beginning_with_solid_is_refused() {
for header in ["solid part", "SOLID PART", " solid part"] {
let opts = StlWriteOpts {
header: Some(header.to_string()),
..Default::default()
};
let mut buf = Vec::new();
assert!(
write_stl_to(&mut buf, &simple(), &opts).is_err(),
"header {:?} should have been refused",
header
);
}
let opts = StlWriteOpts {
header: Some("a solid part".to_string()),
..Default::default()
};
let mut buf = Vec::new();
assert!(write_stl_to(&mut buf, &simple(), &opts).is_ok());
}
#[test]
fn an_oversized_header_is_truncated_on_a_character_boundary() -> Result<()> {
let opts = StlWriteOpts {
header: Some(format!("x{}", "😀".repeat(26))),
..Default::default()
};
let mut buf = Vec::new();
write_stl_to(&mut buf, &simple(), &opts)?;
assert_eq!(buf.len(), 80 + 4 + 50 * 2);
let header = std::str::from_utf8(&buf[..80]).expect("the header must remain valid utf8");
let text = header.trim_end_matches('\0');
assert_eq!(text.chars().count(), 20);
assert_eq!(text.len(), 77);
Ok(())
}
#[test]
fn reading_welds_the_triangle_soup() -> Result<()> {
let mesh = simple();
assert_eq!(mesh.point_count(), 4);
let back = round_trip(&mesh, &StlWriteOpts::default())?;
assert_eq!(back.point_count(), 4);
assert_eq!(back.face_count(), 2);
Ok(())
}
#[test]
fn coordinates_are_quantized_to_f32() -> Result<()> {
let exact = 1_000.000_03_f64;
let mesh = MeshData3::new(
vec![
Point3::new(exact, 0.0, 0.0),
Point3::new(exact + 1.0, 0.0, 0.0),
Point3::new(exact, 1.0, 0.0),
],
vec![[0, 1, 2]],
)?;
let back = round_trip(&mesh, &StlWriteOpts::default())?;
let recovered = back.points().iter().map(|p| p.x).fold(f64::MAX, f64::min);
assert_ne!(recovered, exact);
assert_eq!(recovered, exact as f32 as f64);
let step = 1000.0_f32.to_bits() + 1;
let step = f32::from_bits(step) as f64 - 1000.0;
assert!((recovered - exact).abs() > step * 0.4);
assert!((recovered - exact).abs() <= step * 0.5);
Ok(())
}
#[test]
fn either_container_writes_identical_bytes() -> Result<()> {
let data = simple();
let mesh = crate::Mesh3::from_data(data.clone(), false)?;
for binary in [true, false] {
let opts = StlWriteOpts {
binary,
..Default::default()
};
let mut from_data = Vec::new();
write_stl_to(&mut from_data, &data, &opts)?;
let mut from_mesh = Vec::new();
write_stl_to(&mut from_mesh, &mesh, &opts)?;
assert_eq!(from_data, from_mesh, "binary = {binary}");
}
Ok(())
}
}