@page intersections Self-Intersection Detection

# Self-Intersection Highlighting in 3D Viewer

## Overview

The 3D dendrite viewer now supports automatic detection and highlighting of self-intersecting edges. When enabled, edges that cross through each other (not connected at vertices) are displayed in bright yellow with increased thickness.

## Features

- **Automatic Detection**: The viewer automatically detects all pairs of edges that intersect in 3D space
- **Visual Highlighting**: Intersecting edges are shown in bright yellow (`rgba(255, 255, 0, 0.9)`) with 4px width
- **Hover Info**: Hover over intersecting edges to see their index numbers
- **Optional**: The feature can be toggled on/off with a simple parameter

## API Usage

### Python API

```python
from quadrix import Vertex, Edge, Dendrite
from quadrix import py_plot_dendrite_3d, py_plot_dendrite_3d_show

# Create your dendrite
vertices = [...]
edges = [...]
dendrite = Dendrite(vertices, edges)

# Method 1: Save to HTML file with intersection highlighting
py_plot_dendrite_3d(
    dendrite, 
    title="My Dendrite",
    output_path="dendrite_with_intersections.html",
    highlight_intersections=True  # Enable intersection highlighting
)

# Method 2: Show directly in browser
py_plot_dendrite_3d_show(
    dendrite,
    title="My Dendrite",
    highlight_intersections=True  # Enable intersection highlighting
)

# Method 3: Check for intersections programmatically
if dendrite.py_has_self_intersections():
    print("Warning: Dendrite has self-intersections!")
    edge_pair = dendrite.py_find_self_intersections()
    print(f"Intersecting edges: {edge_pair}")
```

### Rust API

```rust
use quadrix::dendrite::Dendrite;
use quadrix::plotting::plot_dendrite_3d_interactive;

let dendrite = Dendrite::new(vertices, edges);

// Check for intersections
if dendrite.has_self_intersections() {
    println!("Warning: Dendrite has self-intersections!");
    if let Some((i, j)) = dendrite.find_self_intersections() {
        println!("Edges {} and {} intersect", i, j);
    }
}

// Plot with intersection highlighting
let plot = plot_dendrite_3d_interactive(
    &dendrite,
    "My Dendrite",
    Some("output.html"),
    true  // highlight_intersections
)?;
```

## Visual Appearance

- **Normal edges**: Gray with 30% opacity (`rgba(100, 100, 100, 0.3)`), 2px width
- **Intersecting edges**: Bright yellow (`rgba(255, 255, 0, 0.9)`), 4px width
- **Vertices**: Color-coded by type:
  - Root: Green diamond, 10px
  - Branch points: Red cross, 8px
  - Regular vertices: Steel blue circle, 3px

## Detection Algorithm

The intersection detection uses a 3D line segment intersection algorithm:

1. Computes the closest points between two line segments
2. Checks if these points are within the segment bounds (0 <= t <= 1)
3. Measures the distance between the closest points
4. If distance < tolerance (0.01), segments are considered intersecting
5. Connected edges (sharing a vertex) are automatically excluded

## Performance Notes

- Detection runs in O(n²) where n is the number of edges
- For large dendrites (>10,000 edges), detection may take a few seconds
- Detection only runs when `highlight_intersections=True`
- Results are not cached; detection runs each time the plot is generated

## Example: Creating a Test Case

```python
from quadrix import Vertex, Edge, Dendrite

# Create two crossing edges in 3D
# Edge 1: (0,0,0) → (10,10,10)
# Edge 2: (0,10,10) → (10,0,0)
# They intersect at (5,5,5)

v1 = Vertex(0.0, 0.0, 0.0)
v2 = Vertex(10.0, 10.0, 10.0)
v3 = Vertex(0.0, 10.0, 10.0)
v4 = Vertex(10.0, 0.0, 0.0)

edge1 = Edge(v1, v2)
edge2 = Edge(v3, v4)

dendrite = Dendrite([v1, v2, v3, v4], [edge1, edge2])

# This dendrite has intersections!
assert dendrite.py_has_self_intersections() == True

# Visualize with highlighting
py_plot_dendrite_3d_show(dendrite, highlight_intersections=True)
```

## Troubleshooting

**Q: Why aren't my intersections being detected?**
- Make sure edges don't share vertices (those are connections, not intersections)
- Check that edges actually cross in 3D space, not just appear to cross in 2D projection
- The tolerance is 0.01 units; edges that pass very close but don't truly intersect may not be detected

**Q: Performance is slow with large dendrites**
- Consider disabling intersection highlighting for dendrites with >10,000 edges
- Or implement spatial partitioning (future enhancement)

**Q: False positives/negatives?**
- Adjust the `TOLERANCE` constant in `src/dendrite.rs` if needed
- Current default is 0.01 which works well for typical dendrite data

