Skip to main content

DriveID Filter

The DriveID Filter identifies license plates in video frames using a custom Faster R-CNN model. It can log detections to disk, propagate bounding boxes as ROI polygons, and integrates seamlessly with OpenFilter pipelines.

This document is automatically published to production documentation on every production release.

✨ Key Features​

  • CNN-based license plate detection using PyTorch Faster R-CNN
  • Customizable confidence threshold for filtering predictions
  • Optional JSON logging of detections for post-processing and audit
  • ROI forwarding support for integration with downstream filters (e.g., OCR or Crop)
  • Metadata-aware frame skipping via meta.skip_plate_detection
  • Environment-variable-based configuration for runtime overrides
  • Optimized for GPU or CPU inference based on availability

🚀 Usage Modes​

1. Standard Detection Mode​

Given a frame, the filter performs detection and returns bounding boxes for license plates. The output is stored in:

frame.data['license_plate_detection']

Each detection includes:

{
  "label": "license_plate",
  "score": 0.91,
  "box": [x1, y1, x2, y2]
}

2. Polygon ROI Forwarding​

If enabled via forward_detection_rois, the filter adds a meta entry:

frame.data["meta"]["license_plate_roi"] = [
  [(x1, y1), (x2, y1), (x2, y2), (x1, y2)]
]

These can be consumed by other filters (e.g., Crop Filter, OCR Filter) downstream.

3. Skip Logic via Metadata​

If frame.data['meta']['skip_plate_detection'] = True, the filter skips processing that frame.

⚙️ Configuration Options​

FieldTypeDescription
model_pathstrPath to the .pth file containing the trained model
confidence_thresholdfloatMinimum score required to keep a detection (default: 0.7)
debugboolEnables verbose debug logs
write_detections_to_jsonboolWhether to write per-frame results to a file
output_json_pathstrFile path for detection logs (e.g., ./output/results.json)
forward_detection_roisboolIf true, forwards bounding boxes as polygon ROIs
roi_output_labelstrLabel under which forwarded ROIs are stored in frame.meta

All fields are configurable via code or environment variables prefixed with FILTER_. Example: FILTER_MODEL_PATH=./model.pth

🧪 Example Configurations​

Basic detection​

FilterLicensePlateDetectionConfig(
  model_path="./model.pth",
  confidence_threshold=0.8,
  debug=False
)

With JSON output and polygon forwarding​

FilterLicensePlateDetectionConfig(
  model_path="./model.pth",
  write_detections_to_json=True,
  output_json_path="./output/detections.json",
  forward_detection_rois=True,
  roi_output_label="license_plate_roi"
)

🧠 Output Behavior​

  • frame.data['license_plate_detection'] includes detection results
  • If write_detections_to_json = True, a JSONL log is appended with per-frame entries
  • If forward_detection_rois = True, polygons are added under frame.data['meta'][roi_output_label]
  • Frames marked with meta.skip_plate_detection = True are skipped silently

🧩 Integration​

Use the filter directly:

from filter_license_plate_detection.filter import FilterLicensePlateDetection
FilterLicensePlateDetection.run()

Or as part of a multi-stage pipeline:

Filter.run_multi([
    (VideoIn, {...}),
    (FilterLicensePlateDetection, {...}),
    (Webvis, {...})
])

🧼 Notes​

  • The model is loaded onto GPU if available, otherwise CPU
  • Model must have exactly 2 classes: background and license plate
  • Polygon ROI forwarding uses [x1, y1, x2, y1, x2, y2, x1, y2] ordering
  • Output JSON file is opened in append mode and flushed per frame

For contribution and development guidelines, see the CONTRIBUTING guide.