Metadata-Version: 2.4
Name: ros-trviz
Version: 0.1.0
Summary: Terminal RViz for ROS 2 - Lightweight TUI Navigation and Visualization Tool
Author: wkqco
Maintainer: wkqco
Maintainer-email: wkqco <user@todo.todo>
License: Apache-2.0
Project-URL: Homepage, https://github.com/wkqco33/trviz
Project-URL: Repository, https://github.com/wkqco33/trviz.git
Project-URL: Issues, https://github.com/wkqco33/trviz/issues
Description-Content-Type: text/markdown
Requires-Dist: setuptools
Requires-Dist: textual>=0.40.0
Requires-Dist: rich>=13.0.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: wpycli>=0.3.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: maintainer

# TRViz (Terminal RViz for ROS 2)

<p align="center">
  <b>Lightweight Terminal/TUI 2D Navigation & Visualization Workstation for ROS 2</b><br>
  <i>Designed for Headless Robots, Remote SSH Sessions, and Embedded Platforms</i>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
  <a href="AGENTS.md"><img src="https://img.shields.io/badge/TDD-Enforced-success.svg" alt="TDD"></a>
  <a href="https://github.com/wkqco33/trviz"><img src="https://img.shields.io/badge/ROS_2-Jazzy%20%7C%20Humble-orange.svg" alt="ROS 2"></a>
</p>

---

## 🌟 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:

```bash
# 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`

```bash
# 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
```bash
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`)
```bash
source /opt/ros/jazzy/setup.bash
source install/setup.bash
ros2 run trviz_cpp trviz
```

---

## ⌨️ Controls & Keybindings

| Key / Mouse | Action | Description |
| :--- | :--- | :--- |
| `P` | **Set Initial Pose** | Step 1: Click map position $\to$ Step 2: Click to set Heading (`/initialpose`) |
| `G` | **Set 2D Nav Goal** | Step 1: Click map target $\to$ Step 2: Click to set Goal Heading (`/goal_pose`) |
| `Esc` | **Cancel Interaction** | Return to Normal mode |
| `F` | **Toggle Follow** | Automatically keep viewport centered on robot |
| `+` / `-` (or Mouse Wheel) | **Zoom In / Out** | Scale viewport |
| `W`, `A`, `S`, `D` (or Mouse Drag) | **Pan Viewport** | Move map view |
| `T` | **Teleop Mode** | Use WASD/arrows to publish `/cmd_vel` |
| `Space` / `X` | **Emergency Stop** | Publish zero velocity while in Teleop mode |
| `1` | **Toggle Map Layer** | Show / Hide OccupancyGrid map |
| `2` | **Toggle Laser Layer** | Show / Hide LiDAR point cloud |
| `3` | **Toggle Path Layer** | Show / Hide Navigation planned path |
| `4` | **Toggle PointCloud Layer** | Show / Hide 3D PointCloud2 BEV projection |
| `Q` | **Quit** | Exit TRViz |

---

## 📂 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:
```bash
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](LICENSE) file for details.
