# Tier1Detector

## 1. High-Level Overview

**Purpose**: Wraps YOLOE TensorRT FP16 inference. Takes a frame, runs detection + segmentation, returns detections with class labels, confidences, bounding boxes, and segmentation masks.

**Architectural Pattern**: Stateless inference wrapper (load once, call per frame).

**Upstream dependencies**: Config helper (engine path, class names), Types helper

**Downstream consumers**: ScanController

## 2. Internal Interfaces

### Interface: Tier1Detector

| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `load(engine_path, class_names)` | str, list[str] | — | No | EngineLoadError |
| `detect(frame)` | numpy array (H,W,3) | list[Detection] | No | InferenceError |
| `is_ready()` | — | bool | No | — |

**Detection output**:
```
centerX: float (0-1)
centerY: float (0-1)
width: float (0-1)
height: float (0-1)
classNum: int
label: str
confidence: float (0-1)
mask: numpy array (H,W) or None — segmentation mask for seg-capable classes
```

## 5. Implementation Details

**State Management**: Stateful only for loaded TRT engine (immutable after load). Inference is stateless.

**Key Dependencies**:

| Library | Version | Purpose |
|---------|---------|---------|
| TensorRT | JetPack 6.2 bundled | FP16 inference engine |
| Ultralytics | 8.4.x (pinned) | YOLOE model export + set_classes() |
| numpy | — | Frame and mask arrays |
| OpenCV | 4.x | Preprocessing (resize, normalize) |

**Preprocessing**: Matches existing pipeline — `cv2.dnn.blobFromImage` or equivalent, resize to model input resolution (1280px from config).

**Postprocessing**: YOLOE-26 is NMS-free (end-to-end). YOLOE-11 may need NMS. Handle both cases based on loaded engine metadata.

**Error Handling Strategy**:
- EngineLoadError: fatal at startup — cannot proceed without Tier 1
- InferenceError: non-fatal — ScanController skips the frame

## 7. Caveats & Edge Cases

**Known limitations**:
- set_classes() must be called before TRT export (open-vocab only in R&D mode)
- Backbone choice (11 vs 26) determined by config — must match the exported engine file

**Performance bottlenecks**:
- TRT FP16 inference: ~7ms (YOLO11s) to ~15ms (YOLO26s) at 640px on Orin Nano Super
- Frame preprocessing adds ~2-5ms

## 8. Dependency Graph

**Must be implemented after**: Config helper, Types helper
**Can be implemented in parallel with**: Tier2SpatialAnalyzer, VLMClient, GimbalDriver, OutputManager
**Blocks**: ScanController (needs Tier1 for main loop)

## 9. Logging Strategy

| Log Level | When | Example |
|-----------|------|---------|
| ERROR | Engine load failure, inference crash | `TRT engine load failed: /models/yoloe-11s-seg.engine` |
| WARN | Slow inference (>100ms) | `Tier1 inference took 142ms (frame 5678)` |
| INFO | Engine loaded, class count | `Tier1 loaded: yoloe-11s-seg, 8 classes, FP16` |
