Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
name: CI

on:
push:
branches: [main]
pull_request:

jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.11", "3.12"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
cache: pip
- name: Install
run: pip install -e ".[dev]"
- name: Lint
run: |
ruff check .
ruff format --check .
- name: Test
run: pytest
33 changes: 33 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Python
__pycache__/
*.py[cod]
*.egg-info/
.venv/
venv/
.pytest_cache/
.ruff_cache/
.mypy_cache/
build/
dist/

# Notebooks
.ipynb_checkpoints/

# Data and model artefacts (never committed; see data/datasets/ for manifests)
data/raw/
data/processed/
*.tar.xz
*.ckpt
*.pt
*.pth
*.onnx

# Experiment output
outputs/
runs/
results/

# Editors / OS
.vscode/
.idea/
.DS_Store
57 changes: 55 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,55 @@
# vista-inspection
Visual inspection: defect detection, localisation and structured inspection reports
# VISTA

**Visual Inspection & Spatial Tracking Analytics**: find, localise and report defects in images of manufactured parts and materials.

> Status: early development. The pipeline below is the target design; this README tracks what actually works.

## What it does

Give VISTA an image of a part. It returns an anomaly score for the whole image, the regions it thinks are defective, and a structured inspection record you can store, audit and evaluate against ground truth.

## Architecture

```mermaid
flowchart LR
A[Image] --> B[Preprocess]
B --> C[Anomaly model]
C --> D[Score map]
D --> E[Threshold + region extraction]
E --> F[InspectionResult]
F --> G[(Results store)]
F --> H[Annotated image]
G --> I[Evaluation: AUROC, PRO, latency]
```

Every stage exchanges data as an `InspectionResult` ([`src/vista/schema.py`](src/vista/schema.py)), validated at the boundaries.

## Roadmap

- [x] Repo tooling: lint, tests, CI
- [x] Inspection result schema
- [ ] Dataset preparation (MVTec AD)
- [ ] Baseline anomaly model
- [ ] Evaluation harness (image AUROC, pixel AUROC, PRO, latency)
- [ ] Inference API
- [ ] Web demo

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check . && pytest
```

## Data

We benchmark on [MVTec AD](https://www.mvtec.com/company/research/datasets/mvtec-ad), which is licensed **CC BY-NC-SA 4.0** (non-commercial). The dataset is not redistributed in this repository; only manifests and preparation scripts are.

## Team

Built by [V2GWorks](https://github.com/V2GWorks).

## Licence

Code: Apache-2.0. Datasets keep their own licences.
35 changes: 35 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
[build-system]
requires = ["hatchling>=1.24"]
build-backend = "hatchling.build"

[project]
name = "vista-inspection"
version = "0.0.1"
description = "Visual inspection pipeline: defect detection, localisation and structured inspection reports."
readme = "README.md"
requires-python = ">=3.11"
license = "Apache-2.0"
authors = [{ name = "V2GWorks" }]
dependencies = [
"pydantic>=2.6",
]

[project.optional-dependencies]
dev = [
"pytest>=8",
"ruff>=0.6",
]

[tool.hatch.build.targets.wheel]
packages = ["src/vista"]

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP", "SIM"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-q"
3 changes: 3 additions & 0 deletions src/vista/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
"""VISTA: Visual Inspection & Spatial Tracking Analytics."""

__version__ = "0.0.1"
78 changes: 78 additions & 0 deletions src/vista/schema.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
"""Inspection result schema.

Every stage of the pipeline (model, API, report writer, evaluation) exchanges
data in this shape, so it is defined once and validated at the boundaries.
Coordinates are in pixels of the original image, origin top-left.
"""

from __future__ import annotations

from datetime import UTC, datetime
from typing import Literal

from pydantic import BaseModel, ConfigDict, Field, model_validator

SCHEMA_VERSION = "0.1"


class BoundingBox(BaseModel):
model_config = ConfigDict(frozen=True)

x_min: int = Field(ge=0)
y_min: int = Field(ge=0)
x_max: int = Field(gt=0)
y_max: int = Field(gt=0)

@model_validator(mode="after")
def _ordered(self) -> BoundingBox:
if self.x_max <= self.x_min or self.y_max <= self.y_min:
raise ValueError("bounding box must have positive width and height")
return self

@property
def area(self) -> int:
return (self.x_max - self.x_min) * (self.y_max - self.y_min)


class Defect(BaseModel):
"""One localised region the model considers anomalous."""

model_config = ConfigDict(frozen=True)

bbox: BoundingBox
score: float = Field(ge=0.0, le=1.0, description="Normalised anomaly score for the region.")
label: str | None = Field(
default=None,
description="Defect type if a classifier assigned one; None for unsupervised detection.",
)
mask_path: str | None = Field(
default=None, description="Relative path to a binary mask PNG for this region."
)


class InspectionResult(BaseModel):
"""The outcome of inspecting one image."""

schema_version: Literal["0.1"] = SCHEMA_VERSION
image_id: str = Field(min_length=1)
image_width: int = Field(gt=0)
image_height: int = Field(gt=0)
model: str = Field(min_length=1, description="Model identifier, e.g. 'patchcore-wrn50'.")
image_score: float = Field(ge=0.0, le=1.0, description="Image-level anomaly score.")
threshold: float = Field(ge=0.0, le=1.0)
defects: list[Defect] = Field(default_factory=list)
inspected_at: datetime = Field(default_factory=lambda: datetime.now(UTC))

@property
def is_anomalous(self) -> bool:
return self.image_score >= self.threshold

@model_validator(mode="after")
def _defects_inside_image(self) -> InspectionResult:
for d in self.defects:
if d.bbox.x_max > self.image_width or d.bbox.y_max > self.image_height:
raise ValueError(
f"defect bbox {d.bbox} extends beyond image "
f"{self.image_width}x{self.image_height}"
)
return self
57 changes: 57 additions & 0 deletions tests/test_schema.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import pytest
from pydantic import ValidationError

from vista.schema import BoundingBox, Defect, InspectionResult


def make_result(**overrides):
base = dict(
image_id="bottle/test/broken_large/000.png",
image_width=900,
image_height=900,
model="patchcore-wrn50",
image_score=0.82,
threshold=0.5,
defects=[Defect(bbox=BoundingBox(x_min=10, y_min=20, x_max=110, y_max=70), score=0.9)],
)
base.update(overrides)
return InspectionResult(**base)


def test_valid_result_round_trips_through_json():
result = make_result()
restored = InspectionResult.model_validate_json(result.model_dump_json())
assert restored == result
assert restored.is_anomalous


def test_below_threshold_is_not_anomalous():
assert not make_result(image_score=0.2, defects=[]).is_anomalous


def test_bbox_area():
assert BoundingBox(x_min=0, y_min=0, x_max=10, y_max=5).area == 50


@pytest.mark.parametrize(
"coords",
[
dict(x_min=10, y_min=0, x_max=10, y_max=5), # zero width
dict(x_min=0, y_min=8, x_max=5, y_max=3), # inverted
],
)
def test_degenerate_bbox_rejected(coords):
with pytest.raises(ValidationError):
BoundingBox(**coords)


def test_defect_outside_image_rejected():
outside = Defect(bbox=BoundingBox(x_min=850, y_min=850, x_max=950, y_max=890), score=0.7)
with pytest.raises(ValidationError, match="beyond image"):
make_result(defects=[outside])


@pytest.mark.parametrize("score", [-0.1, 1.5])
def test_scores_must_be_normalised(score):
with pytest.raises(ValidationError):
make_result(image_score=score)
Loading