# Vehicle Filters

## Overview

License plate filters act as **quality gates** that skip detections outside specified regions. Proper filtering improves both accuracy and performance by focusing processing on relevant areas and reducing unnecessary computation.

### Why Use Filters?

Not every detected license plate should be processed:

* **Outside region of interest** - Ignore vehicles in irrelevant areas
* **Background traffic** - Focus on specific lanes or zones
* **Parking areas** - Monitor specific parking spots only

Filters improve result quality and prevent wasted compute.

## Zone Filter

Only processes license plates within a specified polygon region.

### Configuration

```python
# Define rectangular zone
zone = [
    [100, 100],   # Top-left corner (x, y)
    [500, 100],   # Top-right corner
    [500, 400],   # Bottom-right corner
    [100, 400]    # Bottom-left corner
]

config = degirum_vehicle.LicensePlateTrackerConfig(
    enable_zone_filter=True,
    zone=zone  # List of [x, y] coordinates (min 3 points)
)
```

### Parameters

* **`enable_zone_filter`** (bool) - Enable/disable the filter (default: False)
* **`zone`** (list of \[x, y]) - Polygon vertices defining the region of interest. Can be any polygon with 3 or more points (triangle, quadrilateral, pentagon, etc.), not limited to rectangles

### How It Works

License plate center point must be inside the polygon zone. Plates outside are skipped.

### When to Use

* Focus on specific areas (specific lane, parking spots, entrance/exit)
* Ignore vehicles outside region of interest
* Reduce false positives from background traffic

### Examples

**Rectangular zone:**

```python
# Rectangle from (100,100) to (500,400)
zone = [[100, 100], [500, 100], [500, 400], [100, 400]]
```

**Arbitrary polygon:**

```python
# Pentagonal zone for angled lane
zone = [[100, 200], [300, 100], [500, 200], [400, 400], [200, 400]]
```

**Entire frame (no filtering):**

```python
# Don't enable zone filter, or use full frame dimensions
zone = [[0, 0], [1920, 0], [1920, 1080], [0, 1080]]
```

**Single lane monitoring:**

```python
# Define zone for leftmost lane on highway
lane_zone = [
    [0, 400],      # Bottom-left
    [0, 200],      # Top-left
    [400, 250],    # Top-right (perspective)
    [400, 500]     # Bottom-right
]

config = degirum_vehicle.LicensePlateTrackerConfig(
    enable_zone_filter=True,
    zone=lane_zone
)
```

**Parking spot monitoring:**

```python
# Monitor specific parking spots (two zones would require multiple trackers)
spot_zone = [
    [300, 400],    # Define zone around parking spots
    [700, 400],
    [700, 600],
    [300, 600]
]

config = degirum_vehicle.LicensePlateTrackerConfig(
    enable_zone_filter=True,
    zone=spot_zone,
    alert_mode=degirum_vehicle.AlertMode.ON_ALL,  # Alert for all plates in zone
)
```

**Entrance/exit gate:**

```python
# Monitor gate area only
gate_zone = [
    [400, 300],
    [800, 300],
    [800, 700],
    [400, 700]
]

config = degirum_vehicle.LicensePlateTrackerConfig(
    enable_zone_filter=True,
    zone=gate_zone,
    notification_message="🚗 Vehicle entered: ${text} at ${time}"
)
```

## Configuration Methods

### Python Configuration

```python
import degirum_vehicle

config = degirum_vehicle.LicensePlateTrackerConfig(
    enable_zone_filter=True,
    zone=[[100, 100], [500, 100], [500, 400], [100, 400]]
)

tracker = degirum_vehicle.LicensePlateTracker(config)
```

### YAML Configuration

```yaml
enable_zone_filter: true
zone:
  - [100, 100]
  - [500, 100]
  - [500, 400]
  - [100, 400]
```

Load from YAML:

```python
import degirum_vehicle

config = degirum_vehicle.LicensePlateTrackerConfig.from_yaml("config.yaml")
tracker = degirum_vehicle.LicensePlateTracker(config)
```

## Performance Impact

Enabling zone filtering has minimal performance impact:

* **Computation:** Simple point-in-polygon check per detection
* **Accuracy:** Improves by focusing on relevant areas
* **Processing:** Reduces OCR calls for out-of-zone plates

**Recommendation:** Always use zone filtering in production to focus on relevant areas and improve result quality.