world-engine-client 0.3.0__tar.gz → 0.4.0__tar.gz

{world_engine_client-0.3.0 → world_engine_client-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: world-engine-client
-Version: 0.3.0
+Version: 0.4.0
 Summary: Remote Gym-style Python client for a World Engine simulation server: connect(token) -> reset/step over HTTP.
 Project-URL: Homepage, https://github.com/Grounded-Intelligence-Initiative/world-engine-client-python
 Project-URL: Repository, https://github.com/Grounded-Intelligence-Initiative/world-engine-client-python
@@ -22,6 +22,10 @@ Provides-Extra: gym
 Requires-Dist: gymnasium>=1.0; extra == 'gym'
 Provides-Extra: img
 Requires-Dist: pillow>=10; extra == 'img'
+Provides-Extra: render
+Requires-Dist: pillow>=10; extra == 'render'
+Requires-Dist: playwright>=1.40; extra == 'render'
+Requires-Dist: websockets>=12; extra == 'render'
 Description-Content-Type: text/markdown
 
 # world-engine-client
@@ -84,11 +88,32 @@ cookies and editor write credentials are not Python control credentials.
 
 Protocol 3 is the default. Direct connections remain reset-required and state-only
 unless requested otherwise. `proto=2` preserves state-only compatibility and
-rejects image/resume requests. Image-enabled operation requires a real GPU renderer
-on the server. `images=True` captures all configured cameras; `cameras=['wrist']`
-selects a subset. RGB arrays appear in `obs['rgb']`; `render()` returns the latest
-camera without stepping. `as_gymnasium()` supplies an optional Gymnasium Env.
-Observations identify the instance, episode, step, and simulation time in `info`.
+rejects image/resume requests. `images=True` captures all configured cameras;
+`cameras=['wrist']` selects a subset. RGB arrays appear in `obs['rgb']`; `render()`
+returns the latest camera without stepping. `as_gymnasium()` supplies an optional
+Gymnasium Env.
+
+### Camera images
+
+Camera images are drawn on your computer, never on the server: the server only
+simulates physics and sends the poses with each observation, and a headless Chrome
+here runs the same scene the browser viewer shows. Nothing is throttled when no
+browser tab is open, and the images never travel over the network. This needs the
+`render` extra:
+
+```bash
+pip install 'world-engine-client[render]'
+python -m playwright install chromium     # skip if Google Chrome is installed
+```
+
+Scene assets are fetched once per session and cached by content hash in a
+temporary directory that `close()` deletes; pass
+`render_options={"cache_dir": "..."}` to keep them across sessions. Chrome must
+get hardware WebGL (check `chrome://gpu`). Without it the renderer refuses to
+start, because software rendering manages only a few frames per second;
+`render_options={"allow_software": True}` accepts that, and the
+`WE_RENDER_CHROME_ARGS` environment variable overrides Chrome's flags.
+`env.last_timings` splits each step into server, transport and render time.
 
 Heartbeats run every 30 seconds with a 90-second controller lease. Expiry freezes
 the simulation until explicit takeover. A lost action response is never retried:
@@ -166,7 +191,7 @@ R = rot6d_to_matrix(demo["action_dict/abs_rot_6d"][t])
 ## Development
 
 ```bash
-pip install -e '.[img,gym]' pytest && python -m pytest
+pip install -e '.[img,gym,render]' pytest && python -m pytest
 ```
 
 `tests/` covers the client alone against a stub server: binary decoding, the

{world_engine_client-0.3.0 → world_engine_client-0.4.0}/README.md

@@ -58,11 +58,32 @@ cookies and editor write credentials are not Python control credentials.
 
 Protocol 3 is the default. Direct connections remain reset-required and state-only
 unless requested otherwise. `proto=2` preserves state-only compatibility and
-rejects image/resume requests. Image-enabled operation requires a real GPU renderer
-on the server. `images=True` captures all configured cameras; `cameras=['wrist']`
-selects a subset. RGB arrays appear in `obs['rgb']`; `render()` returns the latest
-camera without stepping. `as_gymnasium()` supplies an optional Gymnasium Env.
-Observations identify the instance, episode, step, and simulation time in `info`.
+rejects image/resume requests. `images=True` captures all configured cameras;
+`cameras=['wrist']` selects a subset. RGB arrays appear in `obs['rgb']`; `render()`
+returns the latest camera without stepping. `as_gymnasium()` supplies an optional
+Gymnasium Env.
+
+### Camera images
+
+Camera images are drawn on your computer, never on the server: the server only
+simulates physics and sends the poses with each observation, and a headless Chrome
+here runs the same scene the browser viewer shows. Nothing is throttled when no
+browser tab is open, and the images never travel over the network. This needs the
+`render` extra:
+
+```bash
+pip install 'world-engine-client[render]'
+python -m playwright install chromium     # skip if Google Chrome is installed
+```
+
+Scene assets are fetched once per session and cached by content hash in a
+temporary directory that `close()` deletes; pass
+`render_options={"cache_dir": "..."}` to keep them across sessions. Chrome must
+get hardware WebGL (check `chrome://gpu`). Without it the renderer refuses to
+start, because software rendering manages only a few frames per second;
+`render_options={"allow_software": True}` accepts that, and the
+`WE_RENDER_CHROME_ARGS` environment variable overrides Chrome's flags.
+`env.last_timings` splits each step into server, transport and render time.
 
 Heartbeats run every 30 seconds with a 90-second controller lease. Expiry freezes
 the simulation until explicit takeover. A lost action response is never retried:
@@ -140,7 +161,7 @@ R = rot6d_to_matrix(demo["action_dict/abs_rot_6d"][t])
 ## Development
 
 ```bash
-pip install -e '.[img,gym]' pytest && python -m pytest
+pip install -e '.[img,gym,render]' pytest && python -m pytest
 ```
 
 `tests/` covers the client alone against a stub server: binary decoding, the

{world_engine_client-0.3.0 → world_engine_client-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "world-engine-client"
-version = "0.3.0"
+version = "0.4.0"
 description = "Remote Gym-style Python client for a World Engine simulation server: connect(token) -> reset/step over HTTP."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -28,6 +28,9 @@ dependencies = [
 [project.optional-dependencies]
 img = ["Pillow>=10"]
 gym = ["gymnasium>=1.0"]
+# Camera images, rendered on this machine; also run
+# `python -m playwright install chromium` unless Chrome is installed.
+render = ["Pillow>=10", "playwright>=1.40", "websockets>=12"]
 
 [dependency-groups]
 dev = ["pytest>=8", "ruff", "Pillow>=10", "gymnasium>=1.0"]

{world_engine_client-0.3.0 → world_engine_client-0.4.0}/src/world_engine_client/__init__.py

@@ -30,6 +30,7 @@ from .errors import (
     TokenError,
     WorldEngineClientError,
 )
+from .render import RendererError
 from .rotations import (
     axisangle_to_matrix,
     matrix_to_axisangle,
@@ -49,9 +50,10 @@ __all__ = [
     "BadConfigError",
     "RecoveryRequiredError",
     "RecordingPendingError",
+    "RendererError",
     "matrix_to_rot6d",
     "rot6d_to_matrix",
     "axisangle_to_matrix",
     "matrix_to_axisangle",
 ]
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{world_engine_client-0.3.0 → world_engine_client-0.4.0}/src/world_engine_client/env.py

@@ -3,7 +3,8 @@
 Synchronous by design — an inference loop is synchronous. Transport is plain
 HTTP POST (persistent stdlib http.client): one round-trip per step, which the lockstep
 semantics require anyway. Obs arrays come back as JSON lists and are converted
-to numpy here; protocol 3 carries synchronized JPEG camera observations.
+to numpy here. Camera images are rendered on this machine (see render.py): the
+server sends the poses they are drawn from with every observation.
 
 Proto 2 (server ≥ the editor-teleop release): the default control mode is
 ``osc_pose_delta`` — a 7-dim action ``[dpos(3), drot_axisangle(3), gripper]``
@@ -26,7 +27,8 @@ import urllib.parse
 import numpy as np
 
 from .errors import ProtocolError, RecoveryRequiredError, WorldEngineClientError, raise_for
-from .wire import CONTENT_TYPE, MAX_RESPONSE, decode
+
+MAX_RESPONSE = 64 * 1024 * 1024
 
 _PROTO = 3
 
@@ -45,6 +47,8 @@ def connect(
     expected_instance_id: str | None = None,
     proto: int = _PROTO,
     access_provider=None,
+    render: str = "auto",
+    render_options: dict | None = None,
 ) -> RemoteEnv:
     """Bind to the server as THE controller and return a ready RemoteEnv.
 
@@ -52,9 +56,20 @@ def connect(
     shown in the editor Inspector's Python API card during a Simulate session).
     ``takeover=True`` revokes a controller that died without releasing.
     ``control_mode`` / ``obs_keys`` negotiate the space at connect time (see
-    ``env.metadata['supported_control_modes']`` for what the server offers)."""
+    ``env.metadata['supported_control_modes']`` for what the server offers).
+
+    Camera images (``images=True`` or ``cameras=[...]``) are rendered on this
+    machine in headless Chrome; the server only simulates. That needs the
+    ``render`` extra. ``render`` accepts ``"auto"`` or ``"local"`` (the same
+    thing; kept for callers that pass it). ``render_options`` go to
+    :class:`world_engine_client.render.LocalRenderer` (``cache_dir``,
+    ``allow_software``, ``chrome_args``)."""
+    if render not in ("auto", "local"):
+        raise ValueError("render must be 'auto' or 'local': servers no longer render camera images")
     env = RemoteEnv(url.rstrip("/"), token, timeout=timeout)
     env._access_provider = access_provider
+    env._render_request = render
+    env._render_options = dict(render_options or {})
     try:
         env._connect(
             takeover=takeover,
@@ -66,8 +81,8 @@ def connect(
             expected_instance_id=expected_instance_id,
             proto=proto,
         )
-    except Exception:
-        env._http.close()
+    except BaseException:
+        env.close()
         raise
     return env
 
@@ -105,6 +120,9 @@ class RemoteEnv:
         self.action_dim: int = 7
         self.observation_keys: list[str] = []
         self.control_mode: str | None = None
+        self._render_request = "server"
+        self._render_options: dict = {}
+        self.renderer = None  # LocalRenderer when images are rendered on this machine
 
     # ----- Gym API ------------------------------------------------------------ #
     def reset(self, *, seed: int | None = None, options: dict | None = None):
@@ -204,6 +222,9 @@ class RemoteEnv:
         self._stop.set()
         if self._heartbeat_thread is not None:
             self._heartbeat_thread.join(timeout=self._timeout + 1)
+        if self.renderer is not None:
+            self.renderer.close()
+            self.renderer = None
         if self._session_id is None:
             self._http.close()
             return
@@ -233,11 +254,16 @@ class RemoteEnv:
         expected_instance_id=None,
         proto=_PROTO,
     ) -> None:
-        if images or cameras:
-            try:
-                import PIL  # noqa: F401
-            except ImportError as exc:
-                raise ImportError("Install world-engine-client[img] for images") from exc
+        local = bool(images or cameras)
+        if local:
+            from . import render as local_render
+
+            if not local_render.available():
+                raise local_render.RendererError(
+                    "camera images are rendered on this machine and need the render extra",
+                    code="renderer_unavailable",
+                    fixes=local_render._INSTALL_FIXES,
+                )
         body: dict = {
             "proto": proto,
             "takeover": takeover,
@@ -250,6 +276,8 @@ class RemoteEnv:
             body["control_mode"] = control_mode
         if obs_keys is not None:
             body["obs_keys"] = list(obs_keys)
+        if local:
+            body["render"] = "client"
         reply = self._post("/control/connect", body, with_session=False)
         if reply.get("proto") != proto:
             raise ProtocolError("server did not honor the requested protocol")
@@ -259,6 +287,17 @@ class RemoteEnv:
         if proto == 3:
             self._episode_id = reply.get("episode_id")
         self._refresh_env(reply.get("env"))
+        bundle = reply.get("render") if local else None
+        if local and (not bundle or bundle.get("protocol") != 1):
+            raise ProtocolError(
+                "this server predates client rendering; upgrade it, or connect with images=False"
+            )
+        if local:
+            from .render import LocalRenderer
+
+            self.renderer = LocalRenderer(
+                self._open_render, bundle["scene_init"], bundle["digests"], **self._render_options
+            )
         if proto == 3:
             self._heartbeat_thread = threading.Thread(target=self._heartbeat, daemon=True)
             self._heartbeat_thread.start()
@@ -303,19 +342,7 @@ class RemoteEnv:
                 if len(data) > MAX_RESPONSE:
                     raise ProtocolError("response exceeds size limit")
                 received = time.perf_counter()
-                if response.getheader("Content-Type", "").split(";")[0] == CONTENT_TYPE:
-                    reply = decode(data, self.metadata.get("cameras", {}))
-                    decoded = time.perf_counter()
-                    server_ms = reply.get("info", {}).get("timings", {}).get("server_ms", 0)
-                    self.last_timings = {
-                        **reply.get("info", {}).get("timings", {}),
-                        "decode_ms": (decoded - received) * 1000,
-                        "transport_ms": max(0, (received - started) * 1000 - server_ms),
-                        "total_ms": (decoded - started) * 1000,
-                        "response_bytes": len(data),
-                    }
-                else:
-                    reply = json.loads(data)
+                reply = json.loads(data)
                 if not isinstance(reply, dict) or "ok" not in reply:
                     raise ProtocolError("invalid response envelope")
             except (OSError, http.client.HTTPException, ValueError, ProtocolError) as exc:
@@ -328,11 +355,8 @@ class RemoteEnv:
                 raise ProtocolError(f"request failed at {path}: {exc}") from exc
             if reply.get("ok") and path in ("/control/reset", "/control/step", "/control/observe"):
                 try:
-                    if (
-                        self.metadata.get("cameras")
-                        and response.getheader("Content-Type", "").split(";")[0] != CONTENT_TYPE
-                    ):
-                        raise ValueError("image observation silently downgraded to JSON")
+                    if self.renderer is not None and "render_state" not in reply:
+                        raise ValueError("observation without the poses to render")
                     if not isinstance(reply["obs"], dict) or not isinstance(reply["info"], dict):
                         raise ValueError("invalid observation or info")
                     for key, spec in (
@@ -362,7 +386,45 @@ class RemoteEnv:
                 if reply.get("code") == "recovery_required":
                     self._uncertain = True
                 raise_for(reply)
+        if path not in ("/control/reset", "/control/step", "/control/observe"):
             return reply
+        server_ms = reply["info"].get("timings", {}).get("server_ms", 0)
+        timings = {
+            "server_ms": server_ms,
+            "transport_ms": max(0, (received - started) * 1000 - server_ms),
+            "response_bytes": len(data),
+        }
+        if self.renderer is not None:
+            # Outside the lock: the heartbeat must not wait for a frame. A
+            # render failure leaves physics as stepped; observe() renders again.
+            rendering = time.perf_counter()
+            reply["obs"]["rgb"] = self.renderer.render(reply["render_state"])
+            timings["render_ms"] = (time.perf_counter() - rendering) * 1000
+        timings["total_ms"] = (time.perf_counter() - started) * 1000
+        self.last_timings = timings
+        return reply
+
+    def _open_render(self, path: str):
+        """GET <server>/render<path> with this session's credentials, on its own
+        connection (the renderer runs on another thread)."""
+        parsed = urllib.parse.urlsplit(self._base)
+        transport = (
+            http.client.HTTPSConnection if parsed.scheme == "https" else http.client.HTTPConnection
+        )
+        conn = transport(parsed.hostname, parsed.port, timeout=max(self._timeout, 120))
+        headers = {"X-We-Control-Token": self._token}
+        if self._access_provider:
+            headers["Authorization"] = "Bearer " + self._access_provider()
+        conn.request("GET", self._prefix + "/render" + path, headers=headers)
+        response = conn.getresponse()
+        if response.status == 404:
+            conn.close()
+            raise FileNotFoundError(path)
+        if response.status != 200:
+            detail = response.read(500).decode("utf-8", "replace")
+            conn.close()
+            raise OSError(f"HTTP {response.status} for {path}: {detail}")
+        return _Owned(response, conn)
 
     @staticmethod
     def _np_obs(obs: dict) -> dict:
@@ -377,3 +439,19 @@ class RemoteEnv:
             else:
                 out[k] = v
         return out
+
+
+class _Owned:
+    """A response that closes its connection when the caller is done."""
+
+    def __init__(self, response, conn):
+        self._response, self._conn = response, conn
+
+    def read(self, *a):
+        return self._response.read(*a)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self._conn.close()

world_engine_client-0.4.0/src/world_engine_client/render.py

@@ -0,0 +1,373 @@
+"""Render camera observations on this machine (``render="local"``).
+
+The server only simulates physics. It sends the scene description once at
+connect and the poses with every observation; a headless Chrome started here
+runs the same capture page the server-side renderer runs, so the images match.
+Headless Chrome is never a "background tab", so nothing throttles it.
+
+The capture page, its scripts and the scene assets are fetched from the
+server's ``/render/`` prefix with this session's credentials. Assets are cached
+by content digest in a temporary directory that ``close()`` deletes, or in
+``cache_dir`` to keep them across sessions.
+
+Needs the ``render`` extra (Playwright, websockets, Pillow) and a Chrome or
+Chromium: ``pip install 'world-engine-client[render]'`` then
+``python -m playwright install chromium`` (or use an installed Chrome).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import io
+import json
+import mimetypes
+import os
+import shlex
+import shutil
+import sys
+import tempfile
+import threading
+import warnings
+from collections.abc import Callable
+from pathlib import Path
+
+import numpy as np
+
+from .errors import WorldEngineClientError
+
+# Hardware WebGL in headless Chrome, per platform. The Linux flags are the ones
+# the server renderer is verified with (NVIDIA through Vulkan ANGLE); macOS uses
+# Metal; Windows uses Chrome's default (D3D11). WE_RENDER_CHROME_ARGS overrides.
+if sys.platform == "darwin":
+    _CHROME_ARGS = ["--headless=new", "--use-angle=metal", "--ignore-gpu-blocklist"]
+elif sys.platform.startswith("linux"):
+    _CHROME_ARGS = [
+        "--headless=new",
+        "--ozone-platform=headless",
+        "--use-angle=vulkan",
+        "--enable-features=Vulkan",
+        "--use-gl=angle",
+        "--ignore-gpu-blocklist",
+        "--no-sandbox",
+    ]
+else:
+    _CHROME_ARGS = ["--headless=new", "--ignore-gpu-blocklist"]
+
+_INSTALL_FIXES = [
+    "pip install 'world-engine-client[render]' && python -m playwright install chromium",
+    "or pass images=False for a state-only session",
+]
+
+
+class RendererError(WorldEngineClientError):
+    """Local rendering is unavailable or failed. The physics step itself is
+    unaffected: ``env.observe()`` renders the current state again."""
+
+
+def available() -> bool:
+    """True when the ``render`` extra is installed (Chrome is checked on start)."""
+    import importlib.util
+
+    return all(importlib.util.find_spec(m) is not None for m in ("playwright", "websockets", "PIL"))
+
+
+Fetch = Callable[[str], "io.BufferedIOBase"]
+
+
+class LocalRenderer:
+    """Headless Chrome running the capture page; ``render(state)`` -> images.
+
+    ``fetch(path)`` opens ``<server>/render<path>`` with the session's
+    credentials and returns a readable response."""
+
+    def __init__(
+        self,
+        fetch: Fetch,
+        scene_init: dict,
+        digests: dict[str, str],
+        *,
+        cache_dir: str | os.PathLike | None = None,
+        allow_software: bool = False,
+        chrome_args: list[str] | None = None,
+        timeout: float = 300.0,
+    ):
+        if not available():
+            raise RendererError(
+                "local rendering needs the render extra",
+                code="renderer_unavailable",
+                fixes=_INSTALL_FIXES,
+            )
+        self._fetch = fetch
+        self._scene_init = scene_init
+        self._digests = dict(digests)
+        self._own_cache = cache_dir is None
+        self._cache = Path(cache_dir or tempfile.mkdtemp(prefix="we_render_"))
+        self._cache.mkdir(parents=True, exist_ok=True)
+        self._allow_software = allow_software
+        override = os.environ.get("WE_RENDER_CHROME_ARGS")
+        self._args = chrome_args or (shlex.split(override) if override else _CHROME_ARGS)
+        self._timeout = timeout
+        self.gpu = "(unknown)"
+        self.software = False
+        self.lighting: str | None = None
+        self._frame_id = 0
+        self._pending: dict[int, asyncio.Future] = {}
+        self._ws = None
+        self._ready = None
+        self._page_error: dict | None = None
+        self._console: list[str] = []
+        self._http = None
+        self._download_lock = threading.Lock()
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._loop.run_forever, daemon=True)
+        self._thread.start()
+        try:
+            self._call(self._start(), timeout + 30)
+        except BaseException:
+            self.close()
+            raise
+
+    # ----- public ------------------------------------------------------------- #
+    def render(self, state: dict) -> dict[str, np.ndarray]:
+        """Pose the scene as ``state`` (a ``render_state`` from the server) and
+        return ``{camera name: (H, W, 3) uint8}``."""
+        if self._ws is None:
+            raise RendererError("renderer is closed", code="renderer_unavailable")
+        header, payload = self._call(self._render(dict(state)), self._timeout)
+        from PIL import Image
+
+        images = {}
+        for spec in header.get("images", []):
+            chunk = payload[spec["offset"] : spec["offset"] + spec["length"]]
+            with Image.open(io.BytesIO(chunk)) as img:
+                images[spec["name"]] = np.asarray(img.convert("RGB"), dtype=np.uint8).copy()
+        self.last_timings = header.get("timings", {})
+        return images
+
+    def close(self) -> None:
+        if self._loop.is_running():
+            try:
+                self._call(self._stop(), 30)
+            except Exception:
+                pass
+            self._loop.call_soon_threadsafe(self._loop.stop)
+            self._thread.join(timeout=10)
+        if self._own_cache:
+            shutil.rmtree(self._cache, ignore_errors=True)
+
+    def __enter__(self) -> LocalRenderer:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # ----- loop thread ---------------------------------------------------------- #
+    def _call(self, coro, timeout):
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        try:
+            return future.result(timeout)
+        except TimeoutError as exc:
+            future.cancel()
+            raise RendererError(
+                "local renderer timed out: " + " | ".join(self._console[-5:]),
+                code="renderer_unavailable",
+            ) from exc
+
+    async def _start(self):
+        import websockets
+        from playwright.async_api import async_playwright
+
+        self._ready = asyncio.Event()
+
+        async def handler(ws):
+            self._ws = ws
+            async for raw in ws:
+                if isinstance(raw, (bytes, bytearray)):
+                    buf = bytes(raw)
+                    size = int.from_bytes(buf[:4], "little")
+                    header = json.loads(buf[4 : 4 + size].decode("utf-8"))
+                    fut = self._pending.pop(header.get("frame_id"), None)
+                    if fut is not None and not fut.done():
+                        fut.set_result((header, buf[4 + size :]))
+                    continue
+                msg = json.loads(raw)
+                if msg.get("type") == "ready":
+                    self.gpu = msg.get("gpu", self.gpu)
+                    self.software = bool(msg.get("software"))
+                    self.lighting = msg.get("lighting")
+                    self._ready.set()
+                elif msg.get("type") == "error":
+                    self._page_error = msg
+                    self.gpu = msg.get("gpu", self.gpu)
+                    self._ready.set()
+
+        self._server = await websockets.serve(handler, "127.0.0.1", 0, max_size=None)
+        port = self._server.sockets[0].getsockname()[1]
+        self._pw = await async_playwright().start()
+        self._browser = await self._launch()
+        self._page = await self._browser.new_page()
+        self._page.on(
+            "console",
+            lambda m: m.type in ("warning", "error") and self._console.append(m.text[:300]),
+        )
+        self._page.on("pageerror", lambda e: self._console.append(f"pageerror: {e}"))
+        # A real loopback HTTP server serves the page: Chrome's local network
+        # access checks block a page that is not itself on loopback (including
+        # one answered by request interception) from opening ws://127.0.0.1.
+        self._http = _ProxyServer(self)
+        origin = f"http://127.0.0.1:{self._http.port}"
+        query = f"captureOnly=1&ws=ws://127.0.0.1:{port}/"
+        if self._allow_software:
+            query += "&allowSoftware=1"
+        await self._page.goto(f"{origin}/index.html?{query}", wait_until="load")
+        for _ in range(int(self._timeout * 10)):
+            if self._ws is not None:
+                break
+            await asyncio.sleep(0.1)
+        if self._ws is None:
+            raise RendererError(
+                "the capture page did not start: " + " | ".join(self._console[-5:]),
+                code="renderer_unavailable",
+            )
+        await self._ws.send(json.dumps(self._scene_init))
+        try:
+            await asyncio.wait_for(self._ready.wait(), self._timeout)
+        except TimeoutError as exc:
+            raise RendererError(
+                "scene loading timed out: " + " | ".join(self._console[-5:]),
+                code="renderer_unavailable",
+            ) from exc
+        if self._page_error is not None:
+            raise RendererError(
+                f"Chrome has no hardware WebGL here ({self.gpu}); software rendering "
+                "is very slow, so it is off by default",
+                code="software_renderer",
+                fixes=[
+                    "check chrome://gpu, or set WE_RENDER_CHROME_ARGS for your GPU",
+                    "pass render_options={'allow_software': True} to accept slow rendering",
+                    "or pass images=False for a state-only session",
+                ],
+            )
+        if self.software:
+            warnings.warn(
+                f"rendering camera images in software ({self.gpu}); expect a few frames per second",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+    async def _launch(self):
+        errors = []
+        for channel in ("chrome", None):  # an installed Chrome, else Playwright's
+            try:
+                return await self._pw.chromium.launch(
+                    channel=channel,
+                    headless=True,
+                    args=self._args,
+                    ignore_default_args=["--disable-gpu", "--headless"],
+                )
+            except Exception as exc:  # noqa: BLE001 - try the next browser
+                errors.append(str(exc).splitlines()[0])
+        raise RendererError(
+            "no Chrome or Chromium to render with: " + " | ".join(errors),
+            code="renderer_unavailable",
+            fixes=_INSTALL_FIXES,
+        )
+
+    async def _render(self, state):
+        self._frame_id += 1
+        state["frame_id"] = self._frame_id
+        fut = self._loop.create_future()
+        self._pending[self._frame_id] = fut
+        await self._ws.send(json.dumps(state))
+        return await fut
+
+    def _provide(self, path: str) -> tuple[Path | bytes, str]:
+        """The body for ``path`` (a cached file or bytes) and its content type."""
+        ctype = mimetypes.guess_type(path)[0] or "application/octet-stream"
+        if path.endswith(".js"):
+            ctype = "text/javascript"
+        digest = self._digests.get(path)
+        if digest is None:
+            return self._read(path), ctype
+        cached = self._cache / digest
+        with self._download_lock:
+            if not cached.is_file():
+                self._download(path, digest, cached)
+        return cached, ctype
+
+    def _read(self, path: str) -> bytes:
+        with self._fetch(path) as response:
+            return response.read()
+
+    def _download(self, path: str, digest: str, target: Path) -> None:
+        partial = target.with_suffix(".part")
+        h = hashlib.sha256()
+        with self._fetch(path) as response, open(partial, "wb") as out:
+            for chunk in iter(lambda: response.read(1 << 20), b""):
+                h.update(chunk)
+                out.write(chunk)
+        if h.hexdigest() != digest:
+            partial.unlink(missing_ok=True)
+            raise RendererError(f"asset {path} does not match its digest", code="asset_mismatch")
+        partial.replace(target)
+
+    async def _stop(self):
+        for name in ("_browser", "_pw"):
+            obj = getattr(self, name, None)
+            if obj is not None:
+                try:
+                    await (obj.close() if name == "_browser" else obj.stop())
+                except Exception:
+                    pass
+        server = getattr(self, "_server", None)
+        if server is not None:
+            server.close()
+            await server.wait_closed()
+        if self._http is not None:
+            self._http.stop()
+            self._http = None
+        self._ws = None
+
+
+class _ProxyServer:
+    """Loopback HTTP server for the capture page: each GET is answered from
+    the digest cache or fetched from the server's /render/ prefix."""
+
+    def __init__(self, renderer: LocalRenderer):
+        import http.server
+
+        class Handler(http.server.BaseHTTPRequestHandler):
+            def do_GET(self):  # noqa: N802 - http.server API
+                path = self.path.split("?", 1)[0]
+                try:
+                    body, ctype = renderer._provide(path)
+                except FileNotFoundError:
+                    self.send_error(404)
+                    return
+                except Exception as exc:  # noqa: BLE001 - reported in the console tail
+                    renderer._console.append(f"fetch {path}: {exc}")
+                    self.send_error(502)
+                    return
+                size = body.stat().st_size if isinstance(body, Path) else len(body)
+                self.send_response(200)
+                self.send_header("Content-Type", ctype)
+                self.send_header("Content-Length", str(size))
+                self.end_headers()
+                if isinstance(body, Path):
+                    with open(body, "rb") as f:
+                        shutil.copyfileobj(f, self.wfile, 1 << 20)
+                else:
+                    self.wfile.write(body)
+
+            def log_message(self, *args):
+                pass
+
+        self._httpd = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self._httpd.daemon_threads = True
+        self.port = self._httpd.server_address[1]
+        threading.Thread(target=self._httpd.serve_forever, daemon=True).start()
+
+    def stop(self) -> None:
+        self._httpd.shutdown()
+        self._httpd.server_close()

{world_engine_client-0.3.0 → world_engine_client-0.4.0}/src/world_engine_client/rotations.py

@@ -56,8 +56,7 @@ def matrix_to_axisangle(m: np.ndarray) -> np.ndarray:
         if m[0, 2] + m[2, 0] < 0:
             axis[2] = -axis[2]
         return axis * angle
-    axis = (
-        np.array([m[2, 1] - m[1, 2], m[0, 2] - m[2, 0], m[1, 0] - m[0, 1]])
-        / (2.0 * np.sin(angle))
+    axis = np.array([m[2, 1] - m[1, 2], m[0, 2] - m[2, 0], m[1, 0] - m[0, 1]]) / (
+        2.0 * np.sin(angle)
     )
     return axis * angle

{world_engine_client-0.3.0 → world_engine_client-0.4.0}/tests/conftest.py

@@ -4,15 +4,13 @@ These tests exercise the client alone. The wire contract against a real engine
 is covered in the server repository (tests/test_remote_*.py).
 """
 
-import io
 import json
 import socket
 import threading
-from http.server import BaseHTTPRequestHandler, HTTPServer
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 
 import pytest
 
-CONTENT_TYPE = "application/vnd.world-engine.observation-v3"
 DROP = object()  # responder return value: close the socket without replying
 
 ENV = {
@@ -33,25 +31,6 @@ ENV = {
 OBS = {"robot0_eef_pos": [0.1, 0.2, 0.3], "object_ids": ["cube"]}
 
 
-def jpeg(width, height, color=(200, 30, 30)):
-    from PIL import Image
-
-    buf = io.BytesIO()
-    Image.new("RGB", (width, height), color).save(buf, format="JPEG", quality=90)
-    return buf.getvalue()
-
-
-def pack(header, chunks, specs=None):
-    """Protocol-3 packet: u32 length, JSON envelope, concatenated JPEGs."""
-    if specs is None:
-        specs, offset = [], 0
-        for name, w, h, data in chunks:
-            specs.append({"name": name, "w": w, "h": h, "offset": offset, "length": len(data)})
-            offset += len(data)
-    meta = json.dumps({"wire_version": 3, **header, "images": specs}).encode()
-    return len(meta).to_bytes(4, "little") + meta + b"".join(c[3] for c in chunks)
-
-
 class ControlStub:
     """Records every request; ``responders[path]`` overrides the default reply."""
 
@@ -60,6 +39,7 @@ class ControlStub:
         self.responders = {}
         self.step_id = 0
         self.episode = 0
+        self.files = {}  # GET path -> bytes (the /render/ prefix)
 
     def default(self, path, body):
         path = path[path.index("/control/") :]  # tolerate a gateway prefix
@@ -126,10 +106,25 @@ def stub():
             self.end_headers()
             self.wfile.write(data)
 
+        def do_GET(self):
+            state.calls.append((self.path, None, dict(self.headers)))
+            data = state.files.get(self.path)
+            if data is None:
+                self.send_response(404)
+                self.send_header("Content-Length", "0")
+                self.end_headers()
+                return
+            self.send_response(200)
+            self.send_header("Content-Type", "application/octet-stream")
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+
         def log_message(self, *args):
             pass
 
-    server = HTTPServer(("127.0.0.1", 0), Handler)
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    server.daemon_threads = True
     threading.Thread(target=server.serve_forever, daemon=True).start()
     state.url = f"http://127.0.0.1:{server.server_address[1]}"
     yield state

{world_engine_client-0.3.0 → world_engine_client-0.4.0}/tests/test_env_transport.py

@@ -4,13 +4,11 @@ The rule under test: a request whose outcome is unknown is never retried, and
 step/reset failures block further actions until an explicit reset or reconnect.
 """
 
-import copy
-import sys
 import threading
 
 import numpy as np
 import pytest
-from conftest import CONTENT_TYPE, DROP, ENV, OBS, jpeg, pack
+from conftest import DROP, ENV, OBS
 
 import world_engine_client as wec
 from world_engine_client import env as env_module
@@ -286,48 +284,6 @@ def test_render_requires_an_image_observation(env):
         env.render()
 
 
-def image_env(stub):
-    with_cameras = {**copy.deepcopy(ENV), "cameras": CAMERAS, "available_cameras": CAMERAS}
-    stub.responders["/control/connect"] = lambda body: {
-        "ok": True,
-        "session_id": "sess",
-        "proto": 3,
-        "instance_id": "inst",
-        "episode_id": "e0",
-        "env": with_cameras,
-    }
-    return wec.connect("secret", url=stub.url, images=True)
-
-
-def test_binary_image_reply_decodes_and_reports_timings(stub):
-    env = image_env(stub)
-    assert stub.calls[0][1]["images"] is True
-    header = {"ok": True, "obs": OBS, "info": {"episode_id": "e0", "timings": {"server_ms": 1}}}
-    packet = pack(header, [("front", 8, 6, jpeg(8, 6))])
-    stub.responders["/control/observe"] = lambda body: (CONTENT_TYPE, packet)
-    obs, info = env.observe()
-    assert obs["rgb"]["front"].shape == (6, 8, 3)
-    assert env.render() is obs["rgb"]["front"] and env.render("front") is obs["rgb"]["front"]
-    assert {"decode_ms", "transport_ms", "total_ms", "server_ms"} <= set(env.last_timings)
-    assert env.last_timings["response_bytes"] == len(packet)
-    assert env.last_timings["transport_ms"] >= 0
-    env.close()
-
-
-def test_image_session_rejects_a_json_downgrade(stub):
-    env = image_env(stub)
-    with pytest.raises(wec.ProtocolError, match="malformed observation"):
-        env.observe()
-    env.close()
-
-
-def test_images_without_pillow_fail_before_any_request(stub, monkeypatch):
-    monkeypatch.setitem(sys.modules, "PIL", None)
-    with pytest.raises(ImportError, match=r"world-engine-client\[img\]"):
-        wec.connect("secret", url=stub.url, cameras=["front"])
-    assert stub.calls == []
-
-
 class Ticks:
     """Stands in for the stop event: ``wait`` returns immediately, n times."""
 

world_engine_client-0.4.0/tests/test_render.py

@@ -0,0 +1,175 @@
+"""Client rendering without a browser: the extra requirement, the render_state
+hand-off, credentials on asset requests and the digest cache."""
+
+import copy
+import hashlib
+
+import numpy as np
+import pytest
+from conftest import ENV, OBS
+
+import world_engine_client as wec
+from world_engine_client import render as render_module
+
+CAMERAS = {"front": {"width": 8, "height": 6}}
+STATE = {"type": "state", "frame_id": 0, "bodies": [], "robot": {}, "cameras": []}
+BUNDLE = {
+    "protocol": 1,
+    "scene_init": {"type": "scene_init", "cameras": []},
+    "digests": {"/__asset/0.ply": "ab" * 32},
+}
+
+
+class FakeRenderer:
+    instances = []
+
+    def __init__(self, fetch, scene_init, digests, **options):
+        self.fetch, self.scene_init, self.digests = fetch, scene_init, digests
+        self.options = options
+        self.states, self.closed, self.fail = [], False, False
+        FakeRenderer.instances.append(self)
+
+    def render(self, state):
+        if self.fail:
+            raise render_module.RendererError("GPU lost", code="renderer_unavailable")
+        self.states.append(state)
+        return {"front": np.full((6, 8, 3), len(self.states), np.uint8)}
+
+    def close(self):
+        self.closed = True
+
+
+@pytest.fixture
+def client_render(stub, monkeypatch):
+    """A stub that offers client rendering; LocalRenderer replaced by a fake."""
+    FakeRenderer.instances = []
+    monkeypatch.setattr(render_module, "available", lambda: True)
+    monkeypatch.setattr(render_module, "LocalRenderer", FakeRenderer)
+    env = {**copy.deepcopy(ENV), "cameras": CAMERAS, "render": "client"}
+    stub.responders["/control/connect"] = lambda body: {
+        "ok": True,
+        "session_id": "sess",
+        "proto": 3,
+        "instance_id": "inst",
+        "episode_id": "e0",
+        "env": env,
+        **({"render": BUNDLE} if body.get("render") == "client" else {}),
+    }
+    for path in ("/control/reset", "/control/observe"):
+        stub.responders[path] = lambda body: {
+            "ok": True,
+            "obs": dict(OBS),
+            "info": {"episode_id": "e1", "step_id": 0},
+            "render_state": STATE,
+        }
+    stub.responders["/control/step"] = lambda body: {
+        "ok": True,
+        "obs": dict(OBS),
+        "info": {"episode_id": "e1", "step_id": 1},
+        "reward": 0.0,
+        "terminated": False,
+        "truncated": False,
+        "render_state": STATE,
+    }
+    return stub
+
+
+def test_images_are_rendered_locally(client_render):
+    env = wec.connect("secret", url=client_render.url, images=True, render_options={"x": 1})
+    connect = client_render.calls[0][1]
+    assert connect["render"] == "client" and connect["images"] is True
+    fake = FakeRenderer.instances[0]
+    assert fake.scene_init == BUNDLE["scene_init"] and fake.options == {"x": 1}
+    obs, _ = env.reset(seed=0)
+    assert obs["rgb"]["front"].shape == (6, 8, 3) and fake.states == [STATE]
+    assert env.render() is obs["rgb"]["front"]
+    env.close()
+    assert fake.closed and client_render.paths()[-1] == "/control/release"
+
+
+@pytest.mark.parametrize("kw", [{"images": True}, {"cameras": ["front"]}])
+def test_images_without_the_extra_fail_before_any_request(stub, monkeypatch, kw):
+    monkeypatch.setattr(render_module, "available", lambda: False)
+    with pytest.raises(wec.RendererError, match=r"render\]"):
+        wec.connect("secret", url=stub.url, **kw)
+    assert stub.calls == []
+
+
+@pytest.mark.parametrize("mode", ["server", "browser"])
+def test_servers_never_render(stub, mode):
+    with pytest.raises(ValueError, match="no longer render"):
+        wec.connect("secret", url=stub.url, images=True, render=mode)
+    assert stub.calls == []
+
+
+def test_a_server_without_client_rendering_is_released(client_render):
+    client_render.responders["/control/connect"] = lambda body: {
+        "ok": True,
+        "session_id": "sess",
+        "proto": 3,
+        "instance_id": "inst",
+        "episode_id": "e0",
+        "env": {**copy.deepcopy(ENV), "cameras": CAMERAS},
+    }
+    with pytest.raises(wec.ProtocolError, match="predates client rendering"):
+        wec.connect("secret", url=client_render.url, images=True)
+    assert client_render.paths()[-1] == "/control/release"
+
+
+def test_a_render_failure_leaves_physics_and_observe_renders_again(client_render):
+    env = wec.connect("secret", url=client_render.url, images=True)
+    env.reset(seed=0)
+    fake = FakeRenderer.instances[0]
+    fake.fail = True
+    with pytest.raises(wec.RendererError, match="GPU lost"):
+        env.observe()
+    fake.fail = False
+    obs, _ = env.observe()
+    assert obs["rgb"]["front"][0, 0, 0] == 2
+    obs, *_ = env.step([0, 0, 0, 0])  # the failed render blocked no action
+    assert obs["rgb"]["front"][0, 0, 0] == 3
+    env.close()
+
+
+def test_an_observation_without_poses_is_a_protocol_error(client_render):
+    env = wec.connect("secret", url=client_render.url, images=True)
+    client_render.responders["/control/observe"] = lambda body: {
+        "ok": True,
+        "obs": dict(OBS),
+        "info": {"episode_id": "e1", "step_id": 0},
+    }
+    with pytest.raises(wec.ProtocolError, match="malformed observation"):
+        env.observe()
+    env.close()
+
+
+def test_asset_requests_carry_the_session_credentials(client_render):
+    env = wec.connect(
+        "secret", url=client_render.url, images=True, access_provider=lambda: "scoped"
+    )
+    client_render.files["/render/index.html"] = b"<html>"
+    with env._open_render("/index.html") as response:
+        assert response.read() == b"<html>"
+    path, _, headers = client_render.calls[-1]
+    assert path == "/render/index.html"
+    assert headers["X-We-Control-Token"] == "secret"
+    assert headers["Authorization"] == "Bearer scoped"
+    with pytest.raises(FileNotFoundError):
+        env._open_render("/missing.js")
+    env.close()
+
+
+def test_downloads_are_verified_against_their_digest(tmp_path, stub):
+    renderer = object.__new__(render_module.LocalRenderer)  # no browser needed
+    env = wec.connect("secret", url=stub.url)
+    renderer._fetch = env._open_render
+    data = b"splat bytes"
+    stub.files["/render/__asset/0.ply"] = data
+    good = tmp_path / hashlib.sha256(data).hexdigest()
+    renderer._download("/__asset/0.ply", good.name, good)
+    assert good.read_bytes() == data
+    bad = tmp_path / ("0" * 64)
+    with pytest.raises(wec.RendererError, match="digest"):
+        renderer._download("/__asset/0.ply", bad.name, bad)
+    assert not bad.exists() and not bad.with_suffix(".part").exists()
+    env.close()

world_engine_client-0.3.0/src/world_engine_client/wire.py

@@ -1,66 +0,0 @@
-"""Strict protocol-3 binary decoder; Pillow is imported only for images."""
-
-import io
-import json
-
-import numpy as np
-
-from .errors import ProtocolError
-
-CONTENT_TYPE = "application/vnd.world-engine.observation-v3"
-MAX_RESPONSE = 64 * 1024 * 1024
-
-
-def decode(data: bytes, cameras: dict) -> dict:
-    try:
-        if len(data) < 4 or len(data) > MAX_RESPONSE:
-            raise ValueError("invalid packet length")
-        length = int.from_bytes(data[:4], "little")
-        if not 0 < length <= min(len(data) - 4, 1024 * 1024):
-            raise ValueError("invalid metadata length")
-        header = json.loads(data[4 : 4 + length])
-        if type(header["wire_version"]) is not int or header["wire_version"] != 3:
-            raise ValueError("unsupported observation version")
-        payload = data[4 + length :]
-        seen, offset = set(), 0
-        for spec in header["images"]:
-            name = spec["name"]
-            if name in seen or name not in cameras:
-                raise ValueError("unexpected or duplicate camera")
-            seen.add(name)
-            n = spec["length"]
-            if (
-                type(n) is not int
-                or type(spec["offset"]) is not int
-                or type(spec["w"]) is not int
-                or type(spec["h"]) is not int
-                or n <= 0
-                or spec["offset"] != offset
-                or offset + n > len(payload)
-            ):
-                raise ValueError("invalid image offset/length")
-            expected = cameras[name]
-            if (spec["w"], spec["h"]) != (expected["width"], expected["height"]):
-                raise ValueError("camera dimensions changed")
-            offset += n
-        if seen != set(cameras) or offset != len(payload):
-            raise ValueError("missing images or trailing data")
-        try:
-            from PIL import Image
-        except ImportError as exc:
-            raise ImportError(
-                "RGB observations require pip install 'world-engine-client[img]'"
-            ) from exc
-        rgb = {}
-        for spec in header["images"]:
-            chunk = payload[spec["offset"] : spec["offset"] + spec["length"]]
-            if not chunk.endswith(b"\xff\xd9"):
-                raise ValueError("truncated JPEG")
-            with Image.open(io.BytesIO(chunk)) as img:
-                if img.format != "JPEG" or img.size != (spec["w"], spec["h"]):
-                    raise ValueError("decoded image dimensions or format mismatch")
-                rgb[spec["name"]] = np.asarray(img.convert("RGB"), dtype=np.uint8).copy()
-        header["obs"]["rgb"] = rgb
-        return header
-    except (KeyError, TypeError, ValueError, OSError) as exc:
-        raise ProtocolError(f"malformed observation: {exc}") from exc

world_engine_client-0.3.0/tests/test_wire.py

@@ -1,140 +0,0 @@
-"""wire.decode accepts exactly the documented packet and nothing else."""
-
-import json
-import sys
-
-import numpy as np
-import pytest
-from conftest import jpeg, pack
-
-from world_engine_client import ProtocolError, wire
-
-CAMERAS = {"front": {"width": 8, "height": 6}, "wrist": {"width": 4, "height": 4}}
-HEADER = {"obs": {"robot0_eef_pos": [0, 0, 0]}, "info": {"step_id": 1}}
-
-
-def chunks():
-    return [("front", 8, 6, jpeg(8, 6)), ("wrist", 4, 4, jpeg(4, 4, (10, 10, 240)))]
-
-
-def test_round_trip_returns_rgb_uint8_per_camera():
-    reply = wire.decode(pack(HEADER, chunks()), CAMERAS)
-    rgb = reply["obs"]["rgb"]
-    assert list(rgb) == ["front", "wrist"]
-    assert rgb["front"].shape == (6, 8, 3) and rgb["front"].dtype == np.uint8
-    assert rgb["wrist"].shape == (4, 4, 3)
-    # Channel order survives: the first camera is red, the second blue.
-    assert rgb["front"][0, 0, 0] > 150 > rgb["front"][0, 0, 2]
-    assert rgb["wrist"][0, 0, 2] > 150 > rgb["wrist"][0, 0, 0]
-    assert reply["info"] == {"step_id": 1}
-
-
-def raw(header: bytes, payload: bytes = b"") -> bytes:
-    return len(header).to_bytes(4, "little") + header + payload
-
-
-def respec(**change):
-    """A two-camera packet whose first descriptor is altered."""
-    parts = chunks()
-    specs, offset = [], 0
-    for name, w, h, data in parts:
-        specs.append({"name": name, "w": w, "h": h, "offset": offset, "length": len(data)})
-        offset += len(data)
-    specs[0].update(change)
-    return pack(HEADER, parts, specs)
-
-
-@pytest.mark.parametrize(
-    "packet",
-    [
-        b"",
-        b"\x01\x00",
-        raw(b""),  # zero metadata length
-        (2 * 1024 * 1024).to_bytes(4, "little") + b"{}",  # metadata longer than the packet
-        raw(b"{not json"),
-        raw(json.dumps({"wire_version": 3, "obs": {}}).encode()),  # no images key
-        raw(json.dumps({"wire_version": 3, "images": []}).encode()),  # no obs, missing cameras
-        raw(json.dumps([1, 2]).encode()),
-    ],
-    ids=["empty", "short", "zero-meta", "meta-overrun", "bad-json", "no-images", "no-obs", "list"],
-)
-def test_malformed_envelopes_are_rejected(packet):
-    with pytest.raises(ProtocolError, match="malformed observation"):
-        wire.decode(packet, CAMERAS)
-
-
-@pytest.mark.parametrize("version", [2, 4, "3", 3.0, True, None])
-def test_only_integer_wire_version_3_is_accepted(version):
-    meta = json.dumps({"wire_version": version, "obs": {}, "images": []}).encode()
-    with pytest.raises(ProtocolError):
-        wire.decode(raw(meta), {})
-
-
-@pytest.mark.parametrize(
-    "change",
-    [
-        {"name": "wrist"},  # duplicate
-        {"name": "side"},  # not negotiated
-        {"length": 0},
-        {"length": -5},
-        {"length": "12"},
-        {"length": 12.0},
-        {"offset": 1},
-        {"offset": "0"},
-        {"w": 8.0},
-        {"h": "6"},
-        {"w": 16},  # disagrees with the negotiated dimensions
-        {"length": 10**9},  # beyond the payload
-    ],
-    ids=lambda c: "-".join(f"{k}={v!r}" for k, v in c.items()),
-)
-def test_bad_image_descriptors_are_rejected(change):
-    with pytest.raises(ProtocolError):
-        wire.decode(respec(**change), CAMERAS)
-
-
-def test_missing_camera_and_trailing_bytes_are_rejected():
-    with pytest.raises(ProtocolError, match="missing images"):
-        wire.decode(pack(HEADER, chunks()[:1]), CAMERAS)
-    with pytest.raises(ProtocolError, match="trailing"):
-        wire.decode(pack(HEADER, chunks()) + b"\x00", CAMERAS)
-
-
-def test_non_contiguous_offsets_are_rejected():
-    parts = chunks()
-    specs = [
-        {"name": "front", "w": 8, "h": 6, "offset": 0, "length": len(parts[0][3])},
-        {"name": "wrist", "w": 4, "h": 4, "offset": len(parts[0][3]) + 1, "length": 1},
-    ]
-    with pytest.raises(ProtocolError, match="offset"):
-        wire.decode(pack(HEADER, parts, specs), CAMERAS)
-
-
-def test_truncated_and_non_jpeg_images_are_rejected():
-    one = {"front": CAMERAS["front"]}
-    good = jpeg(8, 6)
-    with pytest.raises(ProtocolError, match="truncated JPEG"):
-        wire.decode(pack(HEADER, [("front", 8, 6, good[:-2])]), one)
-    with pytest.raises(ProtocolError):
-        wire.decode(pack(HEADER, [("front", 8, 6, b"not an image" + b"\xff\xd9")]), one)
-
-
-def test_decoded_size_must_match_descriptor():
-    # The descriptor and the negotiated camera agree, but the JPEG itself is 4x4.
-    packet = pack(HEADER, [("front", 8, 6, jpeg(4, 4))])
-    with pytest.raises(ProtocolError, match="dimensions or format"):
-        wire.decode(packet, {"front": CAMERAS["front"]})
-
-
-def test_response_size_limit(monkeypatch):
-    packet = pack(HEADER, chunks())
-    monkeypatch.setattr(wire, "MAX_RESPONSE", len(packet) - 1)
-    with pytest.raises(ProtocolError, match="packet length"):
-        wire.decode(packet, CAMERAS)
-
-
-def test_missing_pillow_is_an_actionable_import_error(monkeypatch):
-    packet = pack(HEADER, chunks())
-    monkeypatch.setitem(sys.modules, "PIL", None)
-    with pytest.raises(ImportError, match=r"world-engine-client\[img\]"):
-        wire.decode(packet, CAMERAS)