TRViz (Terminal RViz for ROS 2)

Lightweight Terminal/TUI 2D Navigation & Visualization Workstation for ROS 2
Designed for Headless Robots, Remote SSH Sessions, and Embedded Platforms

🌟 Key Features

• Terminal 2D Map Visualization: OccupancyGrid (/map) rendering with aspect-ratio correction and rotated map-origin support.
• Interactive 2D Pose Estimate (/initialpose): Set robot initial position & heading directly from the terminal without typing quaternions manually!
• Interactive 2D Nav Goal (/goal_pose): Click/drag to dispatch Nav2 goals directly inside your SSH session.
• Live TF & Sensor Overlay: Real-time robot pose tracking (/tf), LiDAR points (/scan), point clouds (/points), and frame-aware navigation paths (/plan).
• Interactive Viewport: Smooth zoom (+/-), pan (WASD or mouse drag), and auto-follow robot mode (F).
• Standalone Mock Simulation: Built-in simulator (ros2 run trviz mock_sim) for testing without a physical robot or Gazebo.

⚡ Instant One-Line Remote Execution (with uvx)

No workspace build or manual source setup required! Run TRViz directly on your robot or workstation:

# 1. Run directly from GitHub repository over SSH
uvx --from git+https://github.com/wkqco33/trviz.git#subdirectory=src/trviz_py trviz

# 2. Or run locally from workspace source
uvx --from ./src/trviz_py trviz

# 3. Built-in subcommands (powered by wpycli)
uvx --from ./src/trviz_py trviz doctor             # Diagnose ROS 2 & terminal environment
uvx --from ./src/trviz_py trviz mock               # Run synthetic simulation node
uvx --from ./src/trviz_py trviz replay path/log.jsonl # Replay recorded state
uvx --from ./src/trviz_py trviz completion bash    # Generate shell auto-completion

Smart ROS Auto-Discovery: Even if you haven't run source /opt/ros/<distro>/setup.bash, TRViz automatically discovers installed ROS 2 distributions under /opt/ros/ and configures the environment transparently.

📦 Traditional Installation & Build (ROS 2 Workspace)

Prerequisites

• ROS 2 (Jazzy, Humble, Iron, etc.)
• Python 3.10+
• textual, rich, numpy, pyyaml, wpycli

# 1. Build the workspace
cd /home/wkqco/Workspace/ros/trviz
source /opt/ros/jazzy/setup.bash
colcon build --symlink-install
source install/setup.bash

🚀 Quick Start Guide

Launch Python Version

source /opt/ros/jazzy/setup.bash
source install/setup.bash
ros2 run trviz trviz
# Or use the new CLI directly:
trviz run --render-mode half

Launch High-Performance C++ Version (trviz_cpp)

source /opt/ros/jazzy/setup.bash
source install/setup.bash
ros2 run trviz_cpp trviz

⌨️ Controls & Keybindings

📂 Repository Architecture

trviz/
├── AGENTS.md                 # TDD and Developer / AI Agent Guide
├── CONTRIBUTING.md           # Contribution Guidelines
├── LICENSE                   # Apache-2.0 License
├── src/
│   ├── trviz_py/             # ROS 2 Python Package (Textual based)
│   └── trviz_cpp/            # ROS 2 C++ Package (Native High-Performance TUI)
│       ├── include/trviz/    # Core math, terminal driver, visual layers, widgets, ROS node
│       ├── src/              # Implementations
│       └── test/             # GTest TDD Test Suite

🧪 Testing & TDD

Run the full automated test suites:

cd /home/wkqco/Workspace/ros/trviz
source /opt/ros/jazzy/setup.bash
colcon build
colcon test
colcon test-result --all

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.