redoal/ReadMe.md

# Redoal
> Gesture indexing math library for generating stable index keys from gestures

A library focused purely on gesture indexing mathematics for DHT-based path comparisons and similarity search.

## Core Capabilities

1. **Gesture Normalization** - Remove translation and scale variations
2. **Path Resampling** - Fixed number of evenly spaced points
3. **Shape Descriptors** - Hu invariant moments for shape characterization
4. **Spectral Embeddings** - Laplacian eigenvalues for gesture signature
5. **Dimensionality Reduction** - PCA for feature compression
6. **Spatial Indexing** - Morton/Z-order curve for integer keys

## Usage Example

### Creating a Gesture Key for DHT

```rust
use redoal::*;

fn main() {
    // Load or create a gesture (sequence of points)
    let gesture = vec![
        Point::new(0.0, 0.0),
        Point::new(1.0, 0.0),
        Point::new(0.5, 1.0),
        Point::new(0.0, 0.5),
    ];

    // Normalize the gesture (remove translation and scale)
    let normalized = normalize(&gesture);

    // Resample to fixed number of points for consistency
    let resampled = resample(&normalized, 64);

    // Compute spectral signature
    let spectral = spectral_signature(&resampled, 4);

    // Create Morton code for DHT key
    let key = morton2(
        (spectral[0] * 1000.0) as u32,
        (spectral[1] * 1000.0) as u32
    );

    println!("Gesture key: {}", key);
}
```

### Similarity Search

```rust
use redoal::*;

fn find_similar_gestures(query: &[Point], database: &[(&str, Vec<Point>)]) -> Vec<(&str, f64)> {
    // Normalize and resample query
    let query_norm = normalize(query);
    let query_resamp = resample(&query_norm, 64);
    let query_spectral = spectral_signature(&query_resamp, 4);

    // Compute similarity for each gesture in database
    let mut similarities = Vec::new();

    for (name, gesture) in database {
        let gesture_norm = normalize(gesture);
        let gesture_resamp = resample(&gesture_norm, 64);
        let gesture_spectral = spectral_signature(&gesture_resamp, 4);

        // Euclidean distance between spectral signatures
        let distance = query_spectral.iter()
            .zip(gesture_spectral.iter())
            .map(|(a, b)| (a - b).powi(2))
            .sum::<f64>()
            .sqrt();

        similarities.push((name, distance));
    }

    // Sort by similarity (lower distance = more similar)
    similarities.sort_by(|a, b| a.1.partial_cmp(&b.1).unwrap());
    similarities
}
```

## Mathematical Operations

| Module | Function | Purpose |
|--------|----------|---------|
| `point` | `Point::new(x, y)` | Create 2D points with floating-point coordinates |
| `normalize` | `normalize(points)` | Center gesture at origin and scale to unit size |
| `resample` | `resample(points, n)` | Resample to n evenly spaced points |
| `moments` | `hu_moments(points)` | Compute Hu invariant moments (7-value shape descriptor) |
| `spectral` | `spectral_signature(points, k)` | Compute k Laplacian eigenvalues |
| `pca` | `pca(data, k)` | Dimensionality reduction to k principal components |
| `morton` | `morton2(x, y)` | Convert 2D coordinates to 64-bit Morton code |

## Dependencies

- `nalgebra` - Linear algebra and matrix operations
- `ndarray` - Multi-dimensional array support
- `itertools` - Iteration helpers
- `rand` - Test data generation

## Testing

Run tests with:
```bash
cargo test
```

All tests pass, demonstrating correct implementation of gesture indexing mathematics.