Modules | C++
I/O
File I/O operations for reading and writing mesh data.
The I/O module provides functions for reading and writing mesh data in STL format (both ASCII and binary) and OBJ format (ASCII).
Include the module with:
#include <trueform/io.hpp>
Reading
STL Files
Read an STL file and return triangular polygons:
#include <trueform/io.hpp>
// Read with int32 indices
auto polygons = tf::read_stl<int>("model.stl");
// Returns: tf::polygons_buffer<int, float, 3, 3>
// Access polygon data
auto faces = polygons.faces(); // (N, 3) connectivity
auto points = polygons.points(); // (M, 3) vertex positions
// For large meshes (> 2 billion vertices), use int64_t
auto large_polygons = tf::read_stl<int64_t>("large_model.stl");
Features:
- Automatically detects binary vs ASCII format
- Deduplicates vertices during loading via
tf::clean::polygon_soup - Returns 3D triangular polygons with float coordinates
OBJ Files
Read an OBJ file and return polygons:
#include <trueform/io.hpp>
// Read triangular mesh with int32 indices
auto triangles = tf::read_obj<int, 3>("model.obj");
// triangles: tf::polygons_buffer<int, float, 3, 3>
// Read quad mesh
auto quads = tf::read_obj<int, 4>("quad_model.obj");
// quads: tf::polygons_buffer<int, float, 3, 4>
// Read with dynamic ngon (for mixed or unknown face sizes)
auto dynamic_mesh = tf::read_obj<int>("model.obj");
// dynamic_mesh: tf::polygons_buffer<int, float, 3, tf::dynamic_size>
// Access polygon data
auto faces = triangles.faces(); // (N, 3) connectivity
auto points = triangles.points(); // (M, 3) vertex positions
// For large meshes (> 2 billion vertices), use int64_t
auto large_triangles = tf::read_obj<int64_t, 3>("large_model.obj");
// large_triangles: tf::polygons_buffer<int64_t, float, 3, 3>
Features:
- Reads ASCII OBJ format
- Converts 1-based OBJ indices to 0-based
- Only reads vertex positions (ignores normals and texture coordinates)
- Returns 3D polygons with float coordinates
Writing
STL Files
Write polygons to binary STL format:
#include <trueform/io.hpp>
// Write polygons to file (.stl extension auto-appended if missing)
auto polygons = tf::read_stl<int>("input.stl");
bool success = tf::write_stl(polygons, "output.stl");
Requirements:
- Must be 3D triangular polygons
- Normals are written if available, otherwise zero normals are used
With transformations:
#include <trueform/core.hpp>
// Create transformation matrix
auto frame = tf::random_frame<float, 3>();
tf::write_stl(polygons | tf::tag(frame), "translated.stl");
// Or inline
tf::write_stl(polygons | tf::tag(tf::make_frame(transform)), "translated.stl");
Performance: Files < 500MB use parallel buffered writing, files ≥ 500MB use sequential streaming.
OBJ Files
Write polygons to ASCII OBJ format:
#include <trueform/io.hpp>
// Write triangular mesh (.obj extension auto-appended if missing)
auto triangles = tf::read_obj<int, 3>("input.obj");
bool success = tf::write_obj(triangles, "output.obj");
// Write quad mesh
auto quads = tf::read_obj<int, 4>("quad_input.obj");
tf::write_obj(quads, "quad_output.obj");
With transformations:
#include <trueform/core.hpp>
// Create transformation matrix
auto frame = tf::random_frame<float, 3>();
tf::write_obj(triangles | tf::tag(frame), "translated.obj");
For Python bindings, see the Python I/O documentation.