# OMH ROS bags and Gaussian model inspection

An installable Cordis bundle for browsing ROS bag recordings, exporting sensor artifacts, exposing analysis tools to agents, and inspecting compressed Gaussian models.

## Install

Requires Node 22.19+ and OMH/DeepSeek Harness `0.1.6-alpha.1`. Install the **OMH files bundle** first; `@omh/files` supplies the file-opening and sidebar integration this bundle uses.

Keep this repository on disk, then link it to your Web profile:

```sh
node scripts/install.mjs --profile /absolute/path/to/profile --runtime /absolute/path/to/harness
```

The installer adds this bundle and resolves host dependencies without rewriting the harness checkout. Disable legacy copies of these overlay plugins before enabling the bundle, to avoid duplicate routes. Restart the host and refresh its Web UI after setup.

## Set up the ROS companion

The companion reads `.bag`, `.mcap`, and `.db3` recordings without a ROS installation. Use Python 3.10 or later and install its declared dependencies into a virtual environment:

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r companions/rosbag-kit/requirements.txt
export ROSBAG_PYTHON="$PWD/.venv/bin/python"
companions/rosbag-kit/bin/rosbagctl doctor
```

Video export and native camera playback require `ffmpeg` and `ffprobe` on the host PATH, preferably with the `libx264` encoder. Install them with your operating system's package manager, and check their availability with `doctor`. Open3D is optional for additional rendering; ordinary point-cloud previews use the included OpenCV implementation. PyArrow is optional for Parquet output. Neither optional package is required by the basic sidebar, CLI, or MCP tools.

Configure the same absolute Python executable for the sidebar routes and agent tools in the profile's `cordis.patch.yml`:

```yaml
- id: omh-rosbag-rosbag-routes
  config:
    python: /absolute/path/to/this/repository/.venv/bin/python
- id: omh-rosbag-rosbag-mcp
  config:
    python: /absolute/path/to/this/repository/.venv/bin/python
    toolCallTimeoutMs: 1800000
```

Both default to `ROSBAG_PYTHON`, then `python3`. The bundled CLI and MCP server paths are resolved relative to this repository. `ROSBAGCTL` can override the CLI executable; sidebar routes also accept an absolute `cliPath`. The MCP adapter waits for startup and exposes connection failures instead of reporting successful activation prematurely.

## Features and use

- **OMH-45–46:** Open bags from Files, browse cached topics/counts/rates, seek and step through camera/cloud/depth frames, play bounded camera-video segments, change speed, and use fullscreen.
- **OMH-47–49:** Inspect timing gaps and synchronization; extract IMU/odometry series; read calibration and TF; export clips, previews, contact sheets, reports, and browsable directories. Eight agent tools and a resource reader are registered through the standard MCP client.
- **OMH-50–51:** Open `comp.json` containers to inspect component sizes, entries, headers, integrity, and sibling `storage.txt` metrics. Compatible models can also use a workspace-supplied 3D renderer.

Start with `rosbagctl probe /absolute/path/to/recording.bag` or `index`. Frame and series queries should specify a time window, such as `frame BAG TOPIC --at 10` or `series BAG TOPIC --from 10 --to 20`. Plain numeric timestamps are seconds from the bag start; use `epoch:` for absolute timestamps. The panel requests bounded windows and does not download the whole bag into the browser.

Generated artifacts default to `/tmp/omh-rosbag/<slug>/`. They are a temporary cache: automatic cleanup defaults to 12 hours or 20 GiB, while pinned directories and `latest` are retained. Pin outputs with `materialize --pin` before sharing them, and copy anything that must survive system cleanup to durable storage. Recordings are read-only. This repository contains source and synthetic test fixtures, not user recordings, cached artifacts, credentials, or session data.

The MCP tool namespace is `mcp__rosbag__`: `rosbag_index`, `rosbag_sample`, `rosbag_cloud`, `rosbag_depth`, `rosbag_series`, `rosbag_calib`, `rosbag_materialize`, and `rosbag_export`. MCP itself uses Python's standard library and launches the companion CLI in the selected Python environment.

## Compressed Gaussian model assets

The summary view works without external viewer assets. Interactive 3D rendering requires a compatible `fluxgs_web` directory in the session workspace containing:

```text
fluxgs_web/render_shared/main.js
fluxgs_web/render_shared/viewer.css
fluxgs_web/tools/tmc3.js
fluxgs_web/tools/tmc3.wasm
```

The viewer downloads the full model and decoder assets. Renderer code runs in an opaque-origin sandboxed iframe, with network fetches and access to the application origin blocked. Only use renderer assets you intend to give access to the model bytes. The assets are not bundled here; missing or incompatible assets leave the summary available with a viewer error. See [viewer details](plugins/dsh-client-ui-comp-json-preview/README.md).

## Validation and license

See [TESTING.md](TESTING.md) for Node, Python, protocol, and browser checks, and [FEATURES.md](FEATURES.md) for the checklist mapping. Source is extracted from the OMH overlay and its ROS companion. MIT; see [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).