common package

The common package provides shared utilities and data structures used across the VISWIR project. It includes:

• Configuration loading and validation

• Core datatypes for fusion tasks and results

• Logging utilities

• Database access for results

• User interface helpers

This package is designed to centralize functionality that is reused by multiple modules (fusion, optimization, processing, realtime).

Submodules

common.config_loader module

Utility functions for reading and validating configuration files.

config_loader.py

Module centralisé pour charger et valider les fichiers de configuration (YAML ou JSON) utilisés dans VISWIR_vQuasar.

Ce fichier est conçu pour être extensible : - On peux ajouter de nouveaux fichiers de config (ex: logging_config.yaml). - On peux définir des clés obligatoires par contexte (fixed, sql, optuna…). - On peux fusionner plusieurs fichiers en un seul dictionnaire global.

Auteur : Alexandre Riffard

exception common.config_loader.ConfigError

Bases: Exception

Custom exception for configuration-related errors.

common.config_loader.load_all_configs(base_path: str | Path = 'config/config_viswir.yaml', params_path: str | Path = 'config/parameters.json', yolo_path: str | Path = 'config/yolo_config.json', optuna_path: str | Path = 'config/optuna_config.yaml', logging_path: str | Path = 'config/logging_config.yaml') → Dict[str, Dict[str, Any]]

Load and validate all configuration files required for the VISWIR_vQuasar project.

Parameters:

• base_path (str or Path, optional) – General configuration (paths, mode, etc.).

• params_path (str or Path, optional) – Fusion parameters (fixed values or ranges).

• yolo_path (str or Path, optional) – YOLO configuration (model, thresholds, classes).

• optuna_path (str or Path, optional) – Optuna configuration (HPC optimization).

• logging_path (str or Path, optional) – Logger configuration.

Returns:

Structured dictionary containing all loaded configurations.

Return type:

dict of dict

common.config_loader.load_config(path: str | Path, defaults: Dict[str, Any] | None = None) → Dict[str, Any]

Load a YAML or JSON configuration file and merge it with default values.

Parameters:

• path (str or Path) – Path to the configuration file (.yaml/.yml or .json).

• defaults (dict, optional) – Dictionary of default values to merge with the loaded configuration.

Returns:

Final configuration dictionary (file values + defaults).

Return type:

dict

Raises:

ConfigError – If the file does not exist or has an unsupported format.

common.config_loader.load_optuna_search_space(path: str | Path = 'config/optuna_search_space.yaml') → Dict[str, Any]

Load the YAML file defining the Optuna search space.

Parameters:

path (str or Path, optional) – Path to the YAML file describing the search space.

Returns:

Dictionary describing the Optuna search space.

Return type:

dict

common.config_loader.resolve_config_path(path: str | Path) → Path

Resolve a configuration file path relative to current directory, project root, or config directory.

common.config_loader.validate_config(config: Dict[str, Any], required_keys: list[str], context: str = '') → None

Validate that required keys are present in the configuration.

Parameters:

• config (dict) – Loaded configuration dictionary.

• required_keys (list of str) – List of mandatory keys that must be present.

• context (str, optional) – Context name (e.g., “optuna”, “sql”) used in error messages.

Raises:

ConfigError – If one or more required keys are missing.

common.datatypes module

Core dataclasses and type definitions for fusion tasks and results.

Data structures and containers for the VISWIR project.

class common.datatypes.FusionConfig(visible_folder: Path, swir_folder: Path, output_folder: Path, ref_image_path: Path | None = None, ground_truth_path: Path | None = None, mode: str = 'fixed', run_detection: bool = False)

Bases: object

Generic configuration for the VISWIR project (loaded from YAML/JSON).

visible_folder

Path to the folder containing visible images.

Type:

Path

swir_folder

Path to the folder containing SWIR images.

Type:

Path

output_folder

Path to the folder where fused images will be saved.

Type:

Path

ref_image_path

Path to a reference image, if required.

Type:

Path, optional

ground_truth_path

Path to the ground truth image, if available.

Type:

Path, optional

mode

Execution mode. Possible values: “fixed”, “sql”, “optuna”.

Type:

str, default=”fixed”

run_detection

Whether to run object detection after fusion.

Type:

bool, default=False

ground_truth_path: Path | None = None

mode: str = 'fixed'

output_folder: Path

ref_image_path: Path | None = None

run_detection: bool = False

swir_folder: Path

visible_folder: Path

class common.datatypes.FusionTask(visible_path: Path, swir_path: Path, ref_image_path: Path | None, ground_truth_path: Path | None, params: Dict[str, Any], save_output: bool = True, run_detection: bool = False, output_dir: Path | None = None)

Bases: object

Representation of a single fusion task (used by batch_runner / task_manager).

visible_path

Path to the visible image.

Type:

Path

swir_path

Path to the SWIR image.

Type:

Path

ref_image_path

Path to the reference image, if available.

Type:

Path, optional

ground_truth_path

Path to the ground truth image, if available.

Type:

Path, optional

params

Dictionary of fusion parameters for this task.

Type:

dict of str to Any

save_output

Whether to save the fused output image.

Type:

bool, default=True

run_detection

Whether to run object detection after fusion.

Type:

bool, default=False

output_dir

Directory where results should be saved.

Type:

Path, optional

ground_truth_path: Path | None

output_dir: Path | None = None

params: Dict[str, Any]

ref_image_path: Path | None

run_detection: bool = False

save_output: bool = True

swir_path: Path

visible_path: Path

class common.datatypes.OptunaConfig(n_trials: int, n_jobs: int, sampler: str = 'TPE', pruner: str = 'MedianPruner', timeout: int | None = None)

Bases: object

Configuration for Optuna optimization (loaded from optuna_config.yaml).

n_trials

Number of optimization trials.

Type:

int

n_jobs

Number of parallel jobs to run.

Type:

int

sampler

Sampling strategy used by Optuna.

Type:

str, default=”TPE”

pruner

Pruning strategy used by Optuna.

Type:

str, default=”MedianPruner”

timeout

Maximum optimization time in seconds.

Type:

int, optional

n_jobs: int

n_trials: int

pruner: str = 'MedianPruner'

sampler: str = 'TPE'

timeout: int | None = None

class common.datatypes.OptunaResult(visible_path: Path, swir_path: Path, params: Dict[str, Any], metrics_fusion: Dict[str, float] | None = None, error: str | None = None)

Bases: object

Result container optimized for Optuna trials.

visible_path

Path to the visible image.

Type:

Path

swir_path

Path to the SWIR image.

Type:

Path

params

Fusion parameters used in this trial.

Type:

dict of str to Any

metrics_fusion

Metrics computed on the fused image (NR-IQA or detection).

Type:

dict of str to float, optional

error

Error message if the fusion process failed.

Type:

str, optional

error: str | None = None

metrics_fusion: Dict[str, float] | None = None

params: Dict[str, Any]

swir_path: Path

visible_path: Path

class common.datatypes.ProcessResult(visible_path: Path, swir_path: Path, ground_truth_path: Path | None, params: Dict[str, Any], metrics_fusion: Dict[str, float] | None = None, metrics_visible: Dict[str, float] | None = None, metrics_swir: Dict[str, float] | None = None, error: str | None = None)

Bases: object

Container for the result of a VIS-SWIR image fusion process.

visible_path

Path to the visible image used in the fusion.

Type:

Path

swir_path

Path to the SWIR image used in the fusion.

Type:

Path

ground_truth_path

Path to the ground truth image, if available.

Type:

Path, optional

params

Dictionary of fusion parameters (e.g., {“facteur_swir”: 0.89, “beta”: 1.07}).

Type:

dict of str to Any

metrics_fusion

Evaluation metrics computed on the fused image.

Type:

dict of str to float, optional

metrics_visible

Evaluation metrics computed on the visible image.

Type:

dict of str to float, optional

metrics_swir

Evaluation metrics computed on the SWIR image.

Type:

dict of str to float, optional

error

Error message if the fusion process failed.

Type:

str, optional

error: str | None = None

ground_truth_path: Path | None

metrics_fusion: Dict[str, float] | None = None

metrics_swir: Dict[str, float] | None = None

metrics_visible: Dict[str, float] | None = None

params: Dict[str, Any]

swir_path: Path

visible_path: Path

common.logger module

Lightweight logging utilities for console and file output.

logger.py — Centralized logging configuration for VISWIR

This module provides a unified logging system using Loguru for flexible logging and Rich for enhanced terminal output. It allows logging both to the console and to rotating log files.

Features

• Colored and formatted console output (Rich).

• Log file recording with rotation and compression (Loguru).

• Detailed stack traces with customizable format.

• Centralized configuration loaded from logging_config.yaml.

Usage

>>> from logger import logger
>>> logger.info("Processing image {}", path_to_image)

Notes

• Default configuration is loaded from config/logging_config.yaml.

• If the configuration file is missing, fallback defaults are applied.

common.results_db module

Database models and helpers for storing fusion results.

Database models and helpers for storing fusion results in SQLite.

class common.results_db.FusionResult(**kwargs)

Bases: Base

SQLAlchemy ORM model for storing VIS–SWIR fusion results.

id

Primary key identifier.

Type:

int

visible_img

Path to the visible image used in the fusion.

Type:

str

swir_img

Path to the SWIR image used in the fusion.

Type:

str

ref_img

Path to the reference image, if available.

Type:

str

grd_tr

Path to the ground truth image, if available.

Type:

str

alpha

Alpha parameter used in the fusion process.

Type:

float

beta

Beta parameter used in the fusion process.

Type:

float

level

Fusion level parameter.

Type:

float

gamma

Gamma correction value.

Type:

float

metrics_f

Fusion metrics stored as a JSON string.

Type:

str

metrics_v

Visible image metrics stored as a JSON string.

Type:

str

metrics_s

SWIR image metrics stored as a JSON string.

Type:

str

error

Error message if the fusion process failed.

Type:

str, optional

alpha

beta

error

gamma

grd_tr

id

level

metrics_f

metrics_s

metrics_v

ref_img

swir_img

visible_img

common.results_db.get_session(db_path='results.db')

Create a new SQLAlchemy session connected to the results database.

Parameters:

db_path (str, optional) – Path to the SQLite database file (default is “results.db”).

Returns:

A SQLAlchemy session object bound to the database.

Return type:

Session

common.results_db.save_result_to_db(session, visible_img, swir_img, ref_img, grd_tr, alpha, beta, level, gamma, metrics_dict_f, metrics_dict_v, metrics_dict_s, error=None)

Save a new fusion result entry into the database.

Parameters:

• session (Session) – Active SQLAlchemy session.

• visible_img (str) – Path to the visible image.

• swir_img (str) – Path to the SWIR image.

• ref_img (str) – Path to the reference image.

• grd_tr (str) – Path to the ground truth image.

• alpha (float) – Alpha parameter used in the fusion process.

• beta (float) – Beta parameter used in the fusion process.

• level (float) – Fusion level parameter.

• gamma (float) – Gamma correction value.

• metrics_dict_f (dict or str) – Fusion metrics (dictionary or JSON string).

• metrics_dict_v (dict or str) – Visible image metrics (dictionary or JSON string).

• metrics_dict_s (dict or str) – SWIR image metrics (dictionary or JSON string).

• error (str, optional) – Error message if the fusion process failed.

Notes

• Metrics dictionaries are automatically converted to JSON strings.

• The result is committed immediately to the database.

common.ui module

Basic user interface helpers.

Terminal UI formatting and license display utilities using Rich.

common.ui.print_license_info()

Display license information for VISWIR in the terminal.

This function renders the LGPL license notice using Rich’s Markdown and Panel components, providing a styled and readable output.

Notes

• The license is LGPL (Lesser General Public License).

• Users are free to use, modify, and distribute the software, provided derivative works remain under the same license.

• The license text is available at: https://www.gnu.org/licenses/lgpl-3.0.html

common.ui.print_viswir_header()

Display the VISWIR header panel in the terminal.

This function uses the Rich library to render a styled panel announcing the initialization of the VISWIR fusion pipeline. It also calls print_license_info() to display license details.

Notes

• The panel includes a title, subtitle, and a styled message.

• Originally designed to include a spinner animation (currently disabled).

• Intended for user-facing terminal output when launching VISWIR.

Module contents

The top-level common module re-exports selected utilities from its submodules for convenience.

common package

Utility modules shared across the VISWIR project: - Logging - Configuration loading - Database helpers - UI utilities