# Module: ai_config

## Purpose

Data class holding all AI recognition configuration parameters, with factory methods for deserialization from msgpack and dict formats.

## Public Interface

### Class: AIRecognitionConfig

#### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `frame_period_recognition` | int | 4 | Process every Nth frame in video |
| `frame_recognition_seconds` | double | 2.0 | Minimum seconds between valid video annotations |
| `probability_threshold` | double | 0.25 | Minimum detection confidence |
| `tracking_distance_confidence` | double | 0.0 | Distance threshold for tracking (model-width units) |
| `tracking_probability_increase` | double | 0.0 | Required confidence increase for tracking update |
| `tracking_intersection_threshold` | double | 0.6 | IoU threshold for overlapping detection removal |
| `file_data` | bytes | `b''` | Raw file data (msgpack use) |
| `paths` | list[str] | `[]` | Media file paths to process |
| `model_batch_size` | int | 1 | Batch size for inference |
| `big_image_tile_overlap_percent` | int | 20 | Tile overlap percentage for large image splitting |
| `altitude` | double | 400 | Camera altitude in meters |
| `focal_length` | double | 24 | Camera focal length in mm |
| `sensor_width` | double | 23.5 | Camera sensor width in mm |

#### Methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `from_msgpack` | `(bytes data) -> AIRecognitionConfig` | Static cdef; deserializes from msgpack binary |
| `from_dict` | `(dict data) -> AIRecognitionConfig` | Static def; deserializes from Python dict |

## Internal Logic

Both factory methods apply defaults for missing keys. `from_msgpack` uses compact single-character keys (`f_pr`, `pt`, `t_dc`, etc.) while `from_dict` uses full descriptive keys.

**Legacy/unused**: `from_msgpack()` is defined but never called in the current codebase — it is a remnant of a previous queue-based architecture. Only `from_dict()` is actively used. The `file_data` field is stored but never read anywhere.

## Dependencies

- **External**: `msgpack`
- **Internal**: none (leaf module)

## Consumers

- `inference` — creates config from dict, uses all fields for frame selection, detection filtering, image tiling, and tracking

## Data Models

- `AIRecognitionConfig` — the sole data class

## Configuration

Camera/altitude parameters (`altitude`, `focal_length`, `sensor_width`) are used for ground sampling distance calculation in aerial image processing.

## External Integrations

None.

## Security

None.

## Tests

None found.