Add Spotlight integration for interactive visualization

docs/getting_started/index.md

@@ -90,4 +90,5 @@ install
 overview
 intro_tutorials/index
 comparison
+spotlight
 ```

docs/getting_started/spotlight.md

@@ -0,0 +1,170 @@
+# Spotlight Integration
+
+DeepForest integrates with [Renumics Spotlight](https://github.com/Renumics/spotlight) for interactive visualization of detection results. This integration allows you to explore predictions, analyze model performance, and assess data quality through Spotlight's web interface.
+
+> **Note**: The Spotlight manifest format is experimental. For production use, consider the Hugging Face datasets export which offers broader tool compatibility.
+
+## Quick Start
+
+```python
+from deepforest import get_data
+from deepforest.utilities import read_file
+from deepforest.visualize import view_with_spotlight
+
+
+path = get_data("OSBS_029.csv")
+df = read_file(path)
+
+# Convert to Spotlight format
+spotlight_data = df.spotlight()
+# or
+spotlight_data = view_with_spotlight(df)
+
+# Generate new predictions and visualize
+from deepforest.main import deepforest
+model = deepforest()
+model.load_model("Weecology/deepforest-tree")
+image_path = get_data("OSBS_029.tif")
+results = model.predict_image(path=image_path)
+
+# Visualize with confidence scores preserved
+spotlight_data = view_with_spotlight(results)
+
+# Export to file for external tools
+df.spotlight(format="lightly", out_dir="spotlight_export")
+```
+
+## API Reference
+
+- `view_with_spotlight(df, format="lightly"|"objects", out_dir=...)` - Convert DeepForest DataFrame to Spotlight format
+  - Supports flexible image reference columns: `image_path`, `file_name`, `source_image`, `image`
+  - Handles NaN values in optional columns gracefully
+  - Validates required bbox columns: `xmin`, `ymin`, `xmax`, `ymax`
+- `df.spotlight(...)` - DataFrame accessor method (calls `view_with_spotlight`)
+- Core DataFrame-to-Spotlight conversion functionality
+- `export_to_spotlight_dataset(gallery_dir)` - Create Hugging Face Dataset from gallery
+
+## Working with Predictions
+
+When working with model predictions, the integration preserves confidence scores and detection metadata:
+
+```python
+from deepforest import get_data
+from deepforest.main import deepforest
+from deepforest.visualize import view_with_spotlight
+
+# Generate predictions
+model = deepforest()
+model.load_model("Weecology/deepforest-tree")
+image_path = get_data("OSBS_029.tif")
+results = model.predict_image(path=image_path)
+
+# Convert to Spotlight format
+spotlight_data = results.spotlight()
+# or
+spotlight_data = view_with_spotlight(results)
+```
+
+The converted data includes:
+- Bounding boxes (xmin, ymin, xmax, ymax)
+- Class labels
+- Confidence scores (0.0 to 1.0)
+- Source image paths
+
+This enables you to:
+- Filter detections by confidence threshold
+- Compare model performance across images
+- Identify patterns in prediction quality
+- Analyze spatial distribution of detections
+
+## Example Output
+
+The following example shows the Spotlight interface displaying DeepForest predictions:
+
+```python
+from deepforest import get_data
+from deepforest.main import deepforest
+from deepforest.visualize import view_with_spotlight
+
+model = deepforest()
+model.load_model("Weecology/deepforest-tree")
+image_path = get_data("OSBS_029.tif")
+results = model.predict_image(path=image_path)
+
+# Launch Spotlight viewer
+view_with_spotlight(results)
+```
+
+```{image} ../assets/spotlight_demo_screenshot.png
+:alt: Spotlight interface main view showing DeepForest predictions with data table and image viewer
+:width: 600px
+:align: center
+```
+*Main interface showing detection results in an interactive table*
+
+```{image} ../assets/spotlight_demo_screenshot1.png
+:alt: Spotlight interface showing detailed bounding box visualization on forest imagery
+:width: 600px
+:align: center
+```
+*Confidence scores and bounding box coordinates for each detection*
+
+```{image} ../assets/spotlight_demo_screenshot2.png
+:alt: Spotlight interface displaying confidence score distribution and filtering options
+:width: 600px
+:align: center
+```
+*Source imagery with detection metadata*
+
+The screenshots show the Spotlight interface with:
+- **Main view**: Data table displaying tree detections with confidence scores, bounding box coordinates, and interactive sorting capabilities
+- **Image viewer**: Visual representation of detected trees with bounding boxes overlaid on the source forest imagery
+- **Analytics panel**: Confidence score distribution charts and filtering options for analyzing model performance across detections
+
+## Demo Script
+
+Test the integration with the included demo:
+
+```bash
+python demo_spotlight.py
+```
+
+The script will load a model, generate predictions, and launch the Spotlight viewer in your browser.
+
+## Advanced Usage
+
+For more complex workflows, you can combine Spotlight integration with gallery generation:
+
+```python
+from deepforest.visualize import (
+    view_with_spotlight,
+    export_to_gallery,
+    write_gallery_html,
+    export_to_spotlight_dataset
+)
+
+# Direct Spotlight integration
+spotlight_data = view_with_spotlight(df, format="lightly")
+
+# Create thumbnail gallery
+metadata = export_to_gallery(df, "forest_gallery", max_crops=200)
+
+# Generate HTML viewer
+write_gallery_html("forest_gallery")
+
+# Export as HuggingFace dataset
+hf_dataset = export_to_spotlight_dataset("forest_gallery")
+```
+
+## Command Line Interface
+
+```bash
+# Export predictions to gallery
+python -m deepforest.scripts.cli gallery export predictions.csv --out forest_gallery
+
+# Package for Spotlight
+python -m deepforest.scripts.cli gallery spotlight --gallery forest_gallery --out spotlight_package
+
+# Package for Spotlight
+python -m deepforest.scripts.cli gallery spotlight --gallery forest_gallery --out spotlight_package
+```

docs/user_guide/examples/demo_spotlight.py

@@ -0,0 +1,60 @@
+"""
+DeepForest Spotlight Integration Example
+
+This example demonstrates how to use DeepForest predictions with Renumics Spotlight
+for interactive data exploration and visualization.
+
+Requirements:
+    pip install renumics-spotlight
+
+Usage:
+    python demo_spotlight.py
+"""
+
+from deepforest import get_data, main
+from deepforest.visualize import view_with_spotlight
+
+# Load a DeepForest model
+model = main.deepforest()
+model.load_model("weecology/deepforest-tree")
+
+# Make predictions on sample data
+image_path = get_data("OSBS_029.tif")
+results = model.predict_image(path=image_path)
+
+print(f"Generated {len(results)} tree detections")
+print(f"Score range: {results['score'].min():.3f} - {results['score'].max():.3f}")
+
+# Method 1: Use DataFrame accessor
+spotlight_data = results.spotlight()
+print(f"Spotlight format created with {len(spotlight_data['samples'])} samples")
+
+# Method 2: Use function directly
+spotlight_data = view_with_spotlight(results)
+
+# Optional: Save to file for later use
+spotlight_data = view_with_spotlight(results, out_dir="spotlight_output")
+print("Spotlight manifest saved to spotlight_output/manifest.json")
+
+# Optional: Launch Spotlight viewer (requires renumics-spotlight)
+try:
+    import renumics.spotlight as spotlight
+    import pandas as pd
+
+    # Prepare data for Spotlight viewer
+    spotlight_df = pd.DataFrame({
+        'image': [image_path] * len(results),
+        'label': results['label'],
+        'confidence': results['score'],
+        'xmin': results['xmin'],
+        'ymin': results['ymin'],
+        'xmax': results['xmax'],
+        'ymax': results['ymax']
+    })
+
+    print("Opening Spotlight viewer in browser...")
+    spotlight.show(spotlight_df, dtype={'image': spotlight.Image})
+
+except ImportError:
+    print("Install renumics-spotlight to launch the interactive viewer:")
+    print("pip install renumics-spotlight")