diff --git a/.gitattributes b/.gitattributes index 25ddd92..a9463b9 100644 --- a/.gitattributes +++ b/.gitattributes @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 91ceaee..292277e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index 5b66255..db0d45a 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 diff --git a/docs/images/lumen-canyon-1280x720-64spp.png b/docs/images/lumen-canyon-1280x720-64spp.png new file mode 100644 index 0000000..c564fe2 Binary files /dev/null and b/docs/images/lumen-canyon-1280x720-64spp.png differ diff --git a/docs/images/lumen-fixed-point-1280x720-64spp.png b/docs/images/lumen-fixed-point-1280x720-64spp.png new file mode 100644 index 0000000..df5d55b Binary files /dev/null and b/docs/images/lumen-fixed-point-1280x720-64spp.png differ diff --git a/docs/images/lumen-reference-1280x720-64spp.png b/docs/images/lumen-reference-1280x720-64spp.png new file mode 100644 index 0000000..f34456e Binary files /dev/null and b/docs/images/lumen-reference-1280x720-64spp.png differ diff --git a/docs/reference/scenes.md b/docs/reference/scenes.md index 2a522f7..546b2bf 100644 --- a/docs/reference/scenes.md +++ b/docs/reference/scenes.md @@ -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.