Skip to content

Latest commit

 

History

History
108 lines (82 loc) · 4.38 KB

tutorial.md

File metadata and controls

108 lines (82 loc) · 4.38 KB

Render your first image

You will build Lumen from source, render its reference scene to a PNG file, and see the property Lumen exists for: the image is the same bytes however it is computed. It takes a Rust toolchain and a network connection for the first build; nothing else.

Before you begin

  • Rust 1.96.0, through rustup. The repository's rust-toolchain.toml pins it, and rustup installs it on the first cargo command in the checkout; if yours does not, run rustup toolchain install 1.96.0 there. Without rustup, any Rust 1.96 or later builds it (rust-version in Cargo.toml), but 1.96.0 is the toolchain CI tests.
  • Git and a network connection for the first build: Cargo fetches Lumen's only dependency, Bunny's crates, from https://github.com/flyingrobots/bunny at the commit Cargo.lock pins. Lumen uses no crates.io crate.
  • About 7 MB of disk for the checkout, 30 MB for the build in target/ and 7 MB for the downloaded Bunny sources in Cargo's home (measured on aarch64 Linux).

1. Get the source

git clone https://github.com/flyingrobots/lumen
cd lumen

2. Render the reference scene

cargo run --release -p lumen -- render --out first.png

The first run compiles Bunny and Lumen with whole-program optimization, which takes a while; later runs start at once. Cargo's own lines (Compiling ..., Finished ..., Running ...) go to standard error. Then lumen prints its report. Abridged: the lines shown are exact, and the timing lines it also prints vary from run to run:

scene lumen-reference-scene/4
integrator lumen-diffuse-path/1
size 320x180
samples 4
seed 0
image sha256:d6e4ff7d768e266a30e54a04d62f6a13aeeebd2f6f68f8783faaaff9c7f505a8
png first.png (230699 bytes)

first.png is a 320 by 180 picture: a red bumpy sphere, a blue octahedron and a green Stanford bunny on a pale floor before a stone wall, lit low from the right, with long shadows. Open it with any image viewer.

The image line is the image hash: the SHA-256 of the picture's raw pixel bytes. If yours differs from the line above, something is wrong: Lumen promises this exact value on every machine CI checks, and a test (tests/tutorial.rs) runs these steps there.

3. Render it again on one thread

cargo run --release -p lumen -- render --threads 1

Without --out nothing is written (the report says png none), but the hash is still printed:

threads 1
image sha256:d6e4ff7d768e266a30e54a04d62f6a13aeeebd2f6f68f8783faaaff9c7f505a8

It is the same hash. The first render used every core; this one used one. Every number that decides a pixel is an integer computed by Bunny, and each pixel is computed by one worker on its own, so neither the thread count nor the order the work happens in can change a byte.

4. Try another scene

cargo run --release -p lumen -- render --scene fixed-point --out fixed-point.png
scene lumen-fixed-point-scene/2
image sha256:857f44a50529d6f2656dd7b4279ec6b3aeb5a4e9c6a5c11575896de2e339a95b
png fixed-point.png (230699 bytes)

Fixed Point is the Stanford bunny in sunglasses at a craps table, both dice showing four pips on every face. --scene canyon is the third: craft flying along a fractal canyon, 566 005 triangles, which takes longer to build and to render. For a larger picture, add --width 1280 --height 720 --samples 64: more pixels and more samples per pixel take longer and give a different hash, the same one on every machine.

With the container runner

If you have the maintainers' container runner, devrun, at ~/git/devcontainers/bin/devrun, make demo renders the three scenes at 1280 by 720 in the container, puts them in out/ and opens them; make help lists every target. It is a shortcut for maintainers, not needed for anything above.

What you learned

  • lumen render builds a scene, renders it, prints a report and, with --out, writes a PNG.
  • The image line names the picture exactly, and it does not depend on the thread count.
  • A scene is chosen with --scene; size and samples change the picture and its hash.

Next steps