v2.1.0: Extract bugspot core library, add detection-only mode and track composites

- Created bugspot: standalone detection/tracking core (opencv, numpy, scipy)
  https://github.com/orlandocloss/bugspot
- inference.py now imports from bugspot (single source of truth)
- Removed detector.py and tracker.py from bplusplus (live in bugspot)
- Added classify=False for detection-only mode (NaN classification)
- Added track_composites=True for temporal trail images
- Consolidated inference docs in README and notebook

Author: orlandocloss

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2025-02-18
+
+### Added
+- **[BugSpot](https://github.com/orlandocloss/bugspot) core library**: Extracted motion detection, tracking, and path topology into standalone package (opencv + numpy + scipy only, no ML frameworks)
+- **Detection-only mode**: `classify=False` skips model loading — outputs NaN for classification fields
+- **Track composite images**: `track_composites=True` generates per-track temporal trail images (lighten blend on darkened background)
+
+### Changed
+- **Inference now depends on bugspot** for detection, tracking, topology analysis, crop extraction, and composite rendering
+- Removed `detector.py` and `tracker.py` from bplusplus — single source of truth in bugspot
+- Consolidated inference documentation in README and notebook into one clean section
+- `video_path` and `output_dir` are now the first two parameters in `inference()`
+
 ## [2.0.5] - 2025-02-04
 
 ### Added

README.md

@@ -18,6 +18,7 @@ Using the `Bplusplus` library, this pipeline automates the entire machine learni
 - **Intelligent Data Preparation**: Uses a pre-trained model to automatically find, crop, and resize insects from raw images, ensuring high-quality training data.
 - **Hierarchical Classification**: Trains a model to identify insects at three taxonomic levels: **family, genus, and species**.
 - **Video Inference & Tracking**: Processes video files to detect, classify, and track individual insects over time, providing aggregated predictions.
+
 ## Pipeline Overview
 
 The process is broken down into five main steps, all detailed in the `full_pipeline.ipynb` notebook:
@@ -132,49 +133,45 @@ results = bplusplus.validate(
 ```
 
 #### Step 5: Run Inference on Video
-Process a video file to detect, classify, and track insects using motion-based detection. The pipeline uses background subtraction (GMM) to detect moving insects, tracks them across frames, and classifies confirmed tracks.
 
-**Note:** The species list and taxonomy are automatically loaded from the model checkpoint, so you don't need to provide them again.
+Processes a video through a multi-phase pipeline: motion-based detection (GMM), Hungarian tracking, path topology confirmation, and hierarchical classification. Detection and tracking are powered by [BugSpot](bugspot/), a lightweight core that runs on any platform including edge devices.
 
-**Output files generated in `output_dir`:**
-- `{video}_annotated.mp4` - Video showing confirmed tracks with classifications
-- `{video}_debug.mp4` - Debug video with motion mask and all detections
-- `{video}_results.csv` - Aggregated results per confirmed track
-- `{video}_detections.csv` - Frame-by-frame detection data
+The species list is automatically loaded from the model checkpoint.
 
 ```python
-VIDEO_INPUT_PATH = Path("my_video.mp4")
-OUTPUT_DIR = Path("./output")
 HIERARCHICAL_MODEL_PATH = TRAINED_MODEL_DIR / "best_multitask.pt"
 
 results = bplusplus.inference(
+    video_path="my_video.mp4",
+    output_dir="./output",
     hierarchical_model_path=HIERARCHICAL_MODEL_PATH,
-    video_path=VIDEO_INPUT_PATH,
-    output_dir=OUTPUT_DIR,
-    # species_list=names,   # Optional: override species from checkpoint
-    fps=None,               # None = process all frames
-    backbone="resnet50",    # Must match training
-    save_video=True,        # Set to False to skip video rendering (only CSV output)
-    img_size=60,            # Must match training
+    backbone="resnet50",        # Must match training
+    img_size=60,                # Must match training
+    # --- Optional ---
+    # species_list=names,       # Override species from checkpoint
+    # fps=None,                 # None = all frames, or set target FPS
+    # config="config.yaml",     # Custom detection parameters (YAML/JSON)
+    # classify=False,           # Detection only, NaN for classification
+    # save_video=True,          # Annotated + debug videos
+    # crops=False,              # Save crop per detection per track
+    # track_composites=False,   # Composite image per track (temporal trail)
 )
 
-print(f"Detected {results['tracks']} tracks ({results['confirmed_tracks']} confirmed)")
+print(f"Confirmed: {results['confirmed_tracks']} / {results['tracks']} tracks")
 ```
 
-**Note:** Set `save_video=False` to skip generating the annotated and debug videos, which speeds up processing when you only need the CSV detection data.
-
-**Custom Detection Configuration:**
-
-For advanced control over detection parameters, provide a YAML config file:
+**Output files:**
 
-```python
-results = bplusplus.inference(
-    ...,
-    config="detection_config.yaml"
-)
-```
+| File | Description | Flag |
+|------|-------------|------|
+| `{video}_results.csv` | Aggregated results per confirmed track | Always |
+| `{video}_detections.csv` | Frame-by-frame detections | Always |
+| `{video}_annotated.mp4` | Video with detection boxes and paths | `save_video=True` |
+| `{video}_debug.mp4` | Side-by-side with GMM motion mask | `save_video=True` |
+| `{video}_crops/` | Crop images per track | `crops=True` |
+| `{video}_composites/` | Composite images per track | `track_composites=True` |
 
-Download a template config from the [releases page](https://github.com/Tvenver/Bplusplus/releases).
+**Detection configuration** can be customized via a YAML/JSON file passed as `config=`. Download a template from the [releases page](https://github.com/Tvenver/Bplusplus/releases).
 
 <details>
 <summary><b>Full Configuration Parameters</b> (click to expand)</summary>

notebooks/full_pipeline.ipynb

@@ -279,17 +279,9 @@
    "source": [
     "## Step 5: Run Video Inference\n",
     "\n",
-    "Runs motion-based insect detection and hierarchical classification on video files. Detects moving insects using background subtraction (GMM), tracks them across frames, classifies each detection, and aggregates predictions per track.\n",
+    "Processes a video through a multi-phase pipeline: motion-based detection (GMM), Hungarian tracking, path topology confirmation, and hierarchical classification. Detection and tracking are powered by [BugSpot](../bugspot/), a lightweight core that runs on any platform.\n",
     "\n",
-    "**Note:** The species list and taxonomy are automatically loaded from the model checkpoint, so you don't need to provide them again.\n",
-    "\n",
-    "**Output files generated:**\n",
-    "- `{video}_annotated.mp4` - Video with detection boxes and track paths (if `save_video=True`)\n",
-    "- `{video}_debug.mp4` - Side-by-side view with GMM motion mask (if `save_video=True`)\n",
-    "- `{video}_results.csv` - Aggregated results per track\n",
-    "- `{video}_detections.csv` - Frame-by-frame detections\n",
-    "\n",
-    "**Tip:** Set `save_video=False` to skip video rendering and only generate CSV output (faster processing)."
+    "The species list is automatically loaded from the model checkpoint. All detection parameters can be customized via `config=` (YAML/JSON file). See [`detection_config.yaml`](../detection_config.yaml) for all parameters and defaults."
    ]
   },
   {
@@ -299,69 +291,29 @@
    "outputs": [],
    "source": [
     "results = bplusplus.inference(\n",
-    "    hierarchical_model_path=RESNET_MULTITASK_WEIGHTS,\n",
     "    video_path=\"./10.mp4\",\n",
     "    output_dir=\"./output\",\n",
-    "    # species_list=names,  # Optional: override species from checkpoint\n",
-    "    fps=None,              # None = all frames\n",
-    "    backbone=\"resnet50\",   # Must match training\n",
-    "    save_video=True,       # Set to False to skip video rendering (only CSV output)\n",
-    "    img_size=60,           # Must match training\n",
+    "    hierarchical_model_path=RESNET_MULTITASK_WEIGHTS,\n",
+    "    backbone=\"resnet50\",        # Must match training\n",
+    "    img_size=60,                # Must match training\n",
+    "    # --- Optional ---\n",
+    "    # species_list=names,       # Override species from checkpoint\n",
+    "    # fps=None,                 # None = all frames, or set target FPS\n",
+    "    # config=\"config.yaml\",     # Custom detection parameters (YAML/JSON)\n",
+    "    # classify=False,           # Detection only, NaN for classification\n",
+    "    # save_video=True,          # Annotated + debug videos\n",
+    "    # crops=False,              # Save crop per detection per track\n",
+    "    # track_composites=False,   # Composite image per track (temporal trail)\n",
     ")\n",
     "\n",
-    "print(f\"Detected {results['tracks']} tracks ({results['confirmed_tracks']} confirmed)\")"
+    "print(f\"Confirmed: {results['confirmed_tracks']} / {results['tracks']} tracks\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Custom Detection Configuration\n",
-    "\n",
-    "The inference uses motion-based detection with configurable parameters for filtering detections. You can customize these by providing a YAML or JSON config file.\n",
-    "\n",
-    "Download a template config from:  https://github.com/Tvenver/Bplusplus/releases/download/weights/detection_config.yaml\n",
-    "\n",
-    "```python\n",
-    "results = bplusplus.inference(\n",
-    "    ...,\n",
-    "    config=\"detection_config.yaml\"\n",
-    ")\n",
-    "```\n",
-    "\n",
-    "#### Full Configuration Parameters\n",
     "\n",
-    "| Parameter | Default | Description |\n",
-    "|-----------|---------|-------------|\n",
-    "| **GMM Background Subtractor** | | *Motion detection model* |\n",
-    "| `gmm_history` | 500 | Frames to build background model |\n",
-    "| `gmm_var_threshold` | 16 | Variance threshold for foreground detection |\n",
-    "| **Morphological Filtering** | | *Noise removal* |\n",
-    "| `morph_kernel_size` | 3 | Morphological kernel size (NxN) |\n",
-    "| **Cohesiveness** | | *Filters scattered motion (plants) vs compact motion (insects)* |\n",
-    "| `min_largest_blob_ratio` | 0.80 | Min ratio of largest blob to total motion |\n",
-    "| `max_num_blobs` | 5 | Max separate blobs allowed in detection |\n",
-    "| `min_motion_ratio` | 0.15 | Min ratio of motion pixels to bbox area |\n",
-    "| **Shape** | | *Filters by contour properties* |\n",
-    "| `min_area` | 200 | Min detection area (px²) |\n",
-    "| `max_area` | 40000 | Max detection area (px²) |\n",
-    "| `min_density` | 3.0 | Min area/perimeter ratio |\n",
-    "| `min_solidity` | 0.55 | Min convex hull fill ratio |\n",
-    "| **Tracking** | | *Controls track behavior* |\n",
-    "| `min_displacement` | 50 | Min net movement for confirmation (px) |\n",
-    "| `min_path_points` | 10 | Min points before path analysis |\n",
-    "| `max_frame_jump` | 100 | Max jump between frames (px) |\n",
-    "| `max_lost_frames` | 45 | Frames before lost track deleted (e.g., 45 @ 30fps = 1.5s) |\n",
-    "| `max_area_change_ratio` | 3.0 | Max area change ratio between frames |\n",
-    "| **Tracker Matching** | | *Hungarian algorithm cost function* |\n",
-    "| `tracker_w_dist` | 0.6 | Weight for distance cost (0-1) |\n",
-    "| `tracker_w_area` | 0.4 | Weight for area cost (0-1) |\n",
-    "| `tracker_cost_threshold` | 0.3 | Max cost for valid match (0-1) |\n",
-    "| **Path Topology** | | *Confirms insect-like movement patterns* |\n",
-    "| `max_revisit_ratio` | 0.30 | Max ratio of revisited positions |\n",
-    "| `min_progression_ratio` | 0.70 | Min forward progression |\n",
-    "| `max_directional_variance` | 0.90 | Max heading variance |\n",
-    "| `revisit_radius` | 50 | Radius (px) for revisit detection |\n",
     "\n"
    ]
   }

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "bplusplus"
-version = "2.0.5"
+version = "2.1.0"
 description = "A simple method to create AI models for biodiversity, with collect and prepare pipeline"
 authors = ["Titus Venverloo <tvenver@mit.edu>", "Deniz Aydemir <deniz@aydemir.us>", "Orlando Closs <orlandocloss@pm.me>", "Ase Hatveit <aase@mit.edu>"]
 license = "MIT"
@@ -14,6 +14,7 @@ ultralytics = "8.3.173"
 pyyaml = "6.0.1"
 tqdm = "4.66.4"
 prettytable = "3.7.0"
+bugspot = {git = "https://github.com/orlandocloss/bugspot.git"}
 # Pillow with platform-specific compatibility
 pillow = [
     # Windows - stable version