vizion3d 1.0.0__tar.gz

vizion3d-1.0.0/.gitignore

@@ -0,0 +1,239 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# ── vision3d project-specific ─────────────────────────────────────────────
+
+# Claude Code
+.claude/
+
+# macOS
+.DS_Store
+
+# Model weight files (downloaded at runtime — not committed)
+*.pth
+*.pt
+
+# Local scratch / output files
+*.ply
+image.png
+image2.png
+sample.py
+
+# uv python pin (library — consumers choose their own Python)
+.python-version

vizion3d-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MOSES OLAFENWA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vizion3d-1.0.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: vizion3d
+Version: 1.0.0
+Summary: U3D Capability and Intelligence for the real world. 
+Project-URL: Homepage, https://github.com/OlafenwaMoses/vizion3D
+Project-URL: Documentation, https://olafenwamoses.github.io/vizion3D
+Project-URL: Repository, https://github.com/OlafenwaMoses/vizion3D
+Project-URL: Issues, https://github.com/OlafenwaMoses/vizion3D/issues
+License: MIT
+License-File: LICENSE
+Keywords: 3d,ai,artificial intelligence,computer-vision,depth-estimation,lidar,llm,mesh,nerf,point-cloud,reconstruction,slam
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: clean-ioc>=1.3.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: grpcio-tools>=1.60.0
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: open3d>=0.18.0
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: torch>=2.11.0
+Requires-Dist: torchvision>=0.26.0
+Requires-Dist: transformers>=5.6.2
+Requires-Dist: uvicorn>=0.23.0
+Description-Content-Type: text/markdown
+
+# vizion3D
+3D Capability and Intelligence for the real world.

vizion3d-1.0.0/README.md

@@ -0,0 +1,2 @@
+# vizion3D
+3D Capability and Intelligence for the real world.

vizion3d-1.0.0/docs/api/lifting.md

@@ -0,0 +1,27 @@
+# Lifting API Reference
+
+The `lifting` module exposes tasks that convert 2D image data into 3D representations — depth maps, point clouds, and meshes.
+
+---
+
+## DepthEstimation
+
+The primary entry point for the depth estimation task. Instantiate once and call `.run()` with a `DepthEstimationCommand`.
+
+::: vizion3d.lifting.DepthEstimation
+
+---
+
+## DepthEstimationCommand
+
+Input contract for the depth estimation task. All inference parameters are declared here.
+
+::: vizion3d.lifting.commands.DepthEstimationCommand
+
+---
+
+## DepthEstimationResult
+
+Output contract returned by `DepthEstimation.run()`. All fields are always present; optional geometry fields are `None` when the corresponding `return_*` flag was not set.
+
+::: vizion3d.lifting.models.DepthEstimationResult

vizion3d-1.0.0/docs/features/depth_estimation.md

@@ -0,0 +1,290 @@
+# Depth Estimation
+
+**Category:** Lifting (2D → 3D)  
+**Experimental:** No
+
+Depth estimation predicts the per-pixel distance from the camera for every pixel in a 2D RGB image, producing a depth map and optionally unprojecting it into a 3D point cloud or surface mesh. vizion3d uses [Depth Anything V2](https://github.com/DepthAnything/Depth-Anything-V2) as its default backend.
+
+---
+
+## Model backends
+
+| Value | What happens |
+|---|---|
+| `"depth-anything/Depth-Anything-V2-Base-hf"` *(default)* | Downloads the vizion3D release checkpoint (`depth_anything_v2_vitb.pth`) to `~/.cache/vizion3d/models/` on first use, then loads it directly |
+| Any other string | Passed through to Hugging Face `transformers.pipeline(task="depth-estimation", model=...)` |
+| A local `.pth` or `.pt` file path | Loaded directly as a Depth Anything V2 checkpoint — never downloaded |
+
+Models are kept in memory after the first inference in the current process. Subsequent calls to any `DepthEstimation` instance reuse the loaded weights.
+
+Set `VISION3D_MODEL_CACHE` in your environment to change the default cache directory.
+
+---
+
+## Command parameters
+
+`DepthEstimationCommand` is the input contract for this task.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `image_input` | `str \| bytes` | **Yes** | — | Image to process. Pass a file path string or raw image bytes. |
+| `model_backend` | `str` | No | `"depth-anything/Depth-Anything-V2-Base-hf"` | Model backend identifier. See [Model backends](#model-backends) above. |
+| `return_depth_image` | `bool` | No | `False` | If `True`, the result includes a 16-bit grayscale Open3D Image of the depth map. |
+| `return_point_cloud` | `bool` | No | `False` | If `True`, the result includes an Open3D PointCloud unprojected from the RGB-D image. |
+| `return_mesh` | `bool` | No | `False` | If `True`, the result includes an Open3D TriangleMesh reconstructed from the point cloud via ball-pivoting. |
+
+---
+
+## Result fields
+
+`DepthEstimationResult` is the output contract for this task.
+
+| Field | Type | Always present | Description |
+|---|---|---|---|
+| `depth_map` | `list[list[float]]` | Yes | Raw floating-point depth array, shape `[H][W]`. Values are relative (not metric) — closer objects have higher values for inverse-depth models. |
+| `min_depth` | `float` | Yes | Minimum value in `depth_map`. |
+| `max_depth` | `float` | Yes | Maximum value in `depth_map`. Guaranteed `max_depth >= min_depth`. |
+| `backend_used` | `str` | Yes | Resolved model identifier that processed the request (local file path or HuggingFace model ID). |
+| `depth_image` | `open3d.geometry.Image \| None` | When `return_depth_image=True` | 16-bit grayscale image, dtype `uint16`, shape `(H, W)`. The full 0–65535 range maps to `[min_depth, max_depth]`. |
+| `point_cloud` | `open3d.geometry.PointCloud \| None` | When `return_point_cloud=True` | Coloured 3D point cloud unprojected from the RGB-D image using PrimeSense default intrinsics. Coordinates are in metres. |
+| `mesh` | `open3d.geometry.TriangleMesh \| None` | When `return_mesh=True` | Triangle mesh surface reconstructed from the point cloud via ball-pivoting. Includes vertex colours. |
+| `point_cloud_scale` | `float` | Yes | Scale factor: multiply any distance measured between two points in the point cloud by this value to get the equivalent distance in metres. Always `1.0` — Open3D produces point cloud coordinates directly in metres. |
+
+---
+
+## 1. Direct Python import — image bytes
+
+The most common usage: read an image file into bytes and dispatch the command.
+
+```python
+from vizion3d.lifting import DepthEstimation, DepthEstimationCommand
+
+with open("scene.png", "rb") as f:
+    img_bytes = f.read()
+
+cmd = DepthEstimationCommand(image_input=img_bytes)
+result = DepthEstimation().run(cmd)
+
+print(f"Depth map shape : {len(result.depth_map)} rows × {len(result.depth_map[0])} cols")
+print(f"Depth range     : {result.min_depth:.4f} → {result.max_depth:.4f}")
+print(f"Backend used    : {result.backend_used}")
+```
+
+---
+
+## 2. Direct Python import — file path
+
+Pass a file path string instead of bytes; the handler opens it automatically.
+
+```python
+from vizion3d.lifting import DepthEstimation, DepthEstimationCommand
+
+cmd = DepthEstimationCommand(image_input="scene.png")
+result = DepthEstimation().run(cmd)
+
+print(f"Depth range: {result.min_depth:.4f} → {result.max_depth:.4f}")
+```
+
+---
+
+## 3. Depth image (16-bit PNG)
+
+Request a 16-bit grayscale Open3D Image of the depth map for visualization or downstream processing.
+
+```python
+import numpy as np
+from PIL import Image as PILImage
+from vizion3d.lifting import DepthEstimation, DepthEstimationCommand
+
+cmd = DepthEstimationCommand(
+    image_input="scene.png",
+    return_depth_image=True,
+)
+result = DepthEstimation().run(cmd)
+
+# result.depth_image is an open3d.geometry.Image (uint16)
+depth_array = np.asarray(result.depth_image)   # shape (H, W), dtype uint16
+print(f"Depth image shape: {depth_array.shape}, dtype: {depth_array.dtype}")
+
+# Save as 16-bit PNG via PIL
+PILImage.fromarray(depth_array).save("depth.png")
+```
+
+---
+
+## 4. Point cloud
+
+Request a coloured 3D point cloud unprojected from the RGB-D image. Distances between points are in metres (`point_cloud_scale == 1.0`).
+
+```python
+import numpy as np
+import open3d as o3d
+from vizion3d.lifting import DepthEstimation, DepthEstimationCommand
+
+cmd = DepthEstimationCommand(
+    image_input="scene.png",
+    return_point_cloud=True,
+)
+result = DepthEstimation().run(cmd)
+
+pcd = result.point_cloud                          # open3d.geometry.PointCloud
+points = np.asarray(pcd.points)                   # shape (N, 3), float64, in metres
+colors = np.asarray(pcd.colors)                   # shape (N, 3), float64, range [0, 1]
+
+print(f"Points : {len(points)}")
+print(f"Scale  : {result.point_cloud_scale} metre per unit")
+
+# Measure real-world distance between two points
+dist_metres = np.linalg.norm(points[0] - points[1]) * result.point_cloud_scale
+print(f"Distance p0→p1: {dist_metres:.4f} m")
+
+# Save as PLY
+o3d.io.write_point_cloud("scene.ply", pcd)
+```
+
+---
+
+## 5. Surface mesh
+
+Request a triangulated mesh reconstructed from the point cloud via ball-pivoting. Includes vertex colours.
+
+```python
+import open3d as o3d
+from vizion3d.lifting import DepthEstimation, DepthEstimationCommand
+
+cmd = DepthEstimationCommand(
+    image_input="scene.png",
+    return_mesh=True,
+)
+result = DepthEstimation().run(cmd)
+
+mesh = result.mesh                                # open3d.geometry.TriangleMesh
+print(f"Vertices  : {len(mesh.vertices)}")
+print(f"Triangles : {len(mesh.triangles)}")
+
+# Save as PLY
+o3d.io.write_triangle_mesh("scene_mesh.ply", mesh)
+```
+
+---
+
+## 6. All outputs at once
+
+All three optional outputs can be requested in a single inference pass.
+
+```python
+import numpy as np
+import open3d as o3d
+from vizion3d.lifting import DepthEstimation, DepthEstimationCommand
+
+cmd = DepthEstimationCommand(
+    image_input="scene.png",
+    return_depth_image=True,
+    return_point_cloud=True,
+    return_mesh=True,
+)
+result = DepthEstimation().run(cmd)
+
+# Depth map
+print(f"Depth range : {result.min_depth:.4f} → {result.max_depth:.4f}")
+
+# 16-bit depth image
+depth_arr = np.asarray(result.depth_image)        # uint16 (H, W)
+
+# Point cloud
+pcd = result.point_cloud
+o3d.io.write_point_cloud("scene.ply", pcd)
+
+# Mesh
+o3d.io.write_triangle_mesh("scene_mesh.ply", result.mesh)
+```
+
+---
+
+## 7. Custom model backend
+
+Use any Hugging Face depth estimation model or a local `.pth` checkpoint.
+
+```python
+from vizion3d.lifting import DepthEstimation, DepthEstimationCommand
+
+# Hugging Face model
+cmd = DepthEstimationCommand(
+    image_input="scene.png",
+    model_backend="Intel/dpt-large",
+)
+result = DepthEstimation().run(cmd)
+print(f"Backend: {result.backend_used}")
+
+# Local checkpoint
+cmd = DepthEstimationCommand(
+    image_input="scene.png",
+    model_backend="/models/depth_anything_v2_vitl.pth",
+)
+result = DepthEstimation().run(cmd)
+print(f"Backend: {result.backend_used}")
+```
+
+---
+
+## 8. REST API
+
+Start the server:
+
+```bash
+uv run task serve-rest
+```
+
+Send a request with `multipart/form-data`:
+
+```bash
+curl -X POST "http://localhost:8000/lifting/depth-estimation" \
+  -F "image=@scene.png" \
+  -F "return_point_cloud=true" \
+  -F "return_mesh=true"
+```
+
+The response is a JSON-serialised `DepthEstimationResult`. Binary fields (`depth_image`, `point_cloud`, `mesh`) are base64-encoded in the JSON response.
+
+---
+
+## 9. gRPC API
+
+Start the server:
+
+```bash
+uv run task serve-grpc
+```
+
+Call from any gRPC client using the generated stubs:
+
+```python
+import grpc
+from vizion3d.proto import lifting_pb2, lifting_pb2_grpc
+
+channel = grpc.insecure_channel("localhost:50051")
+stub = lifting_pb2_grpc.LiftingServiceStub(channel)
+
+with open("scene.png", "rb") as f:
+    img_bytes = f.read()
+
+request = lifting_pb2.DepthEstimationRequest(
+    image_bytes=img_bytes,
+    return_point_cloud=True,
+    return_mesh=True,
+)
+
+response = stub.RunDepthEstimation(request)
+print(f"Min depth : {response.min_depth}")
+print(f"Max depth : {response.max_depth}")
+print(f"Backend   : {response.backend_used}")
+```
+
+---
+
+## Known limitations
+
+- **Relative depth only** — the default monocular backend produces relative (inverse) depth, not metric depth. Point cloud distances are internally consistent but not calibrated to real-world scale without a known reference distance.
+- **Fixed camera intrinsics** — point cloud unprojection uses `PrimeSenseDefault` (640×480) intrinsics regardless of input image resolution. For accurate metric geometry, supply real camera intrinsics.
+- **Ball-pivoting mesh quality** — the mesh reconstructor works best on dense, evenly sampled point clouds. Sparse or noisy clouds may produce gaps or missing faces.
+- **Python 3.12 required for Open3D** — `return_depth_image`, `return_point_cloud`, and `return_mesh` require Open3D, which currently only supports Python 3.12 in this project.

vizion3d-1.0.0/docs/index.md

@@ -0,0 +1,83 @@
+# vizion3d
+
+**vizion3d** is an open-source Python library for 3D computer vision that gives ML/CV researchers a single, unified interface for running inference across the full spectrum of 3D vision tasks — from depth estimation and point cloud generation to NeRF reconstruction and pose estimation.
+
+Every task is accessible through three consumption modes driven by one shared CQRS architecture:
+
+| Mode | When to use |
+|---|---|
+| **Direct Python import** | Notebooks, research scripts, local prototyping |
+| **REST API** | Web integrations, any-language clients |
+| **gRPC API** | High-throughput, low-latency microservice pipelines |
+
+---
+
+## Installation
+
+Requires **Python 3.12** (Open3D constraint).
+
+```bash
+uv python pin 3.12
+uv sync
+```
+
+---
+
+## Quick start — depth estimation
+
+Get a depth map, point cloud, and mesh from a single image in under 10 lines.
+
+```python
+import open3d as o3d
+from vizion3d.lifting import DepthEstimation, DepthEstimationCommand
+
+result = DepthEstimation().run(
+    DepthEstimationCommand(
+        image_input="scene.png",
+        return_point_cloud=True,
+        return_mesh=True,
+    )
+)
+
+print(f"Depth range : {result.min_depth:.4f} → {result.max_depth:.4f}")
+print(f"Points      : {len(result.point_cloud.points)}")
+print(f"Scale       : {result.point_cloud_scale} metre per unit")
+
+o3d.io.write_point_cloud("scene.ply", result.point_cloud)
+o3d.io.write_triangle_mesh("scene_mesh.ply", result.mesh)
+```
+
+---
+
+## Starting the servers
+
+```bash
+# REST API (FastAPI, default port 8000)
+uv run task serve-rest
+
+# gRPC API (default port 50051)
+uv run task serve-grpc
+```
+
+---
+
+## Architecture
+
+vizion3d uses a [CQRS](https://martinfowler.com/bliki/CQRS.html) pattern throughout:
+
+- **Commands** carry inference parameters and trigger side-effecting handlers.
+- **Queries** retrieve results or metadata without side effects.
+- All handlers are registered through a [`clean_ioc`](https://github.com/peter-daly/clean-ioc) container — no direct handler instantiation anywhere in the public API.
+
+Each task lives in its own module under `vizion3d/<category>/` and exposes exactly `commands.py`, `handlers.py`, and `models.py`. Adding a new task means adding one module and one container registration — nothing else changes.
+
+---
+
+## Tasks
+
+### Lifting (2D → 3D)
+
+| Task | Status | Docs |
+|---|---|---|
+| Monocular depth estimation | Stable | [Depth Estimation](features/depth_estimation.md) |
+