3D Spatial Telemetry Viewer
Relevant source files
The following files were used as context for generating this wiki page:
The 3D Spatial Telemetry Viewer is a specialized visualization component within ComChan designed for real-time IMU (Inertial Measurement Unit) monitoring. It allows developers to visualize orientation data—specifically Pitch, Yaw, and Roll—as a rotating 3D model directly within the terminal interface. This feature is primarily used for debugging embedded systems such as drones, robotics, or any device transmitting spatial orientation telemetry.
Sources: README.md:143-145, src/plotter.rs:649-651
System Architecture
The 3D viewer is integrated into the plotter module and operates as one of two primary tabs (the other being the 2D Line Chart). It relies on the ratatui-wireframe crate for software-based rendering and optionally leverages hardware acceleration via the ratty feature.
Component Relationship
The following diagram illustrates the relationship between the telemetry ingestion and the 3D rendering engine.
The system decodes incoming telemetry strings to find "Pitch", "Yaw", and "Roll" keys. These values are then passed through an interpolation engine to ensure smooth visual transitions between data points.
Sources: src/plotter.rs:163-182, src/plotter.rs:564-582
Rendering Engines
ComChan supports two distinct methods for displaying 3D spatial data depending on the terminal capabilities and compile-time features.
1. Braille Wireframe Engine (Software)
The default engine uses a zero-dependency CPU renderer to project 3D space into terminal Braille characters. It projects 3D vertices into a 2D coordinate system using perspective projection and draws connecting edges on a ratatui Canvas.
Sources: crates/ratatui-wireframe/README.md:11-12, crates/ratatui-wireframe/src/widget.rs:80-100
2. Ratty Graphic Engine (Hardware)
When compiled with the ratty feature and running in a compatible terminal (like Ratty), the system uses the Ratty Graphics Protocol. This allows for native .obj file rendering with higher fidelity, including depth and brightness adjustments.
Sources: src/plotter.rs:105-138, crates/ratatui-wireframe/README.md:13-15
| Feature | Braille Engine | Ratty Engine |
|---|---|---|
| Backend | CPU-based projection | GPU-accelerated (Terminal Protocol) |
| Marker | Braille Symbols | Native Pixels/Vulkan |
| Format | .wrfm, Primitives | .obj Support |
| Requirement | Standard TTY | ratty feature + Ratty Terminal |
Sources: src/plotter.rs:105-156, crates/ratatui-wireframe/README.md:11-20
Data Processing and Interpolation
To prevent "jumpy" visuals during high-latency serial communication, the viewer implements Smooth Interpolation (Lerp).
The interpolator handles Euler angle wrap-around using rem_euclid(360.0) to ensure that the model doesn't spin backward when passing the 360-degree threshold.
Sources: src/plotter.rs:564-582
Mathematical Transformation
The WireframeWidget applies standard rotation matrices for pitch, yaw, and roll:
// crates/ratatui-wireframe/src/widget.rs:64-72
let y1 = y * self.pitch.cos() - z * self.pitch.sin();
let z1 = y * self.pitch.sin() + z * self.pitch.cos();
let x2 = x * self.yaw.cos() + z1 * self.yaw.sin();
let z2 = -x * self.yaw.sin() + z1 * self.yaw.cos();
let x3 = x2 * self.roll.cos() - y1 * self.roll.sin();
let y3 = x2 * self.roll.sin() + y1 * self.roll.cos();
Supported 3D Models
The viewer supports several built-in geometric primitives and the ability to load custom models via the --braille or --obj flags.
| Model Type | File Format | Description |
|---|---|---|
| Cube | Built-in / .wrfm | 8 vertices, 12 edges. Default model for spatial awareness. |
| Tetrahedron | Built-in / .wrfm | 4 vertices, 6 edges. Triangular pyramid, useful for direction. |
| Octahedron | Built-in / .wrfm | 6 vertices, 12 edges. Diamond shape for symmetrical feedback. |
| Custom Wireframe | .wrfm | Human-readable text format for custom vertices/edges. |
| Custom Object | .obj | Standard 3D model format (requires ratty feature). |
Sources: BRAILLE.md:11-40, src/config.rs:24-40, crates/ratatui-wireframe/src/model.rs:136-160
User Interaction and Configuration
Users can interact with the 3D viewer through the keyboard or configure its behavior via CLI arguments.
Key Bindings
| Key | Action |
|---|---|
2 | Switch directly to 3D Wireframe tab |
Tab | Toggle between 2D Chart and 3D View |
Space | Pause/Resume data ingestion |
? | Open Help Modal |
Sources: src/plotter.rs:434-445, src/plotter.rs:818-825
Configuration Parameters
The spatial viewer is controlled by the following MergedConfig fields:
braille: Enum representing the model choice (Cube,Tetrahedron,Octahedron, orCustom(path)).obj_file: Path to a standard.objfile for hardware rendering.simulate: When enabled, generates a sine-wave based rotation (Pitch,Roll,Yaw) for testing.
Sources: src/config.rs:135-144, src/plotter.rs:495-505
Conclusion
The 3D Spatial Telemetry Viewer provides a high-performance, terminal-based alternative to heavy GUI-based telemetry suites. By combining software-based Braille rendering with optional GPU acceleration, it ensures compatibility across diverse terminal environments while maintaining smooth, real-time visual feedback for critical orientation data.