Getting Started

Get Rust

First install Rust. To keep it up to date use rustup:

rustup update

Compiling rs_pbrt

Cloning the repository

There are three repositories you can get the Rust source code from:

  1. sourcehut repository

  2. GitHub repository

  3. Codeberg repository

All three should be exactly the same, but reported issues etc. might differ.

sourcehut

# read-only
git clone https://git.sr.ht/~wahn/rs-pbrt
# read/write
git clone git@git.sr.ht:~wahn/rs-pbrt

GitHub

# using SSH
git clone git@github.com:wahn/rs_pbrt.git
# or using HTTPS
git clone https://github.com/wahn/rs_pbrt.git

Codeberg

# using SSH
git clone codeberg@codeberg.org:wahn/rs_pbrt.git
# or using HTTPS
git clone https://codeberg.org/wahn/rs_pbrt.git

Use Cargo to compile executables

# enter repository
cd rs_pbrt
# compile without OpenEXR support
cargo test --release --no-default-features
# compile executable rs_pbrt (and run it to see options)
cargo run --release --no-default-features

For a debug version compile without the --release option.

# compile without OpenEXR support
cargo test --no-default-features
# compile executable rs_pbrt (and run it to see options)
cargo run --no-default-features

For more information about Cargo, check out its documentation.

The executables can be found in either the release or the debug target directory:

# release
ls ./target/release
# debug
ls ./target/debug

Create a local copy of the documentation

# no OpenEXR support
cargo doc --no-default-features

Use your favourite web browser to open the local (Rust source code) documentation:

firefox target/doc/rs_pbrt/index.html

You can also find the official documentation (of the latest release) on the rs_pbrt web site.

Running the renderer

Without arguments (or by providing the -h or --help option) you get a simple usage message of the main executable rs_pbrt:

# relative path to executable rs_pbrt (assuming release build)
./target/release/rs_pbrt --help
# output
rs_pbrt version 0.9.12 (unknown) [Detected 28 cores]

Physically based rendering (PBR) with Rust

Usage: rs_pbrt [OPTIONS] --path <PATH>

Options:
      --cropx0 <CROPX0>          Specify an image crop window <x0 x1 y0 y1> [default: 0.0]
      --cropx1 <CROPX1>          Specify an image crop window <x0 x1 y0 y1> [default: 1.0]
      --cropy0 <CROPY0>          Specify an image crop window <x0 x1 y0 y1> [default: 0.0]
      --cropy1 <CROPY1>          Specify an image crop window <x0 x1 y0 y1> [default: 1.0]
  -i, --integrator <INTEGRATOR>  ao, directlighting, whitted, path, bdpt, mlt, sppm, volpath
  -t, --nthreads <NTHREADS>      use specified number of threads for rendering [default: 0]
  -s, --samples <SAMPLES>        pixel samples [default: 0]
  -p, --path <PATH>              The path to the file to read
  -h, --help                     Print help information
  -V, --version                  Print version information

The version can be checked by:

# print version number
./target/release/rs_pbrt --version
# output
rs_pbrt version 0.9.12 (unknown) [Detected 28 cores]

rs_pbrt 0.9.12

Your first rendered image

By specifing an input file (in this case cornell_box.pbrt) you can render a PNG image (currently always being called pbrt.png):

# specifing an input file
./target/release/rs_pbrt --path ~/git/gitlab/rs-pbrt-test-scenes/pbrt/cornell_box/cornell_box.pbrt
# output
rs_pbrt version 0.9.12 (unknown) [Detected 28 cores]

Copyright (c) 2016-2023 Jan Douglas Bert Walter.
Rust code based on C++ code by Matt Pharr, Greg Humphreys, and Wenzel Jakob.

Film "image"
  "integer xresolution" [500]
  "integer yresolution" [500]
Sampler "sobol"
  "integer pixelsamples" [8]
Integrator "path"
Integrator "path"
Rendering with 28 thread(s) ...
1024 / 1024 [=======================================================================] 100.00 % 1828.38/s
Writing image "pbrt.png" with bounds Bounds2i { p_min: Point2i { x: 0, y: 0 }, p_max: Point2i { x: 500, y: 500 } }

The resulting image should look like this:

_images/cornell_box_8_pixelsamples.png

If you modify the proper line in cornell_box.pbrt to use more pixel samples you should end up with a less noisy image, but rendering will take longer:

_images/cornell_box_256_pixelsamples.png 
diff --git a/assets/scenes/cornell_box.pbrt b/assets/scenes/cornell_box.pbrt
index aa3a210..559e860 100644
--- a/assets/scenes/cornell_box.pbrt
+++ b/assets/scenes/cornell_box.pbrt
@@ -10,7 +10,7 @@ Film "image"
   "integer yresolution" [ 500 ]
 ##  "integer outlierrejection_k" [ 10 ]
 ##Sampler "sobol"
-Sampler "sobol" "integer pixelsamples" [8]
+Sampler "sobol" "integer pixelsamples" [256]
 ##PixelFilter "blackmanharris"
 ##SurfaceIntegrator "bidirectional"
 ##Integrator "directlighting" "integer maxdepth" [10]

Instead of modifying the .pbrt file you can alternatively specify the samples per pixel on the command line:

./target/release/rs_pbrt --samples 256 --path ~/git/gitlab/rs-pbrt-test-scenes/pbrt/cornell_box/cornell_box.pbrt

More scenes to render

Because rs_pbrt isn’t 100% compatible to the C++ counter part (yet) I collect .pbrt scene files in a separate repository on GitLab. Have a look at the Wiki there.

Just clone it to another location:

# using SSH
git clone git@gitlab.com:jdb-walter/rs-pbrt-test-scenes.git
# or using HTTPS
git clone https://gitlab.com/jdb-walter/rs-pbrt-test-scenes.git

That’s it, for a quick start … have fun rendering some of the provided scenes!

_images/vw-van.png