3d-ascii-viewer

Display a model

$ 3d-ascii-viewer [path/to/model].obj

$ 3d-ascii-viewer -w [width] -h [height] [path/to/model].obj

$ 3d-ascii-viewer --color [path/to/model].obj

$ 3d-ascii-viewer -f [fps] [path/to/model].obj

$ 3d-ascii-viewer --interactive [path/to/model].obj

$ 3d-ascii-viewer --help

3d-ascii-viewer [options] <model.obj>

-h, --help
    Show help and exit

-s <float>, --scale <float>
    Model scale factor (default: 1.0)

-w <int>, --width <int>
    Output width in chars (default: 80)

-f <float>, --fov <float>
    Field of view angle (default: 1.1)

-l <x> <y> <z>, --light <x> <y> <z>
    Light source position (default: 0 0 1)

-m, --mouse
    Enable mouse drag rotation

-r, --reverse
    Reverse mouse Y-axis

-c, --color
    Enable ANSI color shading

-d, --debug
    Display debug info

3d-ascii-viewer is a lightweight, command-line tool for rendering interactive 3D models from OBJ files using ASCII art in any terminal. It supports smooth 60 FPS rotation and viewing with keyboard (WASD/arrows) or mouse controls, making it ideal for quick model previews without graphical dependencies.

Users can adjust model scale, viewer width, field of view, and lighting position via options. Features include optional ANSI color shading for depth, mouse event support in compatible terminals (e.g., xterm, kitty), and debug overlays for troubleshooting. The tool auto-centers and scales models to fit the terminal, handling both simple meshes and complex scenes efficiently.

Perfect for developers testing OBJ exports, retro computing enthusiasts, or SSH sessions where GUI tools fail. No runtime dependencies after compilation; written in portable C for broad Linux compatibility. Example: 3d-ascii-viewer model.obj launches an animated, rotatable view instantly.

Needs valid OBJ file (no textures/materials). Complex models may slow on small terminals. Mouse requires TERM supporting events (e.g., xterm). Resizes poorly if terminal changes size mid-run.

WASD/arrows: rotate view.
Mouse drag: rotate (with -m).
q/Esc: quit.
r: reset view.

git clone https://github.com/ldecheris/3d-ascii-viewer.git
cd 3d-ascii-viewer
make && sudo make install

Created by ldecheris; GitHub repo launched 2023. Evolved from ASCII 3D experiments for high-perf terminal rendering in C.

aa3d(6), aview(1), jp2a(1)