immdebug 0.1.0__py3-none-any.whl

immdebug/__init__.py

@@ -0,0 +1,16 @@
+"""immdebug: send images to the immdebug viewer for visual debugging.
+
+Usage:
+    import numpy as np
+    from immdebug import immdebug
+
+    image = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
+    immdebug(image, "my image")
+
+The viewer can be launched with:
+    python -m immdebug.viewer
+"""
+
+from immdebug.client import immdebug
+
+__all__ = ["immdebug"]

immdebug/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the viewer with: python -m immdebug"""
+
+from immdebug.viewer import main
+
+main()

immdebug/client.py

@@ -0,0 +1,127 @@
+"""Pure Python client for immdebug: send images to the immdebug_viewer app.
+
+Usage:
+    import numpy as np
+    from immdebug import immdebug
+
+    image = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
+    immdebug(image, "my image")
+
+The immdebug_viewer must be running separately. It polls a temp directory
+for incoming image payloads.
+"""
+
+import os
+import struct
+import tempfile
+import time
+import random
+from pathlib import Path
+from typing import Tuple
+
+import numpy as np
+
+
+# OpenCV depth constants: cv::Mat::depth()
+_CV_DEPTH = {
+    np.dtype("uint8"): 0,
+    np.dtype("int8"): 1,
+    np.dtype("uint16"): 2,
+    np.dtype("int16"): 3,
+    np.dtype("int32"): 4,
+    np.dtype("float32"): 5,
+    np.dtype("float64"): 6,
+}
+
+# Random base ID, incremented per call (mirrors C++ static id)
+_next_id = random.randint(100_000_000_000, 1_000_000_000_000)
+
+
+def _immdebug_folder(while_writing: bool) -> Path:
+    base = Path(tempfile.gettempdir()) / "ImmDebug"
+    folder = base / "Writing" if while_writing else base
+    folder.mkdir(parents=True, exist_ok=True)
+    return folder
+
+
+def _make_unique_filename(while_writing: bool) -> Path:
+    global _next_id
+    _next_id += 1
+    return _immdebug_folder(while_writing) / f"{_next_id}.bindata"
+
+
+def _remove_old_images(max_age_seconds: float = 3600.0) -> None:
+    folder = _immdebug_folder(False)
+    now = time.time()
+    for entry in folder.rglob("*"):
+        if not entry.is_file():
+            continue
+        try:
+            if now - entry.stat().st_mtime > max_age_seconds:
+                entry.unlink()
+        except OSError:
+            pass
+
+
+def _write_string(buf: bytearray, s: str) -> None:
+    encoded = s.encode("utf-8")
+    buf += struct.pack("=Q", len(encoded))  # size_t (8 bytes on 64-bit)
+    buf += encoded
+
+
+def _write_mat(buf: bytearray, image: np.ndarray) -> None:
+    image = np.ascontiguousarray(image)
+    rows, cols = image.shape[0], image.shape[1]
+    channels = 1 if image.ndim == 2 else image.shape[2]
+
+    depth = _CV_DEPTH.get(image.dtype)
+    if depth is None:
+        raise ValueError(f"Unsupported dtype: {image.dtype}. Supported: {list(_CV_DEPTH.keys())}")
+
+    elem_type = depth + (channels - 1) * 8
+    elem_size = image.dtype.itemsize * channels
+
+    # Match C++ WriteValue<int>, WriteValue<size_t>, WriteValue<int>
+    # "=" = native byte order, no padding; "Q" = uint64 for size_t
+    buf += struct.pack("=iiQi", cols, rows, elem_size, elem_type)
+    buf += image.tobytes()
+
+
+def immdebug(
+    image: np.ndarray,
+    legend: str = "",
+    zoom_center: Tuple[float, float] = (0.0, 0.0),
+    zoom_ratio: float = -1.0,
+    zoom_key: str = "",
+    color_adjustments_key: str = "",
+    is_color_order_bgr: bool = True,
+) -> None:
+    """Send an image to the immdebug_viewer application.
+
+    Args:
+        image: numpy array (HxW for grayscale, HxWxC for multi-channel)
+        legend: display name in the viewer
+        zoom_center: initial zoom center (x, y)
+        zoom_ratio: initial zoom ratio (-1 for auto-fit)
+        zoom_key: link zoom across images sharing this key
+        color_adjustments_key: link color adjustments across images sharing this key
+        is_color_order_bgr: True if channels are BGR (OpenCV default), False for RGB
+    """
+    _remove_old_images()
+
+    buf = bytearray()
+    _write_string(buf, legend)
+    buf += struct.pack("=dd", zoom_center[0], zoom_center[1])
+    buf += struct.pack("=d", zoom_ratio)
+    _write_string(buf, zoom_key)
+    _write_string(buf, color_adjustments_key)
+    buf += struct.pack("=?", is_color_order_bgr)
+    _write_mat(buf, image)
+
+    writing_path = _make_unique_filename(while_writing=True)
+    done_path = _make_unique_filename(while_writing=False)
+
+    with open(writing_path, "wb") as f:
+        f.write(buf)
+
+    os.rename(str(writing_path), str(done_path))

immdebug/viewer.py

@@ -0,0 +1,269 @@
+"""Pure Python immdebug viewer using imgui_bundle.
+
+Usage:
+    python -m immdebug.viewer
+
+Polls the temp directory for images sent by immdebug (C++ or Python client)
+and displays them using immvision's inspector.
+"""
+
+import struct
+import tempfile
+import time
+import threading
+from pathlib import Path
+from typing import Optional, Tuple
+
+import numpy as np
+
+
+# OpenCV depth constants -> numpy dtype
+_CV_DEPTH_TO_DTYPE = {
+    0: np.dtype("uint8"),
+    1: np.dtype("int8"),
+    2: np.dtype("uint16"),
+    3: np.dtype("int16"),
+    4: np.dtype("int32"),
+    5: np.dtype("float32"),
+    6: np.dtype("float64"),
+}
+
+
+class _ImagePayload:
+    def __init__(self) -> None:
+        self.image: np.ndarray = np.zeros((0, 0), dtype=np.uint8)
+        self.legend: str = ""
+        self.zoom_center: Tuple[float, float] = (0.0, 0.0)
+        self.zoom_ratio: float = -1.0
+        self.zoom_key: str = ""
+        self.color_adjustments_key: str = ""
+        self.is_color_order_bgr: bool = True
+
+
+def _read_value(data: bytes, offset: int, fmt: str) -> Tuple:
+    size = struct.calcsize(fmt)
+    values = struct.unpack_from(fmt, data, offset)
+    return values, offset + size
+
+
+def _read_string(data: bytes, offset: int) -> Tuple[str, int]:
+    (length,), offset = _read_value(data, offset, "=Q")
+    s = data[offset : offset + length].decode("utf-8")
+    return s, offset + length
+
+
+def _read_mat(data: bytes, offset: int) -> Tuple[np.ndarray, int]:
+    (cols, rows, elem_size, elem_type), offset = _read_value(data, offset, "=iiQi")
+
+    depth = elem_type % 8
+    channels = (elem_type // 8) + 1
+    dtype = _CV_DEPTH_TO_DTYPE[depth]
+
+    data_size = cols * rows * elem_size
+    pixel_data = data[offset : offset + data_size]
+
+    if channels == 1:
+        image = np.frombuffer(pixel_data, dtype=dtype).reshape((rows, cols))
+    else:
+        image = np.frombuffer(pixel_data, dtype=dtype).reshape((rows, cols, channels))
+
+    return image.copy(), offset + data_size
+
+
+def _read_image_payload(data: bytes) -> _ImagePayload:
+    payload = _ImagePayload()
+    offset = 0
+    payload.legend, offset = _read_string(data, offset)
+    (cx, cy), offset = _read_value(data, offset, "=dd")
+    payload.zoom_center = (cx, cy)
+    (payload.zoom_ratio,), offset = _read_value(data, offset, "=d")
+    payload.zoom_key, offset = _read_string(data, offset)
+    payload.color_adjustments_key, offset = _read_string(data, offset)
+    (payload.is_color_order_bgr,), offset = _read_value(data, offset, "=?")
+    payload.image, offset = _read_mat(data, offset)
+    return payload
+
+
+def _immdebug_folder() -> Path:
+    return Path(tempfile.gettempdir()) / "ImmDebug"
+
+
+def _remove_old_images(max_age_seconds: float = 3600.0) -> None:
+    folder = _immdebug_folder()
+    if not folder.exists():
+        return
+    now = time.time()
+    for entry in folder.rglob("*"):
+        if not entry.is_file():
+            continue
+        try:
+            if now - entry.stat().st_mtime > max_age_seconds:
+                entry.unlink()
+        except OSError:
+            pass
+
+
+def _read_one_payload() -> Optional[_ImagePayload]:
+    from imgui_bundle import hello_imgui
+
+    folder = _immdebug_folder()
+    if not folder.exists():
+        return None
+
+    bindata_files = sorted(
+        [f for f in folder.iterdir() if f.is_file() and f.suffix == ".bindata"],
+        key=lambda f: f.stat().st_mtime,
+    )
+    if not bindata_files:
+        return None
+
+    oldest = bindata_files[0]
+    try:
+        data = oldest.read_bytes()
+        payload = _read_image_payload(data)
+        oldest.unlink()
+        return payload
+    except Exception as e:
+        hello_imgui.log(hello_imgui.LogLevel.error, f"Error reading {oldest.name}: {e}")
+        try:
+            oldest.unlink()
+        except OSError:
+            pass
+        return None
+
+
+# --- Single instance app (port of single_instance_app.cpp) ---
+
+class _SingleInstanceApp:
+    def __init__(self, lock_name: str) -> None:
+        self._lock_name = lock_name
+        self._exit = threading.Event()
+        self._ping_received = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+
+    def _ping_filename(self) -> Path:
+        return Path(tempfile.gettempdir()) / f"{self._lock_name}.ping"
+
+    def run_single_instance(self) -> bool:
+        ping_file = self._ping_filename()
+
+        # Check for stale ping file
+        if ping_file.is_file():
+            print("Ooops : stale ping file!")
+            ping_file.unlink(missing_ok=True)
+            time.sleep(0.1)
+
+        # Create ping file and wait for master to remove it
+        ping_file.write_text("Lock")
+        time.sleep(0.12)
+
+        if not ping_file.is_file():
+            print("Other instance already launched!")
+            return False
+
+        # We are the first instance
+        print("First instance!")
+        ping_file.unlink(missing_ok=True)
+
+        self._thread = threading.Thread(target=self._ping_loop, daemon=True)
+        self._thread.start()
+        return True
+
+    def was_pinged(self) -> bool:
+        if self._ping_received.is_set():
+            self._ping_received.clear()
+            return True
+        return False
+
+    def _ping_loop(self) -> None:
+        while not self._exit.is_set():
+            ping_file = self._ping_filename()
+            if ping_file.is_file():
+                print("Answering ping!")
+                self._ping_received.set()
+                ping_file.unlink(missing_ok=True)
+            self._exit.wait(timeout=0.06)
+
+    def stop(self) -> None:
+        self._exit.set()
+        if self._thread:
+            self._thread.join()
+
+
+# --- Main viewer ---
+
+def _focus_window() -> None:
+    import glfw
+    from imgui_bundle import glfw_utils
+    glfw.focus_window(glfw_utils.glfw_window_hello_imgui())
+
+
+def main() -> None:
+    import glfw
+    from imgui_bundle import imgui, hello_imgui, immvision
+
+    single_instance = _SingleInstanceApp("immdebug_viewer")
+
+    if not single_instance.run_single_instance():
+        print("Exit...")
+        return
+
+    frame_count = 0
+
+    def add_incoming_images() -> bool:
+        _remove_old_images()
+        found_new = False
+        while True:
+            payload = _read_one_payload()
+            if payload is None:
+                break
+            hello_imgui.log(hello_imgui.LogLevel.info, f"Received image: {payload.legend}")
+            if payload.is_color_order_bgr:
+                immvision.use_bgr_color_order()
+            else:
+                immvision.use_rgb_color_order()
+            immvision.inspector_add_image(
+                payload.image,
+                payload.legend,
+                payload.zoom_key,
+                payload.color_adjustments_key,
+                (payload.zoom_center[0], payload.zoom_center[1]),
+                payload.zoom_ratio,
+            )
+            found_new = True
+        if found_new:
+            _focus_window()
+        return found_new
+
+    def gui() -> None:
+        nonlocal frame_count
+        immvision.inspector_show()
+
+        # Poll for new images every 10 frames
+        if frame_count % 10 == 0:
+            add_incoming_images()
+        frame_count += 1
+
+        if single_instance.was_pinged():
+            _focus_window()
+            hello_imgui.log(hello_imgui.LogLevel.warning, "Pong")
+
+    params = hello_imgui.RunnerParams()
+    params.app_window_params.window_geometry.full_screen_mode = (
+        hello_imgui.FullScreenMode.full_monitor_work_area
+    )
+    params.app_window_params.restore_previous_geometry = True
+    params.app_window_params.window_title = "ImmVision - immdebug viewer"
+    params.callbacks.show_gui = gui
+    params.ini_folder_type = hello_imgui.IniFolderType.app_user_config_folder
+    params.ini_filename = "immdebug_viewer.ini"
+
+    glfw.init()
+    try:
+        hello_imgui.run(params)
+    finally:
+        single_instance.stop()
+
+
+if __name__ == "__main__":
+    main()

immdebug-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: immdebug
+Version: 0.1.0
+Summary: Send images to the immdebug viewer for visual debugging — from any Python process
+Project-URL: Homepage, https://github.com/pthom/immvision
+Project-URL: Repository, https://github.com/pthom/immvision
+Project-URL: Issues, https://github.com/pthom/immvision/issues
+Author-email: Pascal Thomet <pthomet@gmail.com>
+License-Expression: MIT
+Keywords: computer-vision,debugging,image,imgui,immvision
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Requires-Dist: glfw
+Requires-Dist: imgui-bundle
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# immdebug
+
+Visual image debugger for Python — inspect images from any running process with zoom, pan, pixel values, and colormaps.
+
+Part of the [immvision](https://github.com/pthom/immvision) / [Dear ImGui Bundle](https://github.com/pthom/imgui_bundle) ecosystem.
+
+## Install
+
+```bash
+pip install immdebug
+```
+
+This installs both the client (for sending images) and the viewer (for displaying them).
+
+## Quick start
+
+**1. Start the viewer** (in a terminal):
+
+```bash
+immdebug-viewer
+# or: python -m immdebug
+```
+
+**2. Send images** (from your code, a script, a notebook, ...):
+
+```python
+import numpy as np
+from immdebug import immdebug
+
+image = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
+immdebug(image, "random noise")
+```
+
+The image appears in the viewer immediately.
+
+## How it works
+
+`immdebug()` serializes the image to a temp directory (`<tempdir>/ImmDebug/`). The viewer polls this directory and displays incoming images using [immvision](https://github.com/pthom/immvision)'s inspector.
+
+This is the same protocol used by the C++ `ImmDebug()` function, so the Python client works with both the Python and C++ viewers.
+
+## Use with OpenCV
+
+```python
+import cv2
+from immdebug import immdebug
+
+image = cv2.imread("photo.jpg")
+immdebug(image, "original")
+
+gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+immdebug(gray, "grayscale")
+
+edges = cv2.Canny(gray, 100, 200)
+immdebug(edges, "edges")
+```
+
+Images default to BGR channel order (OpenCV convention). For RGB images (e.g. from PIL or matplotlib), pass `is_color_order_bgr=False`.
+
+## API
+
+```python
+def immdebug(
+    image: np.ndarray,
+    legend: str = "",
+    zoom_center: tuple[float, float] = (0.0, 0.0),
+    zoom_ratio: float = -1.0,
+    zoom_key: str = "",
+    color_adjustments_key: str = "",
+    is_color_order_bgr: bool = True,
+) -> None:
+```
+
+| Parameter | Description |
+|---|---|
+| `image` | numpy array — HxW (grayscale) or HxWxC (color). Supports uint8, int8, uint16, int16, int32, float32, float64. |
+| `legend` | Display name in the viewer |
+| `zoom_center` | Initial zoom center (x, y) |
+| `zoom_ratio` | Initial zoom ratio (-1 for auto-fit) |
+| `zoom_key` | Link zoom/pan across images sharing this key |
+| `color_adjustments_key` | Link color adjustments across images sharing this key |
+| `is_color_order_bgr` | True for BGR (OpenCV), False for RGB (PIL, matplotlib) |
+
+## Features
+
+- **Non-blocking**: `immdebug()` just writes a file and returns immediately
+- **Post-mortem**: images persist in the temp directory for 1 hour — start the viewer after your script finishes
+- **Single instance**: launching a second viewer brings the existing one to the front
+- **Cross-language**: works with both the Python and C++ immdebug viewers
+
+## License
+
+MIT

immdebug-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+immdebug/__init__.py,sha256=iJ2Fsmhiso4JorTO2OgguclqKmKe6BH8O3zqwtC3_ws,367
+immdebug/__main__.py,sha256=dh6StRaztiCptl96YPoA7GS1PmUAR7gX_acjHI7qIsI,98
+immdebug/client.py,sha256=PALTTzek1ByRQdh0YuvXIyTa4ax7r4YnCzBBifFg9ZM,3823
+immdebug/viewer.py,sha256=vEV-aL2tU1HP2sO53V1v2AAHCMlydLQgAVWCfAbUClg,7864
+immdebug-0.1.0.dist-info/METADATA,sha256=LHg-fx9dFIjagoalRAwpQ2y2ciPnTxYlW13gwzMt0Kg,3639
+immdebug-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+immdebug-0.1.0.dist-info/entry_points.txt,sha256=X4TrKG9xwtnvcOluIOrHsI8saPdR0QlLXNQDqJBgtB0,57
+immdebug-0.1.0.dist-info/RECORD,,

immdebug-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

immdebug-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+immdebug-viewer = immdebug.viewer:main