Create README.md

README.md

@@ -0,0 +1,141 @@
+# VAAS: Vision-Attention Anomaly Scoring
+
+## Model Summary
+
+VAAS (Vision-Attention Anomaly Scoring) is a dual-module vision framework for image anomaly detection and localisation.
+It combines global attention-based reasoning with patch-level self-consistency analysis to produce a continuous and interpretable anomaly score alongside spatial anomaly maps.
+
+The model is designed to indicate **where anomalies occur** and **how strongly they deviate from expected visual consistency**, supporting explainable image analysis and integrity assessment.
+
+---
+
+## Architecture Overview
+
+VAAS consists of two complementary components:
+
+- **Global Attention Module (Fx)**  
+  A Vision Transformer backbone that captures global semantic and structural irregularities using attention distributions.
+
+- **Patch-Level Module (Px)**  
+  A SegFormer-based segmentation model that identifies local inconsistencies in texture, boundaries, and regions.
+
+These components are combined via a hybrid scoring mechanism:
+
+- `S_F`: Global attention fidelity score  
+- `S_P`: Patch-level plausibility score  
+- `S_H`: Final hybrid anomaly score  
+
+`S_H` provides a continuous measure of anomaly intensity rather than a binary decision.
+
+---
+
+## Model Variant
+
+This release corresponds to:
+
+- **VAAS v1**
+- Trained on **10% of the DF2023 dataset**
+- Input resolution: `224 × 224`
+- Outputs:
+  - Global anomaly score (`S_H`)
+  - Component scores (`S_F`, `S_P`)
+  - Dense anomaly map (`224 × 224`)
+
+Future releases will scale training data size, include cross-dataset evaluation, and explore model compression.
+
+---
+
+## Intended Use
+
+This model can be used for:
+
+- Image anomaly detection
+- Visual integrity assessment
+- Explainable inspection of irregular regions
+- Research on attention-based anomaly scoring
+- Prototyping anomaly-aware vision systems
+
+It supports both **CPU-only inference** & **GPU-only inference** , though GPU is recommended for faster processing.
+
+---
+
+## Usage
+
+### Load the pipeline
+
+```python
+from vaas.inference.pipeline import VAASPipeline
+from PIL import Image
+
+pipeline = VAASPipeline.from_pretrained(
+    "OBA-Research/vaas-v1-df2023",
+    device="cpu",
+    alpha=0.5
+)
+
+image = Image.open("example.jpg").convert("RGB")
+result = pipeline(image)
+
+print(result["S_H"])
+anomaly_map = result["anomaly_map"]
+```
+
+### Output Format
+
+```python
+{
+  "S_F": float,
+  "S_P": float,
+  "S_H": float,
+  "anomaly_map": numpy.ndarray  # shape (224, 224)
+}
+```
+
+---
+
+## Training Data
+
+The model was trained on a reproducible 10% subset of DF2023.
+The exact filenames used for training are released to support experiment reproducibility.
+
+---
+
+## Limitations
+
+- Trained on a subset of a single dataset
+- Does not classify anomaly types
+- Performance may degrade on out-of-distribution imagery
+
+Users are encouraged to fine-tune or retrain for domain-specific applications.
+
+---
+
+## Ethical Considerations
+
+VAAS is intended for research and inspection purposes.
+It should not be used as a standalone decision-making system in high-stakes settings.
+
+---
+
+## Citation
+
+If you use this model, please cite:
+
+```
+Bamigbade, O., Scanlon, M., Sheppard, J.
+Vision-Attention Anomaly Scoring (VAAS).
+Forensic Science International: Digital Investigation, 2026.
+```
+
+---
+
+## License
+
+MIT License
+
+---
+
+## Maintainers
+
+OBA-Research  
+https://huggingface.co/OBA-Research