diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..7acf341 --- /dev/null +++ b/.github/workflows/ci.yml @@ -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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f92575d --- /dev/null +++ b/.gitignore @@ -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 diff --git a/README.md b/README.md index fb83082..339a833 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..94e0c83 --- /dev/null +++ b/pyproject.toml @@ -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" diff --git a/src/vista/__init__.py b/src/vista/__init__.py new file mode 100644 index 0000000..168d743 --- /dev/null +++ b/src/vista/__init__.py @@ -0,0 +1,3 @@ +"""VISTA: Visual Inspection & Spatial Tracking Analytics.""" + +__version__ = "0.0.1" diff --git a/src/vista/schema.py b/src/vista/schema.py new file mode 100644 index 0000000..d509837 --- /dev/null +++ b/src/vista/schema.py @@ -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 diff --git a/tests/test_schema.py b/tests/test_schema.py new file mode 100644 index 0000000..764861a --- /dev/null +++ b/tests/test_schema.py @@ -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)