Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -231,3 +231,8 @@ CODEX.md
.copilot/
graphify-out/
*.pt

# Local working docs and benchmark artifacts (kept out of the repo)
*.local.md
*.local.py
sweep-results/
23 changes: 21 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ roi_polygon: null # Optional detection zone (defaults to source_point
model_override: null # Optional YOLO model override (e.g. "yolov8m.pt")
confidence_override: null # Optional confidence threshold override
min_detections: 10 # Minimum detections to report a valid speed
min_displacement_m: 0.0 # Minimum real-world travel (meters); 0 disables
smoothing_window: 5 # Moving average window for position smoothing
speed_calibration_factor: 1.0 # Multiply all speeds by this value
speed_range: # Discard speeds outside this range
Expand Down Expand Up @@ -218,6 +219,7 @@ All speeds for that camera will be multiplied by this factor. Do 2-3 passes at d

**Filtering settings:**
- `min_detections: 10` - a vehicle tracked for only 2-3 frames produces unreliable speed. 10+ detections gives stable estimates.
- `min_displacement_m` - a track must physically travel this many meters to count. Parked vehicles with jittery bounding boxes fragment into short tracks that read as plausible 3-10 mph "vehicles"; a floor of 5-10m (for a 30m+ calibrated zone) removes them without penalizing fast vehicles the way a higher `min_detections` would. Default 0 (disabled) for backward compatibility.
- `smoothing_window: 5` - reduces bounding box jitter between frames. Higher values = smoother but may round off genuine speed changes. 3-7 is the sweet spot.
- `speed_range` - set `max_mph` to something reasonable for your road (residential: 45, collector: 55, highway: 85). This filters out tracking glitches that show 200+ mph.

Expand All @@ -235,7 +237,8 @@ Server settings in `configs/server.yaml` or via `CLOCKD_` environment variables:
|---------|---------|-------------|
| `host` | `0.0.0.0` | Bind address |
| `port` | `8000` | Bind port |
| `detection_backend` | `local` | `"local"`, `"roboflow"`, `"localai"`, or `"codeproject_ai"` |
| `detection_backend` | `local` | `"local"`, `"roboflow"`, `"localai"`, `"codeproject_ai"`, or `"coralapi"` |
| `detection_fallback` | `none` | `"local"` to fall back to local CPU inference when a remote backend is unreachable |
| `model` | `yolo26n.pt` | Default YOLO model (local backend only) |
| `confidence` | `0.3` | Detection confidence threshold |
| `default_unit` | `mph` | Speed unit (`mph` or `kmh`) |
Expand Down Expand Up @@ -286,11 +289,13 @@ All remote backends offload detection to an external server. Clockd sends each f
| **[Roboflow Inference](https://github.com/roboflow/inference)** | YOLO v8/v10/v11/26, RF-DETR, YOLO-NAS | CUDA + TensorRT | No | Linux, macOS | Very active (daily commits) | GPU server, best model selection |
| **[LocalAI](https://github.com/mudler/localai)** | RF-DETR | CUDA, ROCm, Vulkan | No | Linux, macOS, Windows | Very active (monthly releases) | Already running LocalAI for LLMs |
| **[CodeProject.AI](https://github.com/codeproject/CodeProject.AI-Server)** | YOLOv5, v8, v11 | CUDA | Yes (YOLOv5 TFLite) | Windows, Linux, macOS | Slow (last release Dec 2024) | Raspberry Pi + Coral TPU |
| **[coralapi](https://github.com/nathan-v/coralapi)** | Edge TPU `.tflite` (SSD MobileNet, EfficientDet) | No (TPU only) | Yes (native) | Linux | Active | Dedicated Coral TPU, lowest power |

**Notes:**
- **Roboflow Inference** is the recommended remote backend. Broadest model support, actively maintained, no API key needed for pre-trained COCO models, and supports TensorRT quantization for maximum GPU throughput. Runs on Linux and macOS only (Docker-based). For GPU use, Linux with the NVIDIA Container Toolkit is recommended.
- **LocalAI** only supports RF-DETR for object detection (not YOLO). It's a good choice if you already run LocalAI for other AI tasks. Supports the widest range of GPU vendors (NVIDIA, AMD, Intel).
- **CodeProject.AI** is the only backend with Coral TPU support, via its YOLOv5 TFLite module. This makes it a viable option for low-power deployments like a Raspberry Pi with a Coral accelerator. The project has slowed (volunteer-maintained, 18+ months since last release) but remains functional.
- **CodeProject.AI** supports Coral TPUs via its YOLOv5 TFLite module. The project has slowed (volunteer-maintained, 18+ months since last release) but remains functional.
- **coralapi** is a purpose-built Edge TPU inference server (sync/async API, per-request model selection, automatic model download, no GPU required). It serves quantized Edge TPU `.tflite` models — expect SSD-MobileNet-class accuracy, below the larger YOLO models, at single-digit-watt power draw. Detections return normalized boxes, so `coralapi.resize_max_px` costs no accuracy on this backend.
- For most users, **local + `yolo26n.pt` on CPU** is fast enough. Remote backends are worth it for larger models on GPU, high-volume processing, or shared inference across multiple services.

##### Backend Configuration
Expand Down Expand Up @@ -329,6 +334,20 @@ codeproject_ai:
timeout: 30
```

**coralapi:**

```yaml
detection_backend: "coralapi"

coralapi:
url: "http://localhost:8000"
model: "ssd_mobilenet_v2_coco_quant_postprocess_edgetpu"
timeout: 30
resize_max_px: 640 # optional; Edge TPU models run at ~300px anyway
```

Start the server (Coral Edge TPU required): see the [coralapi quickstart](https://github.com/nathan-v/coralapi#quickstart-docker).

## Event Sources (NVR Integration)

Clockd can automatically poll your NVR for vehicle detection events, download clips, and process them — no external automation needed.
Expand Down
17 changes: 17 additions & 0 deletions configs/server.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ host: "0.0.0.0"
port: 8000
verbose: false
detection_backend: "local" # "local", "roboflow", "localai", or "codeproject_ai"
# Optional: fall back to local CPU inference (using `model`) when a remote
# detection backend is unreachable. "none" (default) keeps the old behavior
# of logging and yielding empty detections.
# detection_fallback: "local"
model: "yolo26n.pt"
confidence: 0.3
default_unit: "mph"
Expand All @@ -26,6 +30,19 @@ roboflow:
url: "http://localhost:9001"
model_id: "yolo11n-640"
timeout: 30
# Optional: downscale frames to this longest-side size before sending.
# The server resizes to the model input anyway; enabling this trades a
# little local CPU for much smaller uploads. Omit to send full frames.
# resize_max_px: 640

# coralapi Edge TPU server (https://github.com/nathan-v/coralapi)
coralapi:
url: "http://localhost:8000"
model: "ssd_mobilenet_v2_coco_quant_postprocess_edgetpu"
timeout: 30
# Edge TPU SSD models run at 300x300; downscaling before upload saves
# bandwidth with no accuracy cost (boxes are returned normalized).
# resize_max_px: 640

localai:
url: "http://localhost:8080"
Expand Down
48 changes: 46 additions & 2 deletions src/clockd/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
import re

import yaml
from pydantic import BaseModel, field_validator
from pydantic import BaseModel, Field, field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict

SAFE_ID_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
Expand Down Expand Up @@ -99,6 +99,13 @@ class CameraConfig(BaseModel):
min_detections: int = 10
smoothing_window: int = 5
speed_range: SpeedRange = SpeedRange()
# Minimum real-world distance (meters) a track must travel to count as a
# vehicle. Stationary vehicles with jittery bounding boxes fragment into
# short tracks whose small net movement over a short window reads as a
# plausible low speed; a displacement floor removes those without
# penalizing fast vehicles the way a higher min_detections would.
# 0 disables the filter.
min_displacement_m: float = 0.0
speed_calibration_factor: float = 1.0 # multiply all speeds by this value

@field_validator("confidence_override")
Expand All @@ -115,6 +122,13 @@ def validate_min_detections(cls, v: int) -> int:
raise ValueError("min_detections must be between 2 and 10000")
return v

@field_validator("min_displacement_m")
@classmethod
def validate_min_displacement(cls, v: float) -> float:
if v < 0 or v > 1000:
raise ValueError("min_displacement_m must be between 0 and 1000 meters")
return v

@field_validator("smoothing_window")
@classmethod
def validate_smoothing_window(cls, v: int) -> int:
Expand Down Expand Up @@ -148,6 +162,11 @@ class RoboflowInferenceConfig(BaseModel):
url: str = "http://localhost:9001"
model_id: str = "yolo11n-640"
timeout: int = 30
# Downscale frames so their longest side is at most this many pixels before
# sending to the inference server. The server resizes to the model input size
# anyway, so this trades local resize CPU for much smaller encode/transfer
# payloads. None sends full-resolution frames (pushes all work to the server).
resize_max_px: Optional[int] = Field(default=None, ge=64, le=8192)


class LocalAIConfig(BaseModel):
Expand All @@ -156,6 +175,18 @@ class LocalAIConfig(BaseModel):
timeout: int = 30


class CoralAPIConfig(BaseModel):
"""coralapi Edge TPU inference server (https://github.com/nathan-v/coralapi)."""

url: str = "http://localhost:8000"
model: str = "ssd_mobilenet_v2_coco_quant_postprocess_edgetpu"
timeout: int = 30
# Same semantics as roboflow.resize_max_px: downscale before upload.
# Edge TPU SSD models run at 300x300, so full-res frames are pure
# transfer overhead; boxes come back normalized, so no accuracy cost.
resize_max_px: Optional[int] = Field(default=None, ge=64, le=8192)


class UnifiProtectConfig(BaseModel):
host: str = ""
username: str = ""
Expand Down Expand Up @@ -232,7 +263,19 @@ def settings_customise_sources(
host: str = "0.0.0.0"
port: int = 8000
verbose: bool = False # enable detailed logging of processing results
detection_backend: str = "local" # "local", "roboflow", "localai", or "codeproject_ai"
detection_backend: str = "local" # "local", "roboflow", "localai", "codeproject_ai", "coralapi"
# "local": if a remote detection_backend is unreachable, fall back to
# local CPU inference (using `model`) for the rest of the job. "none":
# unreachable backends yield empty detections (logged) as before.
detection_fallback: str = "none"

@field_validator("detection_fallback")
@classmethod
def _validate_detection_fallback(cls, v: str) -> str:
if v not in ("none", "local"):
raise ValueError("detection_fallback must be 'none' or 'local'")
return v

model: str = "yolo26n.pt" # validated at startup, must be in ALLOWED_MODELS

@field_validator("model")
Expand All @@ -253,6 +296,7 @@ def validate_model(cls, v: str) -> str:
codeproject_ai: CodeProjectAIConfig = CodeProjectAIConfig()
roboflow: RoboflowInferenceConfig = RoboflowInferenceConfig()
localai: LocalAIConfig = LocalAIConfig()
coralapi: CoralAPIConfig = CoralAPIConfig()
metrics: MetricsConfig = MetricsConfig()
event_sources: dict[str, UnifiEventSourceConfig] = {}

Expand Down
4 changes: 4 additions & 0 deletions src/clockd/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ class ProcessingResult(BaseModel):
vehicles_filtered: int = 0 # tracks excluded by min_detections or speed_range
processing_time_s: float
warnings: list[str] = []
# what actually performed detection (reflects fallback, not just config)
detection_backend: str = ""
detection_model: str = ""
detection_fallback: bool = False


class JobStatus(str, Enum):
Expand Down
Loading
Loading