optimization package¶

The optimization package provides tools for hyperparameter search, objective evaluation, and visualization of the VISWIR fusion pipeline. It integrates with Optuna for automated optimization and includes custom samplers and plotting utilities.

Submodules¶

optimization.objective module¶

Definition of objective functions used to evaluate fusion quality and guide optimization.

Optuna objective functions for hyperparameter optimization.

optimization.objective.objective(trial, visible_files, swir_files, ref_image_path: str | None, run_detection: bool = False)[source]¶

Optuna objective function based on NR-IQA metrics.

This objective evaluates fused images using no-reference image quality assessment metrics (Entropy, BRISQUE, NIQE, PIQE).

Parameters:

trial (optuna.trial.Trial) – Current Optuna trial object.
visible_files (list of str) – List of visible image file paths.
swir_files (list of str) – List of SWIR image file paths.
ref_image_path (str, optional) – Path to the reference image (not used in NR-IQA).
run_detection (bool, default=False) – Whether to run detection in addition to NR-IQA.

Returns:

A tuple containing: - entropy : float - brisque : float - niqe : float - piqe : float

Return type:

tuple of float

Raises:

optuna.TrialPruned – If no valid metrics are computed for the trial.

optimization.objective.objective_detection(trial, visible_files, swir_files, ref_image_path: str | None, run_detection: bool, ground_truth_list: list | None)[source]¶

Optuna objective function based on detection metrics (F1-score).

This objective evaluates fused images by running detection and computing the average F1-score across a sampled subset of images.

Parameters:

trial (optuna.trial.Trial) – Current Optuna trial object.
visible_files (list of str) – List of visible image file paths.
swir_files (list of str) – List of SWIR image file paths.
ref_image_path (str, optional) – Path to the reference image.
run_detection (bool) – Whether detection is enabled.
ground_truth_list (list of str or None) – List of ground truth annotation file paths aligned with visible images, or None if unavailable.

Returns:

Average F1-score across the sampled dataset.

Return type:

float

Raises:

optuna.TrialPruned – If no valid metrics are computed for the trial.

optimization.objective.suggest_params(trial)[source]¶

Generate a dictionary of parameters from the Optuna search space.

Parameters:: trial (optuna.trial.Trial) – Current Optuna trial object.
Returns:: Dictionary of suggested parameters with their values.
Return type:: dict
Raises:: ValueError – If the parameter type in the search space is unsupported.

optimization.optuna_runner module¶

Orchestration of fusion parameter optimisation with Optuna framework to run optimization studies and manage trials (NR-IQA or detection).

Orchestration of Optuna hyperparameter optimization for VISWIR.

optimization.optuna_runner.clear_cache_callback(study, trial)[source]¶

Callback to clear memory after each Optuna trial.

Parameters:

study (optuna.study.Study) – The current Optuna study.
trial (optuna.trial.Trial) – The completed trial.

Notes

Calls Python garbage collector.
Can be extended to clear GPU cache if needed.

optimization.optuna_runner.normalize(values, mins, maxs)[source]¶

Normalize values to [0, 1] given min and max bounds.

Parameters:

values (list of float) – Values to normalize.
mins (list of float) – Minimum values for each dimension.
maxs (list of float) – Maximum values for each dimension.

Returns:

Normalized values in [0, 1].

Return type:

list of float

optimization.optuna_runner.optimize_parameters_for_group_v2(visible_files, swir_files, ref_image_path, output_dir, n_trials: int = 100, run_detection: bool = False, ground_truth_path: Path | None = None, sampler_name: str = 'TPE', pruner_name: str = 'MedianPruner', n_jobs: int = 4, storage: str | None = None)[source]¶

Optimize fusion parameters with Optuna (NR-IQA or detection).

Parameters:

visible_files (list of Path) – List of visible image file paths.
swir_files (list of Path) – List of SWIR image file paths.
ref_image_path (Path or None) – Path to the reference image (optional).
output_dir (Path) – Directory where results and logs will be saved.
n_trials (int, default=100) – Number of optimization trials.
run_detection (bool, default=False) – Whether to optimize based on detection (F1-score).
ground_truth_path (Path, optional) – Path to ground truth annotations (used if detection is enabled).
sampler_name (str, default="TPE") – Name of the Optuna sampler to use.
pruner_name (str, default="MedianPruner") – Name of the Optuna pruner to use.
n_jobs (int, default=4) – Number of parallel jobs.
storage (str, optional) – Storage backend (SQLite or external database).

Returns:

studyoptuna.study.Study
The completed Optuna study.
best_paramsdict
Dictionary of best parameters found.
best_valuestuple
Best objective values.

Return type:

tuple

Raises:

ValueError – If the number of visible and SWIR images does not match.

optimization.optuna_runner.process_folder_optuna(visible_folder: Path, swir_folder: Path, output_dir: Path, ref_image_path: Path | None = None, n_trials: int = 100, run_detection: bool = False, ground_truth_path: Path | None = None) → None[source]¶

Complete optimization pipeline with Optuna.

Parameters:

visible_folder (Path) – Folder containing visible images.
swir_folder (Path) – Folder containing SWIR images.
output_dir (Path) – Directory where results will be saved.
ref_image_path (Path, optional) – Path to the reference image.
n_trials (int, default=100) – Number of optimization trials.
run_detection (bool, default=False) – Whether to optimize based on detection (F1-score).
ground_truth_path (Path, optional) – Path to ground truth annotations.

Raises:

ValueError – If the number of visible and SWIR images does not match.

Notes

Saves the best parameters in best_parameters.json.
Creates or reuses an Optuna study with SQLite or external storage.

optimization.optuna_runner.tchebycheff_distance(values, ideal, weights)[source]¶

Compute the Tchebycheff distance between a solution and the ideal point.

Parameters:

values (list of float) – Values of the current solution.
ideal (list of float) – Ideal target values.
weights (list of float) – Weights for each objective.

Returns:

Tchebycheff distance.

Return type:

float

optimization.optuna_wrapper module¶

Wrapper for Optuna, managing image fusion and metric calculation, as well as detection if enabled.

Orchestration of Optuna hyperparameter optimization for VISWIR.

optimization.optuna_runner.clear_cache_callback(study, trial)[source]¶

Callback to clear memory after each Optuna trial.

Parameters:

study (optuna.study.Study) – The current Optuna study.
trial (optuna.trial.Trial) – The completed trial.

Notes

Calls Python garbage collector.
Can be extended to clear GPU cache if needed.

optimization.optuna_runner.normalize(values, mins, maxs)[source]¶

Normalize values to [0, 1] given min and max bounds.

Parameters:

values (list of float) – Values to normalize.
mins (list of float) – Minimum values for each dimension.
maxs (list of float) – Maximum values for each dimension.

Returns:

Normalized values in [0, 1].

Return type:

list of float

Optimize fusion parameters with Optuna (NR-IQA or detection).

Parameters:

visible_files (list of Path) – List of visible image file paths.
swir_files (list of Path) – List of SWIR image file paths.
ref_image_path (Path or None) – Path to the reference image (optional).
output_dir (Path) – Directory where results and logs will be saved.
n_trials (int, default=100) – Number of optimization trials.
run_detection (bool, default=False) – Whether to optimize based on detection (F1-score).
ground_truth_path (Path, optional) – Path to ground truth annotations (used if detection is enabled).
sampler_name (str, default="TPE") – Name of the Optuna sampler to use.
pruner_name (str, default="MedianPruner") – Name of the Optuna pruner to use.
n_jobs (int, default=4) – Number of parallel jobs.
storage (str, optional) – Storage backend (SQLite or external database).

Returns:

studyoptuna.study.Study
The completed Optuna study.
best_paramsdict
Dictionary of best parameters found.
best_valuestuple
Best objective values.

Return type:

tuple

Raises:

ValueError – If the number of visible and SWIR images does not match.

Complete optimization pipeline with Optuna.

Parameters:

visible_folder (Path) – Folder containing visible images.
swir_folder (Path) – Folder containing SWIR images.
output_dir (Path) – Directory where results will be saved.
ref_image_path (Path, optional) – Path to the reference image.
n_trials (int, default=100) – Number of optimization trials.
run_detection (bool, default=False) – Whether to optimize based on detection (F1-score).
ground_truth_path (Path, optional) – Path to ground truth annotations.

Raises:

ValueError – If the number of visible and SWIR images does not match.

Notes

Saves the best parameters in best_parameters.json.
Creates or reuses an Optuna study with SQLite or external storage.

optimization.optuna_runner.tchebycheff_distance(values, ideal, weights)[source]¶

Compute the Tchebycheff distance between a solution and the ideal point.

Parameters:

values (list of float) – Values of the current solution.
ideal (list of float) – Ideal target values.
weights (list of float) – Weights for each objective.

Returns:

Tchebycheff distance.

Return type:

float

optimization.samplers module¶

Custom Optuna samplers for exploring the hyperparameter space more efficiently.

Sampler and pruner configurations for Optuna.

optimization.samplers.get_pruner(name: str, **kwargs) → BasePruner[source]¶

Return an Optuna pruner based on the provided name.

Parameters:

name (str) – Name of the pruner. Supported values: - “MedianPruner” : Stops unpromising trials using median of past trials. - “SHA” or “SuccessiveHalving” : Successive Halving pruner. - “None” or “Nop” : No pruning applied.
**kwargs (dict) – Additional parameters passed to the pruner constructor.

Returns:

The corresponding Optuna pruner instance.

Return type:

optuna.pruners.BasePruner

Notes

If an unknown pruner name is provided, defaults to MedianPruner.

optimization.samplers.get_sampler(name: str, **kwargs) → BaseSampler[source]¶

Return an Optuna sampler based on the provided name.

Parameters:

name (str) – Name of the sampler. Supported values: - “TPE” : Tree-structured Parzen Estimator sampler. - “Random” : Random search sampler. - “CMAES” : Covariance Matrix Adaptation Evolution Strategy sampler. - “Grid” : Grid search sampler (requires explicit search space).
**kwargs (dict) – Additional parameters passed to the sampler constructor.

Returns:

The corresponding Optuna sampler instance.

Return type:

optuna.samplers.BaseSampler

Raises:

ValueError – If “Grid” is selected but no search_space is provided.

optimization.visualization module¶

Visualization utilities for analyzing optimization results, including loss curves and parameter importance plots.

Optuna optimization result visualization and plotting.

optimization.visualization.visualize_study(study: Study, best_trial, output_dir: Path, run_detection: bool = False)[source]¶

Generate and save visualizations of an Optuna study.

Depending on the optimization mode, this function produces:

NR-IQA mode:
- Pareto front (Entropy, BRISQUE, PIQE)
- Slice plots for each parameter vs. metric
- Contour plots (interpolated surfaces) for parameter pairs
Detection mode:
- Optimization history (F1-score)
- Contour plots for parameter pairs vs. F1-score

Parameters:

study (optuna.study.Study) – The Optuna study object containing all trials.
best_trial (optuna.trial.FrozenTrial) – The best trial selected from the study.
output_dir (Path) – Directory where contour plots will be saved as PNG files.
run_detection (bool, default=False) – If True, generate visualizations for detection (F1-score). If False, generate visualizations for NR-IQA metrics.

Notes

Uses both Plotly (interactive) and Matplotlib (static) visualizations.
Contour plots are saved to disk in output_dir.
Interactive plots may fail to display in some environments; warnings are logged.
Metrics visualized in NR-IQA mode: Entropy, BRISQUE, NIQE, PIQE.
In detection mode, only F1-score is visualized.

Module contents¶

The top-level optimization module re-exports selected functions and classes from its submodules for convenience.

Optimization package¶

This package provides modules and utilities for parameter optimization within the VISWIR project. It is primarily focused on automating the search for optimal fusion parameters using different strategies.

Submodules¶

optuna_runner : integration with Optuna for hyperparameter search.
objective : optimisation target management (NR-IQA or F1 score if detection is enabled).
sampler : sampler for Optuna.
visualization : module for the result visualization if the environnement authorise it.

Features¶

Centralized entry points for launching optimization experiments.
Logging and result tracking integrated with the VISWIR framework.
Extensible design to add new optimization backends.

Notes

This package is intended for research and experimentation. It may consume significant computational resources depending on the chosen optimization strategy.