Welcome to NM4PIG! This is a raytracing library written in C#. It was developed for the course Numerical Methods for Photorealistic Image Generation held by Prof. Maurizio Tomasi at Università degli Studi di Milano (A.Y. 2020-2021).
The contibutors to the project are Tommaso Armadillo, Pietro Klausner and Andrea Sala.
👀
The main funcitonality of this library is to produce photorealistic images from input files describing a certain scene. The scene is made of geometric shapes (see the list of available shapes), each one defined by its coordinates and its material. Our code offers the possibility to choose between a diffusive, emissive or reflective material. The code implements four different backwards ray tracing algorithms to simulate how light rays propagate. A camera (perspective or orthogonal) representing the observer will see the world through a 2D screen placed ahead of it and it is defined by its position, the distance from the screen and the aspect ratio.
Once everything (shapes and observer) is defined and in place, the code solves the rendering equation (with different assumptions, depending on the chosen algorithm) and produces an HDR image (in .pfm format). Later, the HDR image is converted into LDR formats such as .jpgand .png.
💻
This library has been developed and tested with .NET version 5.0.x. It is possible to download the latest version here.
This library uses some external libraries. The user should not worry as .NET automatically imports them with the repository download. The libraries are listed below:
- ImageSharp to convert
.pfmimages into LDR formats - CommandLineUtils to handle Command Line Interface
- ShellProgressBar to show a nice progress bar while rendering
⚙️
In order to use the library you can clone the repository:
git clone git@github.com:andreasala98/NM4PIG.git
To check that the code works as expected, you can run a set of tests using the following command:
dotnet test
✨
Our program is developed to be used mainly in render mode. This mode reads an external file with instructions for the scene, and then performs photorealistic ray tracing according to the specified parameters. In order to use render mode, you can run the following command (from the NM4PIG/NM4PIG folder):
dotnet run -- render --scene ../Examples/Inputs/dummy.txt -ldr ../Examples/dummy.jpg
This command will read the instructions present in the file dummy.txt and generate an image called dummy.jpg. Feel free to use your preferred editor to visualize the image generated. If you want to explore all the settable parameters, you can run
dotnet run -- render -?
The complete list of settable parameters is:
--file| <FILENAME>: name (path) of the input file with instructions. Default isdummy.txt--width|-W <WIDTH>and--height|-H <HEIGHT>: set the dimensions of the generated image. Default is 640x480--pfmfile|-pfm <FILENAME>: name (path) of the.pfmoutput file. This file can be used as input in Convert mode Default isdemoImage.pfm--ldrfile|-ldr <FILENAME>: name (path) of the.pngor.jpgoutput file. Default isdemoImage.jpg--samples-per-pixel|-spp <SAMPLES>: number of extracted samples per pixel (to perform antialiasing). Default is 4--render-type|-rnd <CHAR>: rendering algorithm to be used (On-Off renderer: 'o', Flat renderer: 'f', Pointlight renderer: 'p', Path tracer: 'r'). Default is 'r'--declare-float|-d: Override a variable value from the command line. The syntax is--declare-float VAR:VALUE
--max-depth|-md <INT>: max number of reflections for each ray. Default is 3--n-rays|-n <INT>: number of rays sampled at each reflection. Default is 10--russian-roulette|-rr <INT>: number of reflections beyond which the Russian Roulette Algorithm is used. Default is 2
Input files must be written according to specific syntactic rules. We prepared some tutorial files to explain how these input files should be created:
- Tutorial 1 (Result)
- Tutorial 2 (Result)
- Tutorial 3 (flat renderer) (Result)
- Tutorial 4 (point light renderer) (Result)
Each file has in the same directory the image produced. Once you've learned how to write an input file, you can start creating your own images!
🎮
To run the application and visualize a simple image, use the following command (from the NM4PIG/NM4PIG directory):
dotnet run -- demo
The command uses some default parmaeters. Feel free to explore all the possible options and to use the most suitable for you
dotnet run -- demo -?
It is also possible to vary the angle of the camera in degrees (-a ) in order to obtain something like the image shown (see Examples/Animations/)
It is allowed to add any of the following shapes to the environment:
- Spheres 🏀
- Planes
✈️ (joking, actually these kinds of planes ◻️) - Boxes 📦
- Cones 🍦
- Cylinders 🎩
- Constructive Solid Geometry 💎(CSG): Union, Intersection and Difference of any pair of shapes of the ones mentioned above
- Wikishape a particular case of CSG mixtures
- Pig 🐷 a built-in pig shape, constructed with CSG.
Each shape can be transformed upon creation with a composition of scaling, translations and rotations around any of the three axes.
🔁
To convert an existing .pfm file into a .png or .jpg file, type the following command (if no arguments are passed some default values are used):
dotnet run -- convert -f <FACTOR> -g <GAMMA>
To clean NM4PIG directory from generated .png and .jpg samples, type ./clean.sh. If you want to keep an image, make sure to move it to another folder. This will prevent your image from being deleted.
📑
A webpage with all the documentation is available at this link. This webpage is generated with DocFX. Learn more. Any suggestion to improve the documentation website is welcome!
⚖️
The code is released under a MIT license. See the file LICENSE
Here is a small gallery of some images generated with NM4PIG:
Now it's time to build your own! Have fun!
If you happen to find any issue or bug with our code, you're more than welcome to let us know. Either contact us via email or raise an issue with the apposite issue tracker. We guarantee maintenance up until September 2021.