gps-denied-onboard/docs/02_components/17_configuration_manager/configuration_manager_spec.md

Configuration Manager

Interface Definition

Interface Name: IConfigurationManager

Interface Methods

class IConfigurationManager(ABC):
    @abstractmethod
    def load_config(self, config_path: str) -> SystemConfig:
        pass
    
    @abstractmethod
    def get_camera_params(self, camera_id: Optional[str] = None) -> CameraParameters:
        pass
    
    @abstractmethod
    def validate_config(self, config: SystemConfig) -> ValidationResult:
        pass
    
    @abstractmethod
    def get_flight_config(self, flight_id: str) -> FlightConfig:
        pass
    
    @abstractmethod
    def update_config(self, section: str, key: str, value: Any) -> bool:
        pass
    
    @abstractmethod
    def get_operational_altitude(self, flight_id: str) -> float:
        """Returns predefined operational altitude for the flight (NOT from EXIF)."""
        pass
    
    @abstractmethod
    def get_frame_spacing(self, flight_id: str) -> float:
        """Returns expected distance between consecutive frames in meters."""
        pass
    
    @abstractmethod
    def save_flight_config(self, flight_id: str, config: FlightConfig) -> bool:
        """Persists flight-specific configuration."""
        pass

Component Description

Responsibilities

• Load system configuration from files/environment
• Provide camera parameters (focal length, sensor size, resolution)
• Manage flight-specific configurations
• Validate configuration integrity
• Support configuration updates at runtime

Scope

• System-wide configuration
• Camera parameter management
• Operational area bounds
• Model paths and settings
• Database connections
• API endpoints

API Methods

load_config(config_path: str) -> SystemConfig

Description: Loads system configuration.

Called By: System startup

Input: config_path: str - Path to config file (YAML/JSON)

Output: SystemConfig - Complete configuration

Test Cases:

1. Load valid config → succeeds
2. Missing file → uses defaults
3. Invalid config → raises error

---

get_camera_params(camera_id: Optional[str] = None) -> CameraParameters

Description: Gets camera parameters.

Called By: All processing components

Output:

CameraParameters:
    focal_length: float
    sensor_width: float
    sensor_height: float
    resolution_width: int
    resolution_height: int
    principal_point: Tuple[float, float]
    distortion_coefficients: List[float]

Test Cases:

1. Get default camera → returns params
2. Get specific camera → returns params

---

validate_config(config: SystemConfig) -> ValidationResult

Description: Validates configuration.

Called By: After load_config

Validation Rules:

• Camera parameters sensible
• Paths exist
• Operational area valid
• Database connection string valid

Test Cases:

1. Valid config → passes
2. Invalid focal length → fails

---

get_flight_config(flight_id: str) -> FlightConfig

Description: Gets flight-specific configuration.

Called By: F02 Flight Manager

Output:

FlightConfig:
    camera_params: CameraParameters
    altitude: float
    operational_area: OperationalArea

Test Cases:

1. Get flight config → returns params

---

update_config(section: str, key: str, value: Any) -> bool

Description: Updates config at runtime.

Called By: Admin tools

Test Cases:

1. Update value → succeeds
2. Invalid key → fails

---

get_operational_altitude(flight_id: str) -> float

Description: Returns predefined operational altitude for the flight in meters. This is the altitude provided during flight creation, NOT extracted from EXIF metadata (images don't have GPS/altitude metadata per problem constraints).

Called By:

• F10 Factor Graph Optimizer (for scale resolution)
• H02 GSD Calculator (for GSD computation)
• F09 Metric Refinement (for alignment)

Input: flight_id: str

Output: float - Altitude in meters (typically 100-500m)

Test Cases:

1. Get existing flight altitude → returns value
2. Non-existent flight → raises error

---

get_frame_spacing(flight_id: str) -> float

Description: Returns expected distance between consecutive frames in meters. Used for scale estimation in visual odometry.

Called By:

• F10 Factor Graph Optimizer (for expected displacement calculation)

Input: flight_id: str

Output: float - Expected frame spacing in meters (typically ~100m)

Test Cases:

1. Get frame spacing → returns expected distance

---

save_flight_config(flight_id: str, config: FlightConfig) -> bool

Description: Persists flight-specific configuration when a flight is created.

Called By:

• F02 Flight Processor (during flight creation)

Input:

flight_id: str
config: FlightConfig

Output: bool - True if saved successfully

Test Cases:

1. Save valid config → succeeds
2. Invalid flight_id → fails

Data Models

SystemConfig

class SystemConfig(BaseModel):
    camera: CameraParameters
    operational_area: OperationalArea
    models: ModelPaths
    database: DatabaseConfig
    api: APIConfig

CameraParameters

class CameraParameters(BaseModel):
    focal_length: float  # mm
    sensor_width: float  # mm
    sensor_height: float  # mm
    resolution_width: int
    resolution_height: int
    principal_point: Tuple[float, float]
    distortion_coefficients: List[float]

OperationalArea

class OperationalArea(BaseModel):
    name: str = "Eastern Ukraine"
    min_lat: float = 45.0
    max_lat: float = 52.0
    min_lon: float = 22.0
    max_lon: float = 40.0

RecoveryConfig

class RecoveryConfig(BaseModel):
    """Configuration for failure recovery and progressive search."""
    search_grid_sizes: List[int] = [1, 4, 9, 16, 25]  # Progressive tile search grid
    min_chunk_frames_for_matching: int = 5  # Minimum frames before chunk matching
    max_chunk_frames_for_matching: int = 20  # Maximum frames per chunk
    user_input_threshold_tiles: int = 25  # Request user input after this many tiles
    chunk_matching_interval_seconds: float = 5.0  # Background matching interval
    confidence_threshold_good: float = 0.7  # Confidence for good tracking
    confidence_threshold_degraded: float = 0.5  # Confidence for degraded tracking
    min_inlier_count_good: int = 50  # Inliers for good tracking
    min_inlier_count_tracking: int = 20  # Minimum inliers before tracking loss

RotationConfig

class RotationConfig(BaseModel):
    """Configuration for image rotation and heading tracking."""
    rotation_step_degrees: float = 30.0  # Degrees per rotation step
    litesam_max_rotation_tolerance: float = 45.0  # Max rotation LiteSAM handles
    sharp_turn_threshold_degrees: float = 45.0  # Threshold for sharp turn detection
    heading_history_size: int = 10  # Number of headings to track
    confidence_threshold: float = 0.7  # For accepting rotation match
    
    @property
    def rotation_iterations(self) -> int:
        """Number of rotation steps (360 / step_degrees)."""
        return int(360 / self.rotation_step_degrees)

Dependencies

Internal Components

• F03 Flight Database: For flight-specific configuration persistence (save_flight_config stores to F03)

External Dependencies

• pydantic: Data model validation
• PyYAML: Configuration file parsing