threecrate-io 0.5.0

I/O operations for point clouds and meshes in threecrate
Documentation

ThreeCrate I/O

Crates.io Documentation License

File I/O operations for point clouds and meshes in the threecrate ecosystem.

Features

  • Point Cloud Formats: PLY, PCD, LAS, LAZ, XYZ/CSV file support
  • Mesh Formats: OBJ, PLY file support with normals and textures
  • Memory-Mapped I/O: High-performance reading of large binary files (optional)
  • Streaming I/O: Memory-efficient reading and writing
  • Error Handling: Comprehensive error reporting for invalid files
  • Cross-platform: Works on Windows, macOS, and Linux
  • OS-Gated Features: Platform-specific optimizations with automatic fallback

Supported Formats

Point Clouds

  • PLY: Polygon File Format (ASCII and binary)
  • PCD: Point Cloud Data format (ASCII and binary)
  • LAS/LAZ: LiDAR data formats via Pasture
  • XYZ/CSV: Comma-separated values with configurable columns

Meshes

  • OBJ: Wavefront OBJ format with materials
  • PLY: Triangle meshes in PLY format

Usage

Add this to your Cargo.toml:

[dependencies]
threecrate-io = "0.1.0"
threecrate-core = "0.1.0"

Optional Features

  • las_laz: Enable LAS/LAZ format support via Pasture
  • io-mmap: Enable memory-mapped I/O for improved performance on large binary files
[dependencies]
threecrate-io = { version = "0.1.0", features = ["io-mmap"] }

Examples

Basic Usage

use threecrate_io::{read_point_cloud, write_point_cloud, read_mesh};
use threecrate_core::{PointCloud, Point3f};

// Auto-detect format and load point cloud
let cloud = read_point_cloud("input.ply")?;
println!("Loaded {} points", cloud.len());

// Save point cloud (format determined by extension)
write_point_cloud(&cloud, "output.pcd")?;

// Load mesh from OBJ file
let mesh = read_mesh("model.obj")?;
println!("Loaded mesh with {} vertices", mesh.vertices.len());

Memory-Mapped I/O (io-mmap feature)

For large binary files, enable memory-mapped I/O for better performance:

use threecrate_io::{RobustPlyReader, RobustPcdReader};

// Memory mapping is automatically used for large binary files
// when the io-mmap feature is enabled
let ply_data = RobustPlyReader::read_ply_file("large_cloud.ply")?;
let (header, points) = RobustPcdReader::read_pcd_file("large_cloud.pcd")?;

// Check if memory mapping would be used
#[cfg(feature = "io-mmap")]
{
    let would_use_mmap = threecrate_io::mmap::should_use_mmap("large_cloud.ply");
    println!("Would use memory mapping: {}", would_use_mmap);
}

Benchmarking

Compare performance between memory-mapped and standard I/O:

# Run benchmarks (requires io-mmap feature)
cargo bench --features io-mmap mmap_benchmarks

# Run the memory mapping example
cargo run --example mmap_example --features io-mmap

License

This project is licensed under either of

at your option.