# Quadrix Examples

This directory contains example programs demonstrating how to use the Quadrix library in both Rust and Python.

## Building the Examples

### Rust Examples

Run Rust examples using cargo:

```bash
# With default features
cargo run --example <example_name>

# With database feature
cargo run --example <example_name> --features database

# With web feature
cargo run --example <example_name> --features web
```

**Note:** To build the Rust binaries (not examples), use the Makefile targets:
```bash
make build-all          # Build all Rust binaries
make build-database     # Build database tools
make build-web          # Build web server
```

### Python Examples

First, setup the Python development environment:

```bash
# Setup Python environment and build bindings
make dev

# Or just build the bindings
make build
```

Then run the Python examples:

```bash
python examples/<example_name>.py <arguments>
# Or use the virtual environment directly
.venv/bin/python examples/<example_name>.py <arguments>
```

## Rust Examples

### database_operations.rs

Demonstrates standalone database operations without a web server.

**Features required:** `database`

**Usage:**
```bash
cargo run --example database_operations --features database
```

**What it demonstrates:**
- Creating in-memory and file-based databases
- Schema initialization and verification
- Foreign key constraints
- Database optimization with VACUUM

### process_swc_batch.rs

Process all SWC files in a directory with database caching.

**Features required:** `web`

**Usage:**
```bash
cargo run --example process_swc_batch --features web -- <directory_path> [database_name]
```

**Example:**
```bash
cargo run --example process_swc_batch --features web -- /path/to/swc/files
cargo run --example process_swc_batch --features web -- /path/to/swc/files custom.db
```

**What it demonstrates:**
- Batch processing of SWC files
- Database caching for improved performance
- Dendrite statistics (vertices, edges, lengths, branch points)
- Error handling for invalid files

### simplify_dendrite.rs

Dendritic tree simplification using quadric error metrics and edge contraction.

**Features required:** None (core functionality)

**Usage:**
```bash
cargo run --example simplify_dendrite <swc_file> [distortion_threshold]
```

**Example:**
```bash
cargo run --example simplify_dendrite data/test_neuron.swc 0.5
```

**What it demonstrates:**
- Loading dendrites from SWC files
- Edge contraction simplification algorithm
- Quadric error metrics
- Vertex classification (leaves, regular, forks)
- Branch decomposition
- Simplification statistics

## Python Examples

### load_swc_example.py

Basic example for loading SWC files and analyzing neuronal morphology.

**Usage:**
```bash
python examples/load_swc_example.py
```

**What it demonstrates:**
- Loading neurons from SWC files
- Accessing vertex and edge data
- Finding root and leaf vertices
- Computing bounding boxes
- Edge statistics (length, count)

### vertex_edge_basics.py

Comprehensive guide to working with vertices and edges.

**Usage:**
```bash
python examples/vertex_edge_basics.py
```

**What it demonstrates:**
- Creating vertices with coordinates
- Vertex properties (ID, coordinates, parent/child relationships)
- Distance calculations between vertices
- Building tree structures
- Creating edges
- Edge properties (length, direction, quadric matrices)
- Edge order independence
- Vertex lookup by ID
- Complex multi-level tree structures

### analyze_quadrix.py

Deep dive into quadric matrix analysis for dendritic structures.

**Usage:**
```bash
python examples/analyze_quadrix.py <swc_file>
```

**Example:**
```bash
python examples/analyze_quadrix.py data/test_neuron.swc
```

**What it demonstrates:**
- Edge quadric matrix properties
- Quadric symmetry verification
- Trace and Frobenius norm calculations
- Aggregate node and edge quadrix
- Quadric evaluation at specific points
- Geometric error computation

### simplify_dendrite.py

Analyze dendritic structures to understand simplification potential.

**Usage:**
```bash
python examples/simplify_dendrite.py <swc_file>
```

**Example:**
```bash
python examples/simplify_dendrite.py data/test_neuron.swc
```

**What it demonstrates:**
- Loading and analyzing dendrite structure
- Vertex classification by degree
- Edge statistics
- Aggregate quadric matrices
- Self-intersection detection
- Topological analysis
- Branching distribution

**Note:** The actual edge contraction simplification algorithm is currently only available in Rust. This Python example focuses on analysis and understanding the data structures.

### process_swc_batch.py

Batch process multiple SWC files from a directory.

**Usage:**
```bash
python examples/process_swc_batch.py <directory_path>
```

**Example:**
```bash
python examples/process_swc_batch.py /path/to/swc/files
```

**What it demonstrates:**
- Finding SWC files in a directory (including subdirectories)
- Batch loading multiple files
- Error handling for failed loads
- Per-dendrite statistics
- Overall aggregate statistics
- Vertex type counting

**Note:** Database caching is available in the Rust version with the `web` feature.

## Common Workflows

### Getting Started with Python

1. Setup development environment:
   ```bash
   make dev
   ```

2. Run the basics example:
   ```bash
   python examples/vertex_edge_basics.py
   ```

3. Try loading a real neuron (if you have SWC data):
   ```bash
   python examples/load_swc_example.py
   ```

4. Run tests to verify everything works:
   ```bash
   make test
   ```

### Analyzing Neuron Morphology

1. Load and analyze a single neuron:
   ```bash
   python examples/analyze_quadrix.py data/neuron.swc
   ```

2. Batch process multiple neurons:
   ```bash
   python examples/process_swc_batch.py data/neurons/
   ```

### Simplification (Rust)

1. Analyze simplification at different thresholds:
   ```bash
   cargo run --example simplify_dendrite data/neuron.swc 0.1
   cargo run --example simplify_dendrite data/neuron.swc 0.5
   cargo run --example simplify_dendrite data/neuron.swc 1.0
   ```

### Database Operations (Rust)

1. Test database functionality:
   ```bash
   cargo run --example database_operations --features database
   ```

2. Batch import with caching:
   ```bash
   cargo run --example process_swc_batch --features web -- data/neurons/
   ```

## Data Format

All examples expect SWC (Sholl-Wig Crossover) format files. SWC is the standard format for neuronal morphology data.

Example SWC format:
```
# Sample ID Type X Y Z Radius Parent
1 1 0.0 0.0 0.0 1.0 -1
2 3 1.0 0.0 0.0 0.5 1
3 3 0.0 1.0 0.0 0.5 1
```

## Further Reading

- See the main [README.md](../README.md) for library overview
- See [docs/](../docs/) for detailed documentation
- See [test_quadrix.py](../test_quadrix.py) for comprehensive API tests
