Crate rustracer

source ·

Expand description

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

a multi-threaded raytracer in pure rust

Usage: rustracer <COMMAND>

Commands:
  convert  Convert HDR (pfm) image to LDR (ff|png) image
  demo     Render a demo scene (hard-coded in main)
  render   Render a scene from file (yaml formatted)

Options:
  -h, --help     Print help
  -V, --version  Print version

§rustracer-convert

Convert a pfm file to png:

`rustracer convert image.pfm image.png`

click to show rustracer-convert -h

Convert HDR (pfm) image to LDR (ff|png) image

Usage: rustracer convert [OPTIONS] <HDR> <LDR>

Arguments:
  <HDR>  Input pfm image
  <LDR>  Output image [possible formats: ff, png]

Options:
  -v, --verbose          Print stdout information
  -f, --factor <FACTOR>  Normalization factor [default: 1.0]
  -g, --gamma <GAMMA>    Gamma parameter [default: 1.0]
  -h, --help             Print help (see more with '--help')
  -V, --version          Print version

§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

Render a demo scene (hard-coded in main)

Usage: rustracer demo [OPTIONS] <OUTPUT>

Arguments:
  <OUTPUT>  Output image [possible formats: ff, png]

Options:
  -v, --verbose                        Print stdout information
      --output-pfm                     Output also hdr image
      --orthogonal                     Use orthogonal camera instead of perspective camera
      --width <WIDTH>                  Image width [default: 640]
      --height <HEIGHT>                Image height [default: 480]
      --angle-deg <ANGLE_DEG>          View angle (in degrees) [default: 0.0]
  -f, --factor <FACTOR>                Normalization factor [default: 1.0]
  -g, --gamma <GAMMA>                  Gamma parameter [default: 1.0]
  -a, --algorithm <ALGORITHM>          Rendering algorithm [default: pathtracer] [possible values: onoff, flat, pathtracer]
  -n, --num-of-rays <NUM_OF_RAYS>      Number of rays [default: 10]
  -m, --max-depth <MAX_DEPTH>          Maximum depth [default: 3]
      --init-state <INIT_STATE>        Initial random seed (positive number) [default: 42]
      --init-seq <INIT_SEQ>            Identifier of the random sequence (positive number) [default: 54]
      --anti-aliasing <ANTI_ALIASING>  Anti-aliasing level [default: 1]
  -h, --help                           Print help (see more with '--help')
  -V, --version                        Print version

_{⁽⁴⁾ 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

Render a scene from file (yaml formatted)

Usage: rustracer render [OPTIONS] <INPUT> <OUTPUT>

Arguments:
  <INPUT>   Input scene file
  <OUTPUT>  Output image [possible formats: ff, png]

Options:
  -v, --verbose                        Print stdout information
      --output-pfm                     Output also hdr image
      --width <WIDTH>                  Image width [default: 640]
      --height <HEIGHT>                Image height [default: 480]
      --angle-deg <ANGLE_DEG>          View angle (in degrees) [default: 0.0]
  -f, --factor <FACTOR>                Normalization factor [default: 1.0]
  -g, --gamma <GAMMA>                  Gamma parameter [default: 1.0]
  -a, --algorithm <ALGORITHM>          Rendering algorithm [default: pathtracer] [possible values: onoff, flat, pathtracer]
  -n, --num-of-rays <NUM_OF_RAYS>      Number of rays [default: 10]
  -m, --max-depth <MAX_DEPTH>          Maximum depth [default: 3]
      --init-state <INIT_STATE>        Initial random seed (positive number) [default: 42]
      --init-seq <INIT_SEQ>            Identifier of the random sequence (positive number) [default: 54]
      --anti-aliasing <ANTI_ALIASING>  Anti-aliasing level [default: 1]
  -h, --help                           Print help (see more with '--help')
  -V, --version                        Print version

_{⁽⁵⁾ 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

Generate shell completion script

Usage: rustracer completion [OPTIONS] <SHELL>

Arguments:
  <SHELL>  Shell to generate script for [possible values: bash, fish, zsh]

Options:
  -o, --output <OUTPUT>  Specify output script file
  -h, --help             Print help (see more with '--help')
  -V, --version          Print version

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

§Acknowledgements

pytracer - a simple raytracer in pure Python

Modules§

camera 🔒
Camera module.
cli 🔒
Command Line Interface module.
color 🔒
RGB Color module.
error 🔒
Error reporting module.
hdrimage 🔒
High Dynamic Range Image module.
imagetracer 🔒
Image Tracer module.
material 🔒
Material module.
misc 🔒
Miscellanea module.
normal 🔒
3D Normal module.
point 🔒
3D Point module.
random 🔒
PCG random numbers generator module.
ray 🔒
Light Ray module.
render 🔒
Render module.
scene 🔒
Scene parsing module.
shape 🔒
Geometric Shapes module.
transformation 🔒
3D Homogeneous Transformation module.
vector 🔒
3D Vector module.
world 🔒
World module.

Macros§

check
Macro for fail fast in main subcommands (e.g. inside convert).
exit
Macro for wrap exit logic inside main.
not_match
Support macro when there is a token mismatch.
not_matches
Support macro to check what type of token mismatch occurs.

Functions§

completion 🔒
Generate shell completions file for rustracer command and its subcommands.
convert 🔒
Convert High Dynamic Range (LDR) image to Low Dynamic Range (HDR).
demo 🔒
Render a demo scene (hard-coded inside main).
main 🔒
Crate main function.
render 🔒
Render a scene from file.