Metadata-Version: 2.4
Name: mvkit
Version: 0.2.14
Summary: Machine vision inspection platform for production lines
Author-email: pashidl-lab <pashidl.lab@gmail.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/pashidl-lab/mvkit
Project-URL: Issues, https://github.com/pashidl-lab/mvkit/issues
Keywords: machine-vision,inspection,anomaly-detection,genicam,onnx,industrial
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Manufacturing
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: opencv-python-headless>=4.9
Requires-Dist: Pillow>=10.0
Requires-Dist: onnxruntime>=1.16
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: pydantic>=2.9
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: PyYAML>=6.0
Requires-Dist: cryptography>=42
Requires-Dist: pyzbar>=0.1.9
Requires-Dist: pylibdmtx>=0.1.10
Requires-Dist: pymodbus>=3.6
Provides-Extra: gpu
Requires-Dist: onnxruntime-gpu>=1.16; extra == "gpu"
Provides-Extra: genicam
Requires-Dist: harvesters>=1.4.2; extra == "genicam"
Requires-Dist: genicam>=1.4.0; extra == "genicam"
Provides-Extra: ocr
Requires-Dist: easyocr>=1.7.2; extra == "ocr"
Provides-Extra: train
Requires-Dist: timm>=1.0; extra == "train"
Requires-Dist: transformers<5,>=4.40; extra == "train"
Requires-Dist: scipy>=1.11; extra == "train"
Requires-Dist: segment-anything>=1.0; extra == "train"
Requires-Dist: segment-anything-hq>=0.3; extra == "train"
Requires-Dist: addict>=2.4; extra == "train"
Requires-Dist: yapf>=0.40; extra == "train"
Requires-Dist: pycocotools>=2.0; extra == "train"
Requires-Dist: albumentations>=1.4; extra == "train"
Requires-Dist: imgaug>=0.4; extra == "train"
Requires-Dist: einops>=0.7; extra == "train"
Requires-Dist: empatches>=0.2; extra == "train"
Requires-Dist: positional-encodings>=6.0; extra == "train"
Requires-Dist: scikit-learn>=1.3; extra == "train"
Requires-Dist: tensorboardX>=2.6; extra == "train"
Requires-Dist: tifffile>=2023.1; extra == "train"
Requires-Dist: pandas>=2.0; extra == "train"
Requires-Dist: matplotlib>=3.7; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

# mvkit

Machine vision inspection for production lines — a framework you install, not a
library you call.

`mvkit` runs an unattended inspection loop: wait for a trigger, grab a frame,
run an inspection chain, report the verdict to the line, repeat. Cameras,
triggers, result sinks and inspection modules are all plugins, so a new site is
a configuration change rather than a code change.

**No PyTorch in the default install.** The runtime is `onnxruntime` + `numpy` +
`opencv`.

---

## Install

```bash
pip install mvkit              # CPU
pip install "mvkit[gpu]"       # NVIDIA CUDA via onnxruntime-gpu
pip install "mvkit[genicam]"   # GenICam/GenTL industrial cameras
```

Then:

```bash
mvkit serve                    # http://127.0.0.1:8000 — dashboard and REST API
mvkit doctor                   # what is installed, what is missing, and why
```

The dashboard opens on a demo file camera reading the bundled sample images, so
a fresh install has something to look at before any hardware arrives.

---

## What it does

| Layer | Plugins |
|---|---|
| Cameras | `file` · `opencv` (webcam, RTSP) · `watch_folder` · `harvester` (GenICam) |
| Triggers | `hardware` · `digital_input` · `software` · `interval` · `push` |
| Result sinks | `digital_output` · `modbus_tcp` · `log` — several at once |
| Inspection | see below |

The runtime keeps capture, inference and dispatch on separate threads with
bounded queues, so a slow PLC never stalls inference and a fast line never
silently piles up frames. Camera drop-outs reconnect with backoff; a watchdog
heartbeat tells the line when the inspector itself has stopped.

### Inspection modules

| Module | What it checks | Weights |
|---|---|---|
| `barcode` | 1D barcodes, QR, DataMatrix | none |
| `presence` | part present / missing, by template | none |
| `count` | number of objects | none |
| `color` | colour deviation (Lab ΔE) | none |
| `patchcore` | surface defects — teach from 5–10 good parts | DINOv2 (ONNX) |
| `crane` | surface defects, zero-shot | CLIP + DINOv2 (ONNX) |
| `detect` | object detection | D-FINE (ONNX) |
| `detect_gate` | detect a region, then inspect only that region | D-FINE (ONNX) |
| `ocr` | text reading — needs `mvkit[ocr]` and PyTorch | EasyOCR |
| `schad` | structural + logical anomalies — needs `mvkit[train]` and PyTorch | trained on your machine |

Model weights are **not** bundled in the wheel. They are downloaded per module
on first use, or imported from a disk:

```bash
mvkit models download --module patchcore
mvkit models import D:\mvkit_assets
mvkit models status
```

---

## Teaching a part

Upload five to ten good samples in the dashboard; no defect images are required
and no labelling is involved. The result is stored on your machine and never
leaves it, and a product folder can be copied to another machine as it is.

Teaching from the command line is not available yet.

---

## What needs to be installed separately

Two things cannot come from PyPI.

**Industrial camera SDKs.** `harvesters` talks to a GenTL producer (`.cti`), and
that file ships with the camera vendor's runtime — Basler pylon, Hikrobot MVS,
Teledyne FLIR Spinnaker, and so on. Install the vendor runtime and `mvkit` will
find the producer on its own. Order does not matter; the search happens when a
camera is opened, not at install time.

**PyTorch**, for `mvkit[ocr]` and `mvkit[train]` only. PyPI metadata cannot
express which CUDA build you need, so install it yourself first:

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install "mvkit[train]"
```

`mvkit doctor` reports both, and distinguishes "not installed" from "broken".

---

## Where things are stored

| | Location |
|---|---|
| Model cache | `%LOCALAPPDATA%\mvkit\Cache` · `~/Library/Caches/mvkit` · `~/.cache/mvkit` |
| Products, teaching results, logs | `%LOCALAPPDATA%\mvkit\artifacts` · `~/Library/Application Support/mvkit/artifacts` · `~/.local/share/mvkit/artifacts` |
| Site configuration | `%APPDATA%\mvkit\site.yaml` · `~/.config/mvkit/site.yaml` |

A product folder is self-contained: copy it to another machine and inspection
works there. Retraining caches live outside it and can be deleted.

Line PCs often have a small system drive. `mvkit doctor` prints the artifacts
path with free space; move it with `mvkit config set artifacts_dir D:\...`.

---

## Evaluation

All modules are available for **three months**. After that, `barcode`,
`presence`, `count` and `color` keep working; the rest need a licence.

An expired licence never stops a running line. Inspection in progress continues;
only starting a new run and teaching new products are blocked, and the dashboard
warns 30, 7 and 1 days ahead.

Your teaching results are yours. They are not deleted when a licence expires and
can always be exported.

For a licence, email **pashidl.lab@gmail.com** with your name, organisation and
intended use.

---

## License

Proprietary. Evaluation and non-commercial research use only — see `LICENSE`.
Contact the copyright holder for commercial licensing.
