RayTracing

Project by Alberto Lazzeri, Riccardo Natale and Davide Riva

Repository of "Tecniche Numeriche per la Generazione di Immagini Fotorealistiche" course by Professor Maurizio Tomasi (AY 2024/25). This code has been implemented in Julia and has the intent to create photorealistic images.

INSTALLATION

In order to use this repository, Julia v1.11 is required (see Julia GitHub). In your Julia enviroment then clone this repository or download ZIP at this link:

git clone https://github.com/daviderivaa/myraytracer.git

Before getting started you need to activate myRayTracing module and install dependences.

If you want to get the latest versions, accoring to Project.toml, you can either delete Manifest.toml or keep it and update packages.

Once you've cloned this repository, open Julia REPL and run:

julia> ]

(@v1.11) pkg> activate myRayTracing/

(myRayTracing) pkg> instantiate

Optional:

(myRayTracing) pkg> update

USAGE

In the main directory run:

julia -t <n_threads> main.jl <scene>

where:

• <n_threads> = auto allows to use all available threads (hint: use half of your available threads for a better performance)
• <n_threads> = 1 means not using multi-threading.
• <scene> is a txt filename in examples/ directory.

You can create your own scene in examples/ directory, learn sintax by looking at some examples in the same directory. Output images will be shown in examples_img/ named as <scene>_g1.0a0.5.png with the corresponding PFM file <scene>.pfm.

Tone mapping

You can modify Tone mapping parameters in main method convert_pfm_to_png() (see pfm2png.jl and LdrImage.jl for more informations).

Default values are:

• $\gamma=1.0$
• $\alpha=0.5$

In scene definition when you define an RGB color use only numbers in [0, 1]

HISTORY

See CHANGELOG file.

LICENSE

This project is under MIT License. See LICENSE for more informations.

TESTS AND CONTRIBUTING

To run tests, in Julia REPL run:

julia> ]

(@v1.11) pkg> activate myRayTracing/

(myRayTracing) pkg> test

This code provides CI Builds: tests will be executed at every commit or merge with main branch.

Open a PR for changes and improvements. Open Issue for bugs. Before asking for merge, update or implement tests, make sure they pass.

PROFILING

From Version 0.4.0 you can profile fire_all_rays method.

If not using --profile flag, @btime method of Profile pkg will be used, which gives Minimum time, Allocated memory and Garbage Collector (GC) time. Here's an output example:

Profiling fire_all_rays method:
Time: 3.250902643 s
Allocated memory: 1785.623448 MB
GC: 0.577122232 s
For a complete profiling use --profile flag

When using --profile flag, a profile.pb.gz will be created (ignore errors, see Issue here), with PProf. In order to visualize it, open Julia REPL and use:

julia> using Pkg

julia> Pkg.activate("myRayTracing/")

julia> using PProf

julia> PProf.refresh(file = "profile.pb.gz")

Which will produce an output as:

Serving web UI on http://localhost:57599
Process(`/home/alberto/.julia/artifacts/579b2972c1e7b798ee4281dd37d60a362be0e1f5/bin/pprof -http=localhost:57599 -relative_percentages profile.pb.gz`, ProcessRunning)

Then open http://localhost:57599.

---

SCRIPT EXAMPLES

DEMO

DEMO SINGLE IMAGE (WITH ON/OFF-RENDERER OR FLAT-RENDERER)

If myraytracer/demo/ directory doesn't exist, in myraytracer/ run:

mkdir demo

If you have Version 0.3.0, in myraytracer/script_examples/ you can run:

julia -t <n_threads> demo.jl <camera_type> <angle>

where:

• <n_threads> = auto allows to use all available threads.
• <n_threads> = 1 means not using multi-threading.

A GIF file called <camera_type>.gif will appear in myraytracer/script_examples/.

From Version 0.4.0, in myraytracer/script_examples/ you can run:

julia -t <n_threads> demo.jl <camera_type> <angle> <w_colors>

where:

• <n_threads> = auto allows to use all available threads.
• <n_threads> = 1 means not using multi-threading.
• <w_colors> = "yes" makes 2 colored spheres.
• <w_colors> = "no" makes only white spheres.

In myraytracer/demo/ creates a pfm file and the corresponding png image.

DEMO GIF (WITH ON/OFF-RENDERER OR FLAT-RENDERER)

Before executing demo_gif.jl, you need to install ffmpeg:

• Ubuntu / Debian bash:

  sudo apt install ffmpeg

• Windows prompt:

  choco install ffmpeg

• macOS bash:

  brew install ffmpeg

If myraytracer/demo/ directory doesn't exist, in myraytracer/ run:

mkdir demo

If you have Version 0.3.0, in myraytracer/script_examples/ you can run:

julia -t <n_threads> demo_gif.jl <camera_type>

where:

• <n_threads> = auto allows to use all available threads.
• <n_threads> = 1 means not using multi-threading.

A GIF file called <camera_type>.gif will appear in myraytracer/script_examples/.

From Version 0.4.0, in myraytracer/script_examples/ you can run:

julia -t <n_threads> demo_gif.jl <camera_type> <w_colors>

where:

• <n_threads> = auto allows to use all available threads.
• <n_threads> = 1 means not using multi-threading.
• <w_colors> = "yes" makes 2 colored spheres. A GIF file called <camera_type>_c.gif will appear in myraytracer/script_examples/.
• <w_colors> = "no" makes only white spheres. A GIF file called <camera_type>.gif will appear in myraytracer/script_examples/.

Here are two examples:

DEMO (WITH PATHTRACING ALGORITHM)

If myraytracer/ directory doesn't exist, in myraytracer/ run:

mkdir demo_path

Then in myraytracer/script_examples/ run:

julia -t <n_threads> demo_path.jl <camera_type> <angle_z> <angle_y> --profile(optional)

where:

• <n_threads> = auto allows to use all available threads.
• <n_threads> = 1 means not using multi-threading.
• --profile prints a complete profiling of fire_all_rays method.

In myraytracer/demo_path/ creates a pfm file and the corresponding png image.

Here's an example:

DEMO (WITH POINTLIGHT-TRACING ALGORITHM)

If myraytracer/ directory doesn't exist, in myraytracer/ run:

mkdir demo_PL

Then in myraytracer/script_examples/ run:

julia -t <n_threads> demo_PL.jl <camera_type> <angle_z> <angle_y> --profile(optional)

where:

• <n_threads> = auto allows to use all available threads.
• <n_threads> = 1 means not using multi-threading.
• --profile prints a complete profiling of fire_all_rays method.

In myraytracer/demo_PL/ creates a pfm file and the corresponding png image.

Here's an example:

CHECK CSG (CONSTRUCTIVE SOLID GEOMETRY)

If myraytracer/CSG/ directory doesn't exist, in myraytracer/ run:

mkdir CSG

In myraytracer/script_examples/ run:

julia -t <n_threads> check_csg.jl <camera_type> <angle_z> <angle_y> 

where:

• <n_threads> = auto allows to use all available threads.
• <n_threads> = 1 means not using multi-threading.

In myraytracer/CSG/ creates a pfm file and the corresponding png image.

Here's an example:

DRAW OPEN BOX (WITH ON/OFF-RENDERER OR FLAT-RENDERER)

If myraytracer/CSG/ directory doesn't exist, in myraytracer/ run:

mkdir CSG

In myraytracer/script_examples/ run:

julia -t <n_threads> box.jl <camera_type> <angle_z> <angle_y> --profile(optional)

where:

• <n_threads> = auto allows to use all available threads.
• <n_threads> = 1 means not using multi-threading.
• --profile prints a complete profiling of fire_all_rays method.

In myraytracer/CSG/ creates a pfm file and the corresponding png image.

Here's an example: