TinyTracer

TinyTracer is a Python path tracer that simulates light paths to generate realistic images.

This project is part of Winter of Open Source, where contributors can improve the engine, add materials, implement new shapes, optimize performance etc.

Table of Contents

• Installation
• Demo Images
• Usage
• How to Contribute
• Code of Conduct
• References

Demo Images

Some demos may look noisy due to low sampling for faster renders.

Features

Implemented so far:

• Sphere and Quadrilateral geometry
• Four material types: Lambertian, Metal, Dielectric, Emissive
• Multiprocessing for faster rendering
• Basic caching optimizations

Installation

git clone https://github.com/datavorous/tinytracer.git
cd tinytracer

python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows

pip install -e .
pip install uv pytest

The generated image will be in .ppm format, inside the output folder.

Usage

Run the TinyTracer renderer using uv:

uv run tinytracer/main.py

Advanced controls:

uv run main.py [-help] [--format {png,ppm}] [--width WIDTH] [--height HEIGHT] [--samples SAMPLES] [--output OUTPUT] [--depth DEPTH] [--aspectratio ASPECTRATIO]

The generated image will be in .ppm format by default at tinytracer\output folder.

To run tests:

uv run pytest

Available Arguments :

• width To adjust width of output image.

  uv run  main.py --width=INTEGER # Default = 400

• height To adjust width of output image.

  uv run main.py --height=INTEGER # Default = 225

• aspectratio To adjust aspect ratio of output image (OVERRIDDEN if both height and width given)

  uv run main.py --aspectratio=X:Y # Default = 16:9

• samples To adjust number of samples per pixel.

  uv run main.py --samples=INTEGER # Default = 200

• depth To adjust depth of ray tracing.

  uv run main.py --depth=INTEGER # Default = 50

• output To select file output path ( INCLUDING FILENAME ).

  uv run main.py --output=PATH # Default = tinytracer/output/image.ppm

• format To select file output format [ png / ppm ]

  uv run main.py --format={png/ppm} # Default = ppm

How to Contribute

This project has issues prepared for contributors at all levels: Open Issues

Each issue is labeled by difficulty (good-first-issue, easy, medium, hard) and has clear instructions.

Please follow CONTRIBUTING.md for step-by-step guidance on:

• Setting up your environment
• Choosing and assigning issues
• Branching, committing, and creating PRs
• Code style and formatting rules (using black)
• PR acceptance criteria and points system

Warning

Work on only one issue at a time.

Code of Conduct

Please follow CODE_OF_CONDUCT.md to ensure a welcoming and productive environment for all contributors.

References

• Ray Tracing in One Weekend (Part 1 and Part 2)
• Understanding the Viewport
• See explained.md for additional explanations.