Real-time 3D visualization system for hexapod robot inverse kinematics data. Connects to serial port to receive live data and displays the robot in 3D with configurable visualization options.
- Flexible serial settings: Configurable COM port and baud rate
- Robot geometry: Define leg positions and rotations in body coordinates
- Visualization options: Customizable colors, update rates, and display elements
- Multiple configurations: Supports different hexapod layouts and designs
- Serial communication: Connects to robot via configurable COM port
- Data parsing: Extracts inverse kinematics data from log format
- Performance monitoring: FPS tracking and data rate statistics
- Buffering: Smooth animation despite irregular data timing
- Interactive 3D display: Real-time matplotlib-based visualization
- Multiple view modes: Toggle body, legs, and coordinate axes
- Mouse controls: Rotate view by dragging, zoom with scroll wheel
- Keyboard shortcuts: Quick access to display options and view reset
- Joint chain rendering: Visualizes coxa, femur, tibia segments with angle annotations
- Simulated patterns: Test visualization without robot connection
- Tripod gait: Realistic walking pattern simulation
- Wave motion: Smooth wave-like movement demonstration
-
Clone the repository:
git clone <repository-url> cd hexapod_visualizer
-
Set up Python environment:
# Create virtual environment python -m venv .venv # Activate (Windows) .venv\Scripts\activate # Install dependencies pip install -r requirements.txt
-
Configure your robot:
- Edit
config.yamlto match your hexapod layout - Set correct COM port and baud rate
- Adjust leg positions and rotations
- Edit
# Connect to robot and visualize real-time data
python serial_reader.py # Text-based parser only
python visualizer.py # 3D visualization# Test with simulated movement patterns
python demo.pyserial:
port: "COM5" # Serial port
baudrate: 115200 # Baud rate
timeout: 1.0 # Read timeoutrobot:
body:
length: 0.200 # Body dimensions (meters)
width: 0.150
height: 0.050
legs:
0: # Leg 0 configuration
name: "Left Front"
position: [0.075, 0.075, 0.0] # Attachment point [x,y,z]
rotation: 0.7854 # Rotation from X-axis (radians)
link_lengths: [0.068, 0.088, 0.127] # [coxa, femur, tibia] lengths (m)
joint_angle_offsets: [0.0, 0.5396943301595464, 1.0160719600939494] # Calibration offsets (radians)visualization:
update_rate: 60 # Target FPS
buffer_size: 100 # Data buffer size
show_body: true # Display body outline
show_legs: true # Display leg positions
show_coordinates: true # Display coordinate axes
show_joints: true # Draw articulated joint chain
show_joint_angles: true # Annotate joint angles (C/F/T)
show_joint_coords: false # Annotate each joint endpoint (x,y,z)
show_target_coords: false # Annotate foot/target point (x,y,z)
show_leg_origin_coords: false # Annotate each leg attachment origin (x,y,z)
colors: # RGB colors (0-255)
body: [100, 100, 100]
legs: [50, 150, 200]
coordinates: [255, 0, 0]
joints: [255, 215, 0]- R: Reset view to default angle
- T: Toggle body outline display
- L: Toggle leg display
- C: Toggle coordinate axes display
- H: Show help information
- ESC/Q: Quit application
- Drag: Rotate 3D view
- Scroll: Zoom in/out
- Right-click: Context menu (matplotlib default)
The system parses inverse kinematics log data in the following format:
I (39868) wbc: (39599638)Leg 0 IK: BodyXYZ(0.106, 0.280, -0.043) -> LegXYZ(0.230, -0.026, -0.043) -> LegAng(-0.112, 0.025, 0.768)
Where:
39599638: Robot timestamp (microseconds)Leg 0: Leg index (0-5)BodyXYZ: 3D position in body coordinates (meters)LegXYZ: 3D position in leg coordinates (meters)LegAng: Servo angles (radians)
Each leg reports raw servo angles: (coxa, femur, tibia) in radians. These are adjusted by joint_angle_offsets from the configuration to account for mechanical zero calibration:
effective_angle = raw_angle - offset # Offsets represent mechanical zero bias
The visualized chain uses these effective angles. If only two link_lengths are provided, the system assumes a zero-length coxa for backward compatibility.
- X-axis: Forward direction
- Y-axis: Left side (positive)
- Z-axis: Upward (positive)
0(L-Front) 3(R-Front)
1(L-Mid) 4(R-Mid)
2(L-Back) 5(R-Back)
hexapod_visualizer/
├── main.py # Serial reader and parser
├── visualizer.py # 3D visualization system
├── demo.py # Demo mode with simulated patterns
├── config_loader.py # Configuration management
├── config.yaml # Main configuration file
├── config_example_*.yaml # Example configurations
├── test_*.py # Test scripts
├── pyproject.toml # Project dependencies
└── README.md # This file
- Python 3.12+: Modern Python with type hints
- matplotlib: 3D plotting and visualization
- numpy: Mathematical operations and arrays
- pyserial: Serial port communication
- pydantic: Configuration validation
- PyYAML: YAML configuration file parsing
- Real-time capable: Handles ~100Hz data updates
- Configurable frame rate: 1-120 FPS visualization
- Efficient rendering: Optimized for smooth animation
- Memory management: Bounded data buffers
- Verify COM port in Device Manager (Windows)
- Check baud rate matches robot settings
- Ensure no other programs are using the port
- Try different timeout values
- Lower
update_ratein configuration - Reduce
buffer_sizefor less memory usage - Disable elements (body/legs/coordinates) if not needed
- Close other heavy applications
- Validate YAML syntax
- Check all 6 legs are defined (0-5)
- Verify numeric values are valid
- Use test scripts to validate configuration
- Follow existing code patterns
- Add configuration options to schema
- Update validation in
config_loader.py - Test with both live and demo data
python test_config.py # Test configuration loading
python test_parser.py # Test data parsing
python demo.py # Test visualization