User Guide

This guide describes how to interact with the Biologger Simulation in NVIDIA Omniverse. The extension provides a high-fidelity digital twin environment for visualizing animal movement, sensor fusion accuracy, and behavioral patterns.

Coordinate Systems & Conventions

For users coming from marine science, robotics, or hydrography fields, it is important to note the difference in coordinate conventions between typical oceanographic data and the 3D visualization environment.

Marine Science Standard (NED)

Oceanographic data (e.g., from biologging tags) typically uses the NED (North-East-Down) convention: * X: North * Y: East * Z: Down (Depth) * Heading: Clockwise from North (0° = North, 90° = East)

Visualization Standard (USD Y-Up)

NVIDIA Omniverse and the underlying USD (Universal Scene Description) format use a Y-Up, Right-Handed convention: * Y: Up (Altitude) * -Z: Forward (North) * X: Right (East) * Rotation: Counter-Clockwise (Right-Hand Rule)

Automatic Conversion

The biologger-sim extension automatically handles the re-projection of data to ensure visuals match physical reality:

  1. Heading Negation: The clockwise compass heading (N→E→S→W) is negated to match the counter-clockwise rotation convention of USD’s right-hand rule. A NED heading of +90° (East) becomes -90° in USD, correctly pointing the forward vector toward +X.

  2. Euler-to-Quaternion Mapping:

    • Sensor Pitch (Nose Up/Down) → Rotation around X-Axis

    • Sensor Heading (Compass) → Rotation around Y-Axis (negated)

    • Sensor Roll (Bank Left/Right) → Rotation around -Z-Axis

  3. Rotation Application Order: Yaw (Heading) → Pitch → Roll, matching standard aerospace/marine conventions.

Mesh Orientation & Transform Stack

Animal mesh assets (GLB/USD) are typically authored with an arbitrary “up” direction. The extension applies a spawn rotation to align the mesh with USD conventions before telemetry rotations are applied.

Example: Shark GLB Asset

The shark mesh is authored with its nose pointing along +Y (upward in its native coordinate frame). To align it with USD’s -Z = Forward convention:

  • Spawn Rotation: (-90°, 180°, 0°) XYZ Euler

  • This maps the mesh’s +Y nose to world -Z (North)

Critical: USD XformOp Order

USD applies transform operations in the order they appear in the xformOpOrder attribute. For correct world-space heading rotation, the telemetry orientation must be applied BEFORE the spawn rotation in the op list:

xformOpOrder = ["xformOp:translate", "xformOp:orient:telemetry", "xformOp:rotateXYZ", "xformOp:scale"]

This produces the transform: v_world = telemetry × spawn × v_local

  1. Spawn maps mesh-local nose (+Y) to world -Z

  2. Telemetry then rotates around world Y-axis, correctly affecting the -Z forward direction

Warning

Common Pitfall: If the spawn rotation appears BEFORE telemetry in the op order, telemetry rotations are applied in mesh-local space. Since the mesh nose is along the local Y-axis, a Y-rotation (heading) would rotate around the nose itself—having no visible effect on heading direction.

Warning

For Asset Creators: Ensure your animal models are oriented to face -Z (Forward) in their bind pose, OR document the required spawn rotation. If an asset faces +Z or +X, it will appear to “drift” sideways or backwards relative to the trajectory.

Features Overview

The visualization toolkit includes:

  • Real-time Telemetry HUD: Heads-up display for sensor metrics.

  • Flexible Tracking Modes: Toggle between full position tracking or orientation-only analysis.

  • Cinematic Camera: Smooth follow camera with user-controllable orbit.

  • Instant Replay (Time Travel): Pause and rewind live simulations without losing data.

  • Infinite Track: Full trajectory remains visible during scrubbing, with future path “ghosted”.

Telemetry Display (HUD)

The Heads-Up Display overlays critical sensor data directly in the viewport, allowing for immediate validation of the pipeline’s output.

  • Status Indicators: Shows connection health and data rate.

  • Sensor Metrics: Real-time display of Pitch, Roll, Heading, and Depth.

  • System Diagnostics: Latency counters and processing frame times.

Note

The HUD can be toggled on/off to capture clean screenshots or video recordings.

Tracking & Visualization Modes

The extension supports different visualization strategies depending on your analysis needs:

1. Full Position Tracking (Default)

In this mode, the animal moves through the virtual ocean based on the Dead Reckoned path calculated by the pipeline.

  • Best for: Analyzing large-scale movements, foraging patterns, and depth profiles.

  • Visuals: A 3D trajectory line (“Infinite Track”) is drawn behind the animal, visualizing the path taken.

2. Orientation-Only Mode

This mode locks the animal’s position to the center of the world (0,0,0) while applying real-time rotation updates.

  • Best for: Debugging IMU sensor fusion (AHRS), validating attachment angles, and inspecting fine-scale body motion without the distraction of translation.

  • Usage: Uncheck “Enable Position Tracking” in the extension UI.

Camera Controls

The system features a custom camera controller designed for tracking fast-moving marine animals.

  • Follow Camera: Automatically keeps the animal in frame, smoothing out jittery motions to provide a cinematic view.

  • Orbital Control: While the camera follows the animal, you can orbit around it to view movement from any angle. * Left Click + Drag: Orbit/Rotate camera. * Scroll Wheel: Zoom in/out. * Middle Click: Pan.

Time Control & Analysis (Instant Replay)

The Instant Replay system allows you to pause, rewind, and scrub through the visualization in real-time, decoupling the View Time from the Simulation Time.

Simulation Mode (Real-Time)

  • Live Behavior: The viewport tracks the latest data (“Live Head”).

  • Pause/Rewind: You can pause the view or scrub backward to inspect an anomaly while the simulator continues to record data in the background.

  • Ghost Path: When you scrub backward, the full trajectory remains visible. The “future” path (relative to your playback head) is rendered as a semi-transparent “ghost” line, maintaining context of where the animal eventually goes.

Lab Mode (Post-Facto)

  • Full Access: In post-hoc analysis, the entire dataset is buffered, allowing instant random access to any point in the dive duration.

Configuration

The system is configured at two levels: the Simulation Publisher (YAML) and the Omniverse Subscriber (.kit files).

Omniverse Launch Configurations (.kit)

You can pass specific configuration files to the Omniverse extension using the launch command. These files allow you to pre-set backends, safe modes, and other performance settings without manually toggling them in the UI.

# Launch with standard CPU backend
./repo.bat launch omniverse/apps/config_single_shark.kit

# Launch with GPU-accelerated Warp backend for multiple entities
./repo.bat launch omniverse/apps/config_multi_entity.kit

Example Kit Configurations:

  • config_single_shark.kit: Optimized for single-asset analysis using the CPU backend.

  • config_multi_entity.kit: Enables the NVIDIA Warp backend for high-performance tracking of multiple simultaneous entities.

Simulation Publisher (YAML)

The extension panel and command-line arguments provide access to commonly adjusted settings:

  • Animal Asset: Switch between supported assets (Shark, Swordfish, etc.) via --/biologger/animal=<type>.

  • Backend Selection: Choose the processing engine for coordinate transforms and physics updates. * --/biologger/backend=cpu (Default): Standard Python-based logic. * --/biologger/backend=warp: GPU-accelerated processing via NVIDIA Warp kernels.

  • Buffer Size: Configure how much history is kept in memory (Default: 100k points).

  • Visualization Options: Toggle the HUD, Trajectory Line, or Coordinate Axes.

Multi-Entity Configuration

The simulation supports multiple entities streaming simultaneously to Omniverse. This is configured via the entities list in the simulation section of your YAML configuration.

simulation:
  playback_speed: 1.0  # Real-time multiplier
  entities:
    - sim_id: shark_ahrs_v1
      tag_id: RED001
      sampling_rate_hz: 16.0
      input_file: "datasets/shark_data.csv"
    - sim_id: shark_causal_v1
      tag_id: RED001
      sampling_rate_hz: 16.0
      input_file: "datasets/shark_data.csv"
  loop: true

Key Configuration Fields:

  • sim_id: A unique descriptive handle for the simulation view (e.g., sword_r_exact). Used for labeling and ZMQ topics.

  • tag_id: The biological/deployment ID (e.g., RED001). Used to lookup metadata and species in biologger_meta.csv.

  • sampling_rate_hz: The recording frequency of the source sensor data for this entity.

  • input_file: Path to the CSV or Feather data stream for this specific entity.

Backward Compatibility The system remains compatible with legacy single-file configurations. Existing configurations have been updated to use the descriptive sim_id and tag_id fields, while publication_rate_hz has been retired to ensure high-fidelity playback by default.

ZMQ Protocol (MessagePack)

The communication between the simulator and the Omniverse extension has been upgraded to MessagePack for high-efficiency binary serialization.

  • Transparency: The switch from JSON to MessagePack is handled automatically.

  • Performance: Significant reduction in packet size allows for smooth visualization of dozens of entities simultaneously.

  • Entity Mapping: The system uses a compact integer eid mapping managed by the EcosystemRegistry to identify entities over the wire.

High-Performance Scaling

For simulations requiring extreme scale (10,000+ entities), the extension supports high-performance configuration options:

  • NVIDIA Warp Acceleration: Offloads NED-to-USD transforms and “Slip Angle” calculations to the GPU. Enable via the --/biologger/backend=warp CLI argument.

  • Ecosystem Registry: A structured taxonomy (registry.json) maps diverse telemetry IDs to specific biological and mechanical USD assets.

  • Fabric PointInstancer: (Beta) Utilizing USDRT Fabric and UsdGeom.PointInstancer for low-latency updates to massive schools of animals.