|
Download README.md from brunojtfernandes/PILAR: direct link, hf CLI and curl.
- Browser
- Download file 9.51 kB
-
https://huggingface.co/brunojtfernandes/PILAR/resolve/main/README.md
- Command line
-
hf download hf://brunojtfernandes/PILAR/README.md
-
curl -L -o README.md https://huggingface.co/brunojtfernandes/PILAR/resolve/main/README.md
9.51 kB
| license: mit | |
| language: | |
| - en | |
| tags: | |
| - computer-vision | |
| - anomaly-detection | |
| - visual-anomaly-detection | |
| - industrial-inspection | |
| - pytorch | |
| - reconstruction | |
| - mvtec-ad | |
| - visa | |
| # PILAR | |
| Code and reference results for **Pyramidal Inhibitory Lightweight | |
| Autoassociative Reconstruction for Cost-Constrained Visual Anomaly Detection**. | |
| Published in [Discover Artificial Intelligence (2026)](https://doi.org/10.1007/s44163-026-02671-5). | |
| PILAR learns to reconstruct normal images or frozen pretrained features using a | |
| compact pyramidal encoder, lateral inhibition, a spatial bottleneck, and a | |
| reconstruction decoder. Anomaly scores are reconstruction residuals. | |
| Feature-PILAR-FCN uses ResNet18 in both training and inference; only the PILAR | |
| heads are trained. | |
| This repository reproduces the paper's MVTec AD and VisA experiments, full-category | |
| MVTec ablations, and complementary image and RGB reconstruction experiments. | |
| The Python package is named `lipnet`; its models implement PILAR. | |
| ## Code availability | |
| This repository distributes the **source code** accompanying the published PILAR article under the [MIT License](LICENSE). | |
| - **Main code repository:** [bjtf/PILAR on GitHub](https://github.com/bjtf/PILAR) | |
| - **Download:** [pilar-source.zip](https://huggingface.co/brunojtfernandes/PILAR/resolve/main/pilar-source.zip?download=true), containing the Python package, experiment scripts, configurations, tests, reproduction guides and tabular reference results. | |
| - **Source version:** [`06eef17`](https://github.com/bjtf/PILAR/commit/06eef17fc14a2e870f82d5ea297dcd1efcc3d897). The archive is a fixed snapshot; GitHub remains the main development repository. | |
| - **Integrity:** [SOURCE_MANIFEST.json](https://huggingface.co/brunojtfernandes/PILAR/resolve/main/SOURCE_MANIFEST.json) records the source commit and file hashes. | |
| ## Download the MVTec AD checkpoints | |
| [Download the 135 trained PILAR checkpoints](https://huggingface.co/brunojtfernandes/PILAR-MVTec-AD/tree/main) | |
| from the separate weights repository. The | |
| [checkpoint model card](https://huggingface.co/brunojtfernandes/PILAR-MVTec-AD) | |
| explains how to restore the TorchVision backbone and run inference with the | |
| downloaded weights. The MVTec AD checkpoints are licensed under | |
| [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). | |
| ## Install the source code | |
| Download the archive using the link above, then extract it: | |
| ```bash | |
| unzip pilar-source.zip | |
| cd PILAR | |
| ``` | |
| Alternatively, obtain the same source version from GitHub: | |
| ```bash | |
| git clone https://github.com/bjtf/PILAR.git | |
| cd PILAR | |
| git checkout 06eef17fc14a2e870f82d5ea297dcd1efcc3d897 | |
| ``` | |
| ## Installation | |
| Use Python 3.12 for the paper environment: | |
| ```bash | |
| python3.12 -m venv .venv | |
| source .venv/bin/activate | |
| python -m pip install --upgrade pip | |
| python -m pip install -r requirements-paper.txt -e '.[test]' | |
| python -m unittest discover -s tests -v | |
| python analysis/verify_reference_results.py | |
| ``` | |
| `requirements-paper.txt` records the versions used by the main industrial | |
| experiments. `requirements.txt` provides the separately tested compatibility | |
| environment. See [REPRODUCIBILITY.md](https://github.com/bjtf/PILAR/blob/06eef17fc14a2e870f82d5ea297dcd1efcc3d897/REPRODUCIBILITY.md) for environment, | |
| checkpoint, and evaluation details. The first feature experiment downloads | |
| torchvision's ImageNet-1K V1 ResNet18 weights if they are not already cached. | |
| ## Industrial experiments | |
| Obtain [MVTec AD](https://www.mvtec.com/research-teaching/datasets/mvtec-ad) | |
| and [VisA](https://github.com/amazon-science/spot-diff) under their original | |
| terms and keep their official layouts: | |
| ```text | |
| data/mvtec_ad/ | |
| bottle/train/good/... | |
| bottle/test/good/... | |
| bottle/test/<defect>/... | |
| bottle/ground_truth/<defect>/... | |
| ... | |
| data/visa/ | |
| split_csv/1cls.csv | |
| candle/Data/Images/Normal/... | |
| candle/Data/Images/Anomaly/... | |
| candle/Data/Masks/Anomaly/... | |
| ... | |
| ``` | |
| The main commands train ten epochs per category, with input size 512×512, | |
| batch size 8, and five seeds. Training uses only normal images; evaluation uses | |
| the final checkpoint and the official test split. | |
| ```bash | |
| python scripts/reproduce_paper.py \ | |
| --experiment mvtec --data-root data/mvtec_ad \ | |
| --device mps --output-dir runs/mvtec | |
| python scripts/reproduce_paper.py \ | |
| --experiment visa --data-root data/visa \ | |
| --device mps --output-dir runs/visa | |
| ``` | |
| Use `--device cuda` for an NVIDIA GPU or `--device cpu` for CPU execution. | |
| Device selection is explicit. Results may vary across hardware and library | |
| versions; the reference experiments used Apple MPS. | |
| The MVTec component ablations cover all 15 categories at seed 42: | |
| ```bash | |
| python scripts/reproduce_paper.py \ | |
| --experiment mvtec-ablation --data-root data/mvtec_ad \ | |
| --device mps --output-dir runs/mvtec_ablation | |
| ``` | |
| This trains four alternatives: no inhibition, no hard residual term, layer 2 | |
| only, and layer 3 only. Compare them with the seed-42 result from the main | |
| MVTec campaign; that reference need not be trained a second time. There is no test-based checkpoint selection or | |
| hyperparameter search in these commands. | |
| Each run writes resolved configuration and provenance, complete-epoch training | |
| checkpoints, a final inference export, per-image scores, evaluation maps, and | |
| category metrics. The campaign also writes `category_metrics.csv`, | |
| `image_scores.csv`, and `summary.json`. See the reproduction guide for resuming | |
| an interrupted run and evaluating an export without training. | |
| ## Reference results | |
| All values below are percentages, computed as a category macro within each | |
| seed and then mean ± sample standard deviation over five seeds. | |
| | Dataset | Image-AUROC | Image-AP | Pixel-AUROC | AUPRO@30 | | |
| |---|---:|---:|---:|---:| | |
| | MVTec AD | 96.91 ± 0.10 | 98.86 ± 0.04 | 96.49 ± 0.04 | 92.63 ± 0.05 | | |
| | VisA | 92.53 ± 0.07 | 92.41 ± 0.13 | 97.84 ± 0.04 | 90.30 ± 0.14 | | |
| [RESULTS.md](https://github.com/bjtf/PILAR/blob/06eef17fc14a2e870f82d5ea297dcd1efcc3d897/RESULTS.md) maps the experiments to the reference data, including | |
| all category/seed metrics and 19,435 industrial image scores. The verifier | |
| checks completeness and recomputes image AUROC/AP from these scores. | |
| To regenerate screening curves and the 73-subtype MVTec analysis: | |
| ```bash | |
| python analysis/analyze_mvtec_feature_pilar_subtype_review_budget.py \ | |
| --output-dir results/generated/review_budget | |
| ``` | |
| To analyze a reproduced campaign, add `--scores runs/mvtec/image_scores.csv` | |
| or the corresponding VisA file. Ranking ties use expected random ordering | |
| within the tied block, without label-based tie breaking. | |
| ## Inference and timing | |
| Inference loads the trained heads, ResNet weights, and normal-training score | |
| statistics from a final export: | |
| ```python | |
| import torch | |
| from lipnet.inference import PilarDetector | |
| checkpoint = ( | |
| "runs/mvtec/mvtec/main/seed_42/details/wide64/hard_0p1x1/topk_0p01/" | |
| "model_bottle_layer2+layer3_hard0p1x1_zscore.pt" | |
| ) | |
| model = PilarDetector(checkpoint, device="mps") | |
| rgb = torch.rand(1, 3, 512, 512) # CPU float32, RGB in [0, 1] | |
| scores, maps = model.predict(rgb) | |
| ``` | |
| Measure the paper's PILAR timing protocol on completed seed-42 exports: | |
| ```bash | |
| python scripts/benchmark_pilar.py \ | |
| --run runs/mvtec/mvtec/main/seed_42 --data-root data/mvtec_ad \ | |
| --output runs/timing --device mps | |
| ``` | |
| Run this without concurrent training. The timing scope starts at a resized | |
| CPU RGB tensor and ends at the score and 256×256 map on CPU. It includes | |
| normalization, transfers, feature extraction, reconstruction, and scoring; | |
| it excludes disk reads and metric calculation. Hardware-dependent measurements | |
| should be compared only under a shared protocol on the same device. | |
| To regenerate the paper's fixed qualitative examples from the completed | |
| seed-42 MVTec run: | |
| ```bash | |
| python scripts/generate_mvtec_qualitative.py \ | |
| --run runs/mvtec/mvtec/main/seed_42 --data_root data/mvtec_ad \ | |
| --output_dir runs/qualitative | |
| ``` | |
| This uses the final evaluation maps and writes PNG/PDF figures and an example | |
| selection manifest. It does not retrain a detector or select a different epoch. | |
| ## Complementary experiments | |
| Commands and the fixed configurations for MNIST, Fashion-MNIST, CIFAR-10, | |
| whole-image RGB, and patchwise RGB appear in | |
| [docs/SUPPLEMENTARY_EXPERIMENTS.md](https://github.com/bjtf/PILAR/blob/06eef17fc14a2e870f82d5ea297dcd1efcc3d897/docs/SUPPLEMENTARY_EXPERIMENTS.md). | |
| [docs/ARTIFACT_SCOPE.md](https://github.com/bjtf/PILAR/blob/06eef17fc14a2e870f82d5ea297dcd1efcc3d897/docs/ARTIFACT_SCOPE.md) describes the files and external | |
| data dependencies. | |
| ## Citation | |
| If you use PILAR or this code in your research, please cite the published article: | |
| > Fernandes, B. J. T. Pyramidal inhibitory lightweight autoassociative reconstruction for cost-constrained visual anomaly detection. *Discover Artificial Intelligence* **6**, 1829 (2026). https://doi.org/10.1007/s44163-026-02671-5 | |
| ```bibtex | |
| @article{Fernandes2026PILAR, | |
| author = {Fernandes, Bruno J. T.}, | |
| title = {Pyramidal inhibitory lightweight autoassociative reconstruction for cost-constrained visual anomaly detection}, | |
| journal = {Discover Artificial Intelligence}, | |
| year = {2026}, | |
| volume = {6}, | |
| number = {1}, | |
| pages = {1829}, | |
| doi = {10.1007/s44163-026-02671-5}, | |
| url = {https://doi.org/10.1007/s44163-026-02671-5} | |
| } | |
| ``` | |
| Citation metadata is also available in [CITATION.cff](CITATION.cff). | |
| The PILAR source code is distributed under the [MIT License](LICENSE). | |
| Datasets and externally downloaded backbone weights retain their respective terms. | |