# objcurses: A Minimalistic 3D Object Viewer for Your Terminal

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/admtrv-objcurses
Generated for open source discovery and AI-assisted research.

objcurses is a unique terminal-based 3D object viewer that renders .obj models in real-time using ncurses and ASCII characters. Built from scratch in modern C++20, it offers real-time camera and light control, basic color support, and animation capabilities. This project serves as an excellent example of low-level graphics programming without external engines.

GitHub: https://github.com/admtrv/objcurses
OSRepos URL: https://osrepos.com/repo/admtrv-objcurses

## Summary

objcurses is a unique terminal-based 3D object viewer that renders .obj models in real-time using ncurses and ASCII characters. Built from scratch in modern C++20, it offers real-time camera and light control, basic color support, and animation capabilities. This project serves as an excellent example of low-level graphics programming without external engines.

## Topics

- 3D Viewer
- Terminal Graphics
- ASCII Art
- C++
- ncurses
- Command Line Tool
- Retro Programming
- OBJ Viewer

## Repository Information

Last analyzed by OSRepos: Fri Mar 13 2026 17:08:10 GMT+0000 (Western European Standard Time)
Detail views: 2
GitHub clicks: 4

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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](https://github.com/admtrv/objcurses/releases){target="_blank"}. 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:

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


#### Clone the Repository

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


#### Compile the Program

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


#### Install for Global Use (optional)

bash
sudo make install


### From `.tar.gz`

To install `objcurses` from a binary archive:

bash
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:

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


To uninstall:

bash
sudo dpkg -r objcurses


### Verify Installation

bash
which objcurses
objcurses --help


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

## Examples

### Usage

bash
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:

bash
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](https://github.com/admtrv/objcurses){target="_blank"}