detections/_docs/00_problem/acceptance_criteria.md

Acceptance Criteria

Detection Accuracy

• Detections with confidence below probability_threshold (default: 0.25) are filtered out.
• Overlapping detections with containment ratio > tracking_intersection_threshold (default: 0.6) are deduplicated, keeping the higher-confidence detection.
• Tile duplicate detections are identified when all bounding box coordinates differ by less than 0.01 (TILE_DUPLICATE_CONFIDENCE_THRESHOLD).
• Physical size filtering: detections exceeding max_object_size_meters for their class (defined in classes.json, range 2–20 meters) are removed.

Video Processing

• Frame sampling: every Nth frame processed, controlled by frame_period_recognition (default: 4).
• Minimum annotation interval: frame_recognition_seconds (default: 2 seconds) between reported annotations.
• Tracking: new annotation accepted if any detection moved beyond tracking_distance_confidence threshold or confidence increased beyond tracking_probability_increase.

Image Processing

• Images ≤ 1.5× model dimensions (1280×1280): processed as single frame.
• Larger images: tiled based on ground sampling distance. Tile physical size: 25 meters (METERS_IN_TILE). Tile overlap: big_image_tile_overlap_percent (default: 20%).
• GSD calculation: sensor_width * altitude / (focal_length * image_width).

API

• GET /health always returns status: "healthy" (even if engine is unavailable — aiAvailability indicates actual state).
• POST /detect returns detection results synchronously. Errors: 400 (empty/invalid image), 422 (runtime error), 503 (engine unavailable).
• POST /detect/{media_id} returns immediately with {"status": "started"}. Rejects duplicate media_id with 409.
• GET /detect/stream delivers SSE events with mediaStatus values: AIProcessing, AIProcessed, Error.
• SSE queue maximum depth: 100 events per client. Overflow is silently dropped.

Engine Lifecycle

• Engine initialization is lazy (first detection request, not startup).
• Status transitions: NONE → DOWNLOADING → (CONVERTING → UPLOADING →) ENABLED | WARNING | ERROR.
• GPU check: NVIDIA GPU with compute capability ≥ 6.1.
• TensorRT conversion uses FP16 precision when GPU supports fast FP16.
• Background conversion does not block API responsiveness.

Logging

• Log files: Logs/log_inference_YYYYMMDD.txt.
• Rotation: daily.
• Retention: 30 days.
• Console: INFO/DEBUG/SUCCESS to stdout, WARNING+ to stderr.

Object Classes

• 19 base detection classes defined in classes.json.
• 3 weather modes (Norm, Wint, Night) — total up to 57 class variants.
• Each class has: Id, Name, Color, MaxSizeM (max physical size in meters).