Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,7 @@ assets/stanford-bunny-pbr/*.jpg binary -filter
assets/stanford-bunny-pbr/*.png binary -filter
assets/stanford-bunny-pbr/model.dae -text -filter
assets/stanford-bunny-pbr/README.md text
# The README's images are lossless re-encodings whose decoded pixels are checked against the image
# hash printed beside each: never filter, convert or diff them as text (a contributor's global LFS
# rule must not turn one into a pointer).
docs/images/*.png binary -filter
14 changes: 9 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,11 +161,15 @@ part was built.
file in, an output directory, versioned JSON Lines on standard output and on standard error, and
published JSON Schemas; the key-value report is to be retired. Nothing is built yet.
(flyingrobots/lumen#218; built by #219 to #222.)
- **Documentation**: the README as a short router, a [tutorial](docs/tutorial.md), the command,
library and scene references, an [explanation](docs/explanation.md) ending in a
requirement-to-evidence map, a how-to for measuring render time, a
[contributor guide](CONTRIBUTING.md), an [index](docs/README.md), ADRs 0001 to 0009 and dated
measurement records in `docs/measurements/`. (flyingrobots/lumen#5, #25, #39, #40, #57.)
- **Documentation**: the README as a short router, opening with a rendered picture of the reference
scene and showing Fixed Point and the canyon beside the command and image hash of each (three
1280 by 720, 64 samples per pixel renders in `docs/images/`, lossless re-encodings of the PNGs
`lumen` writes, 2.98 MB in all, kept out of every Git filter by `.gitattributes`), a
[tutorial](docs/tutorial.md), the command, library and scene references, an
[explanation](docs/explanation.md) ending in a requirement-to-evidence map, a how-to for
measuring render time, a [contributor guide](CONTRIBUTING.md), an [index](docs/README.md), ADRs
0001 to 0009 and dated measurement records in `docs/measurements/`. (flyingrobots/lumen#5, #25,
#39, #40, #57, #180.)
- **ADR 0012** ([image decoding](docs/adr/0012-image-decoding.md)): PNG and JPEG are decoded by
Lumen's own float-free code in a dependency-free `lumen-image` crate, with the supported and
refused features of each format stated. The crate is built by #195 to #199.
Expand Down
81 changes: 67 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,65 @@
# Lumen

Lumen is a deterministic ray tracer: a [Geordi](https://github.com/flyingrobots/geordi) runtime
built on [Bunny](https://github.com/flyingrobots/bunny)'s fixed-point math. It renders a scene to
the same bytes, and so the same image hash, on every run, at every thread count, and on every
platform CI checks: x86-64 and aarch64 Linux, aarch64 macOS, x86-64 Windows and WebAssembly
(`wasm32-wasip1`). Each part of that claim is mapped to the tests that check it in the
[evidence map](docs/explanation.md#requirements-and-their-evidence).

It renders three built-in scenes: a reference scene (a bumpy red sphere, a blue octahedron and
the Stanford bunny before a stone wall, under a low sun and a pale sky), Fixed Point (the
full-resolution bunny in sunglasses at a craps table) and a canyon (three craft flying along a
fractal canyon under a banded planet, 566 005 triangles). Every sample is one diffuse path with a
shadow ray and one bounce, all in Bunny's integer arithmetic, and the image is written as a PNG.
Lumen is a ray tracer that renders the same image bytes on every machine: a
[Geordi](https://github.com/flyingrobots/geordi) runtime built on
[Bunny](https://github.com/flyingrobots/bunny)'s fixed-point math.

![The reference scene: a red sphere with a bumpy surface, a blue octahedron and a green Stanford bunny stand on a grey floor before a cream wall, under a pale blue sky.](docs/images/lumen-reference-1280x720-64spp.png)

*The reference scene, `lumen-reference-scene/4`, 1280 by 720 at 64 samples per pixel.*

A render has the same bytes, and so the same image hash, on every run, at every thread count, and
on every platform CI checks: x86-64 and aarch64 Linux, aarch64 macOS, x86-64 Windows and
WebAssembly (`wasm32-wasip1`). Each part of that claim is mapped to the tests that check it in the
[evidence map](docs/explanation.md#requirements-and-their-evidence). Every sample is one diffuse
path with a shadow ray and one bounce, all in Bunny's integer arithmetic, and the image is written
as a PNG.

## The three built-in scenes

Each image below is a render by Lumen at 1280 by 720, 64 samples per pixel and seed 0, re-encoded
losslessly into a smaller PNG file. Its pixels are exactly the render's: the image hash is
SHA-256 over the decoded RGBA8 bytes and identifies an image only together with its size
([ADR 0009](docs/adr/0009-image-hash.md)). Each output excerpt below is abridged: the two lines
shown are exact, in the order the command prints them, and the other lines of the report are
omitted.

The reference scene (above) is a bumpy sphere, an octahedron and the Stanford bunny before a wall.

```sh
cargo run --release -p lumen -- render --scene reference --width 1280 --height 720 --samples 64 --out reference.png
```

```text
size 1280x720
image sha256:7d68fa3ab47c19ba6cee947836b49ad52e4e0891f2a4b41562192576d1700a6e
```

Fixed Point is the full-resolution bunny in sunglasses at a craps table.

![Fixed Point: a white Stanford bunny in black sunglasses sits on a green craps table with white betting lines and numbers, an ON puck and two red dice in front of it.](docs/images/lumen-fixed-point-1280x720-64spp.png)

```sh
cargo run --release -p lumen -- render --scene fixed-point --width 1280 --height 720 --samples 64 --out fixed-point.png
```

```text
size 1280x720
image sha256:86cdfd58d7745297b52f63f443cedd789a773996c66ad57d45b5d8a6f67fb153
```

The canyon is three craft flying along a fractal canyon under a banded planet (566 005 triangles).

![The canyon: an orange, a white and a teal craft fly down a rocky brown canyon under a banded planet in a dark sky, and a white bunny sits on a ledge at the left.](docs/images/lumen-canyon-1280x720-64spp.png)

```sh
cargo run --release -p lumen -- render --scene canyon --width 1280 --height 720 --samples 64 --out canyon.png
```

```text
size 1280x720
image sha256:1bd910dcea9c3daaa3ea57e3972a639202aa341ba59e0e075a2e55184dc56446
```

## Render an image

Expand All @@ -23,14 +71,19 @@ cd lumen
cargo run --release -p lumen -- render --out first.png
```

The report ends with the image hash of the reference scene, `lumen-reference-scene/4`, which is
the same on every platform CI checks:
The report holds the image hash of the reference scene at the default 320 by 180, 4 samples per
pixel, the same on every platform CI checks (abridged: the two lines shown are exact, and the
other lines of the report are omitted):

```text
image sha256:d6e4ff7d768e266a30e54a04d62f6a13aeeebd2f6f68f8783faaaff9c7f505a8
png first.png (230699 bytes)
```

To render all three scenes at the size above, run the three commands in the previous section; the
canyon takes the longest. Maintainers with the container runner `devrun` run `make demo`, which
renders them into `out/` and opens each image.

The [tutorial](docs/tutorial.md) goes on from there.

## Documentation
Expand Down
Binary file added docs/images/lumen-canyon-1280x720-64spp.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/lumen-fixed-point-1280x720-64spp.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/lumen-reference-1280x720-64spp.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
5 changes: 3 additions & 2 deletions docs/reference/scenes.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,8 +276,9 @@ off the face and chest.
`lumen-canyon-scene/1` (`crates/lumen/src/scenes/canyon/`) is a large-triangle-count scene and a
picture: a fractal canyon of integer terrain, three small craft of lumen's own design flying
along it in a chase, the full-resolution Stanford bunny on a ledge, a low sun, a near-black sky
and a banded planet. Composition after a 1990s canyon-chase render; no image from it is in the
repository. The library builds it with `lumen::canyon_scene()`; `canyon_content()` returns its
and a banded planet. Composition after a 1990s canyon-chase render; the
[README](../../README.md#the-three-built-in-scenes) shows its render. The library builds it with
`lumen::canyon_scene()`; `canyon_content()` returns its
566 005 triangles in primitive order (the terrain, each craft's hull and engines, the bunny, the
planet's bands) with the part each belongs to, its material and its vertex normals. Every
coordinate is a whole number of `2^-16` grid steps.
Expand Down
Loading