FGC Pose Visualizer

A real-time, multi-source 2D visualization tool designed for robotics teams (like FGC) to monitor robot pose estimations. It features a live Pygame display and a powerful web-based dashboard for easy, on-the-fly configuration.

This tool helps teams diagnose and tune their localization systems by visually comparing data from different sources (odometry, vision, fused filters) in real-time.

Key Features

• Real-Time Visualization: A smooth Pygame interface displays the robot's position and orientation on a configurable 2D field map.
• Multi-Source Support: Simultaneously render poses from different sources like encoder, vision, and fused to compare their accuracy.
• Interactive Goal Sending: Left-click on the field to send target coordinates (goals) to your robot over UDP.
• Web Configuration Dashboard: A built-in web server provides an easy-to-use dashboard to configure all settings—no code changes required.
• Hot-Reloading: Update certain settings (like robot dimensions) in the web dashboard and press R in the visualizer to see them applied instantly.
• JSON Field Mapping: Easily define your field, obstacles, and AprilTags using a simple JSON file.
• Modular & Extensible: The project is structured into logical modules, making it easy to understand, maintain, and extend.

Project Structure

The project is organized for clarity and scalability:

TeamMexico_PoseVisualizer/  
├── config.ini          \# Main configuration for networking, visuals, etc.  
├── main.py             \# Single entry point to launch both the visualizer and dashboard.  
├── field_fgc.json      \# Defines the field layout, obstacles, and tags.  
├── requirements.txt    \# Project dependencies.  
├── web/                \# Contains the Flask web dashboard files.  
│   └── templates/  
│       └── dashboard.html  
└── src/                \# All core application logic.  
    ├── visualizer.py  
    ├── config_loader.py  
    ├── networking.py  
    ├── models.py  
    └── geometry_utils.py

Getting Started

Prerequisites

• Python 3.8 or newer.
• pip for installing packages.

Installation

1. Clone the repository:

   git clone https://github.com/TeamCerbotics4400/TeamMexico_PoseVisualizer.git
   cd TeamMexico_PoseVisualizer

2. Create and activate a virtual environment (recommended):

   # For macOS/Linux  
   python3 -m venv venv  
   source venv/bin/activate

   # For Windows  
   python -m venv venv  
   .\venv\Scripts\activate

3. Install the required dependencies:

   pip install -r requirements.txt

Running the Application

Launch both the visualizer and the web dashboard with a single command:

python main.py

This will:

1. Start the web server in the background.
2. Automatically open the configuration dashboard in your default web browser.
3. Launch the Pygame visualizer window.

How to Use

Visualizer Controls

• Left Mouse Click: Send a goal coordinate to the robot's IP (configured in config.ini).
• Right Mouse Click: Clear all goal markers from the screen and send a clear command.
• TAB Key: Clear all pose trails and goal markers from the screen.
• R Key: Hot-reload settings from config.ini (e.g., robot dimensions).
• ESC Key: Close the application.

Web Dashboard

The web dashboard, available at http://127.0.0.1:5000, is the primary way to configure the application.

• Modify any value in the provided fields.
• Click "Save Changes".
• The config.ini file will be updated instantly.
• Press R in the visualizer to apply compatible changes without a restart.

Configuration (config.ini)

This file holds all the startup settings for the application.

Section	Key	Description
Application	field_json_path	Path to the JSON file that defines the field layout.
Network	receiver_host	IP address for the visualizer to listen on (0.0.0.0 for all).
	receiver_port	Port for receiving pose data from the robot.
	sender_destination_ip	The robot's IP address to send goals to.
	sender_destination_port	The robot's port for receiving goals.
Visualizer	screen_width / height	Dimensions of the Pygame window in pixels.
	robot_length_m / width_m	Dimensions of the robot in meters for accurate drawing.

UDP Message Format

To send pose data to the visualizer, your robot should broadcast JSON messages over UDP in the following format:

{  
  "src": "encoder",  
  "x_m": 1.5,  
  "y_m": 2.3,  
  "th_rad": 0.785,  
  "stamp": 1665346800.123  
}

• src: The source of the pose (encoder, vision, fused). Must match a key in the source_colors dictionary in visualizer.py.
• x_m, y_m: Position in meters.
• th_rad: Heading in radians.
• stamp: Unix timestamp (optional, used for calculating data age).

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.