Metadata-Version: 2.4
Name: omnivision-cv
Version: 0.2.1
Summary: A backend-agnostic framework for computer vision and 3D model projects, training, workflows, tracking, tuning, visualization, diagnostics, and export.
Author: Milo Evans
License-Expression: MIT
Project-URL: Homepage, https://github.com/milobeans/omnivision
Project-URL: Repository, https://github.com/milobeans/omnivision
Project-URL: Issues, https://github.com/milobeans/omnivision/issues
Keywords: computer-vision,machine-learning,3d,segmentation,detection,training,inference,model-export
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: torch
Requires-Dist: torch>=2.3; extra == "torch"
Requires-Dist: torchvision>=0.18; extra == "torch"
Provides-Extra: vision
Requires-Dist: opencv-python>=4.9; extra == "vision"
Requires-Dist: pillow>=10.0; extra == "vision"
Provides-Extra: cloud
Requires-Dist: boto3>=1.34; extra == "cloud"
Provides-Extra: ultralytics
Requires-Dist: ultralytics>=8.0; extra == "ultralytics"
Provides-Extra: export
Requires-Dist: onnx>=1.16; extra == "export"
Requires-Dist: coremltools>=8.0; extra == "export"
Provides-Extra: spatial
Requires-Dist: open3d>=0.18; extra == "spatial"
Provides-Extra: all
Requires-Dist: boto3>=1.34; extra == "all"
Requires-Dist: coremltools>=8.0; extra == "all"
Requires-Dist: onnx>=1.16; extra == "all"
Requires-Dist: opencv-python>=4.9; extra == "all"
Requires-Dist: open3d>=0.18; extra == "all"
Requires-Dist: pillow>=10.0; extra == "all"
Requires-Dist: torch>=2.3; extra == "all"
Requires-Dist: torchvision>=0.18; extra == "all"
Requires-Dist: ultralytics>=8.0; extra == "all"
Dynamic: license-file

# OmniVision

OmniVision is a backend-agnostic framework for building computer vision and 3D model projects end to end. It gives you an Ultralytics-style command path for common work while keeping the model layer open to any Python library, runtime object, process, repository, or service.

The installable PyPI distribution is `omnivision-cv`; the Python package and CLI are both named `omnivision`.

```bash
pip install omnivision-cv
```

```python
from omnivision import VisionProject, build_model_adapter

project = VisionProject(".omnivision", name="demo")
manifest = project.scan_data("data/images", name="images")
quality = project.assess_data(manifest)

model = build_model_adapter({
    "kind": "universal",
    "name": "detector",
    "backend": "my-cv-library",
    "hooks": {"predict": {"kind": "python", "target": "my_package.detector:predict"}},
})

result = project.infer(model, manifest, batch_size=4)
print(result.to_dict())
```

## What It Includes

- Dataset manifests for images, videos, point clouds, meshes, and custom media.
- Import and export helpers for COCO detection, YOLO detection, image-folder classification, and mask segmentation.
- Quality checks, dataset fingerprints, canonical preparation, splits, and label-safe augmentation planning.
- Universal model integration for Python callables, runtime objects, process commands, external repositories, and HTTP services.
- Optional package-specific adapters for PyTorch and Ultralytics without making them required dependencies or privileged architecture choices.
- Training, hyperparameter search, local experiment tracking, reports, model cards, and improvement plans.
- Inference runs with JSONL predictions and SVG visualizations for detection and segmentation outputs.
- Evaluation and error analysis for classification, detection, segmentation, and spatial/3D outputs.
- Architecture graph construction/rendering, profiling helpers, tracking, postprocessing, export, and export verification.

## CLI

```bash
omnivision --version
omnivision project init .omnivision --name demo
omnivision manifest create data/images --name images --out .omnivision/datasets/images/manifest.json
omnivision manifest quality .omnivision/datasets/images/manifest.json
omnivision integrations list
omnivision presets write universal-integration --out universal.pipeline.toml
omnivision presets write ultralytics-detect --out yolo.pipeline.toml --data data/images --model yolov8n.pt
omnivision train universal.pipeline.toml
omnivision predict universal.pipeline.toml
omnivision evaluate universal.pipeline.toml
omnivision export universal.pipeline.toml
omnivision pipeline run universal.pipeline.toml
omnivision release check
```

## Optional Extras

```bash
pip install "omnivision-cv[vision]"
pip install "omnivision-cv[torch]"
pip install "omnivision-cv[ultralytics]"
pip install "omnivision-cv[export]"
pip install "omnivision-cv[spatial]"
pip install "omnivision-cv[all]"
```

## Backend-Agnostic Adapters

OmniVision does not assume one model runtime. The first-class path is `kind = "universal"`, which can call:

- `kind = "python"` hooks for importable functions from any library.
- `kind = "object"` hooks for instantiated runtime objects and methods.
- `kind = "command"` hooks for CLIs, scripts, or repository-native entrypoints.
- `kind = "http"` hooks for local or remote model services.
- `kind = "adapter"` only when a custom class implementing `ModelAdapter` is the right shape.

All adapters exchange the same manifest, batch, prediction, metrics, artifact, and export contracts, so project tooling stays consistent even when the underlying model stack changes.

```toml
[model]
kind = "universal"
name = "detectron2-or-anything"
backend = "detectron2"
capabilities = ["python-callable", "command-process", "http-service"]

[model.hooks.predict]
kind = "python"
target = "my_integrations.detectron2:predict"

[model.hooks.train]
kind = "command"
argv = ["python", "tools/train_net.py", "--config-file", "{config.config_file}"]
dry_run = true
```

Use `omnivision integrations list` to inspect the integration modes. Torch and Ultralytics are optional convenience adapters built on the same contract, not the framework boundary.

## Plugin SDK

Third-party CV dialects can ship as separate packages and expose an `omnivision.plugins` entry point. A plugin returns a `PluginManifest` containing `PluginRegistration` entries for codecs, model adapters, evaluators, transforms, visualizers, exporters, profilers, storage backends, or workflow ops. Each registration declares capabilities, input/output schema, sample input, expected output, invalid input, and dry-run behavior so `omnivision plugins test <category> <name>` can run conformance checks.

```toml
[project.entry-points."omnivision.plugins"]
toy = "omnivision_toy_plugin:plugin"
```

```bash
omnivision plugins list
omnivision plugins show codec toy_json
omnivision plugins test codec toy_json
```

See `examples/omnivision_toy_plugin` for an installable external plugin that registers a toy codec, model adapter, evaluator, and exporter without modifying OmniVision source.

## Configurable CV Workflows

The preset system creates release-oriented pipeline configs that can be used as-is or refined:

```bash
omnivision presets list
omnivision presets show universal-integration
omnivision presets show ultralytics-detect
omnivision presets write universal-integration --out pipeline.toml --project .omnivision
omnivision presets write torch-classify --out classifier.toml --data data/images --project .omnivision
```

Pipeline configs can be data-only, universal-hook-backed, callable-backed, command-backed, HTTP-service-backed, external-repository-backed, Torch-backed, or Ultralytics-backed. Top-level `train`, `predict`, `evaluate`, and `export` commands run the same pipeline engine while forcing the relevant stage on, which keeps the simple command path and the full config path aligned.

## Torch Integration

The Torch adapter supports custom modules while centralizing training configuration:

- optimizer selection: Adam, AdamW, SGD, RMSprop
- loss selection: cross entropy, BCE, BCE-with-logits, MSE, L1, Smooth L1
- gradient accumulation and gradient clipping
- optional validation loader metrics
- checkpoint export plus TorchScript and ONNX export with explicit example inputs

You can build an adapter from an importable module factory, an OmniVision architecture graph, or inline layer config.

## Detection Evaluation

Detection evaluation reports precision, recall, F1, mean IoU, `map50`, `map75`, and `map50_95`, with per-class AP stored in report metadata. This gives quick local feedback while staying compatible with richer backend-native evaluators.

## Dataset Materialization

Dataset tools support COCO, YOLO, Ultralytics YOLO, image-folder classification, and mask segmentation import/export. Augmentation can remain as a reproducible plan or materialize simple image transforms such as flips, resize, and rotation when Pillow is installed.

## Release Checks

```bash
omnivision release check
python -m pytest
python -m build
python -m twine check dist/*
```

`omnivision release check` verifies the expected package surface, tests directory, typed marker, README, license, and ignored release artifacts before publishing.

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest
python -m build
python -m twine check dist/*
```
