Spinning cube animation via very basic ray tracing on the terminal. Rendered in ASCII.
+==
++======
+============
==================
========================
+===========================..
||+=====================.......
||+=================..........
+||||===========...............
+||||||==+.....................
+||||||........................
+||||||.......................
+||||||~.......................
+||||||....................~.%
|||||...............~.
||||~..........~..
||.........
||....~
In human language, the graphics are rendered by the following algorithm:
rows <- terminal's height
columns <- terminal's width
// a face (surface) is a plane segment (x, y, z) restricted within 4 cube vertices
initialise a cube (6 faces)
for (r in rows):
for (c in columns):
z_rendered <- +inf
have_intersection <- false
pixel_to_draw <- (0, 0)
for (surface in cube's faces):
// from equation ax + by + cz + d = 0
find surface.z(c, r)
if (z < z_rendered) and ((c, r, z) in surface):
z_rendered <- z
have_intersection <- true
pixel_to_draw <- (c, r)
if (have_intersection):
draw(pixel_to_draw)
Currenctly there is no Windows support. You'll need the following Linux packages:
- ncurses
On Debian-based systems it's installed with:
apt-get install libncurses-dev
On Arch-based systems it's installed with:
pacman -S ncurses
- gcc
- make
The naming convention follows the one of stb.
Source files are found in src and headers in include.
You can compile the project with:
make
You can run the binary with (a list of command line arguments is provided in the next section):
./cube
You can delete the binary and object files with:
make clean
The Makefile includes an installation command. The binary will be installed at /usr/bin/cube as:
sudo make install
Similarly, you can uninstall it from /usr/bin as:
sudo make uninstall
On Nix (with flakes enabled) you don't need to install it and you can directly run it with:
nix run github:leonmavr/retrocube
Credits for the Nix packaging to Peter Marreck (pmarreck).
By default the program runs forever so you can stop it with Ctr+C. Below are the command line arguments it accepts.
| Short specifier | Long specifier | Argument type | Default | Description |
|---|---|---|---|---|
| -sx | --speedx | float | 0.7 | Rotational speed around the x axis (-1 to 1) |
| -sy | --speedy | float | 0.4 | Rotational speed around the y axis (-1 to 1) |
| -sz | --speedz | float | 0.6 | Rotational speed around the z axis (-1 to 1) |
| -f | --fps | int | 20 | Maximum fps at which the graphics can be rendered (lower it if high CPU usage or if flicker) |
| -r | --random | no argument | On | If disabled, rotate at constant speed around each axis. Else randomly and sinusoidally. |
| -cx | --cx | int | 0 | x-coordinate of the cube's center in pixels |
| -cy | --cy | int | 0 | y-coordinate of the cube's center in pixels |
| -cz | --cz | int | 0 | z-coordinate of the cube's center in pixels |
| -s | --size | int | 24 | Length of cube's sides in pixels |
| -mi | --maximum-iterations | int | Inf/ty | How many frames to run the program for |
Some terminal emulators have been found not to render the drawing. If so, you can switch to a working one.
| Terminal | Support |
|---|---|
| alacritty |  |
| termite |  |
| urxtv | |
| xterm | |
If everyhing works, this is what it looks like on the command line:
| random speed | constant speed |
|---|---|
 |
 |
- If the animation flickers too much, you can reduce the maximum fps. 15-20 is a relatively flicker-free range. You can do this by:
./cube -f 15or./cube --fps 15.
If you'd like to contribute, please follow the codiing guidelines (section 3.1) and make sure that it builds and runs. I'll be happy to merge new changes.
List of contributors:
- pmarreck - Nix packaging