objcurses: A Minimalistic 3D Object Viewer for Your Terminal

Introduction

objcurses is a minimalistic 3D object viewer designed to run directly in your terminal. Utilizing ncurses, it renders .obj models in real-time using ASCII characters and a simple, custom-built rendering pipeline. Developed from scratch in modern C++20, objcurses showcases up-to-date best practices and a clean, modular design, serving as a personal exploration into low-level graphics programming without relying on external graphic engines or frameworks.

Key features include real-time camera and directional light control, basic color support from .mtl material files, and the ability to start animations with consistent auto-rotation. It also provides a HUD overlay for additional statistics and boasts minimal dependencies, primarily C/C++, ncurses, and math libraries.

Installation

The latest release of objcurses is available on the GitHub releases page. Remember to replace <version> with the actual release version, for example, 1.2.3.

Manual (Build from Source)

To manually compile and install objcurses, follow these steps:

Install Dependencies

Ensure you have CMake and a C++ compiler installed:

sudo apt update
sudo apt install cmake g++ libncurses6 libtinfo6 -y

Clone the Repository

git clone https://github.com/admtrv/objcurses
cd objcurses

Compile the Program

mkdir cmake-build-release
cd cmake-build-release
cmake ..
make

Install for Global Use (optional)

sudo make install

From .tar.gz

To install objcurses from a binary archive:

tar -xzvf objcurses-<version>-linux.tar.gz
cd objcurses-<version>-linux
sudo mv objcurses /usr/local/bin/
sudo chmod +x /usr/local/bin/objcurses

From .deb

For Debian-based distributions (Ubuntu, Mint, etc.), use:

sudo dpkg -i objcurses-<version>-linux.deb

To uninstall:

sudo dpkg -r objcurses

Verify Installation

which objcurses
objcurses --help

You should now be able to use objcurses from anywhere in your terminal.

Examples

Usage

objcurses [OPTIONS] <file.obj>

Options

-c, --color <theme>  Enable colors support, optional theme {dark|light|transparent}
-l, --light          Disable light rotation
-a, --animate <deg>  Start with animated object, optional speed [default: 30.0 deg/s]
-z, --zoom <x>       Provide initial zoom [default: 1.0 x]
    --flip           Flip faces winding order
    --invert-x       Flip geometry along X axis
    --invert-y       Flip geometry along Y axis
    --invert-z       Flip geometry along Z axis
-h, --help           Print help
-v, --version        Print version

Examples:

objcurses file.obj                # basic
objcurses -c file.obj             # enable colors
objcurses -c transparent file.obj # set transparent color theme
objcurses -c -a -z 1.5 file.obj   # start animation with zoom 1.5 x
objcurses -c -a 10 file.obj       # start animation with speed 10.0 deg/s
objcurses -c --invert-z file.obj  # flip z axis if blender model

Controls

objcurses supports arrow keys, WASD, and Vim-style navigation:

?, h, a            Rotate left
?, l, d            Rotate right
?, k, w            Rotate up
?, j, s            Rotate down
+, i               Zoom in
-, o               Zoom out
Tab                Toggle HUD
q                  Quit

Why Use It?

objcurses offers several compelling use cases for developers and enthusiasts alike:

• Preview 3D files instantly without launching heavy editors.
• Generate custom ASCII art for tools like neofetch or terminal splash screens.
• Style CLI tools or games with unique ASCII-based intros and visuals.
• Animate your coding workspace with rotating retro-style ASCII models.
• Create stylish character-based GIFs directly from terminal-rendered scenes.

Links

• GitHub Repository: https://github.com/admtrv/objcurses