Supported Braille Models

Relevant source files

The following files were used as context for generating this wiki page:

• BRAILLE.md
• src/config.rs
• src/plotter.rs
• crates/ratatui-wireframe/src/widget.rs
• crates/ratatui-wireframe/README.md
• README.md

ComChan includes a 3D Telemetry dashboard that utilizes a zero-dependency CPU-rendered Braille wireframe engine. This engine allows users to visualize spatial data such as Pitch, Yaw, and Roll using terminal Braille characters when hardware acceleration (via the ratty feature) is not active. The system supports various built-in geometric primitives and the ability to load custom models at runtime.

The Braille models are integrated into the plotter mode, providing real-time visual feedback for IMU telemetry. The engine projects 3D space into the 2D terminal grid using mathematical transformations, including rotation matrices and perspective projection.

Sources: BRAILLE.md:3-6, crates/ratatui-wireframe/README.md:10-12, src/plotter.rs:647-650

Core Architecture and Data Flow

The 3D rendering pipeline follows a structured path from configuration to terminal display. The user selects a model via the --braille flag, which is then managed by the PlotterState and rendered through the WireframeWidget.

Rendering Pipeline Logic

1. Selection: The BrailleModel enum determines whether a built-in shape or a custom file path is used.
2. Transformation: The WireframeWidget applies standard rotation matrices based on pitch, yaw, and roll inputs (converted to radians).
3. Projection: A perspective projection is applied (defaulting to a distance of 5.0 and scale of 8.0) to create depth.
4. Rasterization: The widget utilizes the ratatui::widgets::canvas::Canvas with a Braille marker to draw lines.

Sources: crates/ratatui-wireframe/src/widget.rs:56-118, src/config.rs:20-25, crates/ratatui-wireframe/README.md:46-52

Model Transformation Flow

The following diagram illustrates how 3D telemetry data is processed into a Braille visual:

The system uses a "Shortest Path Lerp" to prevent backward spinning during 360-degree wrap-around of Euler angles.
Sources: src/plotter.rs:429-446, crates/ratatui-wireframe/src/widget.rs:59-71

Built-in Primitives

ComChan provides three primary built-in wireframe models optimized for spatial awareness in a terminal environment.

Model	Complexity	Best Use Case	Default Flag
Cube	8 Vertices, 12 Edges	General spatial awareness; Default model.	cube
Tetrahedron	4 Vertices, 6 Edges	Visualizing directional heading or drone telemetry.	tetrahedron
Octahedron	6 Vertices, 12 Edges	Highly readable feedback for complex rotations.	octahedron

Sources: BRAILLE.md:12-32, src/config.rs:88-91

Default Gnomon (Axes)

Regardless of the selected model, the WireframeWidget and the 3D Telemetry dashboard render a stationary X/Y/Z axis triad (gnomon) to provide spatial context.

• X-Axis: Red
• Y-Axis: Yellow
• Z-Axis: Light Blue

Sources: crates/ratatui-wireframe/src/widget.rs:125-155, src/plotter.rs:567-610

Custom Models and File Formats

ComChan supports two methods for loading external 3D models, depending on the enabled features and file formats.

.wrfm Format

The .wrfm format is a simple, human-readable text format for defining vertices and edges. It is the primary way to load custom shapes into the standard Braille engine.

• Usage: comchan --plot --braille my_drone.wrfm
• Implementation: Handled via the wrfm crate. The Model::from_wrfm function converts parsed data into the internal Model structure.

Sources: BRAILLE.md:34-44, src/plotter.rs:252-256, crates/ratatui-wireframe/README.md:40-44

.obj Format (Ratty Feature)

When ComChan is compiled with the ratty feature, it can natively parse standard 3D .obj files.

• Hardware Acceleration: If the terminal program is ratty, ComChan uses GPU-accelerated rendering.
• Fallback: If not in a ratty terminal, the engine attempts to render the .obj file using the CPU Braille engine.

Sources: src/plotter.rs:232-249, crates/ratatui-wireframe/README.md:13-19

Configuration and CLI Usage

Selection of the model is managed through the BrailleModel type in the configuration suite.

// src/config.rs:20-25
#[derive(Clone, Debug, PartialEq)]
pub enum BrailleModel {
    Cube,
    Tetrahedron,
    Octahedron,
    Custom(String), // This holds the path to your .wrfm file!
}

CLI Command Summary

To launch the plotter with a specific model:

# Using a built-in model
comchan --plot --auto --braille tetrahedron

# Using a custom wireframe file
comchan --plot --auto --braille aircraft.wrfm

Sources: BRAILLE.md:23, BRAILLE.md:40, src/config.rs:223-228

Summary

The "Supported Braille Models" system in ComChan provides a versatile way to visualize 3D telemetry without specialized hardware. By combining built-in geometric primitives with a modular custom loader for .wrfm and .obj files, the project ensures that spatial orientation data is accessible across diverse terminal environments. The use of the Braille character set allows for relatively high-resolution wireframe rendering within the constraints of a standard text-based interface.