bencher.utils_rrd

Utilities for serving and viewing .rrd files without the rerun Python SDK.

This module provides functions for displaying pre-recorded .rrd files (e.g. those produced by the C++ rerun library) in Panel reports. It does NOT depend on the rerun-sdk package, so downstream projects that cannot install it (e.g. because of a NumPy 2 requirement) can still use these utilities.

See utils_rerun.py for functions that require the rerun Python SDK (live capture, recording management, etc.).

Attributes

`_RRD_CACHE_DIR`
`_VERSION_RE`
`_CDN_VIEWER_TEMPLATE`
`_CDN_VIEWER_INLINE_TEMPLATE`
`_cdn_viewer_files`
`_cdn_viewer_html`
`_RRD_URL_RE`

Functions

`_get_rerun_version`(→ str)	Get the installed rerun package version, or a sensible default.
`rrd_to_pane`(url[, width, height, version])	Display an .rrd file from a URL using the hosted rerun web viewer.
`publish_and_view_rrd`(file_path, remote, branch_name, ...)
`rrd_file_to_pane`(file_path[, width, height, ...])	Create a rerun viewer pane from an .rrd file path.
`_wrap_viewer_controls`(→ str)	Wrap a rerun-viewer iframe with fullscreen and open-in-new-tab controls.
`_cdn_viewer_url`(→ str)	Return the iframe URL for a CDN-based viewer at the given version.
`_get_cdn_viewer_html`(→ str)	Return the viewer HTML string for a given rerun version (cached).
`_write_rrd_sidecar`(→ tuple[str, str])	Copy an .rrd file and its CDN viewer page into dest_dir.
`_portable_rrd_pane`(→ panel.pane.HTML)	Create a self-contained pane with files copied into the report directory.
`_write_inline_viewer`(→ str)	Create a self-contained viewer HTML with the .rrd data inlined as base64.
`inline_rrd_iframes`(→ None)	Post-process a saved HTML report for static hosting.

Module Contents

bencher.utils_rrd._RRD_CACHE_DIR

bencher.utils_rrd._VERSION_RE

bencher.utils_rrd._get_rerun_version() → str: Get the installed rerun package version, or a sensible default.

bencher.utils_rrd.rrd_to_pane(url: str, width: int = 500, height: int = 600, version: str | None = None): Display an .rrd file from a URL using the hosted rerun web viewer.

bencher.utils_rrd.publish_and_view_rrd(file_path: str, remote: str, branch_name: str, content_callback: callable, version: str | None = None)

bencher.utils_rrd.rrd_file_to_pane(file_path, width: int = 300, height: int = 300, viewer_version: str | None = None, report_dir: str | pathlib.Path | None = None)

Create a rerun viewer pane from an .rrd file path.

Uses an HTML iframe to display the .rrd file. By default the viewer is loaded from the @rerun-io/web-viewer CDN at the installed rerun-sdk version. The viewer page and the .rrd data are both served from the Panel server’s /rrd_static/ route, keeping everything on a single origin (no CORS, no extra ports).

The file must be located under cachedir/rrd/.

Parameters:

file_path – Path to the .rrd file (must be under cachedir/rrd/).
width – Width of the viewer iframe in pixels.
height – Height of the viewer iframe in pixels.
viewer_version – Rerun web-viewer version to load from CDN. Defaults to the installed rerun-sdk version. Set explicitly when the .rrd was recorded with a different SDK version.
report_dir – When set, copies the .rrd and viewer HTML into this directory and uses relative URLs in the iframe. This makes the report portable — it works when served from any HTTP origin without a live Panel server.

bencher.utils_rrd._CDN_VIEWER_TEMPLATE = Multiline-String

Show Value

"""<!DOCTYPE html>
<html><head><meta charset="utf-8"/>
<style>html,body{{margin:0;padding:0;width:100%;height:100%;overflow:hidden}}</style>
</head><body>
<div id="c" style="width:100vw;height:100vh"></div>
<div id="e" style="color:red;padding:20px;font-family:monospace;white-space:pre-wrap"></div>
<script type="module">
try {{
  const p = new URLSearchParams(location.search);
  const url = p.get("url");
  if (!url) throw new Error("Missing ?url= parameter");
  const {{WebViewer}} = await import(
    "https://cdn.jsdelivr.net/npm/@rerun-io/web-viewer@{version}/+esm"
  );
  const v = new WebViewer();
  await v.start(new URL(url, location.href).href,
                document.getElementById("c"),
                {{hide_welcome_screen:true,width:"100%",height:"100%"}});
}} catch(e) {{
  document.getElementById("e").textContent = e.message + "\n" + e.stack;
}}
</script></body></html>
"""

bencher.utils_rrd._CDN_VIEWER_INLINE_TEMPLATE = Multiline-String

Show Value

"""<!DOCTYPE html>
<html><head><meta charset="utf-8"/>
<style>html,body{{margin:0;padding:0;width:100%;height:100%;overflow:hidden}}</style>
</head><body>
<div id="c" style="width:100vw;height:100vh"></div>
<div id="e" style="color:red;padding:20px;font-family:monospace;white-space:pre-wrap"></div>
<script id="rrd-data" type="application/octet-stream">{rrd_base64}</script>
<script type="module">
try {{
  const b64 = document.getElementById("rrd-data").textContent.trim();
  const bin = Uint8Array.from(atob(b64), c => c.charCodeAt(0));
  const {{WebViewer}} = await import(
    "https://cdn.jsdelivr.net/npm/@rerun-io/web-viewer@{version}/+esm"
  );
  const v = new WebViewer();
  await v.start(null, document.getElementById("c"),
                {{hide_welcome_screen:true,width:"100%",height:"100%"}});
  const ch = v.open_channel("inline");
  ch.send_rrd(bin);
  ch.close();
}} catch(e) {{
  document.getElementById("e").textContent = e.message + "\n" + e.stack;
}}
</script></body></html>
"""

bencher.utils_rrd._wrap_viewer_controls(iframe_html: str, viewer_url: str, width: int, height: int) → str

Wrap a rerun-viewer iframe with fullscreen and open-in-new-tab controls.

Controls float at the top-center (away from the viewer’s own corner UI). The anchor’s href is set to viewer_url directly so middle-click, Cmd/Ctrl-click, and the context-menu “Open in new tab” all see the right target — not just plain left-click. inline_rrd_iframes() rewrites both the iframe src and the anchor href when a report is saved. A real anchor (rather than window.open()) avoids popup-blocker false positives that silently swallow the click in some browsers.

bencher.utils_rrd._cdn_viewer_files: dict[str, str]

bencher.utils_rrd._cdn_viewer_html: dict[str, str]

bencher.utils_rrd._cdn_viewer_url(rrd_relative: pathlib.Path, version: str) → str

Return the iframe URL for a CDN-based viewer at the given version.

Writes a viewer_<version>.html page into cachedir/rrd/ (served by the Panel server at /rrd_static/) that loads the rerun web viewer from the jsDelivr CDN. Both the viewer page and the .rrd are on the same HTTP origin, avoiding mixed-content blocks.

bencher.utils_rrd._get_cdn_viewer_html(version: str) → str: Return the viewer HTML string for a given rerun version (cached).

bencher.utils_rrd._write_rrd_sidecar(rrd_path: pathlib.Path, version: str, dest_dir: pathlib.Path) → tuple[str, str]

Copy an .rrd file and its CDN viewer page into dest_dir.

Returns (viewer_filename, rrd_filename) — both relative to dest_dir. The viewer page is written idempotently (skipped if already up-to-date).

bencher.utils_rrd._portable_rrd_pane(rrd_path: pathlib.Path, version: str, report_dir: pathlib.Path, width: int, height: int) → panel.pane.HTML

Create a self-contained pane with files copied into the report directory.

Copies the .rrd and a CDN viewer HTML page into report_dir/_rrd/ and returns an iframe with a relative URL. The resulting report can be served from any HTTP origin without a live Panel server.

bencher.utils_rrd._RRD_URL_RE

bencher.utils_rrd._write_inline_viewer(rrd_path: pathlib.Path, version: str, dest_dir: pathlib.Path) → str

Create a self-contained viewer HTML with the .rrd data inlined as base64.

Returns the filename (relative to dest_dir) of the written viewer page.

bencher.utils_rrd.inline_rrd_iframes(html_path: pathlib.Path, rrd_base: pathlib.Path | None = None, portable: bool = False) → None

Post-process a saved HTML report for static hosting.

Scans the HTML file for rerun viewer iframes (those pointing at /rrd_static/), copies the .rrd files next to the report, and rewrites the iframe src to relative URLs.

Parameters:

html_path – Path to the saved HTML file to post-process.
rrd_base – Directory where _rrd/ should be created. When None (default), uses html_path.parent. Pass the top-level report directory for multi-tab saves so all tabs share one _rrd/.
portable – When True, base64-encode the .rrd data directly into the viewer HTML so the report works from file:// without any server. This can be very slow for large recordings (hundreds of MB or more). When False (default), the .rrd is copied as a sidecar file and loaded via a relative URL — the report must be served over HTTP (any static server works).
BenchReport.save(). (Called automatically by)