ptzsim 0.2.0__py3-none-any.whl

ptzsim/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2026 Stephan Strittmatter
+# SPDX-License-Identifier: MIT
+
+"""PTZ camera simulator speaking ONVIF, VISCA (serial, raw TCP/UDP, Sony VISCA over IP) and NDI."""
+
+__version__ = "0.2.0"

ptzsim/__main__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Stephan Strittmatter
+# SPDX-License-Identifier: MIT
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

ptzsim/cli.py

@@ -0,0 +1,221 @@
+# SPDX-FileCopyrightText: 2026 Stephan Strittmatter
+# SPDX-License-Identifier: MIT
+
+"""Command line entry point: ``ptzsim serve`` and ``ptzsim send``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import socket
+import sys
+from typing import List, Optional
+
+from .display import dashboard, log_printer
+from .transports import (SONY_HEADER, SONY_VISCA_COMMAND, SONY_VISCA_INQUIRY,
+                         Simulator, serve_pty, serve_tcp, serve_udp)
+from .onvif import OnvifCamera, serve_discovery, serve_onvif
+from .visca import ViscaCamera, hexdump, parse_hex
+
+DEFAULT_PORTS = {"sony": 52381, "tcp": 5678, "udp": 1259, "onvif": 8080}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ptzsim", description="PTZ camera simulator (ONVIF, VISCA and NDI)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve = sub.add_parser("serve", help="run a simulated camera")
+    serve.add_argument("--host", default="0.0.0.0", help="address to listen on (default 0.0.0.0)")
+    serve.add_argument("--sony", type=int, metavar="PORT", nargs="?", const=DEFAULT_PORTS["sony"],
+                       help="Sony VISCA over IP on UDP (default port 52381)")
+    serve.add_argument("--tcp", type=int, metavar="PORT", nargs="?", const=DEFAULT_PORTS["tcp"],
+                       help="raw VISCA over TCP, e.g. PTZOptics (default port 5678)")
+    serve.add_argument("--udp", type=int, metavar="PORT", nargs="?", const=DEFAULT_PORTS["udp"],
+                       help="raw VISCA over UDP (default port 1259)")
+    serve.add_argument("--pty", nargs="?", const="", metavar="LINK",
+                       help="emulate a serial port via a pseudo terminal; optional symlink path")
+    serve.add_argument("--onvif", type=int, metavar="PORT", nargs="?", const=DEFAULT_PORTS["onvif"],
+                       help="ONVIF (SOAP over HTTP) with WS-Discovery (default port 8080)")
+    serve.add_argument("--onvif-user", metavar="USER", help="require authentication (see --onvif-auth) with this user")
+    serve.add_argument("--onvif-password", metavar="PASSWORD", default="", help="password for --onvif-user")
+    serve.add_argument("--ndi", action="store_true",
+                       help="publish an NDI source with PTZ control (needs: pip install ndi-python numpy)")
+    serve.add_argument("--ndi-fps", type=int, default=25, metavar="FPS", help="NDI frame rate (default 25)")
+    serve.add_argument("--name", default="PTZ-Simulator", help="camera name (ONVIF scope/profile, NDI source name)")
+    serve.add_argument("--no-discovery", action="store_true", help="do not answer WS-Discovery probes")
+    serve.add_argument("--advertise-host", metavar="IP",
+                       help="address announced in WS-Discovery (default: detected per request)")
+    serve.add_argument("--onvif-auth", choices=("both", "digest", "wsse"), default="both",
+                       help="ONVIF authentication: HTTP digest and/or WS-UsernameToken (default both)")
+    serve.add_argument("--onvif-no-absolute", action="store_true",
+                       help="simulate a camera without AbsoluteMove (presets only via SetPreset/GotoPreset)")
+    serve.add_argument("--rtsp-uri", metavar="URI", help="stream URI returned by ONVIF GetStreamUri")
+    serve.add_argument("--address", type=int, default=1, choices=range(1, 8),
+                       help="VISCA camera address (default 1)")
+    serve.add_argument("--instant", action="store_true",
+                       help="jump to target positions instead of moving at motor speed")
+    serve.add_argument("--no-tui", action="store_true", help="print one line per command instead of a dashboard")
+    serve.add_argument("--view-only", action="store_true",
+                       help="show the dashboard without keyboard control")
+    serve.add_argument("-v", "--verbose", action="store_true", help="log every packet sent and received")
+
+    send = sub.add_parser("send", help="send VISCA hex packets to a camera and print the replies")
+    send.add_argument("packets", nargs="+", help='VISCA packets as hex, e.g. "81 01 06 04 FF"')
+    send.add_argument("--host", default="127.0.0.1")
+    send.add_argument("--port", type=int)
+    send.add_argument("--proto", choices=("sony", "tcp", "udp"), default="sony")
+    send.add_argument("--timeout", type=float, default=2.0, help="seconds to wait for replies")
+    return parser
+
+
+async def _serve(args: argparse.Namespace) -> None:
+    camera = ViscaCamera(address=args.address, instant=args.instant)
+    sim = Simulator(camera)
+    endpoints: List[str] = []
+    discovery = None
+
+    if all(v is None for v in (args.sony, args.tcp, args.udp, args.pty, args.onvif)) and not args.ndi:
+        args.sony = DEFAULT_PORTS["sony"]
+    if args.sony is not None:
+        await serve_udp(sim, args.host, args.sony, sony=True)
+        endpoints.append(f"Sony VISCA/IP udp://{args.host}:{args.sony}")
+    if args.tcp is not None:
+        await serve_tcp(sim, args.host, args.tcp)
+        endpoints.append(f"VISCA tcp://{args.host}:{args.tcp}")
+    if args.udp is not None:
+        await serve_udp(sim, args.host, args.udp, sony=False)
+        endpoints.append(f"VISCA udp://{args.host}:{args.udp}")
+    if args.pty is not None:
+        endpoints.append(f"VISCA serial {serve_pty(sim, args.pty or None)}")
+    if args.onvif is not None:
+        onvif = OnvifCamera(camera, name=args.name, username=args.onvif_user,
+                            password=args.onvif_password, rtsp_uri=args.rtsp_uri,
+                            absolute=not args.onvif_no_absolute, auth=args.onvif_auth)
+        await serve_onvif(onvif, args.host, args.onvif)
+        endpoints.append(f"ONVIF http://{args.host}:{args.onvif}/onvif/device_service")
+        if not args.no_discovery:
+            discovery = await serve_discovery(onvif, args.onvif, advertise_host=args.advertise_host)
+            endpoints.append("WS-Discovery udp/3702")
+    if args.ndi:
+        from .ndi import start_ndi
+
+        source = start_ndi(camera, args.name, args.ndi_fps)
+        endpoints.append(f"NDI {source.source_name}")
+
+    title = " | ".join(endpoints)
+    logging.getLogger("ptzsim").info("listening: %s", title)
+    if args.no_tui:
+        view = log_printer(camera)
+    elif args.view_only or not _interactive_terminal():
+        view = dashboard(camera, title)
+    else:
+        from .tui import interactive
+
+        view = interactive(camera, title)
+    tasks = [asyncio.ensure_future(sim.run()), asyncio.ensure_future(view)]
+    try:
+        done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+        for task in pending:
+            task.cancel()
+        for task in done:
+            task.result()  # re-raise errors from the simulator or the view
+    finally:
+        if discovery is not None:
+            discovery.get_protocol().bye()  # WS-Discovery Bye when leaving the network
+
+
+def _interactive_terminal() -> bool:
+    """The keyboard UI needs curses (not on Windows) and a terminal on stdin and stdout."""
+    try:
+        import curses  # noqa: F401
+    except ImportError:
+        return False
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def send_packets(packets: List[bytes], host: str, port: int, proto: str, timeout: float) -> List[bytes]:
+    """Send packets to a camera and return all replies received (helper for manual tests)."""
+    replies: List[bytes] = []
+    if proto == "tcp":
+        with socket.create_connection((host, port), timeout=timeout) as sock:
+            for packet in packets:
+                sock.sendall(packet)
+                replies += _collect_stream(sock, timeout)
+        return replies
+
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+        sock.settimeout(timeout)
+        for seq, packet in enumerate(packets, start=1):
+            if proto == "sony":
+                kind = SONY_VISCA_INQUIRY if len(packet) > 1 and packet[1] == 0x09 else SONY_VISCA_COMMAND
+                packet = SONY_HEADER.pack(kind, len(packet), seq) + packet
+            sock.sendto(packet, (host, port))
+            replies += _collect_datagrams(sock, proto == "sony")
+    return replies
+
+
+def _collect_stream(sock: socket.socket, timeout: float) -> List[bytes]:
+    buffer = bytearray()
+    replies: List[bytes] = []
+    while True:
+        try:
+            data = sock.recv(1024)
+        except socket.timeout:
+            break
+        if not data:
+            break
+        buffer.extend(data)
+        while 0xFF in buffer:
+            end = buffer.index(0xFF)
+            replies.append(bytes(buffer[: end + 1]))
+            del buffer[: end + 1]
+        if replies and _is_final(replies[-1]):
+            break
+    return replies
+
+
+def _collect_datagrams(sock: socket.socket, sony: bool) -> List[bytes]:
+    replies: List[bytes] = []
+    while True:
+        try:
+            data, _ = sock.recvfrom(1024)
+        except socket.timeout:
+            break
+        if sony:
+            data = data[SONY_HEADER.size:]
+        replies.append(data)
+        if _is_final(data):
+            break
+    return replies
+
+
+def _is_final(reply: bytes) -> bool:
+    """Completion, inquiry answer or error ends a request; an ACK (y0 4z) does not."""
+    return len(reply) >= 2 and reply[1] & 0xF0 in (0x50, 0x60) or reply[:1] == b"\x88"
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "send":
+        port = args.port or DEFAULT_PORTS[args.proto]
+        packets = [parse_hex(p) for p in args.packets]
+        for reply in send_packets(packets, args.host, port, args.proto, args.timeout):
+            print(hexdump(reply))
+        return 0
+
+    level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(level=level, format="%(asctime)s %(levelname)s %(message)s",
+                        stream=sys.stderr if args.no_tui else open("ptzsim.log", "a"))
+    try:
+        asyncio.run(_serve(args))
+    except KeyboardInterrupt:
+        pass
+    except (RuntimeError, OSError) as err:
+        print(f"ptzsim: {err}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ptzsim/display.py

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: 2026 Stephan Strittmatter
+# SPDX-License-Identifier: MIT
+
+"""Terminal dashboard showing the simulated camera."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import List
+
+from . import state as st
+from .visca import ViscaCamera
+
+CLEAR = "\x1b[H\x1b[2J"
+HIDE_CURSOR, SHOW_CURSOR = "\x1b[?25l", "\x1b[?25h"
+GREEN, RED, DIM, BOLD, RESET = "\x1b[32m", "\x1b[31m", "\x1b[2m", "\x1b[1m", "\x1b[0m"
+
+
+def bar(value: float, low: float, high: float, width: int = 30, center: bool = False) -> str:
+    pos = round((value - low) / (high - low) * (width - 1))
+    cells = ["─"] * width
+    if center:
+        zero = round((0 - low) / (high - low) * (width - 1))
+        cells[zero] = "┼"
+    cells[max(0, min(width - 1, pos))] = "●"
+    return "[" + "".join(cells) + "]"
+
+
+def render(camera: ViscaCamera, title: str, color: bool = True, log_lines: int = 10) -> str:
+    s = camera.state
+    g, r, d, b, x = (GREEN, RED, DIM, BOLD, RESET) if color else ("",) * 5
+    pan, tilt, zoom, focus = s.position()
+
+    def motion(velocity: float, target) -> str:
+        if target is not None:
+            return f"{g}→ {round(target[0])}{x}"
+        if velocity:
+            return f"{g}{'▶' if velocity > 0 else '◀'} {abs(velocity):.0f}/s{x}"
+        return f"{d}idle{x}"
+
+    lines: List[str] = [
+        f"{b}PTZ camera simulator{x}  {d}{title}{x}",
+        f"Power: {g + 'ON' if s.power else r + 'STANDBY'}{x}   "
+        f"Address: {camera.address}   Commands: {camera.command_count}",
+        "",
+        f"Pan   {pan:6d}  {s.pan_degrees:+7.1f}°  "
+        f"{bar(s.pan, st.PAN_MIN, st.PAN_MAX, center=True)}  {motion(s.pan_velocity, s.pan_target)}",
+        f"Tilt  {tilt:6d}  {s.tilt_degrees:+7.1f}°  "
+        f"{bar(s.tilt, st.TILT_MIN, st.TILT_MAX, center=True)}  {motion(s.tilt_velocity, s.tilt_target)}",
+        f"Zoom  {zoom:#06x}  {s.zoom_ratio:7.1f}x  "
+        f"{bar(s.zoom, st.ZOOM_MIN, st.ZOOM_MAX)}  {motion(s.zoom_velocity, s.zoom_target)}",
+        f"Focus {focus:#06x}  {'AF' if s.autofocus else 'MF':>8}  "
+        f"{bar(s.focus, st.FOCUS_MIN, st.FOCUS_MAX)}  {motion(s.focus_velocity, s.focus_target)}",
+        f"White balance  {s.white_balance:<12}  R {s.red_gain:#04x}  B {s.blue_gain:#04x}",
+        "",
+    ]
+    if s.presets:
+        lines.append(f"{b}Presets{x}")
+        for number, p in sorted(s.presets.items()):
+            marker = "*" if number == s.last_preset else " "
+            lines.append(f" {marker}{number + 1:3d}: pan {p.pan:6d}  tilt {p.tilt:6d}  "
+                         f"zoom {p.zoom:#06x}  focus {p.focus:#06x}"
+                         + (f"  {p.name}" if p.name else ""))
+    else:
+        lines.append(f"{d}No presets stored{x}")
+    lines += ["", f"{b}Last commands{x}"]
+    entries = list(camera.log)[-log_lines:]
+    if not entries:
+        lines.append(f"{d}(waiting for commands){x}")
+    for entry in entries:
+        c = "" if entry.ok else r
+        lines.append(f" {d}{entry.source:<44}{x} {c}{entry.description}{x}")
+    lines += ["", f"{d}Ctrl+C to quit{x}"]
+    return "\n".join(lines)
+
+
+async def dashboard(camera: ViscaCamera, title: str, interval: float = 0.1) -> None:
+    out = sys.stdout
+    out.write(HIDE_CURSOR)
+    try:
+        while True:
+            out.write(CLEAR + render(camera, title) + "\n")
+            out.flush()
+            await asyncio.sleep(interval)
+    finally:
+        out.write(SHOW_CURSOR)
+        out.flush()
+
+
+async def log_printer(camera: ViscaCamera, interval: float = 0.1) -> None:
+    """Plain line output for non-interactive use (``--no-tui``)."""
+    seen = 0
+    while True:
+        total = camera.command_count
+        new = list(camera.log)[-(total - seen):] if total > seen else []
+        seen = total
+        for entry in new:
+            pan, tilt, zoom, focus = camera.state.position()
+            print(f"{entry.source:<44} {entry.description:<36} "
+                  f"pan={pan} tilt={tilt} zoom={zoom:#06x}", flush=True)
+        await asyncio.sleep(interval)

ptzsim/ndi.py

@@ -0,0 +1,285 @@
+# SPDX-FileCopyrightText: 2026 Stephan Strittmatter
+# SPDX-License-Identifier: MIT
+
+"""NDI PTZ camera: an NDI source with PTZ support and a rendered test picture.
+
+NDI receivers send PTZ commands as XML metadata (``<ntk_ptz_pan_tilt .../>`` and
+friends) back to the sender. :class:`NdiPtzController` turns those into camera
+moves; it is plain Python. :class:`NdiSource` needs the NDI runtime via the
+``ndi-python`` package (``pip install ndi-python numpy``).
+
+Value ranges follow the NDI SDK (Processing.NDI.Recv.ex.h):
+  pan  -1 (left) .. +1 (right)      pan_speed  -1 (moving right) .. +1 (moving left)
+  tilt -1 (bottom) .. +1 (top)      tilt_speed -1 (down) .. +1 (up)
+  zoom  0 (zoomed in) .. 1 (out)    zoom_speed -1 (outwards) .. +1 (inwards)
+  focus 0 (infinity) .. 1 (close)   presets 0 .. 99, recall speed 0 .. 1
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import socket
+import threading
+import xml.etree.ElementTree as ET
+from typing import Callable, Optional
+
+from . import state as st
+from .onvif import tilt_from_onvif
+from .visca import ViscaCamera
+
+log = logging.getLogger("ptzsim")
+
+# Connection metadata a sender sends so receivers report PTZ support.
+CAPABILITIES = ('<ndi_capabilities ntk_ptz="true" ntk_pan_tilt="true" ntk_zoom="true" '
+                'ntk_focus="true" ntk_autofocus="true" ntk_white_balance="true" '
+                'ntk_preset_speed="true"/>')
+PRESET_RANGE = range(0, 100)  # NDI SDK: "The preset number is in the range 0 to 99"
+
+
+class NdiPtzController:
+    """Applies NDI PTZ metadata messages to the simulated camera."""
+
+    def __init__(self, camera: ViscaCamera):
+        self.camera = camera
+
+    @property
+    def state(self) -> st.CameraState:
+        return self.camera.state
+
+    def handle(self, xml: str) -> bool:
+        """Handle one metadata frame. Returns False if it was not understood."""
+        try:
+            elem = ET.fromstring(xml)
+        except ET.ParseError:
+            self.camera.record("NDI", f"invalid metadata {xml[:40]!r}", ok=False)
+            return False
+        handler = getattr(self, "_" + elem.tag, None)
+        if handler is None or not elem.tag.startswith("ntk_ptz"):
+            self.camera.record("NDI", f"unsupported metadata <{elem.tag}>", ok=False)
+            return False
+        try:
+            description = handler(elem.attrib)
+        except (KeyError, ValueError) as err:
+            self.camera.record("NDI", f"<{elem.tag}> bad attribute: {err}", ok=False)
+            return False
+        if self.camera.instant:
+            self.state.finish_moves()
+        self.camera.record("NDI", description)
+        return True
+
+    @staticmethod
+    def _num(attrs, name: str, low: float, high: float) -> float:
+        return st.clamp(float(attrs[name]), low, high)
+
+    # ------------------------------------------------------------ pan/tilt
+    def _ntk_ptz_pan_tilt(self, a) -> str:
+        pan, tilt = self._num(a, "pan", -1, 1), self._num(a, "tilt", -1, 1)
+        self.state.move_pan_tilt_to(pan * st.PAN_MAX, tilt_from_onvif(tilt),
+                                    st.PAN_SPEED_MAX, st.TILT_SPEED_MAX)
+        return f"pan/tilt to {pan:+.2f} {tilt:+.2f}"
+
+    def _ntk_ptz_pan_tilt_speed(self, a) -> str:
+        pan, tilt = self._num(a, "pan_speed", -1, 1), self._num(a, "tilt_speed", -1, 1)
+        s = self.state
+        s.pan_target = s.tilt_target = None
+        # NDI: positive pan speed moves left, i.e. towards negative pan.
+        s.pan_velocity = -pan * st.PAN_SPEED_MAX * st.PAN_TILT_UNITS_PER_SPEED_STEP
+        s.tilt_velocity = tilt * st.TILT_SPEED_MAX * st.PAN_TILT_UNITS_PER_SPEED_STEP
+        return "pan/tilt stop" if pan == tilt == 0 else f"pan/tilt speed {pan:+.2f} {tilt:+.2f}"
+
+    # ---------------------------------------------------------------- zoom
+    def _ntk_ptz_zoom(self, a) -> str:
+        zoom = self._num(a, "zoom", 0, 1)
+        self.state.zoom_to(st.ZOOM_MIN + (1 - zoom) * (st.ZOOM_MAX - st.ZOOM_MIN))
+        return f"zoom to {zoom:.2f}"
+
+    def _ntk_ptz_zoom_speed(self, a) -> str:
+        speed = self._num(a, "zoom_speed", -1, 1)
+        self.state.zoom_target = None
+        self.state.zoom_velocity = speed * 8 * st.ZOOM_UNITS_PER_SPEED_STEP
+        return "zoom stop" if speed == 0 else f"zoom speed {speed:+.2f}"
+
+    # --------------------------------------------------------------- focus
+    def _ntk_ptz_focus(self, a) -> str:
+        if a.get("mode") == "auto":
+            self.state.autofocus = True
+            return "auto focus"
+        distance = self._num(a, "distance", 0, 1)
+        self.state.autofocus = False
+        self.state.focus_to(st.FOCUS_MIN + distance * (st.FOCUS_MAX - st.FOCUS_MIN))
+        return f"focus to {distance:.2f}"
+
+    def _ntk_ptz_focus_speed(self, a) -> str:
+        speed = self._num(a, "distance", -1, 1)
+        self.state.autofocus = False
+        self.state.focus_target = None
+        self.state.focus_velocity = speed * 8 * st.FOCUS_UNITS_PER_SPEED_STEP
+        return "focus stop" if speed == 0 else f"focus speed {speed:+.2f}"
+
+    # ------------------------------------------------------------- presets
+    def _preset(self, a) -> int:
+        number = int(a["index"])
+        if number not in PRESET_RANGE:
+            raise ValueError(f"preset {number} out of the NDI range 0..99")
+        if number >= st.PRESET_COUNT:
+            raise ValueError(f"preset {number}: the camera has {st.PRESET_COUNT} presets")
+        return number
+
+    def _ntk_ptz_store_preset(self, a) -> str:
+        number = self._preset(a)
+        self.state.save_preset(number)
+        return f"store preset {number}"
+
+    def _ntk_ptz_recall_preset(self, a) -> str:
+        number = self._preset(a)
+        speed = self._num(a, "speed", 0, 1) if "speed" in a else 1.0
+        if not self.state.recall_preset(number, speed):
+            raise ValueError(f"preset {number} not set")
+        return f"recall preset {number} (speed {speed:.2f})"
+
+    # ------------------------------------------- accepted but not simulated
+    def _ignored(self, name: str, a) -> str:
+        detail = " ".join(f"{k}={v}" for k, v in a.items())
+        return f"{name} {detail} (not simulated)".replace("  ", " ")
+
+    def _ntk_ptz_white_balance(self, a) -> str:
+        mode = a.get("mode")
+        if mode in ("auto", "indoor", "outdoor"):
+            self.state.set_white_balance(mode)
+            return f"white balance {mode}"
+        if mode == "one_shot":
+            self.state.one_push_white_balance()
+            return "white balance one shot"
+        if mode == "manual":
+            red, blue = self._num(a, "red", 0, 1), self._num(a, "blue", 0, 1)
+            self.state.set_white_balance("manual")
+            self.state.set_gains(round(red * 256), round(blue * 256))  # NDI 0.5 is neutral (0x80)
+            return f"white balance manual red {red:.2f} blue {blue:.2f}"
+        return self._ignored("white balance", a)
+
+    def _ntk_ptz_exposure(self, a) -> str:
+        return self._ignored("exposure", a)
+
+    def _ntk_ptz_iris(self, a) -> str:
+        return self._ignored("iris", a)
+
+    def _ntk_ptz_flip(self, a) -> str:
+        return self._ignored("flip", a)
+
+
+# ---------------------------------------------------------------- picture
+class SceneRenderer:
+    """Draws what the camera "sees": a panorama grid that follows pan/tilt/zoom."""
+
+    BASE_FOV = 60.0  # horizontal field of view at 1x, degrees
+
+    def __init__(self, width: int = 640, height: int = 360):
+        import numpy as np
+
+        self.np = np
+        self.width, self.height = width, height
+        self.u = (np.arange(width, dtype=np.float32) / width - 0.5)[None, :]
+        self.v = (np.arange(height, dtype=np.float32) / height - 0.5)[:, None]
+
+    def render(self, s: st.CameraState):
+        np = self.np
+        fov = self.BASE_FOV / s.zoom_ratio
+        az = s.pan_degrees + self.u * fov
+        el = s.tilt_degrees - self.v * fov * self.height / self.width
+        checker = ((np.floor(az / 5) + np.floor(el / 5)) % 2).astype(np.float32)
+        sky = el > 0
+        frame = np.empty((self.height, self.width, 4), dtype=np.uint8)
+        # BGRX: sky blue-ish, ground green-ish, checker pattern every 5 degrees.
+        frame[..., 0] = np.where(sky, 150 + 60 * checker, 40 + 30 * checker)
+        frame[..., 1] = np.where(sky, 90 + 40 * checker, 110 + 50 * checker)
+        frame[..., 2] = np.where(sky, 40 + 20 * checker, 50 + 30 * checker)
+        frame[..., 3] = 255
+        line = fov / self.width * 1.5
+        # Fine 1-degree grid once zoomed in far enough to see it.
+        if fov / self.width < 1 / 16:
+            fine = (np.abs(((az + 0.5) % 1) - 0.5) < line / 2) | (np.abs(((el + 0.5) % 1) - 0.5) < line / 2)
+            frame[np.broadcast_to(fine, frame.shape[:2]), :3] //= 2
+        # Landmarks: red posts every 45 degrees of pan, white horizon.
+        post = np.abs(((az + 22.5) % 45) - 22.5) < line * 2
+        frame[np.broadcast_to(post, frame.shape[:2])] = (40, 40, 220, 255)
+        frame[np.broadcast_to(np.abs(el) < line, frame.shape[:2])] = (255, 255, 255, 255)
+        # Centre crosshair.
+        cx, cy = self.width // 2, self.height // 2
+        frame[cy, cx - 12:cx + 13] = (0, 255, 255, 255)
+        frame[cy - 12:cy + 13, cx] = (0, 255, 255, 255)
+        return frame
+
+
+# ------------------------------------------------------------- NDI source
+class NdiSource:
+    """Publishes the camera as an NDI source and executes received PTZ commands."""
+
+    def __init__(self, camera: ViscaCamera, name: str, fps: int = 25,
+                 width: int = 640, height: int = 360):
+        try:
+            import NDIlib  # noqa: F401  (ndi-python)
+        except ImportError as err:
+            raise RuntimeError("NDI needs the ndi-python package: pip install ndi-python numpy") from err
+        self.camera = camera
+        self.name = name
+        self.fps = fps
+        self.renderer = SceneRenderer(width, height)
+        self.controller = NdiPtzController(camera)
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self.source_name: Optional[str] = None
+
+    def start(self, dispatch: Callable[[Callable[[], None]], None]) -> None:
+        """Start the sender thread. PTZ commands are handed to ``dispatch`` so
+        they run on the simulator's event loop."""
+        import NDIlib as ndi
+
+        if not ndi.initialize():
+            raise RuntimeError("NDI runtime could not be initialised (CPU not supported?)")
+        settings = ndi.SendCreate(self.name, clock_video=True, clock_audio=False)
+        sender = ndi.send_create(settings)
+        if sender is None:
+            raise RuntimeError("could not create NDI sender")
+        caps = ndi.MetadataFrame()
+        caps.data = CAPABILITIES
+        ndi.send_add_connection_metadata(sender, caps)
+        try:
+            self.source_name = ndi.send_get_source_name(sender).ndi_name
+        except TypeError:  # some ndi-python builds cannot convert the return value
+            self.source_name = f"{socket.gethostname().split('.')[0].upper()} ({self.name})"
+        self._thread = threading.Thread(target=self._run, args=(ndi, sender, dispatch),
+                                        name="ndi-sender", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2)
+
+    def _run(self, ndi, sender, dispatch) -> None:
+        frame = ndi.VideoFrameV2()
+        frame.FourCC = ndi.FOURCC_VIDEO_TYPE_BGRX
+        frame.frame_rate_N, frame.frame_rate_D = self.fps, 1
+        try:
+            while not self._stop.is_set():
+                frame.data = self.renderer.render(self.camera.state)
+                ndi.send_send_video_v2(sender, frame)  # blocks to the frame rate
+                while True:
+                    metadata = ndi.MetadataFrame()
+                    ndi.send_capture(sender, metadata, 0)
+                    if not metadata.data:
+                        break
+                    xml = metadata.data
+                    ndi.send_free_metadata(sender, metadata)
+                    log.debug("NDI metadata %s", xml)
+                    dispatch(lambda xml=xml: self.controller.handle(xml))
+        finally:
+            ndi.send_destroy(sender)
+
+
+def start_ndi(camera: ViscaCamera, name: str, fps: int = 25) -> NdiSource:
+    loop = asyncio.get_running_loop()
+    source = NdiSource(camera, name, fps)
+    source.start(loop.call_soon_threadsafe)
+    return source