a multi-threaded raytracer in pure rust
Prerequisites
Platform requirements
x86_64-unknown-linux-gnu (1) x86_64-unknown-linux-musl
(1) note:
Build requirements
for users install cargo
for devels it's advisable to install the entire (stable latest) toolchain using rustup
For unit tests coverage llvm-tools-preview is required as additional component coupled with\
cargo-llvm-cov
There is an handy makefile
preview documentation built with rustdoc
preview html code coverage analysys created with cargo-llvm-cov
create demo animations
Installation
From binary
Install from binary:
curl -sSf https://andros21.github.io/rustracer/install.sh | bash (2)
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
```
(2) note:~/.local/bin
From source
Install from source code, a template could be:
cargo install rustracer (3)
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
```
(3) note:~/.cargo/bin
Usage
rustracer
| subcommands | description |
| :------------------------------------------------ | :-------------------------------------------- |
| rustracer-convert rustracer-demo rustracer-render rustracer-completion
click to show rustracer -h
```console
rustracer 1.0.0
a multi-threaded raytracer in pure rust
USAGE:
rustracer
OPTIONS:
-h, --help Print help information
-V, --version Print version information
SUBCOMMANDS:
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
```
rustracer convert image.pfm image.png
click to show rustracer-convert -h
```console
rustracer-convert 1.0.0
Convert HDR (pfm) image to LDR (ff|png) image
USAGE:
rustracer convert [OPTIONS]
ARGS:
Input pfm image
Output image [possible formats: ff, png]
OPTIONS:
-f, --factor Normalization factor [default: 0.2]
-g, --gamma Gamma parameter [default: 1.0]
-h, --help Print help information
-v, --verbose Print stdout information
-V, --version Print version information
```
rustracer demo --width 1920 --height 1080 --anti-aliasing 3 -f 1 demo.png
(4)
demo.png: cpu Intel(R) Xeon(R) CPU E5520 @ 2.27GHz | threads 8 | time ~35s
\
demo scene 360 degree (see makefile
make demo.gif (4)
demo.gif: cpu Intel(R) Xeon(R) CPU E5520 @ 2.27GHz | threads 8 | time ~15m
click to show rustracer-demo -h
```console
rustracer-demo 1.0.0
Render a demo scene (hard-coded in main)
USAGE:
rustracer demo [OPTIONS]
ARGS:
Output image [possible formats: ff, png]
OPTIONS:
-a, --algorithm Rendering algorithm [default: pathtracer]
[possible values: onoff, flat, pathtracer]
--angle-deg View angle (in degrees) [default: 0.0]
--anti-aliasing Anti-aliasing level [default: 1]
-f, --factor Normalization factor [default: 0.2]
-g, --gamma Gamma parameter [default: 1.0]
-h, --help Print help information
--height Image height [default: 480]
--init-seq Identifier of the random sequence (positive number)
[default: 45]
--init-state Initial random seed (positive number) [default: 45]
-m, --max-depth Maximum depth [default: 3]
-n, --num-of-rays Number of rays [default: 10]
--orthogonal Use orthogonal camera instead of perspective camera
--output-pfm Output also hdr image
-v, --verbose Print stdout information
-V, --version Print version information
--width Image width [default: 640]
```
(4) note:RAYON_NUM_THREADS to override
rustracer render --anti-aliasing 3 -f 1 examples/demo.yml demo.png (5)
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 -f 1 flake.yml flake.png (5)
flake.png: cpu Intel(R) Xeon(R) CPU E5520 @ 2.27GHz | threads 8 | time ~7h
click to show rustracer-render -h
```console
rustracer-render 1.0.0
Render a scene from file
USAGE:
rustracer render [OPTIONS]
ARGS:
Output image [possible formats: ff, png]
OPTIONS:
-a, --algorithm Rendering algorithm [default: pathtracer]
[possible values: onoff, flat, pathtracer]
--angle-deg View angle (in degrees) [default: 0.0]
--anti-aliasing Anti-aliasing level [default: 1]
-f, --factor Normalization factor [default: 0.2]
-g, --gamma Gamma parameter [default: 1.0]
-h, --help Print help information
--height Image height [default: 480]
--init-seq Identifier of the random sequence (positive number)
[default: 45]
--init-state Initial random seed (positive number) [default: 45]
-m, --max-depth Maximum depth [default: 3]
-n, --num-of-rays Number of rays [default: 10]
--output-pfm Output also hdr image
-v, --verbose Print stdout information
-V, --version Print version information
--width Image width [default: 640]
```
(5) note:RAYON_NUM_THREADS to override
rustracer completion bash (6)
note: close-open your shell, and here we go, tab completions now available!
click to show rustracer-completion -h
```console
rustracer-completion 1.0.0
Generate shell completion script
USAGE:
rustracer completion [OPTIONS]
ARGS:
Shell to generate script for [possible values: bash, fish, zsh]
OPTIONS:
-h, --help Print help information
-o, --output Specify output script file
-V, --version Print version information
```
(6) note:bash>4.1 and bash-complete>2.9
Acknowledgements
pytracer - a simple raytracer in pure Python
