| --- |
| license: other |
| tags: |
| - computer-vision |
| - anomaly-detection |
| - image-classification |
| - experimental |
| --- |
| |
| # ParcelGuard |
|
|
| Reference-guided visual anomaly detection for product inspection. |
|
|
| ## Overview |
|
|
| ParcelGuard compares a query product image with one or more reference images. |
| It extracts ResNet18 spatial features, calculates cosine-distance anomaly maps, |
| and returns a provisional defect decision with a visual overlay. |
|
|
| ## Current pipeline |
|
|
| 1. Load a query image and reference images. |
| 2. Resize and normalize images for ResNet18. |
| 3. Extract intermediate spatial features. |
| 4. Compare query features against each reference at corresponding locations. |
| 5. Take the minimum distance across references at each location. |
| 6. Calculate the 95th percentile anomaly score. |
| 7. Compare the score with an exploratory threshold of 0.70. |
| 8. Return a predicted label and anomaly heatmap overlay. |
|
|
| ## Inference |
|
|
| See `src/predict.py`. The predictor requires the saved backbone artifact |
| `parcelguard_resnet18_layer2.pt` and accepts image paths rather than precomputed features. |
|
|
| The classifier artifact is retained for feature-based experiments; the current |
| raw-image predictor uses the P95 anomaly score directly. |
|
|
| ## Exploratory results |
|
|
| Initial experiments used a sample of 100 query images. |
| The two-feature classifier achieved approximately 0.594 balanced accuracy |
| and 0.607 ROC-AUC in five-fold stratified cross-validation. |
| The P95 score achieved approximately 0.684 ROC-AUC in an exploratory comparison. |
|
|
| A threshold of 0.70 was selected during exploratory threshold diagnostics. |
| This threshold has not been validated on a separate held-out dataset. |
|
|
| ## Known limitations |
|
|
| - The dataset sample is small and results may be affected by selection bias. |
| - A demonstrated defective sample was classified as NORMAL at threshold 0.70. |
| - Heatmaps can highlight packaging, reflections, texture, and alignment differences. |
| - Heatmaps are anomaly estimates, not verified defect segmentation masks. |
| - The current spatial comparison does not robustly handle different product views. |
| - No independent held-out test result is claimed. |
| - This project is experimental and is not production validated. |
|
|
| ## Dataset and licensing |
|
|
| Developed using the Amazon Kaputt dataset. Review the dataset's CC BY-NC-ND 4.0 |
| terms and any applicable model/artifact licensing obligations before redistribution |
| or commercial use. Original dataset images are not included in this repository. |
|
|
| The repository metadata uses `license: other` because the model's redistribution |
| license has not been independently established here. This is not a legal conclusion. |
|
|
| ## Reproducibility |
|
|
| See `requirements.txt`, `environment.json`, `pipeline_config.json`, and the |
| evaluation JSON/CSV files for the current environment and experimental artifacts. |
|
|
