tt3de 1.0.0

TT3DE: Tiny Textual 3D Engine

TinyTiny 3D Engine

A minimalistic 2D/3D engine implemented in Rust and bound to Python, designed to render 3D objects using ASCII art.

Features

• Rendering Primitives: Supports points, lines, and triangles in both 2D and 3D contexts.
• ASCII Output: Renders 3D scenes in a charming ASCII art style.
• Color Shading Support: Renders with RGB colors.
• Materials: Supports 14 materials, including:
  • Texture Mapping: Supports textures up to 256x256 pixels.
  • Double Raster: Allows the use of 2 colors per ASCII character (background and foreground).
  • Perlin Noise: Basic Perlin noise mapped texture.

Recommended Terminals :

Terminal	Windows	macOS	Linux
wez Terminal	:star: Fastest rendering accross all terms
tabby	:star: Runs ok, struggle at big resolutions
default Windows Terminal	:x: Can't keep up with the rendering
VScode terminal	:x: Does not even works	:x: Can't keep up with rendering	:x:
gostty		:star: Perfect!	:star: Perfect, assuming you have your graphics drivers installed
kitty		Almost perfect, start to slow down at HighRes	untested
iTerm/iTerm2		Won't keep up with high refresh rate (>10fps)

Setting Up the Development Version

To set up a development version of this engine:

1. Clone this repository:

   git clone <repo_url>
   

2. Install uv (if needed):

   pip install uv
   

3. Create the environment and install project + dev dependencies:

   uv sync --group dev
   

4. Compile the Rust version locally:

   uv run maturin develop --profile release
   

5. Check the demo:

   PYTHONPATH=python uv run python demos/3d/some_models.py
   

6. Run the Rust unit tests:

   cargo test
   

7. Run the Python unit tests:

   uv run pytest
   

8. Material shading threading benchmark (test_bench_material_apply): captures serial vs Rayon (1/2/4/8 threads) over several canvas sizes, writes benchmarks/material_apply.json, and prints a compact Rich KPI report (~100-column friendly). From the repository root:

   ./scripts/bench_material.sh
   

   On Windows PowerShell:

   .\scripts\bench_material.ps1
   

   The report summarizes speedup vs serial (×ser), per-thread efficiency (η/T), scaling loss vs ideal linear speedup (loss), and a throughput bar per configuration. Expect roughly one minute on a typical CPU.

   Equivalent manual invocation:

   mkdir -p benchmarks
   PYTHONPATH=python uv run pytest \
     tests/benchs/r_code/test_bench_r_pix_shader.py::test_bench_material_apply \
     --benchmark-only -q --benchmark-json=benchmarks/material_apply.json
   uv run --no-sync python scripts/dev_material_bench_report.py benchmarks/material_apply.json
   

9. Regenerate TTSL opcode/ABI files after opcode definition changes:

   bash scripts/gen_opcodes.sh
   

   On Windows PowerShell:

   powershell -ExecutionPolicy Bypass -File scripts/gen_opcodes.ps1
   

Build Documentation

From the repository root, regenerate the Sphinx HTML docs with:

uv run sphinx-build -b html source source/_build/html

For a fully clean rebuild:

rm -rf source/_build
uv run sphinx-build -b html source source/_build/html

On Windows PowerShell, use:

Remove-Item -Recurse -Force source\_build
uv run sphinx-build -b html source source/_build/html

Tips for Python Path in VSCode

Due to the mix of Python and Rust in this project, the Python code is located in the python folder. More information can be found here.

In launch.json for VSCode:

"env": {"PYTHONPATH": "${workspaceFolder}/python"}

In settings.json:

{
    "python.analysis.extraPaths": [
        "python"
    ]
}

Known Issues

• Many...