Raytracing package for the generation of photorealistic images in Julia.

Contents

• • Contents
  • Brief description
  • Overview
  • Installation
  • • Package
    • CLI tool

Brief description

The main purpose of this package is to generate photorealistic images given an input scene.

The input scene is composed by a list of shapes (spheres, planes, ...) of various materials (for now diffusive or reflective) with different colors, each one with in a particular position in the 3D space. The observer is represented by a camera, that can do a perspective or an orthogonal projection. The camera will see the scene through a screen, characterized by its aspect ratio, distance from the camera and resolution. The image can be rendered with different backwards ray tracing algorithms: a path tracer (the default renderer), a point-light tracer, a flat renderer and an on-off renderer; this process can be parallelized using multiple threads. Each of these aspects can be managed, tuned and modified using the low-level API of the package (see below).

There are two main steps in the image generation. We offer high-level API and a CLI tool for these steps (see below).

• The generation of an HDR (high dynamic range) image in the PFM format. In this step, the scene is loaded along with the informations about the observer (position, orientation, type of the camera, ...) and the chosen renderer. Then the image is rendered using the chosen algorithm.

• The conversion of this image to an LDR (low dynamic range) image, such as jpg or png, using a tone mapping process.

Overview

We provide:

• A package with both high-level API and low-level API. It's possible to use the package's features directly from the REPL or in more complex scripts. See Basic API usage.

• A CLI tool. Thanks to the simple usage and the extended help messages, it makes possible the use of this package's high-level features to those who do not know Julia lang. See Basic CLI tool usage.

• SceneLang is a Domain-Specific Language (DSL) used to describe a 3D scene that can be rendered by Raytracer. Being a DSL, SceneLang lacks some of the basic features of general purpose languages: there are no functions or custom types or even flexible arithmetic operations. SceneLang is made only to construct scenes to be rendered. See Basic SceneLang usage.

For example, to generate an image from a SceneLang script, you can use the julia REPL:

julia> using Raytracer

julia> render_from_script("path/to/script.sl")

or equivalently the CLI tool:

~/Raytracer.jl❯ julia raytracer_cli.jl render image path/to/script.sl

The CLI tool has more advanced features, like the generation of animations, but using the package from the REPL gives more flexibility.

Installation

Package

The package is not available in the official registry.

To add this package to your main environment (not recommended), open the julia REPL and type the following commands:

import Pkg
Pkg.add(url="https://github.com/Samuele-Colombo/FileIO.jl")
Pkg.add(url="https://github.com/Samuele-Colombo/ImagePFM.jl")
Pkg.add(url="https://github.com/Paolo97Gll/Raytracer.jl")

We use a custom version of FileIO that provides load/save functionalities for pfm files: this integration is done by the package ImagePFM. If FileIO is already present (e.g. the original package), it will be overwritten by this custom version.

You can also create a new environment (recommended). First create a new folder and cd into this folder: this will become the home of the new environment. Then open the julia REPL and type the following commands:

import Pkg
Pkg.activate(".")
Pkg.add(url="https://github.com/Samuele-Colombo/FileIO.jl")
Pkg.add(url="https://github.com/Samuele-Colombo/ImagePFM.jl")
Pkg.add(url="https://github.com/Paolo97Gll/Raytracer.jl")

CLI tool

To use the CLI tool, you don't need to install the package or create a new environment: you just need to clone the repository:

git clone https://github.com/Paolo97Gll/Raytracer.jl.git

Then cd into the cloned folder, open the julia REPL, and type the following commands to instantiate the environment:

import Pkg
Pkg.activate(".")
Pkg.instantiate()