+# AnomaVision
-
+
+
+ Production-oriented visual anomaly detection from normal images. +
-
+ 
+ 
+
-
-{result["threshold"]:.6f}Calibrated thresholds, hardware-aware profiling, and localization health checks in one reproducible report.
{selected_result["threshold"]:.6f}. It was selected {escape(target_text)}. Recheck this threshold on a production validation set before release.| Model | Image AUROC | Pixel AUROC | Median ms | P95 ms | Anomaly coverage | Normal false positives | Threshold |
|---|
Anomaly coverage measures detected defect images. Normal false positives should remain low.
{escape(str(manifest["selected_artifact"]))}{escape(str(selected_result["model_format"]))}{environment_json}
Visa Dataset
-👉 Benchmarks confirm: **AnomaVision is edge-ready, lightweight, and faster — without sacrificing accuracy.** +Use the corrected benchmark before making production claims about accuracy, speed, memory, or model size. --- diff --git a/docs/cli.md b/docs/cli.md index 7be7f40..7938329 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,12 +1,13 @@ # 🛠️ CLI Reference -AnomaVision provides a unified `anomavision` command with four subcommands: +AnomaVision provides a unified `anomavision` command with five subcommands: ```bash anomavision train # Train a PaDiM anomaly detection model anomavision detect # Run inference on test images anomavision eval # Evaluate performance on MVTec-style datasets -anomavision export # Export models to ONNX, TorchScript, or OpenVINO +anomavision export # Export models to ONNX, TorchScript, OpenVINO, or TensorRT +anomavision autopilot # Calibrate, profile, and package a production model ``` Each subcommand accepts both **CLI arguments** and **config files** (`--config config.yml`). @@ -20,6 +21,7 @@ anomavision train --help anomavision detect --help anomavision eval --help anomavision export --help +anomavision autopilot --help ``` --- @@ -169,6 +171,36 @@ anomavision export \ --- +## 5. Production Autopilot — `anomavision autopilot` + +Production Autopilot compares PaDiM and ultra-light PatchCore artifacts on the same complete labeled test split, calibrates algorithm-specific thresholds, measures latency, checks localization health, and creates a deployment package. + +Set the complete dataset root in `config.yml`: + +```yaml +dataset_path: "D:/01-DATA" +class_name: "bottle" +``` + +Use the command below on a CPU-only Windows machine: + +```powershell +anomavision autopilot ` + --config config.yml ` + --padim_model .\distributions\padim\bottle\anomav_exp\model.pt ` + --patchcore_model .\distributions\patchcore\bottle\anomav_exp\model.pt ` + --dataset_path "D:/01-DATA" ` + --class_name bottle ` + --device cpu ` + --validation_split 1.0 ` + --target_latency_ms 50 ` + --output_dir .\production_package +``` + +The generated `production_autopilot_report.html` shows image AUROC, pixel AUROC, anomaly localization coverage, normal-image false-positive localization, anomaly mean mask area, latency, thresholds, and a localization verdict. `N/A` means the required spatial map or ground-truth mask was unavailable; it is not a zero score. + +--- + ## Config File + CLI Override Pattern All subcommands follow the same priority: **CLI args > config file > defaults**. diff --git a/docs/config.md b/docs/config.md index 728bc99..0b5c9cd 100644 --- a/docs/config.md +++ b/docs/config.md @@ -49,7 +49,9 @@ python train.py --config config.yml | `model` | str | None | Model file (`.pt`, `.pth`, `.onnx`). | | `device` | str | auto | Device (`cpu`, `cuda`, or `auto`). | | `batch_size` | int | 1 | Batch size for inference. | -| `thresh` | float | None | Anomaly threshold. | +| `thresh` | float | None | Legacy global anomaly threshold fallback. | +| `thresh_padim` | float | None | PaDiM-specific threshold; takes precedence over `thresh`. | +| `thresh_patchcore` | float | None | PatchCore-specific threshold; takes precedence over `thresh`. | | `enable_visualization` | bool | False | Enable heatmap overlays. | | `save_visualizations` | bool | False | Save visualization images. | | `viz_output_dir` | str | ./results/ | Directory to save images. | @@ -59,7 +61,20 @@ python train.py --config config.yml --- -## 4. Evaluation +## 4. PatchCore + +| Key | Type | Default | Description | +|---|---|---:|---| +| `coreset_ratio` | float | 0.02 | Fraction of normal patches retained. | +| `max_memory_patches` | int | 2048 | Hard memory-bank cap. | +| `patch_grid` | int | 14 | Spatial pooling grid for lightweight localization. | +| `search_chunk_size` | int | 1024 | Chunk size for bounded nearest-neighbor search. | +| `coreset_method` | str | kcenter | `kcenter` for deterministic diverse selection or `random`. | +| `coreset_seed` | int | 42 | Reproducibility seed for coreset selection. | + +--- + +## 5. Evaluation | Key | Type | Default | Description | | ------------------ | ---- | ------- | -------------------------------- | @@ -70,7 +85,7 @@ python train.py --config config.yml --- -## 5. Export +## 6. Export | Key | Type | Default | Description | | ------------------ | ---- | ------- | --------------------------------------------------------- | @@ -82,10 +97,22 @@ python train.py --config config.yml | `quantize_dynamic` | bool | False | Export dynamic INT8 ONNX. | | `quantize_static` | bool | False | Export static INT8 ONNX (requires calibration). | | `calib_samples` | int | 100 | Calibration samples for static quantization. | +| `tensorrt_precision` | str | fp16 | TensorRT precision (`fp32`, `fp16`, or `int8`). | +| `workspace_gb` | float | 2.0 | TensorRT builder workspace limit in GB. | +| `min_batch` | int | 1 | Minimum TensorRT dynamic batch size. | +| `opt_batch` | int | 1 | Optimized TensorRT dynamic batch size. | +| `max_batch` | int | 4 | Maximum TensorRT dynamic batch size. | +| `calib_dir` | str/null | null | Real-image directory for TensorRT INT8 calibration. | --- -## 6. Logging +## 7. Production Autopilot + +Autopilot reads `dataset_path` and `class_name`, uses the complete labeled `test` split by default, and writes `deployment_manifest.json`, `production_autopilot_report.html`, and a Markdown fallback. Its HTML report distinguishes image AUROC, pixel AUROC, anomaly localization coverage, normal-image false-positive localization, and anomaly mean mask area. + +--- + +## 8. Logging | Key | Type | Default | Description | | ----------- | ---- | ------- | ---------------------------------------------------- | @@ -121,6 +148,20 @@ viz_output_dir: ./results/ format: onnx precision: fp16 quantize_dynamic: true + +# Algorithm-specific thresholds +thresh: null +thresh_padim: null +thresh_patchcore: null + +# Ultra-light PatchCore +algorithm: patchcore +coreset_method: kcenter +coreset_seed: 42 +coreset_ratio: 0.02 +max_memory_patches: 2048 +patch_grid: 14 +search_chunk_size: 1024 ``` --- diff --git a/docs/production_deployment.md b/docs/production_deployment.md new file mode 100644 index 0000000..9f39bad --- /dev/null +++ b/docs/production_deployment.md @@ -0,0 +1,121 @@ +# Production deployment + +This page contains the details that are useful after the first successful AnomaVision run. The main README intentionally keeps the beginner workflow short. + +## Lightweight PatchCore + +PatchCore stores normal training patches in a memory bank and scores each test patch by its nearest stored feature. This implementation follows the PaDiM design contract: training is `model.fit(dataloader)`, inference is `model.predict(batch)`, and both image scores and spatial maps are returned. + +Use the configuration below when inference latency or memory is more important than retaining every training patch: + +```yaml +algorithm: patchcore +backbone: resnet18 +layer_indices: [0, 1] +coreset_ratio: 0.02 +max_memory_patches: 2048 +patch_grid: 14 +search_chunk_size: 1024 +``` + +`coreset_ratio` controls the fraction of extracted normal patches retained. `max_memory_patches` provides a hard upper bound. `patch_grid` pools the native feature map to a small spatial grid, and `search_chunk_size` prevents a full query-by-memory distance matrix from being allocated. Start with `resnet18`, `[0]`, a 14x14 grid, and the defaults above; increase the memory cap only after measuring validation quality and latency on the target device. + +The implementation uses normalized embeddings and chunked matrix multiplication rather than `torch.cdist` over the entire batch. This keeps the working memory bounded while preserving a nearest-normal-patch score. It is intentionally an ultra-light approximation of full PatchCore: the lower memory and patch count can reduce accuracy, so validate the trade-off on the target defect classes. + +## TensorRT export + +TensorRT is an optional NVIDIA deployment dependency. The exporter first creates the model graph, then uses the native TensorRT builder and ONNX parser to produce a serialized `.engine` file. TensorRT is imported lazily, so CPU installations continue to support the other formats. + +```bash +# FP16 +anomavision export --config config.yml --format tensorrt \ + --device cuda --tensorrt-precision fp16 + +# Calibrated INT8 +anomavision export --config config.yml --format tensorrt \ + --device cuda --tensorrt-precision int8 \ + --calib-dir ./dataset/bottle/train/good \ + --calib-samples 100 --workspace-gb 4 +``` + +INT8 calibration images should represent the normal production input distribution and use the same resize, crop, and normalization settings as training. The calibration cache is written beside the engine and can be reused when the graph and preprocessing remain unchanged. TensorRT export must be performed on a machine with a compatible CUDA/TensorRT/PyCUDA installation; an engine is generally tied to the TensorRT and GPU environment in which it was built. + +## Verification checklist + +| Check | Recommended evidence | +|---|---| +| Accuracy | Report image and pixel AUROC with the exact dataset split; use `N/A` when spatial maps or masks are unavailable. | +| Latency | Report warm-up policy, batch size, input shape, device, and percentile latency. | +| Memory | Record peak GPU memory and PatchCore memory-bank size. | +| Export parity | Compare PyTorch scores/maps with ONNX or TensorRT outputs on the same images. | +| Reproducibility | Save the effective config, dependency versions, commit SHA, and calibration directory description. | + +## Making the project popular + +Adoption is more likely when a project is easy to verify and easy to integrate. The recommended sequence is to publish a minimal reproducible benchmark command, a short model card, one production export example, and a small demo using a user-provided image. Keep claims tied to the benchmark script rather than to a single headline number. + +A useful release should include a comparison table with dataset split, preprocessing, backbone, hardware, batch size, and latency methodology. Link the raw results and invite independent reproduction. Then publish a short example showing how to load the exported artifact in an existing service. This creates three entry points: researchers can inspect the benchmark, engineers can copy the deployment path, and beginners can run the quickstart. + +For discoverability, use a clear repository description, topic tags such as `anomaly-detection`, `computer-vision`, `patchcore`, and `tensorrt`, a small release note for each version, and issue templates for bug reports and benchmark reproduction. Avoid unsupported claims such as “best” unless the comparison protocol is public and repeatable. + +## Automatic TensorRT conversion + +Use `scripts/convert_to_tensorrt.py` when you already have a compact PaDiM statistics artifact or an ultra-light PatchCore memory-bank artifact. The utility detects the artifact type and delegates model loading and TensorRT construction to the shared export pipeline. + +```bash +python scripts/convert_to_tensorrt.py ` + --model ./model_data/patchcore/bottle/run/model.pth ` + --output-dir ./engines/bottle ` + --precision int8 ` + --device cuda ` + --calib-dir ./dataset/bottle/train/good ` + --calib-samples 100 ` + --min-batch 1 --opt-batch 1 --max-batch 4 +``` + +For FP16, omit the calibration directory and change `--precision int8` to `--precision fp16`. INT8 conversion requires real normal calibration images; the TensorRT path no longer falls back to random calibration data. The utility accepts PNG, JPEG, BMP, TIFF, and nested calibration-image directories, writes a reusable calibration cache beside the engine, and deserializes the generated engine for validation unless `--skip-validation` is supplied. + +The input artifact may be either a PaDiM `.pth` statistics file or a PatchCore artifact containing its memory bank and feature settings. The default dynamic profile is batch 1/1/4; override it when the deployment workload has a different batch distribution. + +## Algorithm-specific thresholds and PatchCore coreset selection + +PaDiM and PatchCore produce different score scales. PaDiM uses Mahalanobis distances, while PatchCore uses bounded normalized nearest-neighbor distances, so a single threshold should not be shared between them. + +Use separate values in `config.yml`: + +```yaml +thresh: null +thresh_padim: null +thresh_patchcore: null +``` + +With an algorithm-specific value set to `null`, `eval` selects a threshold from the evaluation labels and logs the selected value. For production `detect`, copy the threshold selected on a separate validation set into the corresponding field, for example `thresh_patchcore: 0.35`. A threshold of `0.0` is valid and remains active. + +PatchCore now uses deterministic greedy k-center selection by default instead of random memory-bank sampling. This improves coverage of normal feature space while retaining the configured `coreset_ratio` and `max_memory_patches` limits. Set `coreset_method: random` only when you explicitly prefer faster training over representative memory-bank coverage. + +## Production Autopilot + +Production Autopilot evaluates available PaDiM and ultra-light PatchCore artifacts on the same labeled data, calibrates a separate threshold for each algorithm, measures median and p95 latency on the selected hardware, computes image and pixel AUROC when valid targets exist, checks localization health, and packages the selected artifact with a deployment manifest and report. + +Set the complete dataset root and class in `config.yml`: + +```yaml +dataset_path: "D:/01-DATA" +class_name: "bottle" +``` + +The root must contain `bottle/train/good`, `bottle/test/good`, defect folders, and `bottle/ground_truth`. Autopilot uses the complete labeled `test` split by default (`--validation_split 1.0`) so threshold calibration and AUROC evaluation include all available normal and defective test images. The training split is used to fit the artifacts; it is not mixed into the labeled test metrics. + +Run it on CPU with: + +```powershell +anomavision autopilot ` + --config config.yml ` + --padim_model .\distributions\padim\bottle\run\model.pt ` + --patchcore_model .\distributions\patchcore\bottle\run\model.pt ` + --device cpu ` + --target_latency_ms 50 ` + --output_dir .\production_package +``` + +The output contains `model.*`, `deployment_manifest.json`, `production_autopilot_report.html`, and `localization_report.md`. Open `production_autopilot_report.html` in any browser for the polished dashboard; it is self-contained and needs no internet connection or additional assets. The dashboard reports image AUROC, pixel AUROC, anomaly localization coverage, normal-image false-positive localization, anomaly mean mask area, and a localization verdict. `Anomaly coverage` is the fraction of defective images with a non-empty mask; `normal false positives` is the fraction of normal images with a non-empty mask. These are diagnostics, not substitutes for pixel AUROC. The manifest records preprocessing, calibrated thresholds, metrics, latency, localization health, selected model, and runtime environment. Recheck the selected threshold on a production validation set before release. diff --git a/onnxruntime_cpp/oop_anomaly_detector.py b/onnxruntime_cpp/oop_anomaly_detector.py index 4d4f76c..747eb9d 100644 --- a/onnxruntime_cpp/oop_anomaly_detector.py +++ b/onnxruntime_cpp/oop_anomaly_detector.py @@ -196,7 +196,7 @@ def annotate(self, img: np.ndarray, r: Result, t_ms: float): cv2.rectangle(img, (5, 5), (420, 110), (0, 0, 0), -1) cv2.putText( img, - f"Score: {self._to_fixed(r.score,3)}", + f"Score: {self._to_fixed(r.score, 3)}", (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 0.7, @@ -214,7 +214,7 @@ def annotate(self, img: np.ndarray, r: Result, t_ms: float): ) cv2.putText( img, - f"Time: {self._to_fixed(t_ms,2)} ms", + f"Time: {self._to_fixed(t_ms, 2)} ms", (10, 90), cv2.FONT_HERSHEY_SIMPLEX, 0.6, diff --git a/scripts/convert_to_tensorrt.py b/scripts/convert_to_tensorrt.py new file mode 100644 index 0000000..4aba584 --- /dev/null +++ b/scripts/convert_to_tensorrt.py @@ -0,0 +1,211 @@ +"""Convert AnomaVision PaDiM or ultra-light PatchCore artifacts to TensorRT. + +This command detects the compact statistics format written by PaDiM/PatchCore, +loads it through the shared :class:`ModelExporter`, and builds a native TensorRT +engine using the repository's current FP16/INT8 pipeline. + +Examples: + python scripts/convert_to_tensorrt.py \ + --model model_data/patchcore/bottle/run/model.pth \ + --output-dir engines/bottle \ + --calib-dir dataset/bottle/train/good \ + --precision int8 --device cuda + + python scripts/convert_to_tensorrt.py \ + --model model_data/padim/bottle/run/model.pth \ + --output-dir engines/bottle \ + --precision fp16 --device cuda +""" + +from __future__ import annotations + +import argparse +import logging +import sys +from pathlib import Path +from typing import Iterable, Tuple + +import torch + +# Allow `python scripts/convert_to_tensorrt.py` from a source checkout. +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from anomavision.export import ModelExporter + +IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".bmp", ".tif", ".tiff"} +PADIM_KEYS = {"mean", "cov_inv", "channel_indices", "layer_indices", "backbone"} +PATCHCORE_KEYS = {"memory_bank", "layer_indices", "backbone"} + + +def _logger() -> logging.Logger: + """Create a concise standalone logger for conversion output.""" + logger = logging.getLogger("anomavision.convert_tensorrt") + if not logger.handlers: + handler = logging.StreamHandler() + handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s")) + logger.addHandler(handler) + logger.setLevel(logging.INFO) + return logger + + +def _image_files(directory: Path) -> Iterable[Path]: + """Yield supported calibration images in deterministic order.""" + return sorted( + path + for path in directory.rglob("*") + if path.is_file() and path.suffix.lower() in IMAGE_EXTENSIONS + ) + + +def detect_artifact(model_path: Path) -> Tuple[str, object]: + """Load an artifact and identify it as PaDiM, PatchCore, or a full model. + + Args: + model_path: Path to a compact ``.pth``/``.pt`` artifact. + + Returns: + A pair containing the detected model name and the loaded object. + + Raises: + FileNotFoundError: If ``model_path`` does not exist. + ValueError: If the artifact is not a supported AnomaVision model. + """ + if not model_path.is_file(): + raise FileNotFoundError(f"Model artifact does not exist: {model_path}") + artifact = torch.load(model_path, map_location="cpu", weights_only=False) + if isinstance(artifact, dict) and PADIM_KEYS.issubset(artifact): + return "padim", artifact + if isinstance(artifact, dict) and PATCHCORE_KEYS.issubset(artifact): + return "patchcore", artifact + if isinstance(artifact, torch.nn.Module): + name = artifact.__class__.__name__.lower() + if "padim" in name: + return "padim", artifact + if "patchcore" in name: + return "patchcore", artifact + raise ValueError( + "Unsupported artifact. Expected PaDiM statistics, PatchCore memory-bank " + "statistics, or a serialized PaDiM/PatchCore module." + ) + + +def validate_engine(engine_path: Path, input_name: str = "input") -> None: + """Deserialize a TensorRT engine and verify that it has an input tensor.""" + try: + import tensorrt as trt + except ImportError as exc: + raise RuntimeError( + "TensorRT is required for engine validation; the engine was still built." + ) from exc + runtime = trt.Runtime(trt.Logger(trt.Logger.ERROR)) + with engine_path.open("rb") as handle: + engine = runtime.deserialize_cuda_engine(handle.read()) + if engine is None: + raise RuntimeError(f"TensorRT could not deserialize {engine_path}") + if hasattr(engine, "num_io_tensors"): + names = [engine.get_tensor_name(i) for i in range(engine.num_io_tensors)] + else: + names = [engine.get_binding_name(i) for i in range(engine.num_bindings)] + if input_name not in names: + raise RuntimeError( + f"Engine inputs/outputs {names} do not include '{input_name}'" + ) + + +def build_parser() -> argparse.ArgumentParser: + """Build the conversion CLI parser.""" + parser = argparse.ArgumentParser( + description="Convert an AnomaVision PaDiM or PatchCore artifact to TensorRT." + ) + parser.add_argument( + "--model", type=Path, required=True, help="Input .pth/.pt model artifact" + ) + parser.add_argument( + "--output-dir", + type=Path, + required=True, + help="Directory for the engine and calibration cache", + ) + parser.add_argument( + "--output-name", + default=None, + help="Engine filename; defaults to