Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/andros21/rustracer
rustracer - a multi-threaded raytracer in pure rust
https://github.com/andros21/rustracer
cargo clap cosign coverage cue rayon raytracing rust slsa yaml
Last synced: 2 months ago
JSON representation
rustracer - a multi-threaded raytracer in pure rust
- Host: GitHub
- URL: https://github.com/andros21/rustracer
- Owner: andros21
- License: gpl-3.0
- Created: 2022-03-09T08:40:40.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-10-27T07:41:06.000Z (3 months ago)
- Last Synced: 2024-10-27T08:42:00.181Z (3 months ago)
- Topics: cargo, clap, cosign, coverage, cue, rayon, raytracing, rust, slsa, yaml
- Language: Rust
- Homepage: https://andros21.github.io/rustracer/docs
- Size: 27.8 MB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
## Prerequisites
### Platform requirements
- `x86_64-unknown-linux-gnu` (1)
- `x86_64-unknown-linux-musl`
(1) 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 (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: will install latest musl release in ~/.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: will install latest release in ~/.cargo/bin
## Usage
### rustracer
| **subcommands** | **description** |
| :------------------------------------------------ | :------------------------------------------- |
| [**rustracer-convert**](#rustracer-convert) | convert an hdr image into ldr image |
| [**rustracer-demo**](#rustracer-demo) | render a simple demo scene (example purpose) |
| [**rustracer-render**](#rustracer-render) | render a scene from file (yaml formatted) |
| [**rustracer-completion**](#rustracer-completion) | generate shell completion script (hidden) |
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 (4)
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)):
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
```
(4) 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 (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 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
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
```
(5) 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 (6)
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
```
(6) note: bash>4.1 and bash-complete>2.9
## Acknowledgements
- [pytracer](https://github.com/ziotom78/pytracer) - a simple raytracer in pure Python
