The Donut Of Great Rotation docs

A real-time C++ engine that renders 3D ASCII graphics. Projects a spinning mathematical torus directly onto the terminal screen using perspective projection, depth z-buffering, dynamic terminal window detection, and surface luminance calculations.

Overview

Inspired by Andy Sloane’s mathematical donut, this C++ implementation enhances the classic algorithm with dynamic terminal dimension query (ioctl), color palette mapping, and modern C++ memory structures (std::vector). It runs at steady frame rates in any POSIX terminal without external graphics dependencies.

Mathematical Mechanics

The engine generates and animates the 3D donut through three consecutive mathematical transformations:

Torus Surface Parameterization: A circle of radius $R_1$ is rotated around an axis at distance $R_2$ using cross-sectional angle $\theta$ and rotational sweep angle $\phi$: $$\begin{pmatrix} x \ y \ z \end{pmatrix} = \begin{pmatrix} (R_2 + R_1 \cos\theta)\cos\phi \ (R_2 + R_1 \cos\theta)\sin\phi \ R_1 \sin\theta \end{pmatrix}$$
3D Frame Rotation: The coordinates are rotated simultaneously in 3D space along two perpendicular axes using rotation angles $A$ and $B$.
Perspective Projection and Z-Buffering: Points in $(x, y, z)$ space are mapped to terminal screen coordinates $(x’, y’)$ using perspective division by $(z + K_2)$. A depth buffer array tracks the inverse depth ($1/z$) for every character cell to discard occluded background surfaces.
Surface Normal and Lighting: Calculates the dot product between the surface normal vector and an overhead light vector $(0, 1, -1)$. The resulting intensity index selects an ASCII character from the luminance ramp:
```
.,-~:;=!*#$@
```

Key Features

Dynamic Terminal Geometry: Queries terminal dimensions on launch via sys/ioctl.h (TIOCGWINSZ) to scale aspect ratio and center the rendering window.
Double Buffering: Uses separate character output and depth buffers to prevent tearing and flickering.
ANSI Terminal Escapes: Uses cursor reset escapes (\x1b[H) for smooth in-place frame animation.
Zero External Dependencies: Pure standard C++ (<iostream>, <cmath>, <vector>).

Requirements

C++ compiler supporting C++11 or newer (g++, clang++)
POSIX terminal with ANSI support (macOS Terminal, Ghostty, iTerm2, Alacritty, Linux console)

Compilation

Compile using standard optimization:

g++ -std=c++17 -O3 Donut.cpp -o Donut

On macOS with Clang:

clang++ -std=c++17 -O3 Donut.cpp -o Donut

Usage

Run the executable in your terminal:

./Donut

To stop execution, press Ctrl+C.

Project Status

Stable and complete. Demonstrates fundamentals of 3D computer graphics, matrix rotations, and terminal rasterization.

Authors and Acknowledgment

Implemented by Adam Anwar. Mathematical framework based on Andy Sloane’s 3D ASCII torus formulation.

License

MIT License.

Support

Submit issues, questions, or bug reports to the GitHub issue tracker: https://github.com/ADM1SH/the-donut-of-great-rotation/issues

Roadmap

Done: Core architecture and baseline implementation.
Done: Functional verification and test coverage.
To do: Add interactive rotation control via arrow keys
To do: Implement color illumination shading via ANSI escape sequences

Contributing

Contributions are welcome.

Fork the repository.
Create a feature branch: git checkout -b feature/improvement.
Commit your changes: git commit -m "feat: enhance functionality".
Push to the branch: git push origin feature/improvement.
Open a Pull Request.