TEMPLATE.md

a multi-threaded raytracer in pure rust

Prerequisites · Installation · Usage

Prerequisites

Platform requirements

• x86_64-unknown-linux-gnu ⁽¹⁾
• x86_64-unknown-linux-musl

_{⁽¹⁾ note: glibc version >= 2.35}

Build requirements

• for users install cargo stable latest build system (see rust-toolchain.toml for stable version)

• for devels install rustup that will automatically provision the correct toolchain

  For unit tests coverage cargo-tarpaulin is required as additional component

  There is an handy makefile useful to:

  • preview documentation built with rustdoc
  • preview html code coverage analysis created with cargo-tarpaulin
  • create demo animations

Installation

From binary

Install from binary:

curl -sSf https://andros21.github.io/rustracer/install.sh | bash  ⁽²⁾

click to show other installation options

## Install the latest version `gnu` variant in `~/.rustracer/bin`
export PREFIX='~/.rustracer/'
curl -sSf https://andros21.github.io/rustracer/install.sh | bash -s -- gnu

## Install the `0.4.0` version `musl` variant in `~/.rustracer/bin`
export PREFIX='~/.rustracer/'
curl -sSf https://andros21.github.io/rustracer/install.sh | bash -s -- musl 0.4.0

_{⁽²⁾ note: will install latest musl release in ~/.local/bin}

From source

Install from source code, a template could be:

cargo install rustracer  ⁽³⁾

click to show other installation options

## Install the latest version using `Cargo.lock` in `~/.rustracer/bin`
export PREFIX='~/.rustracer/'
cargo install --locked --root $$PREFIX rustracer

## Install the `0.4.0` version in `~/.rustracer/bin`
export VER='0.4.0'
export PREFIX='~/.rustracer/'
cargo install --root $$PREFIX --version $$VER rustracer

_{⁽³⁾ note: will install latest release in ~/.cargo/bin}

Usage

rustracer

subcommands	description
rustracer-convert	convert an hdr image into ldr image
rustracer-demo	render a simple demo scene (example purpose)
rustracer-render	render a scene from file (yaml formatted)
rustracer-completion	generate shell completion script (hidden)

click to show rustracer -h

$rustracer

---

rustracer-convert

Convert a pfm file to png:

rustracer convert image.pfm image.png

click to show rustracer-convert -h

$rustracer_convert

---

rustracer-demo

Rendering demo scene:

rustracer demo --width 1920 --height 1080 --anti-aliasing 3 demo.png  ⁽⁴⁾

_{demo.png: cpu Intel(R) Xeon(R) CPU E5520 @ 2.27GHz | threads 8 | time ~35s}

demo scene 360 degree (see makefile):

make demo.gif  ⁽⁴⁾

_{demo.gif: cpu Intel(R) Xeon(R) CPU E5520 @ 2.27GHz | threads 8 | time ~15m}

click to show rustracer-demo -h

$rustracer_demo

_{⁽⁴⁾ note: all available threads are used, set RAYON_NUM_THREADS to override}

---

rustracer-render

Rendering demo scene from scene file examples/demo.yml:

rustracer render --anti-aliasing 3 examples/demo.yml demo.png  ⁽⁵⁾

you can use this example scene to learn how to write your custom scene, ready to be rendered!

But let's unleash the power of a scene encoded in data-serialization language such as yaml
Well repetitive scenes could be nightmare to be written, but for these (and more) there is cue

Let's try to render a 3D fractal, a sphere-flake, but without manually write a yaml scene file
we can automatic generate it from examples/flake.cue

cue eval flake.cue -e "flake" -f flake.cue.yml   # generate yml from cue
cat flake.cue.yml | sed "s/'//g" > flake.yml     # little tweaks
wc -l flake.cue flake.yml                        # compare lines number
   92 flake.cue                                  # .
 2750 flake.yml                                  # .

so with this trick we've been able to condense a scene info from 2750 to 92 lines, x30 shrink! 😎
and the generated flake.yml can be simple parsed

rustracer render --width 1280 --height 720 --anti-aliasing 3 flake.yml flake.png  ⁽⁵⁾

_{flake.png: cpu Intel(R) Xeon(R) CPU E5520 @ 2.27GHz | threads 8 | time ~7h}

click to show rustracer-render -h

$rustracer_render

_{⁽⁵⁾ note: all available threads are used, set RAYON_NUM_THREADS to override}

---

rustracer-completion

Simple generate completion script for bash shell (same for fish and zsh):

rustracer completion bash ⁽⁶⁾

_{note: close-open your shell, and here we go, tab completions now available!}

click to show rustracer-completion -h

$rustracer_completion

_{⁽⁶⁾ note: bash>4.1 and bash-complete>2.9}

---

Acknowledgements

• pytracer - a simple raytracer in pure Python