KirubaLS/parcelguard-reference-defect-detection

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.