Custom .wrfm and .obj Files

Relevant source files

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

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

ComChan provides a flexible 3D visualization system within its serial plotter mode, allowing developers to visualize spatial telemetry (such as IMU data) using wireframe models. The system supports three built-in primitives—Cube, Tetrahedron, and Octahedron—while offering extensive support for custom external models via the .wrfm and .obj file formats.

These models are rendered using two distinct engines depending on the terminal capabilities: a zero-dependency CPU-rendered Braille engine for standard TTYs and a hardware-accelerated engine via the ratty feature for compatible terminals like Ratty. Custom models enable precise visual feedback for specific hardware targets, such as drones or specialized sensors.

Sources: BRAILLE.md:1-7, crates/ratatui-wireframe/README.md:10-18

Model Formats and Loading

ComChan distinguishes between two primary methods for loading custom 3D data: the lightweight .wrfm format and the industry-standard .obj format.

The .wrfm Format

The .wrfm format is described as a human-readable text format for defining 3D vertices and their connecting edges. It is handled by the wrfm crate. In ComChan, these files are specifically intended for the Braille wireframe engine.

• Loading: Users provide the path to a .wrfm file via the --braille flag.
• Parsing: The project uses wrfm::WrfmModel::from_file to generate a Model instance.

Sources: BRAILLE.md:38-48, src/config.rs:36-40, src/plotter.rs:408-412

The .obj Format

Support for .obj files is typically tied to the ratty feature flag. This allows for more complex geometries and hardware-accelerated rendering.

• Loading: Users specify the path using the --obj CLI argument or the obj_file configuration field.
• Parsing: The Model::from_obj function parses standard Wavefront OBJ data, specifically extracting vertex coordinates (v) and face/line definitions (f, l).

Sources: src/config.rs:163, crates/ratatui-wireframe/src/model.rs:20-25, crates/ratatui-wireframe/README.md:52-58

Technical Architecture

The architecture for custom model processing involves the ratatui-wireframe crate, which defines the core Model structure and the WireframeWidget.

The Model Data Structure

The internal representation of a 3D object is unified into a Model struct, regardless of the source file format.

pub struct Model {
    pub vertices: Vec<(f64, f64, f64)>,
    pub edges: Vec<(usize, usize)>,
}

Sources: crates/ratatui-wireframe/src/model.rs:6-9

Model Loading Logic

The following diagram illustrates how ComChan resolves which model to use based on configuration and file extensions.

Parsing Logic and Constraints

OBJ Parsing Implementation

The Model::from_obj function implements a subset of the Wavefront OBJ specification:

1. Vertices (v): Parses three floating-point numbers representing X, Y, and Z coordinates.
2. Faces/Lines (f, l): Extracts vertex indices. Since OBJ indices are 1-based, the parser converts them to 0-based indices.
3. Edge Generation: For faces, the parser automatically creates edges between consecutive indices, including a closing edge between the last and first vertex of the face.
4. Deduplication: Edges are sorted and deduped to prevent redundant drawing calls.

Sources: crates/ratatui-wireframe/src/model.rs:35-85

Data Comparison

Feature	.wrfm	.obj
Primary Use	Braille Engine	Ratty/GPU Engine
CLI Flag	--braille <PATH>	--obj <PATH>
Parsing Source	wrfm crate	Internal Model::from_obj
Complexity	Simple Edges	Polygons and Lines
Coordinate System	0-based indices	1-based indices

Sources: src/config.rs:240-247, src/plotter.rs:400-420, crates/ratatui-wireframe/src/model.rs:55-60

Integration with Plotter State

The PlotterState struct maintains the custom_model if one is provided. During the render loop, ComChan checks if a custom model is active before falling back to built-in primitives.

Coordinate Transformation

When rendering a custom model, the WireframeWidget applies rotation for Pitch, Yaw, and Roll:

• Pitch: Rotation around the X-axis (y*cos - z*sin).
• Yaw: Rotation around the Y-axis (x*cos + z*sin).
• Roll: Rotation around the Z-axis (x*cos - y*sin).
• Projection: A perspective projection is applied using a distance constant (default 5.0) and a scale factor (8.0).

Sources: crates/ratatui-wireframe/src/widget.rs:55-85

Usage Examples

Loading a Custom Drone Model (.wrfm)

To use a custom wireframe for drone telemetry:

comchan --plot --auto --braille assets/drone.wrfm

Sources: BRAILLE.md:46

Loading a Hardware-Accelerated OBJ

To use a complex model with the ratty feature enabled:

comchan --plot --obj spaceship.obj

Sources: crates/ratatui-wireframe/README.md:52-58

Summary

The custom model system in ComChan provides a robust bridge between raw telemetry data and visual spatial context. By supporting both simple .wrfm files for text-based Braille rendering and standard .obj files for hardware-accelerated graphics, the system caters to both minimal terminal environments and modern, high-performance terminal emulators. The core parsing logic ensures that external assets are efficiently transformed into the internal Model representation for real-time 3D rotation.