# VAAS — Vision-Attention Anomaly Scoring

VAAS is a research-driven, inference-first dual-module vision framework for image anomaly detection and localisation.

It integrates global attention-based reasoning with patch-level consistency analysis to produce:

- A continuous hybrid anomaly score (`S_H`)
- Dense spatial anomaly maps
- Interpretable attention overlays

The output is designed to be spatially grounded, explainable, and suitable for research and prototyping workflows.

> This package provides the **runtime inference pipeline only**.  
> Pretrained model weights are hosted separately on Hugging Face.

[Research Paper](https://arxiv.org/pdf/2512.15512) |
[GitHub](https://github.com/OBA-Research/VAAS) |
[Hugging Face Models](https://huggingface.co/OBA-Research/vaas)

---

## Installation

```bash
pip install vaas
```

### Optional dependency: PyTorch

VAAS uses **lazy loading** for PyTorch.

* Importing `vaas` does **not** require PyTorch
* PyTorch is required **only when running inference**

If PyTorch is not installed, VAAS will raise a clear runtime error when inference is invoked.

Install PyTorch (CPU, CUDA, or ROCm) from:
[https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)

---

## Quick Start

```python
from vaas.inference.pipeline import VAASPipeline
from PIL import Image

pipeline = VAASPipeline.from_pretrained(
    repo_id = "OBA-Research/vaas",
    device="cpu",
    alpha=0.5,
    model_variant = "v1-base-df2023" # v1-medium-df2023 and v1-large-df2023 are other model variants you can use.
  )

image = Image.open("image.jpg").convert("RGB")
result = pipeline(image)

print(result["S_H"])
```

### Output format

```python
{
    "S_F": float,           # global feature anomaly score
    "S_P": float,           # patch consistency score
    "S_H": float,           # hybrid anomaly score
    "anomaly_map": ndarray  # shape (224, 224)
}
```

---

## Visualisation

Generate qualitative visual explanations combining:

* Patch-level anomaly heatmaps
* Global attention overlays
* A hybrid anomaly score gauge

```python
pipeline.visualize(
    image="image.jpg",
    save_path="vaas_visualization.png",
    mode="all",
    threshold=0.5,
)
```

---

## Model Variants

VAAS models are versioned by architecture, scale, and dataset.

Example:

- v1-base-df2023
- v1-medium-df2023
- 1-large-df2023

Each variant is stored as a separate versioned branch on Hugging Face.

See:
- https://github.com/OBA-Research/VAAS 
- https://huggingface.co/OBA-Research/vaas

---

## Reproducibility

Each published model variant contains structured metadata:

- Architecture version
- Dataset
- Dataset fraction
-Runtime defaults
- Backbone configuration

This ensures reproducible loading and transparent model lineage.

## Intended Use

VAAS is intended for:

* Image anomaly detection
* Visual integrity assessment
* Explainable inspection of irregular regions
* Research on attention-based anomaly scoring
* Digital forensics research
* Prototyping anomaly-aware vision systems

Supports CPU-only inference and GPU acceleration.

---

## Limitations

* Trained on a single dataset
* Does not classify anomaly types
* Performance may degrade on out-of-distribution imagery

VAAS should not be used as a standalone decision-making system in high-stakes applications.

---

## Citation

If you use VAAS in your research, please cite both the software and the associated paper as appropriate.

### Software Citation

```python
@software{vaas,
  title        = {VAAS: Vision-Attention Anomaly Scoring},
  author       = {Bamigbade, Opeyemi and Scanlon, Mark and Sheppard, John},
  year         = {2025},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.18064355},
  url          = {https://doi.org/10.5281/zenodo.18064355}
}

```

### Paper Citation

```python
@article{bamigbade2025vaas,
  title={VAAS: Vision-Attention Anomaly Scoring for Image Manipulation Detection in Digital Forensics},
  author={Bamigbade, Opeyemi and Scanlon, Mark and Sheppard, John},
  journal={arXiv preprint arXiv:2512.15512},
  year={2025}
}
```

---

## License

MIT License

---

## Maintainers

OBA-Research
- [https://github.com/OBA-Research](https://github.com/OBA-Research)
- [https://huggingface.co/OBA-Research](https://huggingface.co/OBA-Research)
