# Basic Concepts

## What Can You Do With degirum-vehicle?

`degirum-vehicle` enables license plate recognition workflows across images and video:

* **Detect and recognize** license plates in photos, video files, and live streams
* **Track vehicles** across video frames with persistent IDs
* **Improve accuracy** via Bayesian multi-frame text aggregation
* **Real-time alerts** when license plates are detected
* **Batch processing** for large image collections
* **Automated clip extraction** for detected vehicles

All with minimal code and flexible deployment options.

## Deployment Options

### Where Can It Run?

The `inference_host_address` parameter controls where your models execute:

| Option               | Description                                               | Best For                                                    |
| -------------------- | --------------------------------------------------------- | ----------------------------------------------------------- |
| **Cloud (`@cloud`)** | Models run on DeGirum's cloud servers                     | Quick start, experimentation, trying different hardware     |
| **Local (`@local`)** | Models run on your machine                                | Production, lowest latency, full privacy, offline operation |
| **AI Server**        | Models run on a dedicated server (e.g., `server-ip:port`) | Centralized GPU/accelerator resources on your network       |

**Cloud** is ideal for getting started quickly without hardware setup. **Local** gives you complete control and privacy. **AI Server** lets you share powerful hardware across multiple applications. See [AI Server Setup Guide](https://docs.degirum.com/pysdk/user-guide-pysdk/setting-up-an-ai-server) for server deployment.

### What Hardware Is Supported?

The `device_type` parameter specifies which accelerator to use. The following hardware platforms are supported (listed in alphabetical order by vendor):

| Hardware Platform  | Device Types                                                                               | Description                           |
| ------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------- |
| **CPU**            | `TFLITE/CPU`                                                                               | Standard CPU inference (baseline)     |
| **Axelera Metis**  | `AXELERA/METIS`                                                                            | Axelera Metis AI accelerator          |
| **DeepX**          | `DEEPX/M1A`                                                                                | DeepX M1A accelerator                 |
| **DeGirum Orca**   | `N2X/ORCA1`                                                                                | DeGirum Orca AI accelerator           |
| **Google Coral**   | `TFLITE/EDGETPU`                                                                           | Google Coral Edge TPU                 |
| **Hailo**          | <p><code>HAILORT/HAILO8</code><br><code>HAILORT/HAILO8L</code></p>                         | Hailo-8 and Hailo-8L AI accelerators  |
| **Intel OpenVINO** | <p><code>OPENVINO/CPU</code><br><code>OPENVINO/GPU</code><br><code>OPENVINO/NPU</code></p> | Intel CPUs, integrated GPUs, and NPUs |

See [DeGirum PySDK Installation](https://docs.degirum.com/pysdk/installation) for platform requirements and [Runtimes & Drivers](https://docs.degirum.com/pysdk/runtimes-and-drivers) for hardware-specific setup.

### Discovering Available Hardware

Use helper functions to check what's supported and available before configuring:

```python
# See all supported hardware platforms
supported = degirum_vehicle.model_registry.get_hardware()

# Check what's available on cloud or local
available = degirum_vehicle.get_system_hw("@cloud")

# Find compatible hardware you can use right now
compatible = degirum_vehicle.get_compatible_hw("@cloud")
```

## Model Registry

`degirum-vehicle` includes a curated **model registry** - a collection of pre-optimized license plate detection and OCR models for various hardware platforms. The registry automatically selects the best model for your chosen hardware, eliminating the need to manually pick models or tune parameters.

Helper functions like `get_license_plate_detection_model_spec()` and `get_license_plate_ocr_model_spec()` query this registry to get optimized models for your hardware. For complete control, you can also provide custom models outside the registry.

## Core Components

`degirum-vehicle` provides three main components:

**LicensePlateRecognizer** - For static images and batch processing

* Process photos or image collections
* Detect and recognize license plates
* One-time batch recognition

**LicensePlateTracker** - For video streams and real-time monitoring

* Monitor live camera feeds or video files
* Track vehicles across frames with persistent IDs
* Bayesian multi-frame text aggregation for improved accuracy
* Generate real-time alerts and automated clip extraction

**LPRClipManager** - For managing saved video clips

* List and retrieve video clips from object storage (S3 or local)
* Access clips recorded by LicensePlateTracker alerts
* Download and manage alert recordings

***

Before diving into the component-specific guides, let's understand the underlying recognition pipeline that powers all these tools.

## The Recognition Pipeline

Both LicensePlateRecognizer and LicensePlateTracker use the same core pipeline for processing license plates:

```
┌─────────────┐     ┌──────────────────┐     ┌──────────────┐     ┌──────────────┐
│ Input Image │ ──> │ License Plate    │ ──> │   Crop &     │ ──> │     OCR      │
│             │     │   Detection      │     │   Extract    │     │  Extraction  │
└─────────────┘     └──────────────────┘     └──────────────┘     └──────────────┘
```

### 1. License Plate Detection

Locates license plates in the image and provides bounding boxes for each detected plate.

**Output:** Bounding box coordinates per plate

### 2. Cropping & Extraction

Extracts each detected license plate region and resizes to standard OCR input size.

**Output:** Cropped plate image (typically 256×128 pixels)

### 3. OCR Extraction

Converts the cropped plate image into recognized text using character detection.

**Output:** Plate text string + confidence score

### 4. Bayesian Aggregation (Tracker Only)

For video streams, combines OCR results across multiple frames using exponential moving average of character probabilities.

**Output:** Aggregated text + confidence score per vehicle track

### Additional Capabilities

**Zone Filtering** (optional) - Applied after detection to process only plates within specified polygon regions. See [Vehicle Filters Reference](https://docs.degirum.com/vehicle-analytics/reference/vehicle-filters).

**Tracking** (LicensePlateTracker only) - Maintains persistent IDs for vehicles across video frames using visual tracking. Enables features like trajectory tracking, temporal consistency, and multi-frame text fusion.

**Alert & Recording** (LicensePlateTracker only) - Triggers events when license plates are detected and automatically records video clips to object storage (S3 or local filesystem).

## Understanding Results

Results are returned as `LPRResult` objects containing detected plates with their text and metadata:

```python
result = lpr.predict("car.jpg")

for plate in result.license_plates:
    print(f"Plate: {plate.plate_number} (OCR: {plate.ocr_score:.2f})")
```

**Key properties:**

* `plate_number` - Recognized text (or `None` if unreadable)
* `ocr_score` - OCR confidence (0.0-1.0)
* `detection_score` - Detection confidence (0.0-1.0)
* `bbox` - Plate bounding box

See [LPR Data Classes Reference](https://docs.degirum.com/vehicle-analytics/reference/lpr-data) for complete property list and usage examples.

***

## Next Steps

Now that you understand deployment options, hardware support, the core components, and how the recognition pipeline works, you're ready to start using degirum-vehicle.

**Choose your path:**

* **Process images or batches** → [LP Recognizer Guide](https://docs.degirum.com/vehicle-analytics/guides/overview)
* **Monitor video streams** → [LP Tracker Guide](https://docs.degirum.com/vehicle-analytics/guides/overview-1)
* **Learn about models** → [LPR Models](https://docs.degirum.com/vehicle-analytics/reference/models)