lumen-geometry 0.1.0

# lumen-geometry

Mathematical models for tubular anatomical structures.

[![Crates.io](https://img.shields.io/crates/v/lumen-geometry.svg)](https://crates.io/crates/lumen-geometry)
[![Documentation](https://docs.rs/lumen-geometry/badge.svg)](https://docs.rs/lumen-geometry)

## What is this?

This crate provides **pure math** for generating and querying the geometry of hollow organs like the colon, bronchi, and intestines. No game engine required - just math you can use anywhere.

**"Lumen"** is the medical term for the interior space of a tubular organ (from Latin *lumen*, meaning "light" or "opening").

## Who is this for?

- **Medical students** learning GI tract anatomy
- **Simulation developers** building surgical trainers
- **Researchers** needing procedural anatomical models
- **Game developers** creating medical environments

## Quick Start

```rust
use lumen_geometry::colon::{ColonConfig, ColonCurve};
use lumen_geometry::TubularCurve;

// Create a colon with default anatomical parameters
let config = ColonConfig::default();
let colon = ColonCurve::new(&config);

// Query positions along the centerline (t: 0.0 = rectum, 1.0 = cecum)
let rectum_pos = colon.position_at(0.0);
let transverse_pos = colon.position_at(0.5);
let cecum_pos = colon.position_at(1.0);

// Get the direction the tube is heading at any point
let forward = colon.tangent_at(0.3);

// Query wall position including haustra (pouches)
let wall_point = colon.wall_position_at(0.3, std::f32::consts::PI);
```

## Colon Anatomy

The human colon is approximately 1.5 meters long and consists of anatomically distinct regions:

```
t=0.0                                                    t=1.0
  │                                                        │
  ▼                                                        ▼
Rectum → Sigmoid → Descending → Splenic → Transverse → Hepatic → Ascending → Cecum
                                Flexure                 Flexure
```

### Segments

| Segment | t-range | Characteristics |
|---------|---------|-----------------|
| **Rectum** | 0.00-0.08 | Entry point, relatively straight |
| **Sigmoid** | 0.08-0.20 | S-shaped curve, highly variable between individuals |
| **Descending** | 0.20-0.35 | Runs down the left side of abdomen |
| **Splenic Flexure** | 0.35-0.40 | Sharp ~90° bend near the spleen |
| **Transverse** | 0.40-0.65 | Crosses abdomen horizontally |
| **Hepatic Flexure** | 0.65-0.70 | Sharp ~90° bend near the liver |
| **Ascending** | 0.70-0.90 | Runs up the right side of abdomen |
| **Cecum** | 0.90-1.00 | Pouch at terminus, connects to small intestine |

### Haustra

The colon wall has characteristic sac-like pouches called **haustra**, formed by:

1. **Taeniae coli**: Three longitudinal muscle bands running the length of the colon, spaced 120° apart
2. **Circular muscle contractions**: Create individual pouch boundaries

```
    Taenia 1 (0°)
         │
   ╭─────┴─────╮
  ╱             ╲
 │   Haustrum    │
  ╲             ╱
   ╰─────┬─────╯
         │
    Taenia 2 (120°)
```

## Procedural Variation

Different seeds produce anatomically plausible variations:

```rust
use lumen_geometry::colon::{ColonConfig, ColonCurve};

// Same anatomy every time
let standard = ColonCurve::new(&ColonConfig::default());

// Procedurally varied
let patient_a = ColonCurve::new(&ColonConfig::with_seed(42));
let patient_b = ColonCurve::new(&ColonConfig::with_seed(123));
```

Seeds affect:
- Segment length ratios (within anatomical bounds)
- Flexure angles
- Radius variations
- Secondary curve wobble

## Key Concepts

### t-parameter

Position along the curve is expressed as `t ∈ [0.0, 1.0]`:
- `t = 0.0` → Rectum (entry point)
- `t = 1.0` → Cecum (end)

### Arc Length

Physical distance along the curve (in world units). Convert between t and arc length:

```rust
use lumen_geometry::TubularCurve;

// Travel 10 units forward from t=0.3
let new_t = colon.advance_by_arc(0.3, 10.0);

// Get arc length to a specific t
let distance = colon.t_to_arc(0.5);
```

### Local Coordinate Frame

At any point, you can get a local coordinate system:
- **Tangent**: Forward direction (along the curve)
- **Normal**: Up direction
- **Binormal**: Right direction

```rust
use lumen_geometry::TubularCurve;

let tangent = colon.tangent_at(0.5);
let normal = colon.normal_at(0.5);
let binormal = colon.binormal_at(0.5);
let frame = colon.frame_at(0.5); // As a quaternion
```

## No Dependencies on Game Engines

This crate only depends on:
- `glam` - Standard 3D math (Vec3, Quat)
- `rand` / `rand_chacha` - Deterministic random number generation

Use it with Bevy, Godot, Unity (via FFI), or plain Rust.

## License

Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.