# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Synthesis
- Added `pyimgano.synthesis` package for industrial synthetic anomaly generation:
  - Perlin/fBm noise (`perlin_noise_2d`, `fractal_perlin_noise_2d`)
  - Mask primitives (blobs/ellipses/scratches) + alpha/Poisson blending utilities
  - CutPaste variants and an `AnomalySynthesizer` pipeline with deterministic seeding + ROI constraints
  - Built-in presets: `scratch`, `stain`, `pit`, `glare`, `rust`, `oil`, `crack`
- Expanded synthesis mask primitives with more industrial shapes:
  - Brush strokes (`random_brush_stroke_mask`)
  - Spatter/droplets (`random_spatter_mask`)
  - Edge-band wear (`random_edge_band_mask`)
- Expanded built-in synthesis presets:
  - `brush`, `spatter`, `tape`, `marker`, `burn`, `bubble`, `fiber`, `wrinkle`, `texture`, `edge_wear`
- Added shift/misalignment stress-test presets:
  - `illumination` (global gradient / vignetting)
  - `warp` (slight affine misalignment)
- Added preset mixture support (`make_preset_mixture`) to sample multiple defect types.
- `AnomalySynthesizer` now supports multiple defects per image (`num_defects`) and a global severity scalar (`severity`).
- Added `SyntheticAnomalyDataset` wrapper to generate synthetic anomalies on-the-fly, including severity curriculum controls.
- Added `TextureSourceBank` to support industrial texture-driven synthesis variants.
- Added industrial camera artifact synthesis primitives and presets:
  - Defocus blur (`apply_defocus_blur`) via preset `defocus`
  - Lens distortion (`apply_lens_distortion`) via preset `lens_distortion`
- Added defect-bank copy/paste synthesis (`DefectBank`) to paste real defect crops onto normal images.
- Presets can now optionally return a continuous `alpha_mask_u8` for smoother alpha blending while keeping `mask_u8` binary for label/manifest semantics.
- Added CLI `pyimgano-synthesize` to generate a tiny synthetic dataset + masks + JSONL manifest.
  - Added `--preview` mode (grid output) for fast preset debugging.
  - Added `--from-manifest` mode to sample normals from a JSONL manifest and append synthetic anomalies.
  - Added `--presets` to sample from a preset mixture and attach chosen preset metadata to manifest records (`meta.preset_id`).
  - Added `--roi-mask` to constrain anomalies to an allowed region (useful for fixtures/background exclusion).
  - Added `--num-defects` and `--severity-range` to control multi-defect generation and severity sampling.
  - Added `--defect-bank-dir` to blend defects from a real defect library (defect bank).
  - Manifest anomaly records now include `meta.severity` (0..1) for curriculum-style workflows.

### Robustness
- Robustness benchmark corruptions can now optionally emit masks; benchmark updates labels based on returned masks so image-level metrics remain consistent.
- Added a synthesis-style robustness corruption helper (`apply_synthesis_preset`).
- Added `pyimgano.datasets.CorruptionsDataset` to apply deterministic corruptions in torch-style pipelines.

### Preprocessing
- Added MSRCR-lite Retinex illumination normalization (`msrcr_lite`) and an industrial preset helper `retinex_illumination_normalization`.

### Recipes
- Added a best-effort builtin recipe `classical-struct-iforest-synth` to run a classical baseline on a generated synthetic manifest dataset.

### CLI
- CLIs now default to offline-safe behavior (`--no-pretrained`) to avoid implicit weight downloads.
  - Affected: `pyimgano-benchmark`, `pyimgano-robust-benchmark`, and direct `pyimgano-infer --model ...`.
  - Opt in explicitly via `--pretrained` when you want upstream weights (may download).
- `pyimgano-infer` now supports ONNX Runtime CPU tuning helpers for ONNX-based routes:
  - `--onnx-session-options` (SessionOptions shorthand; avoids nested `--model-kwargs`)
  - `--onnx-sweep` (small grid sweep over threads + graph optimization level; optional `--onnx-sweep-json`)

### Feature Extractors
- Added `torchscript_embed` feature extractor for industrial “bring-your-own checkpoint” deployments (TorchScript `.pt`),
  keeping the embedding+core route offline-safe (no implicit downloads).

### Tooling
- Added `tools/audit_no_tensorrt_imports.py` to forbid TensorRT (`tensorrt` / `trt`) imports under `pyimgano/`.

### Docs
- Added `docs/SYNTHETIC_ANOMALY_GENERATION.md` and updated the industrial preprocessing cookbook with synthesis usage.
- Added industrial “MVP loop” documentation: `docs/INDUSTRIAL_MVP_LOOP.md` (synthesize → infer → defects).
- Added a v4 research-to-implementation mapping doc: `docs/PAPER_TO_MODULE_MAP_V4.md`.
- Added a v5 research-to-implementation mapping doc: `docs/PAPER_TO_MODULE_MAP_V5.md`.
- Added a v5 execution plan: `docs/plans/2026-03-02-optimize-pyimgano-next-100-tasks-v5.md`.
- Updated the reference study index: `docs/INDUSTRIAL_REFERENCE_PROJECTS.md`.
- Added reference-based inspection recipes: `docs/RECIPES_REFERENCE_BASED_INSPECTION.md`.
- Added embedding/core selection guidance: `docs/CORE_SELECTION_ON_EMBEDDINGS.md`.
- Added dataset notes:
  - `docs/DATASET_MVTEC_AD2_NOTES.md`
  - `docs/DATASET_REAL_WORLD_IAD_NOTES.md`

### Models
- Removed runtime dependency on `pyod` by porting PyOD-backed classical detectors to native implementations built around `BaseDetector`.
- Deep vision models now default to offline-safe behavior (no implicit pretrained weight downloads); enable pretrained weights explicitly (e.g. `pretrained=True` or providing an explicit embedder).
- Added/ported native classical detectors and ensembles: `vision_hbos`, `vision_mcd`, `vision_ocsvm`, `vision_kpca`, `vision_inne`, `vision_feature_bagging`, `vision_lscp`, `vision_suod`, `vision_rgraph`, `vision_sampling`.
- `vision_lscp` and `vision_lscp_spec` now provide a cheap default base-detector set, so they work out-of-the-box without explicitly passing `detector_list` / `detector_specs`.
- Added spec-friendly *core* ensemble variants for feature-matrix workflows:
  - `core_lscp` and `core_lscp_spec`
  - `core_suod_spec`
- Added spec-friendly Feature Bagging variants:
  - `core_feature_bagging_spec`
  - `vision_feature_bagging_spec`
- Spec-friendly Feature Bagging now requires `base_estimator_spec` to be JSON-friendly (string/dict); estimator instances are rejected.
- Dropped PyOD-only heavy wrappers from the default registry: `vision_cd`, `vision_auto_encoder`, `vision_anogan`, `vision_dif`, `vision_lunar`, `vision_so_gaal`, `vision_so_gaal_new`, `vision_mo_gaal`, `vision_xgbod`.
- Added more native core detectors (feature-matrix first) with optional `vision_*` wrappers:
  - `core_elliptic_envelope`, `core_mst_outlier`, `core_lid`
  - `core_cook_distance`, `core_studentized_residual`
  - `core_extra_trees_density`, `core_random_projection_knn`, `core_kde_ratio`, `core_neighborhood_entropy`
  - `core_oddoneout`, `core_knn_cosine_calibrated`, `core_cosine_mahalanobis`
- Added/modernized pipeline models:
  - `vision_embedding_core` (deep embedding extractor + classical core detector)
  - `vision_score_standardizer` and `core_score_standardizer` (score standardization wrappers)
  - `vision_score_ensemble` and `core_score_ensemble` (spec-friendly score ensembles)
- Improved the native detector contract (`BaseDetector`):
  - Added sklearn-style parameter helpers (`get_params` / `set_params`).
  - Added convenience methods (`fit_predict`, `score_samples`).
  - Added optional POT (Peaks Over Threshold) tail thresholding mode for converting scores to labels.
- Added new native classical detectors (both `core_*` and `vision_*` variants where applicable):
  - LoOP (`core_loop` / `vision_loop`)
  - LDOF (`core_ldof` / `vision_ldof`)
  - ODIN (`core_odin` / `vision_odin`)
  - RRCF-style random cut forest baseline (`core_rrcf` / `vision_rrcf`)
  - Half-Space Trees (`core_hst` / `vision_hst`)
  - Mahalanobis baseline (`core_mahalanobis` / `vision_mahalanobis`)
  - Distance-to-centroid baseline (`core_dtc` / `vision_dtc`)
  - Robust z-score baseline (`core_rzscore` / `vision_rzscore`)
  - kNN graph degree detector (`core_knn_degree` / `vision_knn_degree`)
  - Distance-correlation influence (`core_dcorr` / `vision_dcorr`)
  - PCA + Mahalanobis (`core_pca_md` / `vision_pca_md`)
- Added `vision_feature_pipeline` to compose feature extractors with `core_*` detectors via a single registry model.
- Added pixel-map capable SSIM template baselines:
  - `ssim_template_map` and `ssim_struct_map` (return `predict_anomaly_map`)
- Added additional pixel-map template baselines:
  - `vision_template_ncc_map` (local NCC similarity → anomaly map)
  - `vision_phase_correlation_map` (translation alignment → abs-diff anomaly map)
- Added reference-based pixel-map baseline:
  - `vision_ref_patch_distance_map` (torchvision feature-map patch distance vs a golden reference)
- Added patch-memory pixel-map baseline:
  - `vision_patchcore_lite_map` (patch embeddings + memory-bank kNN distance → anomaly map)
- Added patch-embedding + classical core pixel-map baseline:
  - `vision_patch_embedding_core_map` (patch embeddings + `core_*` detector → anomaly map)
- Added torch-based reconstruction baselines:
  - `core_torch_autoencoder` (MLP autoencoder on feature matrices)
  - `vision_torch_autoencoder` (feature extractor + autoencoder core)
- Added a tiny VQ-VAE reconstruction baseline (`vqvae_conv`) and an embedding-first AE route (`vision_embedding_torch_autoencoder`).
- Added lightweight preconfigured industrial wrappers (embedding + core):
  - `vision_resnet18_ecod`, `vision_resnet18_iforest`, `vision_resnet18_knn`, `vision_resnet18_torch_ae`
- Refined `vision_crossmad` to be safe-by-default and align with `BaseDetector` score/threshold semantics.

### Feature Extractors
- Added a first-class feature extractor subsystem (`pyimgano.features`) with a registry API and runtime protocol validation.
- Added extractors:
  - `IdentityExtractor` (canonical)
  - `HOGExtractor`, `LBPExtractor`, `GaborBankExtractor`
  - `ColorHistogramExtractor`, `EdgeStatsExtractor`, `FFTLowFreqExtractor`, `PatchStatsExtractor`
  - `MultiExtractor` (concat) and `PCAProjector` / `StandardScalerExtractor` (fit/transform)
- Added embedding-focused extractors:
  - `torchvision_backbone_gem` (GeM pooled conv feature map embeddings; safe `pretrained=False` default)
  - `torchvision_vit_tokens` (ViT token embeddings)
  - `normalize` (embedding normalization / power transform)
  - `TorchvisionConvPatchEmbedder` (conv feature map patch embeddings; safe `pretrained=False` default)
 - `torchvision_backbone` now accepts in-memory images as `PIL.Image.Image` and `torch.Tensor`, and supports CHW numpy arrays (`(C,H,W)`) in addition to HWC (`(H,W,C)`).
- Added feature pipeline spec support (string/dict extractor specs) and feature export helpers (`FeatureExport`).
- Added optional disk caching for feature vectors when inputs are file paths (useful for large datasets).

### Calibration
- Added rank-based calibration helpers for unsupervised score alignment.
- Added POT thresholding utility (`pyimgano.calibration.pot_threshold`) and integrated it into the base detector contract.

### Preprocessing
- Vectorized `frequency_filter` to remove O(HW) Python loops (faster and more stable on large images; optimize performance).
- Added guided filter, Perona–Malik anisotropic diffusion, rolling-ball background subtraction, and high-res tiling + blending helpers.
- Added industrial presets (shading correction, defect amplification, JPEG artifact robustness) and mask-aware enhancement.
- Added a best-effort torch (GPU) Gaussian blur path with CPU fallback.

### CLI / Pipelines
- Added `pyimgano-features` CLI to list feature extractors and precompute feature vectors.
- Added `pyimgano.pipelines.feature_pipeline` helpers and benchmark support for a `cache_dir` to persist feature vectors.
- Added CLI support for lightweight industrial model presets (preset names resolve to model+kwargs).
- `pyimgano --model-info <name>` now materializes lazy registry entries so signatures/accepted kwargs are accurate and actionable.

### Utilities
- Made `pyimgano.models` discovery lightweight by scanning model source files and registering lazy constructors, avoiding implicit imports of heavy roots like `torch`/`cv2` during `--list-models` workflows.
- Made `pyimgano.utils` exports lazy to avoid importing heavy optional dependencies at package import time (e.g. `torchvision` / `cv2`), while preserving the same re-exported API.
- Added consistent project logging utilities and deterministic `random_state` helpers.
- Added score normalization helpers and lightweight parallel utilities.
- Added typing helpers for stable public annotations.
- Added best-effort AMP helper (`pyimgano.utils.torch_amp`) and an optional eval-time tensor cache for deep vision models.
- Added audit helper `tools/audit_pixel_map_models.py` to check pixel-map model registry/tag consistency (warn-only by default).

### Packaging
- Removed `pyod` from core dependencies.

### Docs
- Updated examples/quickstart snippets to use `vision_deep_svdd` in place of the removed `vision_auto_encoder` wrapper.
- Added migration notes for the PyOD removal.
- Added:
  - `docs/FEATURE_EXTRACTORS.md`
  - `docs/INDUSTRIAL_PREPROCESSING_COOKBOOK.md`
  - `docs/TUTORIAL_CLASSICAL_ON_EMBEDDINGS.md`
  - `docs/INDUSTRIAL_EMBEDDING_PLUS_CORE.md`
  - `docs/RECIPES_EMBEDDINGS_PLUS_CORE.md`
  - `docs/ARCHITECTURE_DEEP_CONTRACTS.md`
  - `docs/DEEP_MODELS_STATUS.md`
- Added algorithm pages for new classical detectors (`loop`, `ldof`, `odin`, `rrcf`, `hst`) and refreshed the selection guide + comparisons.

### Tests
- Added extensive coverage for the native detector contract, calibration utilities, feature extractors, preprocessing ops, and CLI smoke checks.
- Added guardrail tests for inference flags (`--include-maps` vs `--defects`), OpenCLIP no-download defaults, and torch-tensor inputs for `core_*` models.
- Added guardrail tests ensuring deep models do not implicitly download pretrained weights by default.
- Added end-to-end coverage for defect-bank synthesis + `vision_patchcore_lite_map`, and core detector score-direction contract checks.
- Added strict pixel-map registry audit coverage (`tools/audit_pixel_map_models.py --strict`) and alpha-mask blending tests for synthesis.
- Added smoke/e2e coverage for `vision_patch_embedding_core_map`.
- Added a regression test ensuring CLI `--model-info` returns real constructor signatures under the lazy registry.

## [0.6.37] - 2026-03-07

### Fixed
- Restored Python 3.9 runtime compatibility (avoid `zip(..., strict=...)` and runtime-evaluated PEP 604 unions in production modules).

### Tooling
- `tox`: default `tox` run no longer gates on `type` / `coverage` (run explicitly via `tox -e type` / `tox -e coverage`).

### Packaging
- `pyproject.toml`: use SPDX-style `license = "MIT"` to satisfy upcoming setuptools deprecations.

## [0.6.36] - 2026-03-06

### Feature Extractors
- `onnx_embed` now supports a `session_options` mapping for production CPU tuning (threads, execution mode, graph optimization level, memory arena/pattern, logging, and session config entries).
- `onnx_embed` embedding cache fingerprint now includes `session_options` to avoid mixing cached embeddings across runtime configurations.

### Models
- Industrial ONNX wrappers (`vision_onnx_*`) now accept `session_options` and pass it through to the default `onnx_embed` extractor.

### Docs
- Documented onnxruntime CPU SessionOptions tuning for `vision_onnx_*` in `docs/INDUSTRIAL_EMBEDDING_PLUS_CORE.md`.

### Tests
- Added coverage for `onnx_embed` SessionOptions plumbing, wrapper pass-through, and cache fingerprinting.

## [0.6.35] - 2026-03-05

### CLI
- `pyimgano-infer` now supports production guardrails:
  - `--continue-on-error` (record per-input errors and keep going; exit code 1 if any errors)
  - `--max-errors` (stop early after N errors)
  - `--flush-every` (periodically flush JSONL outputs)
  - `--profile-json` (write a machine-friendly timing payload)

### Inference
- Torch AMP context now prefers `torch.amp.autocast` when available (avoids deprecation warnings) and uses best-effort `torch.inference_mode`.

### Docs
- Documented `pyimgano-infer` production guardrails in the CLI reference and the industrial inference guide.

### Tests
- Added coverage for `pyimgano-infer --continue-on-error` and `--profile-json`.

## [0.6.34] - 2026-03-05

### CLI
- `pyimgano-doctor` now supports `--accelerators` to report best-effort accelerator/runtime diagnostics (torch CUDA/MPS, onnxruntime providers, openvino devices), with actionable extras install hints.

### Docs
- Documented `pyimgano-doctor --accelerators` usage in quickstart and the CLI reference.

### Tests
- Added coverage for the `--accelerators` JSON payload and missing-deps install hints.

## [0.6.33] - 2026-03-05

### Models
- Numba-backed classical models now fail with actionable extras hints when `numba` is missing:
  - `pyimgano.models.imdd` (IMDD/LMDD)
  - `pyimgano.models.qmcd` (QMCD)

### Tests
- Added subprocess-based coverage ensuring missing `pyimgano[numba]` produces an `ImportError` with install hint for numba-backed model modules.

## [0.6.32] - 2026-03-05

### Datasets
- Torch-backed dataset helpers now fail with actionable extras hints when torch/torchvision are missing:
  - `pyimgano.datasets.image`
  - `pyimgano.datasets.array`
  - `pyimgano.datasets.transforms`
  - `pyimgano.datasets.datamodule`
  - `pyimgano.datasets.corruptions`

### Tests
- Added subprocess-based coverage ensuring missing `pyimgano[torch]` produces an `ImportError` with install hint for the torch-backed dataset modules.

## [0.6.31] - 2026-03-05

### CLI
- `pyimgano-demo --infer-defects` now also writes:
  - `<suite_dir>/infer/overlays/` (FP debugging overlays)
  - `<suite_dir>/infer/regions.jsonl` (defect regions export)

### Tooling
- Centralized extras root-module mapping in `pyimgano.utils.extras` and reused it in suite skip hints + `pyimgano-doctor`, keeping extras checks consistent with packaging.

### Tests
- Extended demo smoke coverage to assert overlays/regions artifacts are produced.

## [0.6.30] - 2026-03-05

### Baselines / Suites
- Aligned suite extras skip hints with packaging extras:
  - `torch` now checks both `torch` and `torchvision`
  - `onnx` now checks `onnxruntime`, `onnx`, and `onnxscript`
- This makes `pyimgano-benchmark --suite ...` skip optional baselines more accurately instead of attempting to run and failing later.

### Tests
- Added coverage for suite skip hints when a dependency in an extra group is missing (e.g. `torchvision` missing under `pyimgano[torch]`).

## [0.6.29] - 2026-03-05

### CLI
- Hardened `pyimgano-doctor --require-extras ...` to check **importability**, not just module presence, so CI/deploy gates catch broken wheels / missing shared libraries.
- Expanded the `torch` and `onnx` extras root-module checks to reflect the actual extras groups (`torch` + `torchvision`, and `onnxruntime` + `onnx` + `onnxscript`).

### Tooling
- Updated Ruff config keys to the modern `tool.ruff.lint` schema (removes deprecation warnings).

### Tests
- Added coverage for `--require-extras` when a module exists but fails to import.

## [0.6.28] - 2026-03-05

### CLI
- Added `pyimgano-doctor --require-extras ...` for CI/deploy environment gating (non-zero exit when required extras are missing).
- Added `pyimgano-demo --infer-defects` to run an end-to-end demo loop that writes inference + defects artifacts without manually invoking `pyimgano-infer`.

### Docs
- Updated CLI reference with `pyimgano-doctor --require-extras ...` and `pyimgano-demo --infer-defects` examples.

### Tests
- Added coverage for `pyimgano-doctor --require-extras ...` and the `pyimgano-demo --infer-defects` smoke loop.

## [0.6.27] - 2026-03-05

### CLI
- `pyimgano-doctor` now supports `--suite <name>` to report which baselines would be skipped due to missing extras.

### Docs
- Updated quickstart + CLI reference with `pyimgano-doctor --suite ...` examples.

### Tests
- Added coverage for `pyimgano-doctor --suite ...` JSON payload.

## [0.6.26] - 2026-03-05

### CLI
- Added `pyimgano-doctor` to print a lightweight environment report and optional dependency (extras) availability.

### Docs
- Updated quickstart + CLI reference to include `pyimgano-doctor` usage.

### Tests
- Added smoke coverage for `pyimgano-doctor` JSON/text output.

## [0.6.25] - 2026-03-05

### Baselines / Suites
- Added `industrial-v4` suite (v3 + more CPU-friendly feature pipelines: edge/patch-stats/color-hist/FFT; optional texture baselines LBP/HOG/Gabor via `pyimgano[skimage]`).
- Added `industrial-feature-small` sweep profile for bounded parameter scans over the new feature baselines.

### Docs
- Updated README and CLI docs to reference `industrial-v4` and the new sweep profile.

### Tests
- Extended suite/sweep discovery tests to cover `industrial-v4` and `industrial-feature-small`.

## [0.6.24] - 2026-03-04

### Packaging
- Moved heavy runtimes behind extras (`pyimgano[torch]`, `pyimgano[onnx]`, `pyimgano[openvino]`, `pyimgano[skimage]`, `pyimgano[numba]`, `pyimgano[viz]`) while keeping the core install lightweight.
- Hardened optional dependency boundaries so missing extras do not break base imports and errors include actionable install hints.

### Baselines / Suites
- Added curated industrial baseline suites and suite sweeps for small grid searches:
  - `industrial-v3` (adds optional deep pixel-map baselines)
  - `industrial-deep-map-small` sweep profile (bounded variants for PatchCore-lite-map / patch-embedding-core-map)

### Extensibility
- Added opt-in plugin loading via Python entry points (`pyimgano.plugins`) for third-party models/features.

### Docs
- Added `docs/OPTIONAL_DEPENDENCIES.md` (extras map) and `docs/PLUGINS.md` (plugin authoring guide).
- Updated README/CLI examples to reflect suites, sweeps, and extras.

### Tests
- Added coverage for extras metadata, suite/sweep discovery and execution, plugin entry points, and lightweight import guardrails.

## [0.6.23] - 2026-02-25

### Preprocessing
- `pyimgano-train --preflight` now emits `PREPROCESSING_REQUIRES_NUMPY_MODEL` when `preprocessing.illumination_contrast` is enabled on a model that does not support numpy inputs.
- `pyimgano-infer` now fails early with `PREPROCESSING_REQUIRES_NUMPY_MODEL` when an infer-config/run requests preprocessing but the selected model is not numpy-capable.

### Examples
- Added `examples/configs/industrial_adapt_preprocessing_illumination.json` as a starting point for illumination/contrast normalization in industrial runs.

### Docs
- Documented the preprocessing/model compatibility requirement in the workbench and inference docs.

## [0.6.22] - 2026-02-25

### Preprocessing
- Workbench configs now support an optional `preprocessing.illumination_contrast` block (illumination/contrast normalization knobs).
- Exported `artifacts/infer_config.json` now includes the preprocessing block when configured.
- Workbench runs and `pyimgano-infer` now apply the same preprocessing automatically (deploy consistency).
- CLAHE in `apply_illumination_contrast(...)` is now channel-order independent (no RGB/BGR assumption).

### Infer-config
- `pyimgano-validate-infer-config` now validates/coerces `preprocessing.illumination_contrast.*` fields when present.

### Tests
- Added coverage for preprocessing config plumbing and CLAHE channel-order independence.

## [0.6.21] - 2026-02-25

### Recipes
- Added two builtin industrial recipes:
  - `industrial-adapt-highres` (tiling + seam-reducing blending defaults)
  - `industrial-adapt-fp40` (defects FP-reduction defaults for deploy-style inference export)

### Preprocessing
- Added opt-in industrial illumination/contrast knobs:
  - `IlluminationContrastKnobs`
  - `apply_illumination_contrast(...)`
- `ImageEnhancer` now exposes illumination/contrast helpers for pipeline usage (`illumination_contrast`, white balance, homomorphic filter).

### sklearn integration
- Hardened `RegistryModelEstimator` with clearer input validation and better model-name errors.

### Docs
- Added a practical false-positive tuning guide: `docs/FALSE_POSITIVE_DEBUGGING.md` (linked from `docs/INDUSTRIAL_INFERENCE.md`).
- Quickstart now documents the recommended paths-first / manifest dataset workflow.
- Updated positioning docs to compare `pyimgano` vs PyOD vs anomalib.
- Refreshed READMEs to align with the FP40 inference workflow and example configs.
- Model index generator now includes discovery + extension guidance.

### Tests
- Expanded detector contract tests with a lightweight deep + pixel-map smoke test (`vision_softpatch` with a stub embedder).
- Added workbench recipe smoke coverage using the manifest dataset.

## [0.6.20] - 2026-02-25

### Infer-config
- Added infer-config validation utilities and CLI: `pyimgano-validate-infer-config`.
- Added deploy bundle export (`pyimgano-train --export-deploy-bundle`) which writes a `deploy_bundle/` directory containing:
  - `infer_config.json`
  - referenced checkpoints (preserving relative paths)
  - best-effort run metadata when available

### Inference
- `pyimgano-infer` now supports `--seed` for best-effort reproducibility (also passed as `random_seed/random_state` when supported).

### Docs
- Updated workbench and CLI reference docs to include deploy bundle + infer-config validation workflows.

### Tests
- Added coverage for deploy bundle export and tiling defaults loaded from infer-config.

## [0.6.19] - 2026-02-25

### Inference
- Added streaming inference API: `pyimgano.inference.infer_iter(...)` (recommended for large runs with anomaly maps).
- `pyimgano-infer` now streams JSONL output and supports chunked inference (`--batch-size`) to reduce peak memory.
- Added best-effort AMP/autocast for torch-backed models (`--amp`) and a stage timing summary (`--profile`).
- Added `--include-anomaly-map-values` to embed raw anomaly-map values in JSONL (debug only; very large output).

### Defects
- Added compressed mask export format `npz` (`--mask-format npz`) for large batches.

### Tiling
- `TiledDetector` now caches tile coordinate grids per image shape for better throughput on repeated input sizes.

### Docs
- Documented tiling knobs in the CLI reference and expanded practical guidance for seam blending (`hann`/`gaussian`).

### Tests
- Added coverage for NPZ mask export and tiling coordinate caching.

## [0.6.18] - 2026-02-25

### Defects
- Added anomaly-map border suppression, optional smoothing, and hysteresis thresholding for more stable defect masks.
- Added shape filters (`min_fill_ratio` / `max_aspect_ratio` / `min_solidity`) to remove elongated/non-compact fragments.
- Added region merging (`merge_nearby`) to combine nearby fragments in the exported regions list (mask unchanged).
- Region ordering and `max_regions` selection are now deterministic and configurable via `max_regions_sort_by: score_max|score_mean|area`.

### Inference
- `pyimgano-infer --defects` supports image-space bbox mapping (`--defects-image-space`) and overlay export (`--save-overlays DIR`) for FP debugging.

### Workbench
- Exported `infer_config.json` now includes more `defects.*` defaults (border ignore, smoothing/hysteresis blocks, shape filters, merge settings, and max-regions sorting).

### Docs
- Updated CLI reference and industrial inference guide with FP40 knobs and recommended usage patterns.

### Tests
- Added unit and CLI smoke coverage for new defects controls and infer-config defaults.

## [0.6.17] - 2026-02-25

### Inference
- Fixed `pyimgano-infer --infer-config --defects` so `defects.pixel_threshold` remains usable as a fallback when `pixel_threshold_strategy=normal_pixel_quantile` but `--train-dir` is not provided.
- When `--train-dir` *is* provided and `pixel_threshold_strategy=normal_pixel_quantile`, `pyimgano-infer` still recalibrates pixel threshold from normal/train maps (even if the infer-config contains a fixed `defects.pixel_threshold`).

### Tests
- Added coverage for pixel-threshold recalibration vs infer-config fallback behavior.

## [0.6.16] - 2026-02-25

### Defects
- Added region-level score filters for defect mask extraction (`min_score_max` / `min_score_mean`) to reduce noisy false positives.

### Inference
- `pyimgano-infer` now supports ROI + region-score filtering knobs via `--infer-config` / `--from-run` exported defaults and new CLI flags.

### Docs
- Documented region score filters and updated the industrial defects recipe template.

## [0.6.15] - 2026-02-25

### CLI
- Fixed `pyimgano-train --dry-run` / `--preflight` crashing due to a local `asdict` shadowing bug.

## [0.6.14] - 2026-02-25

### Inference
- `pyimgano-infer` now applies exported `defects.*` settings from `--infer-config` / `--from-run` as defaults (ROI, morphology, min area, mask format, etc.). Explicit CLI flags override.

### Defects
- Pixel-threshold calibration via `normal_pixel_quantile` now supports ROI-aware calibration when an ROI is provided (reduces false positives from background/fixtures).

### Docs
- Updated defects export docs to reflect infer-config defaults and ROI-aware calibration behavior.

### Tests
- Added coverage for ROI-aware pixel-threshold calibration and infer-config defects defaults.

## [0.6.13] - 2026-02-25

### Docs
- Added PyPI badges to the README now that the project is published.
- Clarified PyPI token scope guidance for first publish vs subsequent releases.

## [0.6.12] - 2026-02-24

### Packaging
- Removed a VCS direct-URL optional dependency from published metadata so the project can be uploaded to PyPI.

### Docs
- Updated PatchCore-Inspection checkpoint docs to install the upstream repo explicitly (instead of via extras).

## [0.6.11] - 2026-02-24

### Docs
- Expanded the README with practical model selection notes (tags like `numpy`/`pixel_map`) and a one-off `pyimgano-infer --model ...` example.
- Updated translated READMEs to align with the CLI-first industrial workflow entry points.

## [0.6.10] - 2026-02-24

### Docs
- Rewrote `README.md` to be shorter and oriented around the industrial CLI/workbench workflow.
- Updated `README_cn.md` to mirror the new README structure and CLI entry points.

## [0.6.9] - 2026-02-24

### Docs
- Improved publishing docs (including GitHub Actions release flow and first-time PyPI token note).
- Refreshed Sphinx docs landing page and added missing Sphinx pages so `make html` works out of the box.
- Added a short defects + infer-config quickstart snippet to the README.

### CI
- Documentation workflow now uploads the correct Sphinx build output path.

## [0.6.8] - 2026-02-24

### Docs
- Workbench/recipes docs now describe how to configure and deploy defects export via `infer_config.json`.
- Added a workbench config template: `examples/configs/industrial_adapt_defects_roi.json`.

## [0.6.7] - 2026-02-24

### Added
- Workbench `artifacts/infer_config.json` exports a `defects` block (mask/regions/ROI settings) for deploy-style `pyimgano-infer --infer-config` usage.

### Fixed
- Workbench now ensures custom/lightweight detectors expose a discoverable `contamination` attribute so default threshold calibration and `threshold_provenance` stay consistent.

### Changed
- `pyimgano.datasets` uses lazy exports for torch-dependent dataset/datamodule helpers, keeping `import pyimgano.datasets` usable in minimal environments.

## [0.6.6] - 2026-02-24

### Added
- `threshold_provenance` is now persisted in workbench reports and exported in `artifacts/infer_config.json` for auditable deploy configs.
- Shared score-threshold quantile resolver (`pyimgano.calibration.resolve_calibration_quantile`) to keep benchmark/workbench/infer defaults consistent.
- Benchmark reports include `threshold_provenance` (strategy/quantile/source) so runs are self-describing.

### Changed
- `pyimgano-infer` now auto-calibrates `threshold_` from train scores when `--train-dir` is provided and the detector does not set `threshold_`.

### Docs
- Documented threshold calibration defaults and provenance fields across CLI + industrial workflow guides.

## [0.6.5] - 2026-02-24

### Added
- Workbench dataset preflight validation (`pyimgano-train --preflight`) for catching manifest/data issues before training.
- Workbench reports now include `dataset_summary` (counts, anomaly ratio, pixel-metric gating).
- Infer-config driven deployment-style inference (`pyimgano-infer --infer-config ...`), including multi-category selection via `--infer-category`.
- Benchmark CLI can now run manifest datasets (`pyimgano-benchmark --dataset manifest --manifest-path ...`) and propagates manifest `meta` to per-image JSONL.

## [0.6.4] - 2026-02-24

### Added
- Manifest dataset (JSONL) support for workbench runs (`dataset.name="manifest"`).
- `pyimgano-manifest` for generating a JSONL manifest from the built-in `custom` dataset layout.
- `pyimgano-benchmark --list-categories` supports `--dataset manifest --manifest-path ...`.
- Workbench per-image JSONL records propagate manifest `meta` when present.
- `pyimgano-train --dry-run` validates that `dataset.manifest_path` exists and is readable.

### Fixed
- Workbench `dataset.category="all"` now runs and aggregates per-category runs correctly.

## [0.6.3] - 2026-02-23

### Added
- `pyimgano-train --dry-run` for validating and printing effective configs without running.
- `pyimgano-train --export-infer-config` (writes `artifacts/infer_config.json`).
- Workbench docs and examples:
  - `docs/WORKBENCH.md`
  - `examples/configs/*.json`
- Workbench reports include `seed` for better provenance.

### Fixed
- Recipe metadata `callable` paths now point at the actual registered callable (functions included).

## [0.6.2] - 2026-02-23

### Added
- Training utilities: `pyimgano.training.save_checkpoint` and `pyimgano.training.micro_finetune`.
- Workbench training config (`training.*`) and checkpoint artifacts under `checkpoints/<category>/...`.
- Builtin micro-finetune recipe: `micro-finetune-autoencoder`.
- `pyimgano-infer --from-run` for loading model/threshold/checkpoint from a workbench run directory.
- Optional anomalib recipe skeleton: `anomalib-train` (requires `pyimgano[anomalib]`).

## [0.6.1] - 2026-02-23

### Added
- Workbench adaptation knobs: tiling inference, anomaly-map postprocess, and optional map saving (`pyimgano.workbench`).
- Workbench runner for recipe execution with benchmark-compatible artifacts (reports + per-image JSONL + optional anomaly maps).
- `industrial-adapt` recipe now uses the workbench runner and supports `adaptation.save_maps=true`.
- Documentation for recipes + `pyimgano-train`: `docs/RECIPES.md`.

## [0.6.0] - 2026-02-23

### Added
- Workbench config loader: `pyimgano.config.load_config` (JSON by default; YAML optional with `PyYAML`).
- Workbench config normalization: `pyimgano.workbench.WorkbenchConfig`.
- Recipe registry: `pyimgano.recipes` (`register_recipe`, `list_recipes`, `recipe_info`).
- Builtin workbench recipe: `industrial-adapt`.
- New CLI: `pyimgano-train` (recipe discovery + config-driven execution).
- Workbench run artifact helpers: `build_workbench_run_dir_name` and `build_workbench_run_paths`.

## [0.5.8] - 2026-02-23

### Added
- Classical feature cache: `pyimgano-benchmark --cache-dir` (speeds up repeated path-based scoring).
- Run timing breakdown in benchmark reports (`timing` block with load/fit/score/eval durations).
- Developer audits:
  - `tools/audit_public_api.py`
  - `tools/audit_registry.py`
- Documentation:
  - `docs/CLI_REFERENCE.md`
  - `docs/MIGRATION.md`

### Changed
- Optional dependency errors now include clearer pip install hints (including common module ↔ pip name mismatches).

### CI
- CI runs the public API + registry audits on Linux/Python 3.11.

## [0.5.7] - 2026-02-23

### Added
- Benchmark reproducibility: `pyimgano-benchmark --seed` (best-effort) and persisted in `config.json`.
- Classical detector serialization helpers: `pyimgano.serialization.save_detector/load_detector` (pickle; restricted safe set).
- Benchmark pipeline options:
  - `pyimgano-benchmark --save-detector [PATH|auto]`
  - `pyimgano-benchmark --load-detector PATH` (skip fit)
- sklearn integration:
  - `pyimgano.sklearn_adapter.RegistryModelEstimator`
  - `docs/SKLEARN_INTEGRATION.md`
- Contract tests for detector API consistency (`tests/contracts/test_detector_contract.py`).
- Benchmark docs now describe run directory collision policy.

## [0.5.6] - 2026-02-23

### Added
- Image IO helpers: `pyimgano.io.image` (`read_image`, `resize_image`, `convert_color`).
- Dataset catalog helper: `pyimgano.datasets.catalog.list_dataset_categories`.
- Custom dataset validation: `CustomDataset.validate_structure()` and CLI preflight validation for `--dataset custom`.
- Benchmark pipeline supports `input_mode=paths|numpy` (with CLI flag `pyimgano-benchmark --input-mode`).
- Run artifact: `environment.json` (Python/platform/package snapshot).
- Report metadata stamping: `schema_version`, `timestamp_utc`, `pyimgano_version`.

### Changed
- Benchmark dataset loaders in `pyimgano.utils.datasets` now route image/mask IO via `pyimgano.io`.
- `pyimgano.pipelines.run_benchmark.list_dataset_categories` delegates to the dataset catalog.

## [0.5.5] - 2026-02-23

### Added
- Shared CLI helper module: `pyimgano.cli_common` (stable `--model-kwargs` parsing/merging/filtering).
- Registry introspection utilities:
  - `pyimgano.models.introspection`
  - `pyimgano.models.registry.model_info` / `MODEL_REGISTRY.model_info`
- Computed model capability helper: `pyimgano.models.capabilities`.
- `pyimgano-benchmark --list-categories` for dataset category discovery.
- Shared JSON conversion helper: `pyimgano.utils.jsonable.to_jsonable`.

### Changed
- `pyimgano-infer` and `pyimgano-robust-benchmark` now share model-kwargs behavior via `pyimgano.cli_common`.
- `pyimgano-benchmark` uses `to_jsonable` for JSON output and `pyimgano.reporting` uses it for report artifacts.
- CLI discovery flags are mutually exclusive across `--list-models`, `--model-info`, and `--list-categories`.

## [0.5.4] - 2026-02-23

### Added
- Industrial one-click benchmark runner: `pyimgano.pipelines.run_benchmark` (single category or `category=all`).
- Run artifacts layout (JSON + JSONL): `report.json`, `config.json`, and per-category `per_image.jsonl`.
- Reporting helpers:
  - `pyimgano.reporting.save_jsonl_records`
  - `pyimgano.reporting.runs` (`build_run_dir_name`, `ensure_run_dir`)
- Torch-like public surface for benchmark datasets: `pyimgano.datasets.{load_dataset,MVTecDataset,VisADataset,...}`.

### Changed
- `pyimgano-benchmark` gains industrial pipeline flags:
  - `--dataset custom`, `--category all`, `--resize H W`
  - `--output-dir`, `--save-run/--no-save-run`, `--per-image-jsonl/--no-per-image-jsonl`
  - `--calibration-quantile`, `--limit-train`, `--limit-test`
- `runs/` is now ignored by default (CLI writes run artifacts by default unless disabled).

## [0.5.3] - 2026-02-22

### Added
- Auto-generated registry index: `docs/MODEL_INDEX.md` (generated by `tools/generate_model_index.py`).
- Canonical `vision_*` aliases for legacy deep models: `vision_cutpaste`, `vision_memseg`, `vision_differnet`, `vision_devnet`, `vision_riad`.

### Changed
- `setup.py` is now a minimal stub delegating metadata to `pyproject.toml` to prevent packaging drift.
- Docs examples prefer canonical `vision_*` model names for consistency with the CLI/registry.

## [0.5.2] - 2026-02-22

### Added
- Legacy compatibility module: `pyimgano.detectors` with common `*Detector` class names.

### Fixed
- Ensure `_classes` is initialized for PyOD-backed detectors to keep `predict_proba()` working even when wrappers override `fit()`.

## [0.5.1] - 2026-02-22

### Added
- `pyimgano-robust-benchmark` adds `--input-mode`:
  - `numpy` (default): load decoded frames in memory (corruptions enabled)
  - `paths`: pass file paths to detectors (clean-only; corruptions skipped)
- Robustness reporting metadata: input mode, corruption mode, and skip reasons when corruptions/pixel metrics cannot run.

### Changed
- Documentation updated to use the registry-driven API (`pyimgano.models.create_model`, `pyimgano.models.list_models`) instead of `pyimgano.detectors`.
- Sphinx API reference refreshed to document the registry/factory interface.
- Benchmark scripts updated to use `create_model` + model registry names.

### Fixed
- PyOD `predict_proba()` compatibility for vision wrappers by initializing `_classes` during `fit()`.

## [0.5.0] - 2026-02-22

### Added
- VAND-style pixel SegF1 + background FPR (`bg_fpr`) metrics under a single calibrated pixel threshold.
- Normal-pixel quantile calibration helper for deploy-style pixel thresholding.
- `pyimgano.robustness` module:
  - deterministic corruptions: lighting, JPEG, blur, glare/specular, geo-jitter (mask-aware)
  - robustness benchmark runner (clean + corruption suite)
- New CLI: `pyimgano-robust-benchmark` for clean + corruption robustness evaluation.
- New augmentation preset: `get_industrial_drift_augmentation()` (camera/lighting drift aligned with the corruption suite).
- New model: `vision_superad` (DINOv2 patch-kNN using k-th NN distance per patch).

### Changed
- `pyimgano-benchmark` adds `--pixel-segf1` + pixel-threshold calibration flags (single-threshold evaluation).
- `evaluate_detector()` can optionally report SegF1/bg-FPR when a fixed pixel threshold is provided.

### Fixed
- Pixel thresholding uses strict `>` comparison to avoid false positives when `threshold == max(normal)`.

## [0.4.0] - 2026-02-22

### Added
- `vision_mambaad` (MambaAD-style patch embedding reconstruction) and a new optional extra: `pyimgano[mamba]`.
- PatchCore speed/memory knobs:
  - `feature_projection_dim` + `projection_fit_samples` for random-projection feature reduction.
  - `memory_bank_dtype` for FP16/FP32 memory-bank storage.
- Tiled inference map blending modes: `map_reduce` now supports `"hann"` and `"gaussian"` in addition to `"max"`/`"mean"`.
- Industrial defect-synthesis augmentations:
  - `add_scratches`, `add_dust`, `add_specular_highlight`
  - `get_industrial_surface_defect_synthesis_augmentation` preset pipeline.

### Changed
- PatchCore coreset selection is now deterministic (seeded) and uses squared L2 distances (faster).
- `pyimgano-infer --tile-map-reduce` choices updated to include `"hann"`/`"gaussian"`.
- PatchCore CLI presets (`industrial-fast` / `industrial-balanced`) now enable feature projection + FP16 memory bank.

## [0.3.0] - 2026-02-22

### Added
- New industrial datasets:
  - `mvtec_loco` (MVTec LOCO AD) via `MVTecLOCODataset`
  - `mvtec_ad2` (MVTec AD 2, `test_public` split) via `MVTecAD2Dataset`
- High-resolution tiling inference:
  - `pyimgano.inference.TiledDetector`
  - `pyimgano-infer` tiling flags (`--tile-size/--tile-stride/...`)
- Industrial preprocessing presets: gray-world, max-RGB white balance + homomorphic filtering.
- Industrial augmentation ops: JPEG recompress, vignetting, random channel gain drift + preset pipeline.
- Inference API hardening: supports detectors that require ndarray batches for scores/maps.
- OpenCLIP backend supports numpy image inputs (not just paths).
- `docs/WEIGHTS.md` for weight/checkpoint management.

### Changed
- `pyimgano-benchmark --dataset` choices now include `btad`, `mvtec_loco`, and `mvtec_ad2`.
- `BTADDataset` accepts a `load_masks` kwarg for pipeline/CLI compatibility (BTAD still returns no masks).

## [0.2.1] - 2026-02-22

### Added
- More PyOD wrappers: `vision_cd`, `vision_dif`, `vision_lunar`, `vision_rgraph`, `vision_sampling`,
  `vision_so_gaal`, `vision_so_gaal_new`, `vision_auto_encoder`, `vision_anogan`.

## [0.2.0] - 2026-02-22

### Added
- **Image Preprocessing Module** (`pyimgano.preprocessing`) ⭐ NEW!
  - **ImageEnhancer** - High-level interface for basic operations (25 operations)
  - **AdvancedImageEnhancer** - Extended with 25+ advanced operations (50+ total)
  - **PreprocessingPipeline** - Sequential operation composition with method chaining
  - **PreprocessingMixin** - Easy integration with detectors via mixin pattern

  **Basic Operations (25)**:
  - **Edge Detection** (7 methods): Canny, Sobel, Sobel X/Y, Laplacian, Scharr, Prewitt
  - **Morphological Operations** (7 types): Erosion, Dilation, Opening, Closing, Gradient, TopHat, BlackHat
  - **Filters** (4 types): Gaussian, Bilateral, Median, Box
  - **Normalization** (4 methods): MinMax, Z-Score, L2, Robust (IQR-based)
  - **Enhancement** (3): Sharpen, Unsharp Mask, CLAHE

  **Advanced Operations (25+)**:
  - **Frequency Domain** (6): FFT, IFFT, Lowpass, Highpass, Bandpass, Bandstop filters
  - **Texture Analysis** (3): Gabor filters, Local Binary Pattern (LBP), GLCM texture features
  - **Color Space Transformations** (8): RGB, HSV, LAB, YCrCb, HLS, LUV + conversions
  - **Advanced Enhancement** (4): Gamma correction, Contrast stretching, Single/Multi-Scale Retinex
  - **Advanced Denoising** (2): Non-local means denoising, Anisotropic diffusion
  - **Feature Extraction** (4): HOG features, Harris corners, Shi-Tomasi, FAST detector
  - **Advanced Morphology** (4): Skeletonization, Thinning, Convex hull, Distance transform
  - **Segmentation** (6): Otsu, Adaptive (mean/Gaussian), Triangle, Yen, Watershed
  - **Image Pyramids** (2): Gaussian pyramid, Laplacian pyramid

  **Augmentation Operations (30+)** ⭐ NEW!:
  - **Geometric Augmentations** (7): Rotation, Flipping, Scaling, Translation, Shearing, Perspective, Affine
  - **Color Augmentations** (5): Brightness, Contrast, Saturation, Hue adjustment, Color jitter
  - **Noise Addition** (4): Gaussian noise, Salt-and-pepper noise, Poisson noise, Speckle noise
  - **Blur Effects** (4): Motion blur, Defocus blur, Glass blur, Zoom blur
  - **Weather Effects** (5): Rain, Fog, Snow, Shadow, Sunflare effects
  - **Occlusion & Cutout** (4): Random cutout, Grid mask, Mixup, CutMix
  - **Distortion** (2): Elastic transform, Grid distortion
  - **Pipeline System** (8): Compose, OneOf, RandomApply, + 5 preset pipelines (light, medium, heavy, weather, anomaly)

  - **Total operations: 80+** (25 basic + 25 advanced + 30 augmentation)
  - Comprehensive preprocessing documentation (docs/PREPROCESSING.md)
  - Complete test suite (tests/test_preprocessing.py - 500+ lines)
  - Usage examples (examples/preprocessing_example.py, advanced_preprocessing_example.py, augmentation_example.py)
- **3 New High-Performance Deep Learning Algorithms** ⚡:
  - **DRAEM** (ICCV 2021) - Discriminatively trained reconstruction with synthetic anomalies
  - **CFlow-AD** (WACV 2022) - Real-time conditional normalizing flows
  - **DFM** - Fast discriminative feature modeling (training-free)
- Total algorithms now: **37+** (19 classical ML + 18 deep learning)
- Enterprise-grade package configuration
- Modern `pyproject.toml` build system configuration
- Comprehensive GitHub Actions CI/CD workflows
- Pre-commit hooks for code quality
- Code quality tools integration (Black, isort, flake8, mypy, ruff)
- Contributing guidelines (CONTRIBUTING.md)
- This changelog file
- Support for Python 3.9-3.12
- Type hints marker (py.typed)
- MANIFEST.in for proper package distribution
- .editorconfig for consistent coding style
- tox configuration for multi-version testing
- **34+ total algorithms** (19 classical ML + 15 deep learning)
- New PyOD classical ML integrations (19 total):
  - **ECOD** (Empirical CDF-based, TKDE 2022) - State-of-the-art, parameter-free
  - **COPOD** (Copula-based, ICDM 2020) - High-performance, parameter-free
  - **KNN** (K-Nearest Neighbors) - Classic, simple and effective
  - **PCA** (Principal Component Analysis) - Classic dimensionality reduction
  - **COF** (Connectivity-Based Outlier Factor, PAKDD 2002) - Density-based detection
  - **MCD** (Minimum Covariance Determinant, 1999) - Robust statistical method
  - **Feature Bagging** (KDD 2005) - Ensemble method for stability
  - **INNE** (Isolation Nearest Neighbors, ICDM 2014) - Fast isolation-based
- New state-of-the-art deep learning algorithms (15 total):
  - **SimpleNet** (CVPR 2023) ⭐ - Ultra-fast SOTA, 10x faster training, ~99% AUROC
  - **PatchCore** (CVPR 2022) ⭐ - Best accuracy (99.6% AUROC), memory-based, pixel localization
  - **STFPM** (BMVC 2021) ⭐ - Student-Teacher matching, multi-scale features, ~97% AUROC
- Enhanced error handling and logging for all detectors
- Improved PyOD version compatibility (>=1.1.0, <3.0.0)
- Comprehensive algorithm selection guide
- **Deep Learning Models Guide** - Detailed documentation for SOTA DL algorithms
- Complete test suite with comprehensive coverage:
  - Classical ML tests (test_pyod_models.py)
  - Deep learning tests (test_dl_models.py) - 400+ lines covering all DL models
- Enhanced documentation structure with dedicated DL guide
- **Comprehensive Evaluation Module** (`pyimgano.evaluation`) ⭐
  - `compute_auroc()` - ROC-AUC computation
  - `compute_average_precision()` - Average Precision for imbalanced datasets
  - `compute_classification_metrics()` - Precision, Recall, F1, Specificity, Accuracy
  - `find_optimal_threshold()` - Automatic threshold optimization (F1, Youden, etc.)
  - `evaluate_detector()` - One-stop comprehensive evaluation
  - `compute_pro_score()` - Pixel-level PRO score for localization
  - `print_evaluation_summary()` - Formatted result display
- **Benchmarking Tools** (`pyimgano.benchmark`) ⭐
  - `AlgorithmBenchmark` class - Systematic multi-algorithm comparison
  - `quick_benchmark()` - Fast benchmarking with defaults
  - Automatic timing measurements (training and inference)
  - Performance ranking by any metric
  - JSON export for results
- **Visualization Module** (`pyimgano.visualization`) ⭐
  - `plot_anomaly_map()` - Heatmap overlay on images
  - `plot_roc_curve()` - ROC curve with AUC
  - `plot_precision_recall_curve()` - PR curve with AP
  - `plot_score_distribution()` - Score histograms for normal/anomaly
  - `compare_detectors()` - Side-by-side detector comparison
  - `save_anomaly_overlay()` - Fast OpenCV-based overlay (no matplotlib)
- **Example Scripts** (examples/) ⭐
  - `quick_start.py` - Basic usage example
  - `benchmark_example.py` - Multi-algorithm benchmarking
  - `visualization_example.py` - Visualization demonstrations
- **Expanded Test Suite** ⭐
  - `test_evaluation.py` - 400+ lines testing all metrics
  - `test_integration.py` - End-to-end workflow tests
  - Synthetic dataset fixtures for testing
  - Edge case and error handling tests
- **Documentation**:
  - `EVALUATION_AND_BENCHMARK.md` - Complete evaluation guide

- Additional PyOD classical wrappers (unified vision API):
  - `vision_iforest` (Isolation Forest)
  - `vision_kde` (Kernel Density Estimation)
  - `vision_gmm` (Gaussian Mixture Model)
  - `vision_sos` (Stochastic Outlier Selection)
  - `vision_sod` (Subspace Outlier Detection)
  - `vision_rod` (Rotation-based Outlier Detection)
  - `vision_qmcd` (Quantile-based MCD)
  - `vision_mad` (Median Absolute Deviation)
  - `vision_lmdd` (LMDD)

### Fixed
- `compute_pro_score` now computes **region-aware** PRO/AUPRO (connected components + FPR-limited integration),
  instead of using pixel-level ROC TPR as a proxy.
- `pyimgano.models.ae` no longer hard-requires `pytorch_msssim` at import time; `ComposedLoss` falls back to L1
  when the optional dependency is missing.

### Changed
- Enhanced package metadata and classifiers
- Improved dependency version specifications
- Updated development workflow documentation
- Updated `__init__.py` to export new modules and functions
- Version bump to 0.2.0

### Improved
- Test configuration with coverage reporting
- Documentation structure
- Code quality and consistency

## [0.1.0] - 2025-01-XX

### Added
- Initial release of PyImgAno
- Visual anomaly detection utilities
- Support for 15+ classical ML anomaly detectors:
  - ABOD (Angle-Based Outlier Detection)
  - CBLOF (Cluster-Based Local Outlier Factor)
  - DBSCAN
  - Isolation Forest
  - HBOS (Histogram-Based Outlier Score)
  - K-Means
  - Kernel PCA
  - LOCI (Local Correlation Integral)
  - LODA (Lightweight On-line Detector)
  - LOF (Local Outlier Factor)
  - LSCP (Locally Selective Combination)
  - MO_GAAL
  - One-Class SVM
  - SUOD (Scalable Unsupervised Outlier Detection)
  - XGBOD (XGBoost Outlier Detection)

- Support for 15 deep learning anomaly detectors:
  - **SimpleNet** (CVPR 2023) - Ultra-fast SOTA ⭐
  - **PatchCore** (CVPR 2022) - Best accuracy ⭐
  - **STFPM** (BMVC 2021) - Student-Teacher ⭐
  - AutoEncoder (AE)
  - AE + SVM
  - ALAD (Adversarial Learning)
  - Anomalib integration
  - Deep SVDD
  - EfficientAD
  - FastFlow
  - IMDD
  - PaDiM
  - Reverse Distillation
  - SSIM-based methods
  - VAE (Variational AutoEncoder)

- Model registry system with factory pattern
- Flexible data loading utilities
- Image preprocessing and transformation pipeline
- Augmentation registry system
- Defect detection operations
- Support for diffusion models (optional)
- Multi-language documentation (English, Chinese, Japanese, Korean)
- Example scripts and notebooks
- MIT License

### Features
- Unified API for all anomaly detection models
- PyTorch Lightning data modules
- Extensible architecture
- Easy model registration system
- Comprehensive image operations
- OpenCV-based augmentation
- Visualization utilities

---

## Release Notes Guidelines

### Types of Changes
- **Added** for new features
- **Changed** for changes in existing functionality
- **Deprecated** for soon-to-be removed features
- **Removed** for now removed features
- **Fixed** for any bug fixes
- **Security** for vulnerability fixes
- **Improved** for enhancements to existing features

### Version Format
- **Major.Minor.Patch** (e.g., 1.0.0)
- **Major**: Incompatible API changes
- **Minor**: New features, backward compatible
- **Patch**: Bug fixes, backward compatible

[Unreleased]: https://github.com/jhlu2019/pyimgano/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/jhlu2019/pyimgano/releases/tag/v0.1.0
