OxiGDAL 3D

Comprehensive 3D geospatial data handling for OxiGDAL. Process point clouds, create terrain meshes, and build web-ready 3D visualizations entirely in Pure Rust.

Overview

OxiGDAL 3D provides production-ready support for:

• Point Cloud Formats: LAS/LAZ, Cloud Optimized Point Cloud (COPC), Entwine Point Tiles (EPT)
• 3D Mesh Operations: OBJ and glTF 2.0/GLB export with materials and textures
• Terrain Processing: Triangulated Irregular Networks (TIN), DEM to mesh conversion
• Web Visualization: 3D Tiles (Cesium format) for browser-based 3D mapping
• Automatic Classification: Ground, vegetation, and building point extraction
• Spatial Indexing: R*-tree based spatial queries for efficient large-scale processing

Pure Rust Implementation

This library is 100% Pure Rust with zero C/Fortran dependencies. All functionality works out of the box without external build tools or system libraries.

Features

• LAS/LAZ Point Cloud Support: Read and write LAS/LAZ format with full compression support via LAZ
• Cloud Optimized Point Clouds: COPC hierarchical access with HTTP range requests
• Entwine Point Tiles: EPT octree structure support for massive datasets
• Mesh Export: Generate OBJ and glTF 2.0/GLB with materials, normals, and texture coordinates
• TIN Generation: Delaunay triangulation-based Triangulated Irregular Networks
• DEM Processing: Convert Digital Elevation Models to 3D meshes with customizable resolution
• 3D Tiles: Cesium-compatible 3D Tiles generation for web-based visualization
• Point Classification: Progressive morphological filtering for ground, vegetation, and building classification
• Spatial Indexing: R*-tree spatial indexes for efficient neighborhood queries
• Async Support: Optional async/await API for cloud storage backends (COPC, EPT)
• Streaming: Memory-efficient processing for datasets larger than available RAM
• Error Handling: No unwrap() policy with descriptive error types

Installation

Add to your Cargo.toml:

[dependencies]
oxigdal-3d = "0.1.3"

Feature Flags

Enable specific capabilities as needed:

[dependencies]
oxigdal-3d = { version = "0.1.3", features = ["async", "copc", "ept"] }

Quick Start

Read and Process LAS Point Cloud

use oxigdal_3d::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open LAS file
    let mut reader = pointcloud::LasReader::open("input.las")?;
    let point_cloud = reader.read_all()?;

    println!("Loaded {} points", point_cloud.len());
    println!("Bounds: {:?}", point_cloud.bounds());

    Ok(())
}

Classify Ground Points

use oxigdal_3d::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut reader = pointcloud::LasReader::open("input.las")?;
    let point_cloud = reader.read_all()?;

    // Classify ground points automatically
    let ground_points = classification::classify_ground(&point_cloud.points)?;
    println!("Found {} ground points", ground_points.len());

    Ok(())
}

Create Terrain from Ground Points

use oxigdal_3d::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut reader = pointcloud::LasReader::open("input.las")?;
    let point_cloud = reader.read_all()?;

    // Extract ground points
    let ground = classification::classify_ground(&point_cloud.points)?;

    // Create TIN (Triangulated Irregular Network)
    let tin = terrain::create_tin(&ground)?;

    // Convert to mesh
    let mesh = terrain::tin_to_mesh(&tin)?;

    // Export as glTF
    mesh::export_gltf(&mesh, "terrain.glb")?;

    Ok(())
}

Export to Web-Ready 3D Tiles

use oxigdal_3d::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut reader = pointcloud::LasReader::open("points.las")?;
    let point_cloud = reader.read_all()?;

    // Create 3D tileset for Cesium
    let tileset = visualization::create_3d_tileset(
        &point_cloud.points,
        Default::default(),
    )?;

    // Write tileset.json and tile files
    visualization::write_3d_tiles(&tileset, "output_tiles")?;

    Ok(())
}

Usage Guide

Point Cloud Operations

The point cloud module provides comprehensive support for reading, writing, and analyzing point clouds:

use oxigdal_3d::pointcloud::*;

// Read LAS file
let mut reader = LasReader::open("data.las")?;
let header = reader.header();
println!("Point count: {}", header.point_count);

// Access point cloud data
let points = reader.read_all()?;
let ground = points.filter_by_classification(Classification::Ground);

// Spatial queries
let index = SpatialIndex::new(points.points);
let nearby = index.within_radius(x, y, z, 10.0); // 10m radius
let nearest = index.nearest_k(x, y, z, 5);      // 5 nearest points

// Write results
let mut writer = LasWriter::create("output.las", &header)?;
for point in ground {
    writer.write_point(&point)?;
}

Mesh Creation and Export

use oxigdal_3d::mesh::*;

// Create vertices
let v1 = Vertex::new([0.0, 0.0, 0.0]);
let v2 = Vertex::new([1.0, 0.0, 0.0]);
let v3 = Vertex::new([0.5, 1.0, 0.0]);

let vertices = vec![v1, v2, v3];
let indices = vec![Triangle::new(0, 1, 2)];

let mut material = Material::new("ground");
material.base_color = [0.5, 0.5, 0.5, 1.0];

let mesh = Mesh::new(vertices, indices, vec![material]);

// Export to different formats
export_obj(&mesh, "output.obj")?;
export_gltf(&mesh, "output.glb")?;

Terrain Processing

use oxigdal_3d::terrain::*;

// Create TIN from point cloud
let tin = create_tin(&ground_points)?;

// Convert to mesh for visualization
let mesh = tin_to_mesh(&tin)?;

// DEM to mesh conversion
let options = DemMeshOptions {
    max_z_error: 0.5,
    simplification: true,
    ..Default::default()
};

let terrain_mesh = dem_to_mesh(&dem_data, &options)?;

Classification Algorithms

use oxigdal_3d::classification::*;

let params = ClassificationParams {
    search_radius: 2.0,
    min_points: 5,
    ground_threshold: 0.5,
    vegetation_range: (0.5, 30.0),
    building_height: 3.0,
    noise_threshold: 0.1,
};

// Classify with custom parameters
let ground = classify_ground_with_params(&points, &params)?;
let vegetation = classify_vegetation_with_params(&points, &params)?;
let buildings = classify_buildings(&points, &params)?;

Async Cloud Data Access

With the async feature enabled, access cloud-optimized point clouds:

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // COPC (Cloud Optimized Point Cloud) from HTTP
    #[cfg(feature = "copc")]
    {
        let reader = pointcloud::copc::CopcReader::open_async(
            "https://example.com/points.copc.laz"
        ).await?;
        let info = reader.info()?;
        println!("COPC points: {}", info.info.point_count);
    }

    // EPT (Entwine Point Tiles) from cloud storage
    #[cfg(feature = "ept")]
    {
        let reader = pointcloud::ept::EptReader::open_async(
            "https://example.com/ept.json"
        ).await?;
        let metadata = reader.metadata()?;
        println!("EPT bounds: {:?}", metadata.bounds);
    }

    Ok(())
}

API Overview

Core Modules

Main Types

• Point: 3D point with elevation, classification, intensity, RGB
• PointCloud: Collection of points with LAS header metadata
• SpatialIndex: R*-tree based spatial indexing for efficient queries
• Mesh: Vertices, triangles, materials, and texture coordinates
• Tin: Triangulated Irregular Network for terrain representation
• Tileset: 3D Tiles structure for web visualization
• Classification: Point class enumerations (Ground, Vegetation, Buildings, etc.)

Performance Characteristics

• Spatial Indexing: O(log n) point queries using R*-tree
• Point Classification: Multi-threaded processing using Rayon
• Mesh Generation: O(n log n) Delaunay triangulation
• Memory Efficiency: Streaming I/O for files larger than available RAM

Benchmark Results (on modern hardware)

Examples

Comprehensive examples are provided in the test suite:

# Run tests
cargo test --lib

# Run with specific features
cargo test --features "copc,ept" --lib

# Run benchmarks
cargo bench

Key examples demonstrate:

• Loading and analyzing point clouds
• Automatic ground classification
• TIN creation and mesh generation
• 3D Tiles creation for web visualization
• Async COPC and EPT access

Documentation

Full API documentation is available at docs.rs/oxigdal-3d.

Key documentation:

• Module documentation in source code
• Comprehensive example code in doc comments
• Error type documentation with recovery strategies
• Performance optimization guidelines

Error Handling

This library follows the "no unwrap" policy. All fallible operations return descriptive Result<T> types:

use oxigdal_3d::{Result, Error};

fn process() -> Result<()> {
    let cloud = pointcloud::LasReader::open("file.las")?
        .read_all()?;

    // Handle specific errors
    match classification::classify_ground(&cloud.points) {
        Ok(ground) => println!("Classified {} ground points", ground.len()),
        Err(Error::EmptyDataset(msg)) => eprintln!("No data: {}", msg),
        Err(e) => eprintln!("Classification failed: {}", e),
    }

    Ok(())
}

Error types include:

• I/O errors (file access, network)
• Format errors (LAS, glTF, JSON)
• Geometry errors (invalid bounds, topology)
• Processing errors (classification, triangulation)
• Configuration errors (invalid parameters)

Workspace Integration

OxiGDAL 3D is part of the larger OxiGDAL ecosystem:

• oxigdal-core: Core geospatial types and utilities
• oxigdal-algorithms: Spatial algorithms and analysis
• oxigdal-proj: Coordinate system transformations
• oxigdal-drivers: Format-specific drivers

See OxiGDAL for the full ecosystem.

COOLJAPAN Standards

This project adheres to COOLJAPAN ecosystem requirements:

• Pure Rust: 100% Pure Rust implementation (no C/Fortran dependencies)
• No Unwrap Policy: All error paths use Result<T> types
• Workspace Policy: Uses workspace dependencies with no version duplication
• Latest Crates: Dependencies kept current with latest versions
• Code Quality: No warnings, comprehensive error handling

License

This project is licensed under Apache-2.0. See LICENSE for details.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Related Projects

• OxiGDAL - Complete geospatial data toolkit
• OxiBLAS - Pure Rust linear algebra
• SciRS2 - Scientific computing ecosystem

Part of the COOLJAPAN ecosystem of Pure Rust geospatial and scientific computing libraries.