JTracer

This project was developed by Matteo Picciolini and Francesco Villa to generate photorealistic images by using Numerical Methods. This project is developed for Numeric calculus for photorealistic images generation course, held by professor Maurizio Tomasi at University of Milan, Physics Department. The project has been written in Java and can be compiled using Gradle. Additionally, it is integrated with some bash scripts that allow generating animations using the open-source software FFmpeg. It is available for Linux, Windows and macOS.

Table of Contents

• Overview
• Prerequisites
• Usage
  • Modes
  • Tutorials
• Animations
• Shapes
• Gallery
• Issue Tracking

Overview

The primary objective of this library is to generate photorealistic images from input files that describe a specific scene. The scene comprises geometric shapes (please refer to the list of available shapes), each defined by its coordinates and material. Our code allows you to select between diffusive or reflective materials. The code incorporates various backward ray tracing algorithms to simulate the propagation of light rays. A camera (perspective or orthogonal), representing the observer, will view the world through a two-dimensional screen positioned in front of it. The camera is defined by its position, distance from the screen, and aspect ratio.

Prerequisites

For this project, we are using version 18.0.2 of Amazon Corretto, an OpenJDK distribution provided by Amazon Web Services. It is possible to download the correct version of Java for your operating system on the Oracle website.

On a Debian-based system, you can install it by executing the following commands:

wget https://download.oracle.com/java/18/archive/jdk-18.0.2.1_linux-x64_bin.tar.gz
tar -xvf jdk-18.0.2.1_linux-x64_bin.tar.gz

Additionally, add the following line to the .bashrc file:

export JAVA_HOME=/path/to/.jdks/corretto-18.0.2

Please note that the provided path /path/to/.jdks/corretto-18.0.2 assumes a specific directory structure. Make sure to adjust the path according to your actual system configuration.

For the project compilation, we relied on the Gradle build automation tool. Gradle allows specifying project dependencies in the build file so that it can automatically download the necessary external libraries during the compilation phase, ensuring that the required classes and methods are available for the proper execution of the program.

For this project, the following external libraries have been imported:

• JUnit Jupiter (version 5.9.2), required for writing automated tests;
• Picocli (version 4.6.1), used for creating a command-line interface;
• JavaTuples (version 1.2), used to provide a series of tuple classes.

It is not necessary to install Gradle, as the project provides an executable ./gradlew that can be used to avoid local installation of Gradle.

Usage

In order to use and modify the code you can clone the repository with the command:

git clone git@github.com:matteopicciolini/JTracer.git

Then, you can run the command ./gradlew test to verify that the package functions correctly by executing the tests. Project can be built from source code running the command ./gradlew build.

To run the code, you can proceed in two ways:

1. By generating an executable using the command ./gradlew installDist and you can launch it with the specified parameters below.
2. By using the file ./gradlew and running it in run mode: ./gradlew run.

With the --args flag, you can pass parameters from the command line. For example:

./gradlew run --args="render --input=image.txt"

Below, and in more detail in DOCUMENTATION file, are the available execution modes and parameters using the Gradle run task, as it avoids the generation of the binary file. However, please note that what follows is also (and especially) valid for the binary file generated with the installDist task.

Modes

This program can be executed in three different modes:

1. convert mode. With this mode, you can convert a PFM file to an LDR file.
2. demo mode. This mode allows the creation of photorealistic images by directly interacting with the source code of the Tracer class. If this mode is launched without modifying the code, a default image will be generated. Editing the source code is recommended for advanced users only.
3. render mode. That's the main feature of this program. With this mode, you can describe the scene inside a .txt file using some simple rules, and generate your photorealistic image without touching the source code.
4. sum mode. This technique allows to "combine" multiple images of the same scene generated with different seeds, in order to reduce the noise present in the image. It is typically used after generating many images in parallel.

All of these modes include the -h option which displays specifications for each one. For a detailed description of the commands and options available, please refer to the documentation.

Tutorials

For proper functionality, this code requires the user to be familiar with some syntax rules for describing the scene. To learn how to write the necessary .txt files for the program, you can refer to the documentation or use the tutorials provided in the Tutorials folder.

Animations

This code also implements the ability to generate animations. Animations can be created by appropriately modifying and making executable the bash files animation.sh and/or parallel-generate-image.sh. Similarly, these files can be used to generate different images of the same scene in parallel, and then utilize the sum mode.

Shapes

This raytracer implements the following shapes:

From version 1.0.0:

• Spheres 🌍
• Planes ✈️
• Boxes 📦
• Cylinders 🎩
• Cones 🍦
• Hyperboloids ⏳
• CSG Union ➕
• CSG Difference ➖
• CSG Intersection ⋂

From version 1.1.0:

• Triangles ▲
• Triangle Meshes 🦌

Concerning about the last shape, using triangle meshes is a bit complex than other shapes. In facts, in order to build a scene with some specific shapes (tetrahedron, icosahedron and all the possible shapes like deers or cats) it is necessary to include a particular file .txt with the following structure:

# vertices
v 0.00 0.00 0.00
v 1.00 0.00 0.00
v 0.00 1.00 0.00
v 0.00 0.00 1.00
 
# faces
f 1 3 2
f 1 2 4
f 1 3 4
f 2 3 4

In this project, there is also a Python script that takes an input .obj file and generates an output .txt file with the preavious features.

Gallery

Cornell Box rendered using JTracer with varying
the number of rays cast per pixel (antialiasing algorithm).

Examples of pigments generated from existing pfm files.

Some implementations of abstract scenes.

Milano Design Week. Picciolini Collection.

New York Zoo. Villa Collection.

Issue Tracking

If you encounter any issues while using this project or find a bug in the code, please feel free to let us know! You can reach us at picciolinimatteo@gmail.com or fravilla30@gmail.com.