# Quadrix

A Rust library for analyzing dendritic structures using quadric matrices. This project provides efficient tools for representing dendritic trees, computing quadric error metrics, and visualizing eigenvalue distributions on hexagonal plots.

## Overview

This library implements quadric-based geometric analysis of dendritic structures, commonly found in neuroscience applications. Key features include:

- **Tree data structures**: Hierarchical vertex and edge representations for dendritic trees
- **Quadric matrices**: Computation of quadric error metrics for edges and vertices
- **Visualization**: Hexagonal plot generation using NormPolar transformations
- **Interactive tools**: Desktop application with plotting capabilities

## Core Concepts

### Quadric Matrices

A quadric matrix represents the squared distance from a geometric primitive (like a line or point). For an edge in 3D space:

```
Q = v1·v1ᵀ + v2·v2ᵀ
```

where v1 and v2 are orthonormal vectors perpendicular to the edge direction. The quadric matrix is:
- Symmetric (3×3)
- Positive semi-definite
- Has eigenvalues that characterize the local geometry

### Data Structures

- **Vertex**: 3D point with optional parent/children relationships for tree structure
- **Edge**: Pair of vertices with cached quadric matrix
- **Dendrite**: Collection of vertices and edges with aggregated quadric matrices

## Development Setup

### Prerequisites
- Rust toolchain (install via [rustup](https://rustup.rs/))
- Node.js and npm (for frontend build)

### Building and Development

```bash
# Build the desktop application (dev mode)
just build

# Run with hot reload
just dev

# Production build
just release

# Package for distribution
just package
```

## Features

The project uses Cargo features to manage optional dependencies:

- `plotting`: Enable plotters and CSV support for static plots
- `interactive`: Enable interactive visualizations
- `database`: Enable SQLite persistence with rusqlite
- `desktop`: Enable Tauri desktop application

## Project Structure

```
.
├── src/                             # Core library
│   ├── lib.rs                       # Main library module
│   ├── geometry/                    # 3D spatial primitives
│   ├── morphology/                  # Neuronal structure data
│   ├── analysis/                    # Computational algorithms
│   ├── viz/                         # Visualization and plotting
│   ├── population_comparison/       # Multi-neuron statistical analysis
│   ├── database/                    # SQLite persistence layer
│   └── bin/                         # CLI tools
│
├── ui/                              # Frontend for Tauri desktop
├── icons/                           # Application icons
├── Cargo.toml                       # Rust dependencies
├── tauri.conf.json                  # Tauri app configuration
└── justfile                         # Common development commands
```

## Mathematical Background

### NormPolar Transformations

The hexagonal plots use NormPolar transformations to map 3D eigenvalue data onto 2D hexagonal coordinates.

### Quadric Properties

For a properly computed quadric matrix Q:
- Trace(Q) = 2 (sum of eigenvalues)
- det(Q) = 0 (one zero eigenvalue along the edge direction)
- Symmetric: Q = Qᵀ
- Positive semi-definite: all eigenvalues >= 0

## Version History

- **0.2.1** (June 2026): Beta release - Removed deprecated server and Python bindings
- **0.2.0** (February 2026): Enhanced validation and features
- **0.1.0** (Initial): Core library and desktop foundations

## License

MIT License

## Documentation

- [QUICKSTART.md](./QUICKSTART.md) — Get started in 5 minutes
- [GUI_APPLICATIONS.md](./GUI_APPLICATIONS.md) — Detailed application usage