🚘 DriveID Filter

DriveID Filter is a modular OpenFilter-based component that detects license plates in video frames using a custom-trained Faster R-CNN model.

It supports per-frame bounding box predictions, polygon ROI forwarding, and configurable JSON logging — making it easy to plug into OpenFilter pipelines and downstream processing systems.

✨ Features

• 🚘 Detects license plates in RGB video frames using Faster R-CNN
• 🔍 Configurable confidence threshold and debug logging
• 📤 Forwards detection ROIs as polygons to other filters
• 🧾 Optional logging of per-frame detections to JSON
• 🧩 Fully compatible with OpenFilter pipelines

📦 Installation

Install from PyPI:

pip install filter-license-plate-detection

Or install from source:

# Clone the repo
git clone https://github.com/PlainsightAI/filter-license-plate-detection.git
cd filter-license-plate-detection

# (Optional but recommended) create a virtual environemnt:
python -m venv venv && source venv/bin/activate

# Install the filter and download the model
make install

🚀 Quick Start (CLI)

Run the DriveID Filter as part of a pipeline:

openfilter run \
  - VideoIn --sources file://example_video.mp4!loop \
  - filter_license_plate_detection.filter.FilterLicensePlateDetection \
      --model_path ./model.pth \
      --forward_detection_rois true \
      --write_detections_to_json true \
      --output_json_path ./detections.json \
  - Webvis

Or simply:

make run

Then open http://localhost:8000 to view results.

🧰 Using from PyPI

After installation:

pip install filter-license-plate-detection

You can run the filter directly:

Standalone usage

from filter_license_plate_detection.filter import FilterLicensePlateDetection

if __name__ == "__main__":
    FilterLicensePlateDetection.run()

In an OpenFilter pipeline

from openfilter.filter_runtime.filter import Filter
from openfilter.filter_runtime.filters.video_in import VideoIn
from openfilter.filter_runtime.filters.webvis import Webvis
from filter_license_plate_detection.filter import FilterLicensePlateDetection

if __name__ == "__main__":
    Filter.run_multi([
        (VideoIn, dict(sources='file://example.mp4!loop')),
        (FilterLicensePlateDetection, dict(
            model_path="./model.pth",
            confidence_threshold=0.75,
            forward_detection_rois=True
        )),
        (Webvis, {}),
    ])

🧪 Testing

Run unit tests:

make test

Or a specific test:

pytest -v tests/test_filter_license_plate_detection.py

Tests include:

• Model inference
• Confidence filtering
• Polygon forwarding
• JSON logging
• Frame skipping logic

⚙️ Configuration

All fields can also be configured via environment variables using the prefix FILTER_ (e.g., FILTER_MODEL_PATH).

📤 Detection Output Format

Each frame’s detection output is stored in:

frame.data['license_plate_detection']

Example output:

{
  "frame_id": "frame_001",
  "plates": [
    {
      "label": "license_plate",
      "score": 0.92,
      "box": [320, 180, 460, 240]
    }
  ]
}

If forward_detection_rois is enabled, the filter also adds polygon metadata:

frame.data["meta"]["license_plate_roi"] = [
  [(320, 180), (460, 180), (460, 240), (320, 240)]
]

📄 License

Licensed under the Apache 2.0 License.

🙌 Acknowledgements

Thanks for using and improving the DriveID Filter! To report bugs or suggest improvements, open a GitHub issue.