diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..e2fd8fa
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,29 @@
+name: CI
+
+on:
+ pull_request:
+ push:
+ branches:
+ - main
+
+permissions:
+ contents: read
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ python-version: ["3.10", "3.12", "3.14"]
+ steps:
+ - uses: actions/checkout@v6
+ - uses: actions/setup-python@v6
+ with:
+ python-version: ${{ matrix.python-version }}
+ cache: pip
+ - run: python -m pip install -r requirements.txt pytest
+ - run: python -m compileall -q .
+ - run: pytest -q
+ - run: node --input-type=module --check < web/visualization.js
+ - run: node --check web/js/threeVisualizer.mjs
diff --git a/.github/workflows/publish_action.yml b/.github/workflows/publish_action.yml
index 828f300..023b689 100644
--- a/.github/workflows/publish_action.yml
+++ b/.github/workflows/publish_action.yml
@@ -11,11 +11,12 @@ jobs:
publish-node:
name: Publish Custom Node to registry
runs-on: ubuntu-latest
+ permissions:
+ contents: read
steps:
- name: Check out code
- uses: actions/checkout@v4
+ uses: actions/checkout@v6
- name: Publish Custom Node
- uses: Comfy-Org/publish-node-action@main
+ uses: Comfy-Org/publish-node-action@1.0.1
with:
- ## Add your own personal access token to your Github Repository secrets and reference it here.
- personal_access_token: ${{ secrets.REGISTRY_ACCESS_TOKEN }}
\ No newline at end of file
+ personal_access_token: ${{ secrets.REGISTRY_ACCESS_TOKEN }}
diff --git a/README.md b/README.md
index 9ec00c9..e55fecd 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,60 @@
-# [DualView](https://dualview.ai)
+# ComfyUI Depth Visualization
-## Tools
+An interactive, in-node 3D preview for any ComfyUI reference image and depth
+map. The current implementation is compatible with the modern ComfyUI
+frontend, works offline, supports batches, and cleans up its WebGL resources
+when a node is removed.
-| Tool | Description |
-|------|-------------|
-| [DualView](https://dualview.ai) | Free side-by-side comparison tool for VLM outputs, images, videos, and AI prompts |
+
-## Works with any Depth Map and visualizes the applied version of it inside ComfyUI
-
+## Features
+
+- Interactive orbit, pan, and zoom controls
+- Adjustable positive or negative displacement
+- Batch frame selector with single-image broadcasting
+- PNG screenshots
+- Baked depth-mesh export as GLB, GLTF, or OBJ
+- Local, pinned Three.js assets with no runtime CDN dependency
+- Correct copy/paste, collapse, resize, and node-removal behavior
+- Stale-load cancellation and visible error reporting
+
+## Installation
+
+Install with ComfyUI Manager, or clone the repository manually:
+
+```bash
+cd ComfyUI/custom_nodes
+git clone https://github.com/gokayfem/ComfyUI-Depth-Visualization.git
+python -m pip install -r ComfyUI-Depth-Visualization/requirements.txt
+```
+
+Restart ComfyUI after installation.
+
+## Usage
+
+1. Add **Depth Viewer** from `visualization/3D`.
+2. Connect a reference `IMAGE` and a depth-map `IMAGE`.
+3. Queue the workflow.
+4. Drag to orbit, scroll to zoom, or right-drag to pan.
+
+When one input contains a single image and the other contains a batch, the
+single image is reused for every frame. Other unequal batch sizes produce a
+clear validation error instead of silently dropping images.
+
+Mesh export bakes the current depth slider value into the vertices. GLB is the
+recommended portable format; OBJ contains geometry only.
+
+## Development
+
+```bash
+python -m pip install pytest
+pytest -q
+```
+
+The browser assets are vendored from Three.js 0.185.1. Its MIT license is in
+`web/vendor/THREE-LICENSE.txt`.
## Acknowledgements
-[flowtyone](https://github.com/flowtyone/ComfyUI-Flowty-TripoSR)
+
+The original viewer was inspired by
+[ComfyUI-Flowty-TripoSR](https://github.com/flowtyone/ComfyUI-Flowty-TripoSR).
diff --git a/__init__.py b/__init__.py
index f918094..3a9de08 100644
--- a/__init__.py
+++ b/__init__.py
@@ -1,12 +1,71 @@
-import sys
-from os import path
+"""Depth-map preview node for ComfyUI."""
-sys.path.insert(0, path.dirname(__file__))
-from folder_paths import get_save_image_path, get_output_directory
-from PIL import Image
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import folder_paths
import numpy as np
+from PIL import Image
+
+
+def _as_pil(image: Any, *, grayscale: bool = False) -> Image.Image:
+ """Convert one ComfyUI IMAGE tensor to a web-safe PIL image."""
+ array = image.detach().cpu().float().numpy()
+ array = np.nan_to_num(array, nan=0.0, posinf=1.0, neginf=0.0)
+ array = np.clip(array, 0.0, 1.0)
+
+ if array.ndim == 2:
+ mode = "L"
+ elif array.ndim == 3 and array.shape[-1] == 1:
+ array = array[..., 0]
+ mode = "L"
+ elif array.ndim == 3 and array.shape[-1] >= 3:
+ array = array[..., :3]
+ mode = "RGB"
+ else:
+ raise ValueError(f"Expected an HxW, HxWx1, or HxWx3+ image, got {array.shape}.")
+
+ converted = Image.fromarray((array * 255.0).round().astype(np.uint8), mode=mode)
+ return converted.convert("L" if grayscale else "RGB")
+
+
+def _batch_item(batch: Any, index: int, target_count: int, name: str) -> Any:
+ count = len(batch)
+ if count == target_count:
+ return batch[index]
+ if count == 1:
+ return batch[0]
+ raise ValueError(
+ f"{name} has {count} images but the other input has {target_count}. "
+ "Batch sizes must match, or one input must contain a single image."
+ )
+
+
+def _save_image(
+ image: Image.Image,
+ *,
+ prefix: str,
+ suffix: str,
+ batch_number: int,
+) -> dict[str, str]:
+ output_dir = folder_paths.get_temp_directory()
+ full_folder, filename, counter, subfolder, _ = folder_paths.get_save_image_path(
+ prefix,
+ output_dir,
+ image.width,
+ image.height,
+ )
+ filename = filename.replace("%batch_num%", str(batch_number))
+ image_name = f"{filename}_{counter:05}_{suffix}.png"
+ image.save(os.path.join(full_folder, image_name), compress_level=1)
+ return {"filename": image_name, "subfolder": subfolder, "type": "temp"}
+
class DepthViewer:
+ """Preview an image displaced by a matching depth map in an interactive 3D view."""
+
@classmethod
def INPUT_TYPES(cls):
return {
@@ -16,60 +75,52 @@ class DepthViewer:
}
}
-
- def __init__(self):
- self.saved_reference = []
- self.saved_depth = []
- self.full_output_folder, self.filename, self.counter, self.subfolder, self.filename_prefix = get_save_image_path("imagesave", get_output_directory())
-
RETURN_TYPES = ()
OUTPUT_NODE = True
FUNCTION = "process_images"
- CATEGORY = "DepthViewer"
+ CATEGORY = "visualization/3D"
+ DESCRIPTION = (
+ "Interactively previews an image as a depth-displaced mesh. "
+ "Supports image batches and browser-side PNG, OBJ, GLTF, and GLB export."
+ )
+
def process_images(self, reference_image, depth_map):
- self.saved_reference.clear()
- self.saved_depth.clear()
- image = reference_image[0].detach().cpu().numpy()
- depth = depth_map[0].detach().cpu().numpy()
+ reference_count = len(reference_image)
+ depth_count = len(depth_map)
+ batch_count = max(reference_count, depth_count)
- image = Image.fromarray(np.clip(255. * image, 0, 255).astype(np.uint8)).convert('RGB')
- depth = Image.fromarray(np.clip(255. * depth, 0, 255).astype(np.uint8))
+ references: list[dict[str, str]] = []
+ depths: list[dict[str, str]] = []
+ for index in range(batch_count):
+ reference = _as_pil(
+ _batch_item(reference_image, index, batch_count, "reference_image")
+ )
+ depth = _as_pil(
+ _batch_item(depth_map, index, batch_count, "depth_map"),
+ grayscale=True,
+ )
+ references.append(
+ _save_image(
+ reference,
+ prefix="depth_viewer",
+ suffix="reference",
+ batch_number=index,
+ )
+ )
+ depths.append(
+ _save_image(
+ depth,
+ prefix="depth_viewer",
+ suffix="depth",
+ batch_number=index,
+ )
+ )
- return self.display([image], [depth])
+ return {"ui": {"reference_image": references, "depth_map": depths}}
- def display(self, reference_image, depth_map):
- for (batch_number, (single_image, single_depth)) in enumerate(zip(reference_image, depth_map)):
- filename_with_batch_num = self.filename.replace("%batch_num%", str(batch_number))
-
- image_file = f"{filename_with_batch_num}_{self.counter:05}_reference.png"
- single_image.save(path.join(self.full_output_folder, image_file))
-
- depth_file = f"{filename_with_batch_num}_{self.counter:05}_depth.png"
- single_depth.save(path.join(self.full_output_folder, depth_file))
-
- self.saved_reference.append({
- "filename": image_file,
- "subfolder": self.subfolder,
- "type": "output"
- })
-
- self.saved_depth.append({
- "filename": depth_file,
- "subfolder": self.subfolder,
- "type": "output"
- })
- self.counter += 1
-
- return {"ui": {"reference_image": self.saved_reference, "depth_map": self.saved_depth}}
-
-NODE_CLASS_MAPPINGS = {
- "DepthViewer": DepthViewer,
-}
-
-NODE_DISPLAY_NAME_MAPPINGS = {
- "DepthViewer": "DepthViewer",
-}
+NODE_CLASS_MAPPINGS = {"DepthViewer": DepthViewer}
+NODE_DISPLAY_NAME_MAPPINGS = {"DepthViewer": "Depth Viewer"}
WEB_DIRECTORY = "./web"
-__all__ = ['NODE_CLASS_MAPPINGS', 'NODE_DISPLAY_NAME_MAPPINGS', 'WEB_DIRECTORY']
+__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS", "WEB_DIRECTORY"]
diff --git a/conftest.py b/conftest.py
new file mode 100644
index 0000000..f7e8fc7
--- /dev/null
+++ b/conftest.py
@@ -0,0 +1,12 @@
+"""Minimal ComfyUI module shim used while pytest collects this package."""
+
+from __future__ import annotations
+
+import sys
+import types
+
+
+try:
+ import folder_paths # noqa: F401
+except ModuleNotFoundError:
+ sys.modules["folder_paths"] = types.ModuleType("folder_paths")
diff --git a/pyproject.toml b/pyproject.toml
index d6fe363..99c0858 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,12 +1,17 @@
[project]
name = "comfyui-depth-visualization"
-description = "Works with any Depth Map and visualizes the applied version it inside ComfyUI"
-version = "1.0.2"
-license = "LICENSE"
-dependencies = ["Pillow>=10.1.0"]
+description = "Interactive, batch-aware depth-map visualization and mesh export for ComfyUI"
+version = "2.0.0"
+requires-python = ">=3.10"
+license = { file = "LICENSE.txt" }
+dependencies = [
+ "numpy>=1.25.0",
+ "Pillow>=10.1.0",
+]
[project.urls]
Repository = "https://github.com/gokayfem/ComfyUI-Depth-Visualization"
+Issues = "https://github.com/gokayfem/ComfyUI-Depth-Visualization/issues"
[tool.comfy]
PublisherId = "gokayfem"
diff --git a/requirements.txt b/requirements.txt
index 7182b41..e689584 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1 +1,2 @@
+numpy>=1.25.0
Pillow>=10.1.0
diff --git a/tests/test_frontend_assets.py b/tests/test_frontend_assets.py
new file mode 100644
index 0000000..408b782
--- /dev/null
+++ b/tests/test_frontend_assets.py
@@ -0,0 +1,35 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).parents[1]
+
+
+def test_only_extension_entrypoint_uses_js_suffix():
+ javascript_files = sorted(
+ path.relative_to(ROOT).as_posix() for path in (ROOT / "web").rglob("*.js")
+ )
+ assert javascript_files == ["web/visualization.js"]
+
+
+def test_frontend_has_no_runtime_cdn_dependency():
+ frontend_text = "\n".join(
+ path.read_text(encoding="utf-8")
+ for path in (ROOT / "web").rglob("*")
+ if path.suffix in {".html", ".js", ".mjs", ".css"}
+ and "vendor" not in path.parts
+ )
+ assert "https://" not in frontend_text
+ assert "http://" not in frontend_text
+ assert "@latest" not in frontend_text
+
+
+def test_vendored_three_modules_are_present():
+ vendor = ROOT / "web" / "vendor"
+ expected = {
+ "three.module.min.mjs",
+ "OrbitControls.mjs",
+ "GLTFExporter.mjs",
+ "OBJExporter.mjs",
+ "THREE-LICENSE.txt",
+ }
+ assert expected.issubset({path.name for path in vendor.iterdir()})
diff --git a/tests/test_nodes.py b/tests/test_nodes.py
new file mode 100644
index 0000000..6c5920d
--- /dev/null
+++ b/tests/test_nodes.py
@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import importlib.util
+import sys
+import types
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+
+class FakeTensor:
+ def __init__(self, array):
+ self.array = np.asarray(array, dtype=np.float32)
+
+ def detach(self):
+ return self
+
+ def cpu(self):
+ return self
+
+ def float(self):
+ return self
+
+ def numpy(self):
+ return self.array
+
+
+class FakeBatch:
+ def __init__(self, arrays):
+ self.items = [FakeTensor(array) for array in arrays]
+
+ def __len__(self):
+ return len(self.items)
+
+ def __getitem__(self, index):
+ return self.items[index]
+
+
+@pytest.fixture()
+def depth_module(tmp_path, monkeypatch):
+ folder_paths = types.ModuleType("folder_paths")
+ folder_paths.get_temp_directory = lambda: str(tmp_path)
+
+ def get_save_image_path(prefix, output_dir, width, height):
+ assert width > 0 and height > 0
+ return output_dir, f"{prefix}_%batch_num%", 1, "", prefix
+
+ folder_paths.get_save_image_path = get_save_image_path
+ monkeypatch.setitem(sys.modules, "folder_paths", folder_paths)
+
+ module_path = Path(__file__).parents[1] / "__init__.py"
+ spec = importlib.util.spec_from_file_location("depth_viewer_test_module", module_path)
+ module = importlib.util.module_from_spec(spec)
+ assert spec.loader
+ spec.loader.exec_module(module)
+ return module, tmp_path
+
+
+def test_processes_full_batch_and_broadcasts_single_depth(depth_module):
+ module, output_dir = depth_module
+ reference = FakeBatch(
+ [
+ np.zeros((8, 12, 3)),
+ np.ones((8, 12, 3)),
+ ]
+ )
+ depth = FakeBatch([np.full((8, 12, 1), 0.5)])
+
+ result = module.DepthViewer().process_images(reference, depth)["ui"]
+
+ assert len(result["reference_image"]) == 2
+ assert len(result["depth_map"]) == 2
+ for descriptor in result["reference_image"] + result["depth_map"]:
+ assert descriptor["type"] == "temp"
+ assert (output_dir / descriptor["filename"]).is_file()
+
+
+def test_rejects_incompatible_batch_sizes(depth_module):
+ module, _ = depth_module
+ reference = FakeBatch([np.zeros((4, 4, 3)) for _ in range(2)])
+ depth = FakeBatch([np.zeros((4, 4, 1)) for _ in range(3)])
+
+ with pytest.raises(ValueError, match="Batch sizes must match"):
+ module.DepthViewer().process_images(reference, depth)
+
+
+def test_sanitizes_non_finite_pixels(depth_module):
+ module, _ = depth_module
+ image = FakeTensor([[[np.nan, np.inf, -np.inf]]])
+
+ converted = np.asarray(module._as_pil(image))
+
+ assert converted.tolist() == [[[0, 255, 0]]]
diff --git a/web/html/threeVisualizer.html b/web/html/threeVisualizer.html
index 6527421..640aa02 100644
--- a/web/html/threeVisualizer.html
+++ b/web/html/threeVisualizer.html
@@ -1,33 +1,58 @@
-
+
-
-
-
-
-
-
+
+
+
+ Depth Viewer
+
+
+
+
+
+
+ Waiting for output…
+
-
-
-
-