dsgoficial/pytorch_segmentation_models_trainer: v1.4.0

[1.4.0] - 2026-08-13

WRS sqrt Sampler Weights

• Added compute_class_weights_from_proportions(props, formula) to tools/sampling/weight_calculator.py. Supports two formulas: sqrt_inverse_freq (article-validated, smoother rare-class upweighting) and inverse_freq (linear). Zero-frequency classes are handled gracefully (treated as infinite frequency → zero contribution).
• New CLI command compute-sampler-weights <yaml_path> with source: topographic_vector_source mode (reads c0..c{N-1} columns from the coreset CSV).
• Example config at conf/examples/compute_sampler_weights.yaml.
• 100% test coverage (tests/test_weight_calculator.py).

Hybrid Coreset Selection

• Added tools/coreset/vector_selector.py with five stateless selection primitives: compute_intersection_areas, select_by_vector_intersection, fd_embedding_select (K-Means round-robin FD), lc_fd_select (top-entropy LC + FD), entropy_sweep_select.
• Added tools/coreset/hybrid_coreset_selector.py with HybridVectorCoresetConfig, VectorSelectionStep, EmbeddingSelectionStep dataclasses and HybridVectorCoresetSelector.select() orchestrator. Selection proceeds in three phases: spatial vector intersection → embedding FD/LC-FD → entropy sweep. Each selected patch is tagged with its selection_step.
• New CLI command select-hybrid-coreset <yaml_path> registered in cli.py.
• Example config added at conf/examples/hybrid_coreset.yaml.
• Exports added to tools/coreset/__init__.py.
• 100% test coverage (tests/test_vector_selector.py + tests/test_hybrid_coreset_selector.py, 41 tests).

SAM Label Correction

• Added pytorch_segmentation_models_trainer/tools/sam_correction/ package with SAMLabelCorrectionConfig, SAMSegmentCache, SamLabelCorrector, and apply_sam_correction.
• apply_sam_correction: pure-function majority vote within each SAM AMG segment across the original topographic vector source and optional auxiliary LULC rasters. Non-target pixels are never modified. Masks processed ascending by (predicted_iou, area) so higher-confidence segments overwrite.
• SAMSegmentCache: NPZ-based segment cache keyed by tile/window coordinates. Disabled when cache_dir="". Old-format files (missing iou_N arrays) are rejected gracefully.
• SamLabelCorrector.run(): orchestrates tile-level processing with tqdm progress, parallel target output directories, and optional chunk-level caching for multi-run experiments. Supports start_idx/end_idx for multi-GPU splits.
• New CLI command build-sam-corrected-masks <yaml_path> (registered in cli.py). Validates SAM checkpoint presence before starting.
• Example config added at conf/examples/sam_label_correction.yaml.
• 100% test coverage across all new modules (tests/test_sam_label_corrector.py, 37 tests).

Optuna Hyperparameter Search

• Added OptunaRunner (tools/experiments_runner/optuna_runner.py): integrates Optuna HPO into the ExperimentsRunner pipeline. Configure via experiments_runner.optuna_search in any training YAML.
• Supports four search param types: float (with optional log-scale), int (with optional step), categorical, and config_block — the last allows swapping entire config subtrees (loss function, scheduler, optimizer) where different choices have heterogeneous parameters.
• Five samplers available: TPE (default, Bayesian), GP (Gaussian Process), CmaEs, Random, and Grid.
• Study persistence and automatic resume via SQLite (storage: sqlite:///study.db). Pointing to an existing database with the same study_name resumes from where it left off.
• After each trial, an incremental trial_summary.csv is written. At study end: best_trial_config.yaml (full config with best HPs), param_importances.json (fANOVA scores), and four Plotly HTML visualisation files under plots/.
• Mode B: when seeds or n_runs is also set in the runner block, a standard seed-loop run is automatically executed with the best trial's config after HPO completes.
• ExperimentsRunner._run_single now accepts optional run_cfg and output_dir parameters to bypass _build_run_cfg.
• ExperimentsRunner._validate no longer requires seeds/n_runs when optuna_search is present.
• Added config_definitions/optuna_config.py with OptunaSearchConfig and SearchParamConfig dataclasses.
• New dependencies: optuna>=3.0.0, plotly>=5.0.0.
• Example config: conf/examples/optuna_search.yaml.
• Docs: website/docs/user-guide/optuna-search.md.

Bug fixes

• Fixed CI failure introduced by the Optuna integration: optuna and plotly were only added to requirements.txt, not to pyproject.toml's dependencies, so tests/test_optuna_runner.py failed to collect with ModuleNotFoundError: No module named 'optuna'. Added both packages to pyproject.toml and regenerated uv.lock.

Model

• Model.get_model() now supports zero_init_extra_input_channels: true as a top-level config key. Zeros the extra-channel Conv2d weights after instantiation so models with LULC-appended inputs start identically to the 3-channel RGB baseline. See conf/examples/multichannel_zero_init_segmentation.yaml.

MBTiles Mask Dataset

• MBTilesMaskWindowedDataset now accepts mask_base_path, patch_size (square window), and world-coordinate bounds (tile_minx/tile_miny/tile_maxx/tile_maxy) in addition to pixel-window row_off/col_off/width/height. window_index_mask_path_key supports custom mask path column names.
• Added MBTilesSoftLabelMaskWindowedDataset: reads RGB from MBTiles, aligns BAGS/LULC sources on the fly, computes P_soft/W_conf for E3-E5-style soft-label experiments.

LULC Input Dataset

• Added MBTilesLulcInputMaskWindowedDataset: reads RGB from MBTiles, aligns LULC rasters, one-hot encodes them, and concatenates with RGB for E2-style experiments.

Experiments Runner

• ExperimentsRunner now collects Lightning metric keys with the current suffix convention (loss/val, JaccardIndex/val) in addition to the legacy prefix convention.
• Model._compute_loss() now unwraps direct loss functions that return (loss, extra_info), matching the SoftLabelWeightedCELoss contract.

CoreSet Selection

• CoreSetSelector.compute_sampler_weights() added: per-patch inverse-class-frequency weights for WeightedRandomSampler, capped at cap to prevent rare-class dominance.
• score_fa now follows the paper's gamma-based FA formula: gamma_i = -(1 - mu_i) * log(sigma_i + eps).