raytracer

raytracer is a C++ code that you can use to generate simple photorealistic images using spheres and planes. Secondly, it can be also used to convert a image from pfm to png or jpeg format.

Documentation is available online at https://federicopellegatta.github.io/raytracing/html/index.html

Installation

Note that raytracer since v1.0.0 works only on Linux machines.

Dependencies

• C++ Compiler (at least C++17)
• CMake (at least version 3.16)
• GD library (at least version 2.5.5)
• pkg-config (at least version 0.29)

If you want to generate animations, we also recommend:

• ffmpeg (at least version 4.2.4)
• GNU parallel

If you're willing to use conda, or if you already do, all the above dependencies can be installed via

$ conda env create -n <envname> -f requirements.yml

Or you can use your distribution package manager to install them.

Download and building

If all the dependencies have been met,

• you can download the latest stable release here, and unpack it

  $ tar -xvf /path/to/tar #or zip file -C /path/to/your/directory

• if you want to stay up to date with the latest changes (note that they might not work as intended), clone this repository

  $ git clone https://github.com/federicopellegatta/raytracing.git

Next, follow the instructions below in order to compile raytracer in your own directory.

$ cd /path/to/your/directory  
$ # (if you're using conda -> conda activate <envname>)
$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release 
$ cd build/
$ cmake --build . -j <NUM_OF_CORES> # We advise at least 2 cores, as the compilation process is a bit slow

You will find tests and executable files in build directory. Note that the executable main file is raytracer.

Usage

To check if tests are passing do

$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug 
$ cd build
$ cmake --build . -j <NUM_OF_CORES>
$ ctest

If tests are not passing feel free to open an issue.

A help menu will be displayed by typing (the command-line interface is built using Taywee/args)

$ ./raytracer --help

Render

raytracer can generate images using 3 algorithms:

• on-off renderer: it produces black and white image. We recommed to use this algorithm in order to debug, because it is really fast;
• flat renderer: it estimates the solution of the rendering equation by neglecting any contribution of the light. It just uses the pigment of each surface to determine how to compute the final radiance;
• pathtracing: it allows the caller to tune number of rays thrown at each iteration, as well as the maximum depth. It implements Russian roulette, so in principle it will take a finite time to complete the calculation. Inside the examples directory there are input files defining different scenes.

Note that the file examples/demo.txt contains instructions on how to write a correct input file.

The following command

$ ./raytracer render -w 640 -h 360 --alg pathtracing --num-of-rays 5 --max-depth 4 --samples-per-pixel 25 --outf demo-5 -i ../examples/demo.txt

will generate the image below (which is defined in the input file examples/demo.txt)

Thanks to ffmpeg and a couple of cli options it is possibile to generate simple animations; the scripts demo_animation.sh and generate-image.sh facilitates this, and by launching

$ ./demo_animation.sh -j <NUM_OF_CORES>

will produce

Feel free to tweak the scripts to your own liking.

Convert images from HDR to LDR format

raytracer can also convert images from HDR to LDR format (only png and jpeg are supported): use the convertpfm2png command as in the following example:

$ ./raytracer convertpfm2png --inpfm=/path/to/pfm-file --outpng=/path/to/output-file -f 1.0 -g 1.0

Contributing

If you wish to contribute or you have just found any bug, please open an issue or a pull request on our GitHub repository. Thank you!

Licence

raytracer is licensed under the terms of the GNU General Public License v3.0 and is available for free. See the file LICENCE.md.