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`](https://github.com/rust-lang/cargo/) stable latest build system (see [`rust-toolchain.toml`](https://github.com/andros21/rustracer/blob/master/rust-toolchain.toml) for stable version) - for **devels** install [`rustup`](https://www.rust-lang.org/tools/install) that will automatically provision the correct toolchain For unit tests coverage [`cargo-tarpaulin`](https://crates.io/crates/cargo-tarpaulin) is required as additional component There is an handy [`makefile`](https://github.com/andros21/rustracer/blob/master/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

```bash ## 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

```bash ## 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}

click to show rustracer -h

```console a multi-threaded raytracer in pure rust Usage: rustracer 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

```console Convert HDR (pfm) image to LDR (ff|png) image Usage: rustracer convert [OPTIONS] Arguments: Input pfm image Output image [possible formats: ff, png] Options: -v, --verbose Print stdout information -f, --factor Normalization factor [default: 1.0] -g, --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`](https://github.com/andros21/rustracer/blob/master/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

```console Render a demo scene (hard-coded in main) Usage: rustracer demo [OPTIONS] Arguments: 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 Image width [default: 640] --height Image height [default: 480] --angle-deg View angle (in degrees) [default: 0.0] -f, --factor Normalization factor [default: 1.0] -g, --gamma Gamma parameter [default: 1.0] -a, --algorithm Rendering algorithm [default: pathtracer] [possible values: onoff, flat, pathtracer] -n, --num-of-rays Number of rays [default: 10] -m, --max-depth Maximum depth [default: 3] --init-state Initial random seed (positive number) [default: 42] --init-seq Identifier of the random sequence (positive number) [default: 54] --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`](https://github.com/andros21/rustracer/blob/master/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`](https://github.com/cue-lang/cue) Let's try to render a 3D fractal, a [sphere-flake](https://en.wikipedia.org/wiki/Koch_snowflake), but without manually write a yaml scene file\ we can automatic generate it from [`examples/flake.cue`](https://github.com/andros21/rustracer/blob/master/examples/flake.cue) ```bash 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

```console Render a scene from file (yaml formatted) Usage: rustracer render [OPTIONS] Arguments: Input scene file Output image [possible formats: ff, png] Options: -v, --verbose Print stdout information --output-pfm Output also hdr image --width Image width [default: 640] --height Image height [default: 480] --angle-deg View angle (in degrees) [default: 0.0] -f, --factor Normalization factor [default: 1.0] -g, --gamma Gamma parameter [default: 1.0] -a, --algorithm Rendering algorithm [default: pathtracer] [possible values: onoff, flat, pathtracer] -n, --num-of-rays Number of rays [default: 10] -m, --max-depth Maximum depth [default: 3] --init-state Initial random seed (positive number) [default: 42] --init-seq Identifier of the random sequence (positive number) [default: 54] --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

```console Generate shell completion script Usage: rustracer completion [OPTIONS] Arguments: Shell to generate script for [possible values: bash, fish, zsh] Options: -o, --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](https://github.com/ziotom78/pytracer) - a simple raytracer in pure Python

a multi-threaded raytracer in pure rust

curl -sSf https://andros21.github.io/rustracer/install.sh | bash (2)

cargo install rustracer (3)

rustracer convert image.pfm image.png

rustracer demo --width 1920 --height 1080 --anti-aliasing 3 demo.png (4)

make demo.gif (4)

rustracer render --anti-aliasing 3 examples/demo.yml demo.png (5)

rustracer render --width 1280 --height 720 --anti-aliasing 3 flake.yml flake.png (5)

rustracer completion bash (6)