Metadata-Version: 2.4
Name: common-vision-studio
Version: 1.2.0
Summary: Open-source edge vision workbench for acquisition, recognition, measurement, control, and replay
Author: QiuYDvv
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/QiuYDvv/common-vision-studio
Project-URL: Documentation, https://github.com/QiuYDvv/common-vision-studio/tree/main/docs
Project-URL: Issues, https://github.com/QiuYDvv/common-vision-studio/issues
Project-URL: Source, https://github.com/QiuYDvv/common-vision-studio
Keywords: computer-vision,opencv,raspberry-pi,edge-ai,robotics,camera-calibration
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Manufacturing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: Flask<4,>=3.1
Requires-Dist: numpy<3,>=1.24
Requires-Dist: opencv-python<5,>=4.8
Requires-Dist: platformdirs<5,>=4
Requires-Dist: pyserial<4,>=3.5
Provides-Extra: production
Requires-Dist: waitress<4,>=3; extra == "production"
Requires-Dist: gunicorn<24,>=23; platform_system != "Windows" and extra == "production"
Provides-Extra: inference
Requires-Dist: ultralytics<9,>=8.4; extra == "inference"
Requires-Dist: ncnn; extra == "inference"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Requires-Dist: ruff<1,>=0.16; extra == "dev"
Requires-Dist: bandit<2,>=1.9; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pybind11<4,>=3; extra == "dev"
Requires-Dist: cmake<5,>=3.18; extra == "dev"
Requires-Dist: ninja<2,>=1.11; extra == "dev"
Dynamic: license-file

# Common Vision Studio

[English](README.md) | [简体中文](README.zh-CN.md)

[![CI](https://github.com/QiuYDvv/common-vision-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/QiuYDvv/common-vision-studio/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/common-vision-studio.svg)](https://pypi.org/project/common-vision-studio/)
[![Python](https://img.shields.io/pypi/pyversions/common-vision-studio.svg)](https://pypi.org/project/common-vision-studio/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

**An open-source edge vision workbench for Raspberry Pi and Linux.** Calibrate
cameras, run OpenCV/YOLO pipelines, measure world coordinates, control a gimbal,
and replay reproducible sessions from one browser.

![Synthetic Common Vision Studio demo](docs/assets/demo.gif)

> The media in this repository is generated by the safe synthetic demo. It does
> not represent measured hardware or model performance.

## Why Common Vision Studio?

Most prototypes grow around separate camera loops, one-off calibration scripts,
and control processes that cannot reproduce an earlier run. Common Vision Studio
provides one shared latest-frame source and a consistent operational boundary:

- camera capture, calibration, source switching, and health diagnostics;
- reusable preprocessing, recognition, geometry, and measurement services;
- navigation, ball tracking, A4 targeting, and a fail-safe gimbal protocol;
- event recording, configuration snapshots, offline replay, and A/B comparison;
- ground-truth evaluation that keeps code regression separate from vision quality;
- a no-hardware demo that never opens a camera or serial port.

## Three-minute demo

Python 3.11 or newer is required.

```bash
python -m pip install common-vision-studio
common-vision --demo
```

Open <http://127.0.0.1:5000>. Demo mode always binds to loopback, uses synthetic
frames and an in-process gimbal transport, disables laser authorization, and
stores mutable data in an isolated temporary directory.

To work from a clone:

```bash
python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
common-vision --demo
```

## Feature map

| Area | Included capabilities |
| --- | --- |
| Acquisition | OpenCV/Picamera2 camera, files, RTSP, MJPEG, UDP, reconnect supervision |
| Calibration | Diverse chessboard capture, robust outlier filtering, undistortion quality gates |
| Vision | ROI, illumination correction, color/shape/character/QR/fiducial/YOLO recognition |
| Geometry | Camera/world transforms, planar homography, pose and approximate ranging |
| Tasks | Vehicle navigation, ball tracking, A4 target planning and aiming |
| Control | Framed serial protocol, heartbeat, telemetry, stale-command expiry, E-stop, laser authorization |
| Reproducibility | Recording, replay, configuration bundles, scoring, ground-truth evaluation |

## Architecture

```mermaid
flowchart LR
  Sources[Camera / file / stream / synthetic] --> Hub[Shared latest-frame hub]
  Hub --> Vision[Calibration and vision services]
  Vision --> Tasks[Measurement and task pipelines]
  Tasks --> Safety[Expiry, authorization and E-stop]
  Safety --> Gimbal[Gimbal protocol / simulated transport]
  Hub --> Sessions[Record, replay and evaluation]
  Vision --> Sessions
```

See the [architecture guide](docs/ARCHITECTURE.md) for ownership, threading, and
failure boundaries.

## Screenshots

| Dashboard | Image preprocessing |
| --- | --- |
| ![Dashboard](docs/assets/dashboard.png) | ![Preprocessing](docs/assets/preprocess.png) |
| Camera calibration | Record and replay |
| ![Calibration](docs/assets/calibration.png) | ![Replay](docs/assets/replay.png) |

## Hardware and platform support

| Platform | Status | Notes |
| --- | --- | --- |
| Linux x86-64 | Supported | OpenCV camera and production WSGI deployment |
| Raspberry Pi OS 64-bit | Supported | Picamera2/OpenCV; validate on the target device |
| Windows 11 | Software-tested | OpenCV camera and demo; Waitress for serving |
| macOS | Community-tested | Demo and OpenCV paths; no maintained hardware profile |
| Gimbal firmware | Reference implementation | C codec and host vectors are included; hardware acceptance remains mandatory |

Detailed combinations and reporting requirements are in
[hardware compatibility](docs/HARDWARE_COMPATIBILITY.md).

## Installation profiles

```bash
pip install common-vision-studio                 # core and safe demo
pip install "common-vision-studio[production]"  # Waitress/Gunicorn
pip install "common-vision-studio[inference]"   # Ultralytics and NCNN
```

Mutable data defaults to the operating system's application data directory. Use
`--data-dir PATH` or `COMMON_VISION_DATA_DIR` to select a device data root. Run
`common-vision-doctor` before a real deployment.

## Documentation

- [Getting started](docs/GETTING_STARTED.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Hardware compatibility](docs/HARDWARE_COMPATIBILITY.md)
- [Deployment](docs/DEPLOYMENT.md)
- [Operations API](docs/API.md)
- [Algorithm validation](docs/ALGORITHM_VALIDATION.md)
- [Maintainer release guide](docs/MAINTAINER_RELEASE.md)
- [Roadmap](ROADMAP.md)

## Contributing and support

Issues and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md)
and use the structured issue forms so reports include platform and hardware data.
Questions belong in GitHub Discussions; security issues must follow
[SECURITY.md](SECURITY.md).

The code is licensed under [Apache-2.0](LICENSE). Model weights and datasets have
separate terms described in [MODEL_LICENSES.md](MODEL_LICENSES.md).
