geodesic 0.0.0

A Rust library for constructing and sampling 3D geometric scenes.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

# Geodesic

[![crates.io](https://img.shields.io/crates/v/geodesic.svg)](https://crates.io/crates/geodesic)
[![Documentation](https://docs.rs/geodesic/badge.svg)](https://docs.rs/geodesic)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A high-performance ray tracing library for Rust, featuring efficient Bounding Volume Hierarchy (BVH) acceleration structures and support for a range of geometric primitives.

## Features

- 🚀 **High Performance**: Optimized BVH acceleration structures with Surface Area Heuristic (SAH)
- 📐 **Multiple Primitives**: Support for spheres, AABBs, triangles, and meshes
- 🎯 **Ray Tracing**: Efficient ray-geometry intersection testing
- 📦 **Mesh Loading**: Built-in Wavefront (.obj) file loader
- 🔄 **Instancing**: Mesh instancing with transformation matrices
- 📸 **Camera System**: Configurable perspective camera with field-of-view controls
- 🎨 **Rendering Pipeline**: Complete ray casting to distance field rendering
- 📊 **Generic Design**: Works with any real number type (f32, f64, etc.)

## Quick Start

Add this to your `Cargo.toml`:

```toml
[dependencies]
geodesic = "0.0.0"
```

### Basic Example

```rust
use geodesic::prelude::*;
use nalgebra::Point3;

// Configure BVH acceleration structure
let bvh_config = BvhConfig::new(
    1.0,    // traverse_cost
    1.25,   // intersect_cost
    16,     // sah_buckets
    4,      // max_shapes_per_node
    16      // max_depth
);

// Set up camera
let resolution = [600, 800];        // [height, width]
let camera = Camera::new(
    Point3::new(10.0, 10.0, 10.0),  // position
    Point3::new(0.0, 0.0, 3.0),     // look_at
    90.0_f32.to_radians(),          // field_of_view
    resolution,
);

// Create scene objects
let mut objects = Vec::new();
objects.push(SceneObject::Sphere(Sphere::new(Point3::new(0.0, 0.0, 0.0), 1.0)));
objects.push(SceneObject::Mesh(Mesh::load(&bvh_config, "./assets/tree.obj")));

// Build scene with BVH acceleration
let scene = Scene::new(&bvh_config, &objects);

// Render distance field
for row in 0..resolution[0] {
    for col in 0..resolution[1] {
        let ray = camera.generate_ray([row, col]);
        if let Some((_object_index, hit)) = scene.intersect(&ray) {
            let distance = hit.distance;
            // ...
        }
    }
}
```

## Core Components

### Geometry Primitives

- **Sphere**: Basic sphere primitive with center and radius
- **AABB**: Axis-Aligned Bounding Box with min/max corners
- **Triangle**: Optimised triangle with pre-computed edges and normals
- **Mesh**: Triangle mesh with BVH acceleration and .obj loading support

### Scene Management

- **Scene**: Top-level container for all objects with BVH acceleration
- **SceneObject**: Enumeration wrapper for different geometry types
- **Instance**: Mesh instancing with transformation matrices

### Acceleration Structures

- **BvhConfig**: Configurable parameters for BVH construction
- **BVH**: Bounding Volume Hierarchy with Surface Area Heuristic

### Ray Tracing

- **Ray**: Ray structure with origin, direction, and optimisation data
- **Hit**: Intersection result with distance and normal information
- **Camera**: Perspective camera for generating sampling rays

## File Format Support

### Wavefront OBJ

The library supports loading triangle meshes from Wavefront (.obj) files:

```rust
let mesh = Mesh::load(&bvh_config, "./path/to/model.obj");
```

**Supported features:**

- Vertex positions (`v`)
- Vertex normals (`vn`)
- Triangular faces (`f`)

**Requirements:**

- Meshes must be triangulated
- Faces must include both vertex and normal indices (format: `v//vn`)

## Performance Considerations

### BVH Optimization

The library uses Surface Area Heuristic (SAH) for optimal BVH construction:

- **Traverse Cost**: Higher values favor broader trees (fewer internal nodes)
- **Intersect Cost**: Higher values favor deeper trees (fewer primitives per leaf)
- **SAH Buckets**: More buckets provide better splits but trade-off with a slower construction time
- **Max Shapes Per Node**: Controls leaf size vs. tree depth trade-off

### Memory Usage

- BVH construction requires temporary memory proportional to scene size
- Mesh data is stored efficiently with pre-computed edge vectors
- Ray intersection uses stack-based traversal (no heap allocation)

## Examples

See the `simple.rs` example for a complete rendering pipeline that:

1. Sets up a scene with a sphere and mesh
2. Configures a perspective camera
3. Renders a distance field image
4. Saves the result as a PNG file