> For the complete documentation index, see [llms.txt](https://docs.degirum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.degirum.com/vehicle-analytics/guides/overview-1/configuration.md).

# Configuration

## Configuration Inheritance

`LicensePlateTrackerConfig` extends `LicensePlateRecognizerConfig` and inherits all base settings:

* Model specifications - License plate detection and OCR models (device\_type, inference\_host\_address)
* OCR score threshold - Minimum confidence to display plate text (0.0-1.0)
* Show OCR score - Whether to display OCR confidence percentage

See [LicensePlateRecognizer Configuration](https://docs.degirum.com/vehicle-analytics/guides/overview/configuration.md) for details on these settings.

## Configuration Parameters

LicensePlateTracker adds the following tracking-specific parameters:

### Video Source

Parameters:

* `video_source` - Input video source (default: 0 for first webcam):
  * Integer (e.g., `0`, `1`) - Local webcam index
  * String path (e.g., `"highway.mp4"`) - Video file
  * RTSP URL (e.g., `"rtsp://192.168.1.100/stream"`) - IP camera
* `video_source_fps_override` (optional) - Override frame rate when camera reports incorrect FPS (default: 0.0 = no override)
* `video_source_resolution_override` (optional) - Override resolution as `(width, height)` tuple when camera reports incorrect dimensions (default: (0, 0) = no override)

### Credence Count

Controls when a detected license plate is confirmed as a valid track for processing.

Parameter:

* `credence_count` - Number of consecutive frames a plate must appear before being confirmed (default: 4). Reduces false positives from momentary detections or camera noise.

Recommended values:

* `2-4` - Real-time monitoring (quick confirmation)
* `5-10` - High-traffic areas (reduce false positives)
* `10+` - Critical applications (maximum stability)

### Alert Mode and Notifications

Controls when alerts are triggered and how notifications are delivered.

Parameters:

* `alert_mode` - When to trigger alerts (default: AlertMode.NONE):
  * `AlertMode.NONE` - No alerts
  * `AlertMode.ON_UNKNOWNS` - Alert when unknown plate detected
  * `AlertMode.ON_KNOWNS` - Alert when known plate detected
  * `AlertMode.ON_ALL` - Alert for all plates
* `alert_once` (bool) - Alert once per track (True) or every time plate text changes for the given track ID (False) (default: True)
* `clip_duration` (int) - Length of video clips in frames (default: 100, e.g., 100 frames ≈ 3.3 seconds at 30 FPS)
* `notification_config` (str) - Apprise configuration string for notification delivery
* `notification_message` (str) - Message template with variables: `${time}`, `${plate_alerts}`, `${filename}`, `${url}`
* `notification_timeout_s` (float, optional) - Timeout in seconds for sending notifications

Apprise notification examples:

* Email: `"mailto://user:pass@gmail.com"`
* Slack: `"slack://token/channel"`
* Discord: `"discord://webhook_id/webhook_token"`
* SMS (Twilio): `"twilio://account_sid:auth_token@from_phone/to_phone"`
* Console: `"console://"` (testing)

See [Apprise documentation](https://github.com/caronc/apprise) for all supported services.

### Clip Storage

Configuration for saving video clips to S3-compatible storage or local filesystem.

See [Object Storage Configuration Reference](https://docs.degirum.com/degirum-tools/object_storage_config) for complete documentation including:

* Parameters (endpoint, bucket, access\_key, etc.)
* Storage backend examples (AWS S3, MinIO, local filesystem)
* Environment-specific configurations
* Best practices

### Alerting and Storage Combinations

**Important:** Both notifications and clip recording only trigger when alerts are generated. If `alert_mode=AlertMode.NONE`, no alerts are generated, so notifications and clip recording will not happen even if configured.

| alert\_mode  | clip\_duration | notification\_config | Result                                     |
| ------------ | -------------- | -------------------- | ------------------------------------------ |
| NONE         | any            | any                  | No alerts, no clips, no notifications      |
| ON\_ALL      | > 0            | configured           | Alert + clip + notification for all plates |
| ON\_UNKNOWNS | 0              | configured           | Alert + notification only (no clips)       |

### Live Streaming

Controls video output display.

Parameters:

* `live_stream_mode` - Output mode:
  * `"LOCAL"` - Display in local window
  * `"WEB"` - Stream via RTSP for web viewing
  * `"NONE"` - No live display
* `live_stream_rtsp_url` (str, optional) - RTSP URL path suffix (used when mode is `"WEB"`)

### Zone Filtering

Controls zone-based filtering for license plates.

Parameters:

* `enable_zone_filter` (bool) - Enable zone-based filtering (default: False)
* `zone` (list) - Zone polygon as list of \[x, y] coordinate pairs. Minimum 3 points required. Example: `[[100, 200], [500, 200], [500, 600], [100, 600]]`

## Configuration Options

### Option 1: Python Configuration

### Option 1: Python Configuration

```python
import degirum_vehicle
import degirum_tools

config = degirum_vehicle.LicensePlateTrackerConfig(
    # Models (using model registry)
    license_plate_detection_model_spec=degirum_vehicle.get_license_plate_detection_model_spec(
        device_type="HAILORT/HAILO8",
        inference_host_address="@cloud"
    ),
    license_plate_ocr_model_spec=degirum_vehicle.get_license_plate_ocr_model_spec(
        device_type="HAILORT/HAILO8",
        inference_host_address="@cloud"
    ),
    
    # OCR settings
    show_ocr_score=True,
    ocr_score_threshold=0.6,
    
    # Video source
    video_source="rtsp://192.168.1.100/stream",
    
    # Tracking
    credence_count=4,
    
    # Alerting
    alert_mode=degirum_vehicle.AlertMode.ON_ALL,
    alert_once=True,
    clip_duration=100,
    
    # Clip storage
    clip_storage_config=degirum_tools.ObjectStorageConfig(
        endpoint="./lpr_clips",
        bucket="plates"
    ),
    
    # Notifications
    notification_config="mailto://alerts@company.com",
    notification_message="🚗 ${time}: Plate detected: ${plate_alerts}",
    notification_timeout_s=10.0,
    
    # Live display
    live_stream_mode="WEB",
    live_stream_rtsp_url="lpr_feed",
)

tracker = degirum_vehicle.LicensePlateTracker(config)
```

### Option 2: YAML Configuration

`LicensePlateTrackerConfig` can be initialized from a YAML file or string using the `from_yaml()` method. This approach separates configuration from code, making it easier to version control settings, share configurations across teams, and maintain different configs for development, staging, and production environments.

Complete YAML structure:

```yaml
# License plate detection model
license_plate_detection_model:
  hardware: HAILORT/HAILO8
  inference_host_address: "@cloud"
  
# License plate OCR model
license_plate_ocr_model:
  hardware: HAILORT/HAILO8
  inference_host_address: "@cloud"

# OCR settings
show_ocr_score: true
ocr_score_threshold: 0.6

# Video source
video_source: "rtsp://192.168.1.100/stream"
video_source_fps_override: 0.0              # 0 = use source FPS (no override)
video_source_resolution_override: [0, 0]    # [0, 0] = use source resolution (no override)

# Tracking
credence_count: 4

# Alerting
alerts:
  alert_mode: ON_ALL                        # NONE, ON_UNKNOWNS, ON_KNOWNS, ON_ALL
  alert_once: true
  clip_duration: 100
  notification_config: "mailto://alerts@company.com"
  notification_message: "🚗 ${time}: Plate detected: ${plate_alerts}"
  notification_timeout_s: 10.0

# Clip storage
storage:
  endpoint: "./lpr_clips"
  access_key: ""
  secret_key: ""
  bucket: "plates"
  url_expiration_s: 3600

# Zone filtering
enable_zone_filter: false
zone: []

# Live streaming
live_stream:
  mode: WEB                                 # LOCAL, WEB, NONE
  rtsp_url: "lpr_feed"
```

#### Loading from YAML

```python
import degirum_vehicle

config, _ = degirum_vehicle.LicensePlateTrackerConfig.from_yaml(yaml_file="lpr_tracking.yaml")
tracker = degirum_vehicle.LicensePlateTracker(config)
```

Returns:

* `config` - Initialized `LicensePlateTrackerConfig` object
* `settings` - Raw dictionary (useful for debugging)

#### Loading from YAML String

```python
import degirum_vehicle

yaml_string = """
license_plate_detection_model:
  hardware: HAILORT/HAILO8
  inference_host_address: "@cloud"
license_plate_ocr_model:
  hardware: HAILORT/HAILO8
  inference_host_address: "@cloud"
video_source: 0
alerts:
  alert_mode: ON_ALL
"""

config, _ = degirum_vehicle.LicensePlateTrackerConfig.from_yaml(yaml_str=yaml_string)
tracker = degirum_vehicle.LicensePlateTracker(config)
```

#### Benefits of YAML

* Clean separation - Config separate from code
* Easy modification - Change hardware without editing code
* Version control - Track config changes in git
* Team collaboration - Share standardized configs
* Multiple environments - dev.yaml, staging.yaml, prod.yaml

## Configuration Examples

### Example 1: Parking Lot Monitoring

Monitor RTSP camera, alert on all plates, save clips, send email:

```python
import degirum_vehicle
import degirum_tools

config = degirum_vehicle.LicensePlateTrackerConfig(
    license_plate_detection_model_spec=degirum_vehicle.get_license_plate_detection_model_spec(
        device_type="HAILORT/HAILO8",
        inference_host_address="@cloud"
    ),
    license_plate_ocr_model_spec=degirum_vehicle.get_license_plate_ocr_model_spec(
        device_type="HAILORT/HAILO8",
        inference_host_address="@cloud"
    ),
    video_source="rtsp://192.168.1.100/stream",
    credence_count=4,
    alert_mode=degirum_vehicle.AlertMode.ON_ALL,
    alert_once=True,
    clip_duration=150,
    clip_storage_config=degirum_tools.ObjectStorageConfig(
        endpoint="./parking_clips",
        bucket="all_plates"
    ),
    notification_config="mailto://security@company.com",
    notification_message="⚠️ Plate detected at ${time}: ${plate_alerts}",
    live_stream_mode="WEB",
    live_stream_rtsp_url="parking_feed",
)

tracker = degirum_vehicle.LicensePlateTracker(config)
```

### Example 2: Local Video File Processing

Process local video file, display locally:

```python
config = degirum_vehicle.LicensePlateTrackerConfig(
    license_plate_detection_model_spec=degirum_vehicle.get_license_plate_detection_model_spec(
        device_type="TFLITE/CPU",
        inference_host_address="@cloud"
    ),
    license_plate_ocr_model_spec=degirum_vehicle.get_license_plate_ocr_model_spec(
        device_type="TFLITE/CPU",
        inference_host_address="@cloud"
    ),
    video_source="highway_traffic.mp4",
    alert_mode=degirum_vehicle.AlertMode.NONE,
    live_stream_mode="LOCAL",
    show_ocr_score=True,
)

tracker = degirum_vehicle.LicensePlateTracker(config)
```

### Example 3: High-Traffic Zone Filtering

Reduce false positives with zone filtering and higher credence:

```python
config = degirum_vehicle.LicensePlateTrackerConfig(
    license_plate_detection_model_spec=degirum_vehicle.get_license_plate_detection_model_spec(
        device_type="HAILORT/HAILO8",
        inference_host_address="@cloud"
    ),
    license_plate_ocr_model_spec=degirum_vehicle.get_license_plate_ocr_model_spec(
        device_type="HAILORT/HAILO8",
        inference_host_address="@cloud"
    ),
    video_source="rtsp://toll-camera/stream",
    credence_count=8,  # Higher confirmation threshold
    alert_mode=degirum_vehicle.AlertMode.ON_ALL,
    enable_zone_filter=True,
    zone=[[100, 200], [800, 200], [800, 600], [100, 600]],  # Define detection zone
    live_stream_mode="LOCAL",
)

tracker = degirum_vehicle.LicensePlateTracker(config)
```
