admtrv

objcurses: View 3D OBJ Models in the Terminal

objcurses is a C++20 terminal viewer that renders Wavefront OBJ models as ASCII using ncurses. It suits quick previews and retro terminal visuals, without requiring a full graphics application.

View on GitHub Compare
Stars
231
Forks
13
Stars, last 30 days
+0

Our take

Health score

16/100

How it is scored
Activity
19
Community
4
Issues
21
Pull requests
20

+0 stars in the last 30 days

  • Fewer contributors than 91% of the projects we track

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

232

Forks

13

Change since Nov 16, 2026: 0 stars·0 forks

Overview

objcurses loads Wavefront .obj models and renders them in a terminal with ASCII characters. Its lightweight rendering pipeline is intended for viewing models without launching a graphical editor or depending on a graphics engine.

The project is also useful as a learning example for low-level 3D rendering in modern C++. It includes interactive viewing controls, optional material colors, and an animation mode.

Key Features

  • Renders Wavefront .obj models in an ncurses terminal interface.
  • Supports real-time rotation and zoom through keyboard controls.
  • Reads basic color information from .mtl material files.
  • Offers optional object auto-rotation and directional-light controls.
  • Displays an optional HUD overlay.
  • Includes options to invert geometry axes and flip face winding order.

Use Cases

  • Developers can quickly inspect an OBJ model from a command line without opening a full 3D editor.
  • C++ learners can explore a from-scratch terminal renderer and its basic 3D rendering pipeline.
  • Terminal customization enthusiasts can use rendered models for retro-style visuals or terminal introductions.
  • Users troubleshooting model orientation can try the axis-inversion and face-winding options.

Getting Started

Install CMake, a C++ compiler, and ncurses, then build from the repository:

git clone https://github.com/admtrv/objcurses
cd objcurses
mkdir cmake-build-release && cd cmake-build-release
cmake .. && make
./objcurses path/to/model.obj

See the README for installation options, command-line flags, and controls.

Considerations

  • Requires a terminal with ncurses support, plus CMake and a C++ compiler to build from source.
  • The viewer is designed for Wavefront OBJ files, with basic material color support through MTL files, not as a general-purpose 3D editor.
  • Rendering uses ASCII characters, so it does not provide the visual detail or workflow of a graphical viewer.

Found this useful?

Share it with someone who would like objcurses.