Merge pull request #55 from OlafenwaMoses/moses/vizion3d-playground

auto cache of reconstruction bundle

Author: OlafenwaMoses

.github/workflows/apisec-scan.yml

@@ -158,12 +158,16 @@ The task resolves the reconstruction runtime asset bundle from:
 
 1. the explicit `model_bundle` command field;
 2. `VIZION3D_RECONSTRUCTION_MODEL_BUNDLE`;
-3. the repository root;
-4. `~/.cache/vizion3d/models`.
+3. `~/.cache/vizion3d/models`;
+4. the repository root;
+5. the default `essentials-v1` GitHub release asset URL.
 
-The bundle is extracted into the cache directory before reconstruction. It
-contains the runtime assets needed for foreground isolation, mesh generation,
-and optional accelerated execution.
+If no local bundle exists, the default release asset is downloaded and cached
+before extraction. The bundle contains the runtime assets needed for foreground
+isolation, mesh generation, and optional accelerated execution.
+
+Direct download:
+[scene-components-3d-models.zip](https://github.com/OlafenwaMoses/vizion3D/releases/download/essentials-v1/scene-components-3d-models.zip)
 
 ## Python Usage
 

docs/assets/images/coconut-water.jpeg

@@ -177,8 +177,11 @@ The task applies these processing stages to the input image:
 
 The reconstruction runtime asset bundle is resolved the same way as
 `Object3DReconstruction`: explicit `model_bundle`,
-`VIZION3D_RECONSTRUCTION_MODEL_BUNDLE`, repository root, then
-`~/.cache/vizion3d/models`.
+`VIZION3D_RECONSTRUCTION_MODEL_BUNDLE`, `~/.cache/vizion3d/models`,
+repository root, then the default `essentials-v1` GitHub release asset URL.
+
+Direct download:
+[scene-components-3d-models.zip](https://github.com/OlafenwaMoses/vizion3D/releases/download/essentials-v1/scene-components-3d-models.zip)
 
 ## Python Usage
 

docs/assets/images/living-dining-room.jpg

@@ -26,7 +26,7 @@
         SceneComponents3DReconstructionCommand,
         SceneComponents3DReconstructionConfig,
     )
-    from vizion3d.reconstruction.defaults import extract_model_bundle
+    from vizion3d.reconstruction.defaults import extract_model_bundle, resolve_model_bundle
     from vizion3d.reconstruction.handlers import (
         Object3DReconstructionHandler,
         SceneComponents3DReconstructionHandler,
@@ -69,6 +69,28 @@ def _result(point_count=12):
     )
 
 
+def test_reconstruction_model_bundle_auto_downloads_default_when_missing(tmp_path, monkeypatch):
+    monkeypatch.delenv("VIZION3D_RECONSTRUCTION_MODEL_BUNDLE", raising=False)
+    monkeypatch.setenv("VIZION3D_MODEL_CACHE", str(tmp_path / "cache"))
+    monkeypatch.setattr(
+        "vizion3d.reconstruction.defaults.Path.is_file",
+        lambda path: False,
+    )
+    seen = {}
+
+    def download(url, destination):
+        seen["url"] = url
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(b"zip")
+
+    monkeypatch.setattr("vizion3d.reconstruction.defaults._download", download)
+
+    bundle = resolve_model_bundle()
+
+    assert seen["url"].endswith("/scene-components-3d-models.zip")
+    assert bundle == tmp_path / "cache" / "scene-components-3d-models.zip"
+
+
 def test_extract_model_bundle_validates_and_caches_tiny_zip(tmp_path, monkeypatch):
     bundle = tmp_path / "models.zip"
     with zipfile.ZipFile(bundle, "w") as archive:

docs/reconstruction/object_3d_reconstruction.md

@@ -12,6 +12,10 @@
 from pathlib import Path
 
 MODEL_BUNDLE_FILENAME = "scene-components-3d-models.zip"
+DEFAULT_MODEL_BUNDLE_URL = (
+    "https://github.com/OlafenwaMoses/vizion3D/releases/download/"
+    f"essentials-v1/{MODEL_BUNDLE_FILENAME}"
+)
 _BUNDLE_LOCK = threading.Lock()
 
 
@@ -22,15 +26,17 @@ def model_cache_dir() -> Path:
     return Path.home() / ".cache" / "vizion3d" / "models"
 
 
-def default_model_bundle() -> Path:
+def default_model_bundle() -> str | Path:
     configured = os.environ.get("VIZION3D_RECONSTRUCTION_MODEL_BUNDLE")
     if configured:
         return Path(configured).expanduser()
     cached = model_cache_dir() / MODEL_BUNDLE_FILENAME
     if cached.is_file():
         return cached
     checkout = Path(__file__).resolve().parents[2] / MODEL_BUNDLE_FILENAME
-    return checkout
+    if checkout.is_file():
+        return checkout
+    return DEFAULT_MODEL_BUNDLE_URL
 
 
 def _download(url: str, destination: Path) -> None: