Atrc Renderer Documentation

Building

Dependencies

Prerequests

• cmake (>=3.10)
• MSVC or clang++ (and libc++) with supporting of major features of C++ 17 (g++ should be ok but is untested)

Dependencies Contained in Project Source

• agz-utils for mathematics and image loading
• cxxopts for parsing command-line arguments
• nlohmann json for parsing comfiguration file
• stl reader for parsing STL model file
• tiny obj loader for parsing OBJ model file

Dependencies Need to Be Prepared

• oidn 1.1.0 for denoising (only when USE_OIDN is ON)
• Embree 3.6.1 for better ray-mesh intersection test (only when USE_EMBREE is ON)
• Qt 5.12 (only when BUILD_GUI or BUILD_EDITOR is ON)

CMake Options

Note. OIDN is 64-bit only.

Example

Full-featured Building on Windows

Run following command in PowerShell：

1
git clone --recursive --depth=1 https://github.com/AirGuanZ/Atrc
2
cd Atrc
3
mkdir build
4
cd build
5
cmake -DUSE_EMBREE=ON -DUSE_OIDN=ON -DBUILD_GUI=ON -DBUILD_EDITOR=ON -DQt5_DIR="..." -DOpenImageDenoise_DIR="..." -Dembree_DIR="..." ..

Full-featured Building on *nix

xxxxxxxxxx
7
1
git clone --recursive --depth=1 https://github.com/AirGuanZ/Atrc
2
cd Atrc
3
mkdir build
4
cd build
5
export CC=clang
6
export CXX=clang++
7
cmake -DUSE_EMBREE=ON -DUSE_OIDN=ON -DBUILD_GUI=ON -DBUILD_EDITOR=ON -DQt5_DIR="..." -DOpenImageDenoise_DIR="..." -Dembree_DIR="..." -G "Unix Makefiles" ..

Usage

Components

1. CLI, command-line interface of the off-line renderer
2. GUI, renderer launcher with graphics user interface
3. Editor, scene editor
4. Tracer, off-line rendering library based on ray tracing
5. Factory, JSON config -> Tracer object

CLI Usage

Use following command to print help information:

xxxxxxxxxx
1
1
CLI --help

Typical usage looks like:

xxxxxxxxxx
1
1
CLI -d render_config.json

in which scene_config.json is a configuration file describing scene information and rendering settings.

Configuration

Atrc uses JSON to describe scene and rendering settings. The input JSON file must contains two parts:

xxxxxxxxxx
8
1
{
2
    "scene": {
3
        ...
4
    },
5
    "rendering": {
6
        ...
7
    }
8
}

where scene is a scene object with type Scene (explained later). rendering specifies rendering settings like camera, global illumination algorithm, progress reporter, and post processors.

Here is a simple example, which results in the above image (a bit rough metal sphere):

xxxxxxxxxx
62
1
{
2
  "scene": {
3
    "type": "default",
4
    "entities": [
5
      {
6
        "type": "geometric",
7
        "geometry": {
8
          "type": "sphere",
9
          "radius": 1.6,
10
          "transform": []
11
        },
12
        "material": {
13
          "type": "disney",
14
          "base_color": {
15
            "type": "constant",
16
            "texel": [ 0.7 ]
17
          },
18
          "metallic": {
19
            "type": "constant",
20
            "texel": [ 1 ]
21
          },
22
          "roughness": {
23
            "type": "constant",
24
            "texel": [ 0.15 ]
25
          }
26
        }
27
      }
28
    ],
29
    "env": {
30
      "type": "ibl",
31
      "tex": {
32
        "type": "hdr",
33
        "filename": "${scene-directory}/gray_pier_4k.hdr"
34
      }
35
    }
36
  },
37
  "rendering": {
38
    "camera": {
39
      "type": "thin_lens",
40
      "pos": [ 0, -5, 1 ],
41
      "dst": [ 0, 0, 0 ],
42
      "up": [ 0, 0, 1 ],
43
      "fov": 64
44
    },
45
    "width": 640,
46
    "height": 640,
47
    "renderer": {
48
      "type": "pt",
49
      "spp": 100
50
    },
51
    "reporter": {
52
      "type": "stdout"
53
    },
54
    "post_processors": [
55
      {
56
        "type": "save_to_img",
57
        "filename": "${scene-directory}/output.png",
58
        "inv_gamma": 2.2
59
      }
60
    ]
61
  }
62
}

Atrc's configuration file consists of a series of nested JSON objects, and each field has its type and value. The syntaxes of some commonly used types are listed below:

When a string represents a path or file name, ${scene-directory} means the absolute path of the directory where the configuration file is located, and ${working-directory} means the absolute path of working directory. Take ${scene-directory}/output.png as an example, it means output.png file in the directory where the configuration file is.

Except for fields with above types, other fields appear in the syntax of JSON object. Each object contains a field type, representing its type in Atrc renderer.

In the following description, I will use a simplified tabular form to indicate which fields an object should contain and the meaning of these fields. Taking the last post-processor save_to_img in the above configuration file as an example, its JSON representation is:

xxxxxxxxxx
5
1
{
2
    "type": "save_to_img",
3
    "filename": "${scene-directory}/output.png",
4
    "inv_gamma": 2.2
5
}

The corresponding tabular form is:

In the form, the "default value" column is blank to indicate that this is a required field, and not blank to indicate that it is an optional field.

Rendering Settings

This section describes fields included in the rendering item.

Scene

This section describes the possible type values for fields of type Scene.

default

EntityAggregate

For the intersection test between rays and the entities, Atrc uses a two-level data structure (refer to the design of RTX), where the inside of the entity is one level and the one between entities is another level. EntityAggregate is the field type corresponding to the data structure between entities.

native

native doesn't contain any fields, meaning to traversing all entities.

bvh

Organize entities with a BVH tree.

Camera

This section describes the possible type values for fields of type Camera.

thin_lens

Entity

geometric

Ordinary entity with geometry shape, material and mediums.

FilmFilter

The process of rendering the image is also a process of sampling-reconstructing the image plane. FilmFilter is the filter function used for reconstruction. For details, please refer to this article. If you don't know much about this part, it is recommended to use the simplest (but not the best) reconstruction filter function:

xxxxxxxxxx
2
1
"type": "box",
2
"radius": 0.5

box

The simplest box filter function, coincides with a single pixel with a radius of 0.5.

gaussian

Gaussian filter function

Geometry

Used to describe the geometry of an object.

Most geometric shapes contain a transform field of type [Transform], which is a sequence of Transform. It is worth noting that the Transform in the back of the sequence acts on the object first, and the Transform in front of the sequence acts on the object later.

disk

double_sided

Double-sided adapter, which converts a single-sided geometry to double-sided, and is mainly suitable for geometric shape in the form of disc, quad or triangle.

quad

Quad $ABCD$, constructed by two triangles $ABC$ and $ACD$

sphere

Single-sided sphere

triangle

Single-sided triangle

triangle_bvh

Triangle mesh

Embree is used when enabled, otherwise a simple BVH tree is used.

triangle_bvh_embree

Triangle mesh implemented using Embree. It has the same parameters as triangle_bvh.

Available only when cmake option USE_EMBREE is ON.

triangle_bvh_noembree

Triangle mesh implemented using simple BVH tree. It has the same parameters as triangle_bvh.

Material

Normal Mapping

Some materials support normal mapping. The field list of these materials will include a normal_map.

BSSRDF

Some materials support Normalized Diffusion BSSRDF, which contains following three fields:

1. bssrdf_dmfp. diffuse mean free path length.
2. bssrdf_A. diffuse surface reflectance.
3. bssrdf_eta. ior.

BSSRDF is enabled only when bssrdf_dmfp is specified. According to material type, bssrdf_A and bssrdf_eta may have default value. These fields and their default values are listed in fields of those materials.

disney

see Disney Principled BSDF

glass

Smooth glass

Two color assignment methods are provided:

1. Only provide color_map. Colors of reflection and refraction are given automatically filled with color_map.
2. Provide color_reflection_map and color_refraction_map, which give reflection and refraction colors respectively.

ideal_black

A mass of black

ideal_diffuse

Ideal diffuse reflection, reflects the same radiance in all directions.

mirror

Ideal mirror reflection

phong

NOTE. Atrc will automatically scale $d$ and $s$ to keep energy conservation.

invisible_surface

Surface material which is totally invisible

Medium

void

Vacuum, which means nothing.

heterogeneous

Heterogeneous media defined based on 3D textures

homogeneous

EnvirLight

ibl

Image based lighting

native_sky

Environment light that represents a sky with a gradient of color from top to bottom.

Post Processor

gamma

Perform gamma correction on the image

Only one of gamma and inv_gamma need to be given.

oidn_denoiser

Use OIDN to denoise the image

save_gbuffer_to_png

Save the G-Buffer to png files

save_to_img

Save the rendered image to a file

Only one of gamma/inv_gamma need to be specified for gamma correction.

resize

Resize the image and G-Buffer to the specified resolution

Renderer

pt

Traditional path tracing. You can specify the tracing strategy by integrator.

The entire image is divided into multiple square pixel blocks (rendering tasks), and each pixel block is assigned to a worker thread for execution as a subtask.

When the number of worker threads $n$ is less or equal to 0 and the number of hardware threads is $k$, then $\max\{1, k + n \}$ worker threads will be used. For example, you can set worker_count to -2, which means that you leave two hardware threads and use all other hardware threads.

ao

Ambient occlusion renderer

bdpt

Bidirectional path tracer

particle

Adjoint particle tracer. particle builds path from light source to camera, making the convergence very slow.

particle uses the strategy of starting from a light source to construct a light path, called backward pass; for paths of length 1 (that is, the light source is directly seen from the camera), however, particle builds them from the camera to light sources, called forward pass. The two passes are independent executed and are combined to render the final image.

Backward pass consists of particle_task_count particle tracing tasks. Each task contains particles_per_task particles, so a total number of particle_task_count * particles_per_task paths are traced in backward pass.

pssmlt_pt

Primary sample space metropolis light transport on path tracing

sppm

Stochastic progressive photon mapping

vol_bdpt

Volumetric bidirectional path tracing

ProgressReporter

stdout

Print to standard output

noout

No progress output

Texture2D

All 2d textures contain the following fields (these fields are not listed in the subsequent textures):

Note that inv_v, inv_u, swap_uv and transform are all transformations to uv, where transform applies first, then swap_uv , and inv_u, inv_v applies last. In the transform sequence, the Transform2 in the back of the sequence applies first, and the Transform2 in the front of the sequence applies later.

checker_board

checker board texture

constant

Constant-valued texture, that is, sampling always results in the same value

hdr

Texture loaded from .hdr file

image

Textures loaded from common image file formats (.bmp, .jpg, .png, .tga, etc)

Texture3D

All 3d textures contain the following fields (these fields are not listed in the subsequent textures):

Note that inv_v, inv_u, inv_w, uvw_perm and transform are all transformations to uv, where transform applies first, then uvw_perm , and inv_u, inv_v, inv_w applies last. In the transform sequence, the Transform3 in the back of the sequence applies first, and the Transform3 in the front of the sequence applies later.

constant

Constant-valued texture, that is, sampling always results in the same value

image3d

3D grid.

The format field determines how voxel data is stored in memory. real/spec store one/three float value for each voxel, and gray8/rgb8 use one/three bytes for each voxel. Note that real/gray8 format can only store gray value, and gray8/rgb8 can only store integer between [0, 255] (normalized to [0, 1] when sampled).

There are three ways to provide voxel data to spectrum_grid, one and only one of the three fields (ascii_filename/binary_filename/image_filenames) must be specified.

The format of text voxel data is:

x
1
int32 value (texture width)
2
int32 value (texture height)
3
int32 value (texture depth)
4
for z in 0 to texture depth
5
    for y in 0 to texture height
6
        for x in 0 to texture width
7
            voxel_value at (x, y, z)

The format of voxel_value is determined by format:

x
1
if format == "real" then:
2
    voxel_value is a float
3
else if format == "spec" then:
4
    voxel_value is 3 float values
5
else if format == "gray8" then:
6
    voxel_value is a integer between [0, 255]
7
else if format == "rgb8" then:
8
    voxel_value is 3 integer values (in [0, 255]^3)

The data arrangement of binary voxel data is similar to the text format, except that all data is stored as binary data.

The filename array of image slices refers to the filenames of a series of two-dimensional images obtained by decomposing the voxels in the depth direction. These two-dimensional images must be the same size, and the number of images determines the depth value of the 3d texture.

Transform

Affine transformation on three-dimensional coordinates

translate

rotate

Only one of rad and deg can be provided.

rotate_x

Rotate around the $x$ axis.

Only one of rad and deg can be provided.

rotate_y

Rotate around the $y$ axis.

Only one of rad and deg can be provided.

rotate_z

Rotate around the $z$ axis.

Only one of rad and deg can be provided.

scale

Isotropic scaling

Transform2

Affine transformation on two-dimensional coordinates

translate

rotate

Only one of rad and deg can be provided.

scale

Isotropic scaling

Shared Scene Description

Atrc supports rendering the same scene with different rendering parameters, such as rendering the same scene with multiple camera perspectives. Compared with using multiple configuration files, this solution avoids the overhead of repeatedly loading scene data and constructing data structures. Let the original content of rendering configuration is:

xxxxxxxxxx
4
1
{
2
    "scene": { SceneDescription },
3
    "rendering": { RenderingDescription }
4
}

Now we need to use multiple different RenderDescription to render the same SceneDescription. We can write the configuration file as:

xxxxxxxxxx
9
1
{
2
    "scene": { SceneDescription },
3
    "rendering": [
4
        { RenderingDescription0 },
5
        { RenderingDescription1 },
6
        ...,
7
        { RenderingDescriptionN }
8
    ]
9
}