Issue #65: Add stereo render example, as yet untested.

Author: MattClarkson

.kiro/steering/product.md

@@ -0,0 +1,17 @@
+# Product Overview
+
+scikit-surgeryutils is a collection of small demo applications and utility functions for surgical/medical imaging research. It is part of the SciKit-Surgery ecosystem developed at the Wellcome EPSRC Centre for Interventional and Surgical Sciences (UCL).
+
+## Purpose
+
+- Provide common overlay applications that combine video feeds with VTK-rendered 3D models
+- Offer command-line tools for camera calibration, video lag measurement, model rendering, DICOM reslicing, and text overlays
+- Serve as integration glue between other SciKit-Surgery libraries (scikit-surgeryimage, scikit-surgeryvtk, scikit-surgerycalibration, scikit-surgeryarucotracker)
+
+## Target Users
+
+Researchers and developers working in computer-assisted interventions and surgical guidance systems.
+
+## License
+
+BSD-3-Clause. Copyright University College London.

.kiro/steering/structure.md

@@ -0,0 +1,42 @@
+# Project Structure
+
+```
+scikit-surgeryutils/
+├── sksurgeryutils/              # Main package
+│   ├── __init__.py
+│   ├── _version.py              # Auto-generated by versioneer
+│   ├── common_overlay_apps.py   # Base widget classes for VTK overlay on video
+│   ├── ui/                      # CLI entry points and demo applications
+│   │   ├── *_command_line.py    # argparse CLI wrappers
+│   │   ├── *_demo.py           # Demo/application logic
+│   │   └── *_app.py            # Full application classes
+│   └── utils/                   # Shared utility functions
+│       ├── image_utils.py
+│       ├── opencv_video_capture_utils.py
+│       ├── screen_utils.py
+│       └── string_utils.py
+├── tests/                       # pytest test suite
+│   ├── conftest.py              # Session-scoped QApplication fixture
+│   ├── data/                    # Test data (videos, DICOM, models)
+│   ├── ui/                      # Tests for UI/app modules
+│   ├── utils/                   # Tests for utility modules
+│   └── pylintrc                 # Pylint configuration
+├── docs/                        # Sphinx documentation source
+├── config/                      # Misc config files
+├── sk*.py                       # Standalone runnable demo scripts (project root)
+├── setup.py / setup.cfg         # Package build configuration
+├── tox.ini                      # Tox test environments
+├── requirements.txt             # Runtime dependencies
+├── requirements-dev.txt         # Dev/test dependencies
+└── requirements-docs.txt        # Docs build dependencies
+```
+
+## Conventions
+
+- Each command-line tool has a pair: `*_command_line.py` (CLI/argparse) and `*_demo.py` (logic).
+- Console entry points are registered in `setup.py` under `entry_points`.
+- Test files mirror the source structure (`tests/ui/`, `tests/utils/`).
+- The `# coding=utf-8` header is used in all source files.
+- Classes inherit from `QWidget` and use `QTimer` for frame-loop patterns.
+- Logging uses Python's standard `logging` module.
+- Type validation raises `TypeError`/`ValueError` explicitly rather than using assertions.

.kiro/steering/tech.md

@@ -0,0 +1,60 @@
+# Tech Stack
+
+## Language
+
+- Python (targets 3.9–3.13, CI runs on 3.13)
+
+## Key Dependencies
+
+| Library | Purpose |
+|---------|---------|
+| PySide6 (>=6.5.1.1) | Qt bindings for GUI widgets |
+| opencv-contrib-python-headless (>=4.10) | Computer vision, video capture |
+| numpy (>=2.0.0) | Array/matrix operations |
+| scikit-surgerycore | Core utilities (transforms, config) |
+| scikit-surgeryimage | Image acquisition, processing |
+| scikit-surgeryvtk | VTK overlay rendering |
+| scikit-surgeryarucotracker | ArUco/ChArUco marker tracking |
+| scikit-surgerycalibration | Camera calibration |
+
+## Build & Packaging
+
+- setuptools with `setup.py` / `setup.cfg`
+- Versioning via **versioneer** (PEP 440 style from git tags prefixed `v`)
+- No pyproject.toml yet — uses traditional setup.py
+
+## Dev Dependencies
+
+- pytest, pytest-qt — testing
+- coverage, coveralls — coverage reporting
+- pylint — linting (config in `tests/pylintrc`)
+- tox — test environment orchestration
+- pyfakefs, mock, parameterized — test helpers
+- sphinx — documentation
+
+## Common Commands
+
+All Python commands should be run using the tox-managed virtualenv at `.tox/test/bin/python`. Tox installs all requirements from the top-level requirements files.
+
+```bash
+# Run tests with coverage (creates/uses .tox/test venv)
+tox -e test
+
+# Run linter
+tox -e lint
+
+# Build docs
+tox -e docs
+
+# Run a Python command using the tox venv directly
+.tox/test/bin/python -m pytest -v -s
+
+# Run a script with the tox venv
+.tox/test/bin/python sksurgerystereorenderer.py --help
+```
+
+## CI/CD
+
+- GitHub Actions (`.github/workflows/ci.yml`)
+- Coverage reported to Coveralls
+- Docs hosted on Read the Docs

sksurgerystereorenderer.py

@@ -0,0 +1,8 @@
+#!/usr/bin/python
+#  -*- coding: utf-8 -*-
+import sys
+
+from sksurgeryutils.ui.sksurgerystereorenderer_command_line import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

sksurgeryutils/ui/sksurgerystereorenderer_command_line.py

@@ -0,0 +1,100 @@
+# coding=utf-8
+
+"""
+Command line entry point for sksurgerystereorenderer application.
+"""
+
+import argparse
+from sksurgeryutils import __version__
+from sksurgeryutils.ui.sksurgerystereorenderer_demo import run_demo
+
+
+def main(args=None):
+    """
+    Entry point for sksurgerystereorenderer application.
+    """
+    parser = argparse.ArgumentParser(
+        description='sksurgerystereorenderer - Stereo augmented reality '
+                    'renderer with interactive model manipulation.')
+
+    parser.add_argument("-li", "--left_intrinsics",
+                        required=True,
+                        type=str,
+                        help="File path to left camera 3x3 intrinsics matrix.")
+
+    parser.add_argument("-ri", "--right_intrinsics",
+                        required=True,
+                        type=str,
+                        help="File path to right camera 3x3 intrinsics matrix.")
+
+    parser.add_argument("-l2r", "--left_to_right",
+                        required=True,
+                        type=str,
+                        help="File path to 4x4 stereo left-to-right "
+                             "extrinsic matrix.")
+
+    parser.add_argument("-m", "--models",
+                        required=True,
+                        type=str,
+                        help="Path to models .json configuration file.")
+
+    parser.add_argument("-r", "--clipping_range",
+                        required=True,
+                        type=str,
+                        help="Near,far clipping range (e.g. '1,1000').")
+
+    parser.add_argument("-lv", "--left_video",
+                        required=True,
+                        type=str,
+                        help="Left video source: integer device index, "
+                             "video file path, or static image (.png/.jpg).")
+
+    parser.add_argument("-rv", "--right_video",
+                        required=True,
+                        type=str,
+                        help="Right video source: integer device index, "
+                             "video file path, or static image (.png/.jpg).")
+
+    parser.add_argument("-m2w", "--model_to_world",
+                        required=False,
+                        default=None,
+                        type=str,
+                        help="File path to a 4x4 model-to-world matrix "
+                             "applied to all models on startup.")
+
+    parser.add_argument("-c2w", "--camera_to_world",
+                        required=False,
+                        default=None,
+                        type=str,
+                        help="File path to a 4x4 camera-to-world matrix "
+                             "for the initial camera pose.")
+
+    parser.add_argument("-s", "--stereo_mode",
+                        required=False,
+                        default="stacked",
+                        type=str,
+                        choices=["stacked", "interlaced"],
+                        help="Stereo display mode: 'stacked' (left=top, "
+                             "right=bottom) or 'interlaced'. "
+                             "Default: stacked.")
+
+    version_string = __version__
+    friendly_version_string = version_string if version_string else 'unknown'
+    parser.add_argument(
+        "-v", "--version",
+        action='version',
+        version='sksurgerystereorenderer version '
+        + friendly_version_string)
+
+    args = parser.parse_args(args)
+
+    run_demo(args.left_intrinsics,
+             args.right_intrinsics,
+             args.left_to_right,
+             args.models,
+             args.clipping_range,
+             args.left_video,
+             args.right_video,
+             args.model_to_world,
+             args.camera_to_world,
+             args.stereo_mode)