Component: Domain Models & Configuration

Overview

Purpose: Provides all data models, enums, constants, detection class registry, and logging infrastructure used across the system.

Pattern: Shared kernel — leaf-level types and utilities consumed by all other components.

Upstream: None (foundation layer). Downstream: Inference Engines, Inference Pipeline, API.

Modules

Module	Role
`constants_inf`	Application constants, logging, detection class registry from `classes.json`
`ai_config`	`AIRecognitionConfig` data class with factory methods
`ai_availability_status`	Thread-safe `AIAvailabilityStatus` tracker with `AIAvailabilityEnum`
`annotation`	`Detection` and `Annotation` data models

Internal Interfaces

constants_inf

cdef log(str log_message) -> void
cdef logerror(str error) -> void
cdef format_time(int ms) -> str
annotations_dict: dict[int, AnnotationClass]

ai_config

cdef class AIRecognitionConfig:
    @staticmethod cdef from_msgpack(bytes data) -> AIRecognitionConfig
    @staticmethod def from_dict(dict data) -> AIRecognitionConfig

ai_availability_status

cdef class AIAvailabilityStatus:
    cdef set_status(AIAvailabilityEnum status, str error_message=None)
    cdef bytes serialize()
    # __str__ for display

annotation

cdef class Detection:
    cdef overlaps(Detection det2, float confidence_threshold) -> bool
    # __eq__ for tile deduplication

cdef class Annotation:
    cdef bytes serialize()

External API

None — this is a shared kernel, not an externally-facing component.

Data Access Patterns

classes.json read once at module import time (constants_inf)
All data is in-memory, no database access

Implementation Details

Cython cdef classes for performance-critical detection processing
Thread-safe status tracking via threading.Lock in AIAvailabilityStatus
Detection.__eq__ uses coordinate proximity threshold for tile deduplication
Detection.overlaps uses containment-biased metric (overlap / min_area) rather than standard IoU
Weather mode system triples the class registry (Norm/Wint/Night offsets of 0/20/40)

Caveats

classes.json must exist in the working directory at import time — no fallback
Detection.__eq__ is designed specifically for tile deduplication, not general equality
annotations_dict is a module-level global — not injectable/configurable at runtime

Dependency Graph

graph TD
    ai_availability_status --> constants_inf
    annotation --> constants_inf
    ai_config
    constants_inf

Logging Strategy

All logging flows through constants_inf.log and constants_inf.logerror, which delegate to loguru with file rotation and console output.

2.7 KiB Raw Permalink Blame History