Skip to content
eljojoPublic

About

sunlight leaking through trees

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

605 Commits

Folders and files

Repository files navigation

Komorebi

木漏れ日 — sunlight that leaks through the trees, and the soft, breathing dapples it casts on the ground.

A standalone WebGL2 engine that renders komorebi from physics rather than painting it: a point-sun source seen through canopy layers (shift‑multiply‑summed into dappled light), with two wind bands driving a trunk/limb/twig spring hierarchy. See spec/ for the full vision, physics, and model.

Editor: komorebi.eljojo.net. Examples: examples/ (see live).

Screenshot 2026-08-24 at 19 54 46 Screenshot 2026-08-24 at 19 54 57 Screenshot 2026-08-24 at 19 55 29
see more photos Screenshot 2026-08-24 at 19 56 40 Screenshot 2026-08-24 at 19 55 07 Screenshot 2026-08-24 at 19 55 47 Screenshot 2026-08-24 at 19 57 04

Add it to your page

Download komorebi.player.min.js (about 37 kB gzipped; nix run .#build prints the current size) and put it on your own server. Do not link to the copy on komorebi.eljojo.net. That copy is for the editor and the examples. It changes without notice, and it is not a CDN.

<canvas id="komorebi" style="position:fixed; inset:0; width:100%; height:100%; z-index:-1"></canvas>
<script src="/komorebi.player.min.js"></script>
<script>
  if (window.Komorebi) {
    try {
      Komorebi.create(document.getElementById('komorebi'), { params: Komorebi.PRESETS['morning 2'] });
    } catch (e) { /* no WebGL2 */ }
  }
</script>

Give the canvas a size in CSS. The engine reads that size each frame, so a resize needs no code.

create() throws when the browser has no WebGL2 or no float render targets. Catch it, and the page keeps its background. Test window.Komorebi too, in case the script did not load.

Looks

Komorebi.PRESETS holds the looks:

morning 1 · morning 2 · morning 3 · morning 3b · afternoon 4 · afternoon 4b · afternoon 5 · afternoon 5b · afternoon 6 · afternoon 6b · afternoon 7 · park 2 · prism · memories

Most looks are bright, and dark text stays readable on them. memories is dark. park 2 shows the trees. Open the editor and step with ← → to compare them.

Change the look

eng.transitionTo(Komorebi.PRESETS['afternoon 5b'], { duration: 5 });

The engine selects the transition itself, from the difference between the two looks.

Change a parameter

A look is a plain object. Copy one and set the parameters you want:

Komorebi.create(canvas, { params: { ...Komorebi.PRESETS['morning 2'], wind_strength: 0.4 } });

Komorebi.DEFAULTS holds every parameter at its default value. The editor has a tooltip for each one.

A look saved before November 2026 that leaves out sun_cosine, sun_extinction, edge_area, inner_leaves, exposure or ambient_skylight now takes their new defaults, and may look different: the sun-angle law, the air's loss, soft leaf edges and leaves inside the crown are on by default. To keep it as it was, give it the old values of the ones it leaves out: sun_cosine: 0, sun_extinction: 0, edge_area: false, inner_leaves: 0, exposure: 1.3, ambient_skylight: 0.5. The built-in looks already name what they keep.

The engine handle

const eng = Komorebi.create(canvas, { params, onFrame });
eng.transitionTo(params, { duration, onEnd })   // fade to another look
eng.setParams(params)                           // change look immediately
eng.params                                      // the live parameters
eng.setPaused(true)                             // stop the frame loop
eng.dispose()                                   // free the GL objects and the context

Call eng.dispose() when you remove the canvas. An engine that you drop keeps its context.

Sessions

Opt into device/showing settings with create(canvas, { params, session: {}, environment: { userAgent: navigator.userAgent } }). Use eng.setSession({ quality: 'balanced', presentation: 'projector', playback: { adaptive_motion: false } }) to change this showing. A look may omit fidelity controls to inherit or request less than the session ceiling. Layer count and tone mapping remain authored.

eng.authored is the look's data; eng.params is its concrete render configuration. eng.captureLook() captures edits of live art controls, and eng.setLookRequest(key, undefined) removes a fidelity opinion. Save authored data to preserve inheritance and requests above today's cap. Omitting session retains the existing flat-params API. The editor remembers session preferences locally; embeds supply them explicitly.

The session contract explains profiles, FPS persistence, playlist presentation and export compatibility. Profile values are provisional pending hardware calibration.

ES modules

The bundle wraps ES modules. Import them if you have a bundler:

import { create } from './komorebi.js';
import { PRESETS } from './presets.js';
const eng = create(canvas, { params: PRESETS['morning 2'] });

Serve ES modules over http(s). A page on file:// cannot import them.

A smaller bundle

The bundle contains every shipped look. The experimental looks are not in it: they are the receiver, enclosure and sky-view work, and they are the only looks that use a camera other than the floor.

If your page uses two or three looks, nix run .#embed -- '<look>'... builds a bundle with only those looks, the cameras they use, and the fall tiers they open: the sky fill, the leaf's diffuse share, the autumn pigment, the exposure pass, leaf drop and the litter carpet. A tier none of the looks opens is left out. The three homepage looks ('morning 2' 'afternoon 5b' 'morning 3') come to 84 kB, or 28 kB gzipped, against 36 kB before the fall tiers could be cut; the player bundle keeps every tier, because montebello ships and opens all six. nix run .#embed-check renders each look through the bundle and through the raw modules, and requires the frames to be identical.

If you then switch a page's params to something the bundle was not built for (open canopy_fill on a bundle that left the fill out, say), the tier stays off and the engine logs one console.warn per tier: komorebi: fill is not in komorebi.embed.min.js (...), so it stays off; build a bundle with the look that uses it.

Rendering MP4s

The Mac exporter uses the same scene and deterministic frame clock with four capture pipelines:

--pipeline When to use it How the MP4 is made
master (default) Lossless archives, studies, later re-encoding Lossless RGB segments, then eight-bit HEVC.
gpu Everyday production GPU resize when supersampling, YUV 4:2:0 conversion on the GPU, VideoToolbox eight-bit HEVC.
gpu-main10 Highest measured fidelity, especially faint colours GPU capture, direct P010 conversion, VideoToolbox HEVC Main10. Source RGB remains eight-bit, SDR BT709.
browser Short scene-planning tests Native browser HEVC QP1 from VideoFrame, then MP4 muxing. Fastest in the local comparison, with a small measured fidelity loss.

Pipeline and scene quality are independent. For a 1920x1080 output, --ss 1 renders 1080p directly; --ss 2 renders 3840x2160 and combines four pixels per output pixel in linear light. This reduces sampling artifacts at additional cost; it is 4K down to 1080p. Selecting a GPU pipeline does not force supersampling. Direct pipelines support ss 1 and 2.

nix run .#video -- --look-json look.json --commit <sha> --out test-gl/out/video/preview --seconds 5 --pipeline browser
nix run .#video -- --look-json look.json --commit <sha> --out test-gl/out/video/final --seconds 30 --pipeline gpu-main10 --vt-quality 100 --ss 2

gpu converts each frame to BT.709 limited-range 4:2:0 on the GPU, within a code of ffmpeg's own conversion, and reads back 1.5 bytes a pixel instead of 4. It helps where the CPU is the limit: on an M1 Pro, 4K went from 67.5 to 38.0 ms/frame and 1080p from 25.0 to 19.1, with PSNR against a lossless master unchanged. On a host whose GPU is already the limit the conversion costs about 1.5 ms a frame at 1080p and 3 ms at 4K; --cpu-yuv reads back RGBA and lets ffmpeg convert, as before.

GPU and master pipelines keep the existing 60M bitrate default; --vt-quality 100 chooses highest-fidelity encoding with larger files. Browser QP1 is fixed and refuses VT delivery controls. Main10 is ten-bit YUV 4:2:0, not HDR. All pipelines checkpoint each segment. Direct modes retain encoded segments across interruption, stream-copy the final delivery, verify it and delete those temporary segments. They have no lossless master or raw pixel hashes, so they refuse --measure, --stills, --encode-only, --merge-master and --drop-segments. Their manifest records encoded checksums, the selected pipeline and exact decoded frame accounting.

In two matched 30-second supersampled 1080p60 clips on an M1 Pro, the prototype GPU eight-bit path was 14–16% faster than the master workflow, Main10 12–15% faster and browser 20–22% faster. GPU eight-bit was near-identical to the old MP4; Main10 had the best measured source fidelity and roughly twice the file size. These are two looks, one run per method, before server segment integration; use actual job timing rather than assuming those gains on another machine. The render server exposes these as the job's pipeline field.

On Linux with an AMD GPU, use --chrome chromium+angle-vulkan+enable-gpu --delivery hevc_vaapi with master, gpu or gpu-main10. Rendering uses Vulkan; hardware HEVC encoding uses VA-API on /dev/dri/renderD128, with NV12 for Main or P010 for Main10. The fixed 60M bitrate has a 75M cap and 120M buffer. Software frames are converted to YUV and uploaded before hardware encoding. VideoToolbox delivery controls and the browser pipeline remain Mac-only. Hardware initialization or encoding failures stop the export, with no CPU fallback. --delivery libx265 remains an explicit CPU option for master exports. --delivery none --stills 0 captures a still without a video delivery.

Mesa graphics and LIBVA_DRIVER_NAME=radeonsi with LIBVA_DRIVERS_PATH pointing at Mesa's video drivers are required. On NixOS, use patched Chromium with the same Playwright version as test-gl/package.json; the flake's Linux devShell and komorebi-render's Linux package provide that environment. Run the hardware checks with nix develop -c node --test test-gl/vaapi-gpu.test.mjs: they interrupt and resume each pipeline, verify decoded frames and colour tags, and include 4K Main10.

Develop

ES‑module dev needs http (not file://). With Nix:

nix run .#dev      # serve + live‑reload at http://localhost:8000
nix run .#test     # the unit tests (bun, no browser)
nix run .#lint     # biome
nix run .#build    # bundle dist/komorebi.player.min.js (every shipped look, no experimental ones)
node glslcheck.mjs # offline shader validation — compiles every GLSL literal in the engine modules (glslangValidator, no GPU)
nix run .#pixels   # the pixel harness — render every look + pixel suites (first run: cd test-gl && npm install && npx playwright install chromium)
nix run .#editor   # the editor smoke — mode ladder + macro bus driven in headless Chromium (same first-run setup)
nix run .#embed -- 'morning 2' 'afternoon 5b' 'morning 3'   # a one-page bundle: only those looks, only the cameras they use
nix run .#embed-check                                       # ...and check it renders them byte-identically
nix run .#arboretum-dev     # arboretum (arboretum/) and this checkout on https://localhost:8787 (first run: cd arboretum && nix develop -c npm ci)
nix run .#arboretum-test    # arboretum's typecheck and tests
nix run .#arboretum-deploy  # deploy komorebi.eljojo.net (the Worker and the site) from HEAD

CLAUDE.md is the repo map. A push to main builds dist/ and publishes the site.

Credits

Komorebi stands on research into how real trees grow and how real leaves handle light.

In the engine

  • Trees grown year by year from buds (komorebi-growth.js): W. Pałubicki, K. Horel, S. Longay, A. Runions, B. Lane, R. Měch and P. Prusinkiewicz, "Self-organizing tree models for image synthesis", ACM Transactions on Graphics 28(3), SIGGRAPH 2009; with R. Borchert and H. Honda (1984), Botanical Gazette 145, for the resource split, and A. Takenaka (1994), Journal of Plant Research 107, for shedding.
  • Fallen leaves' colour (komorebi-litter.js): P. Kubelka and F. Munk (1931), Zeitschrift für technische Physik 12, and P. Kubelka (1948), Journal of the Optical Society of America 38.
  • The autumn pigments (komorebi-season.js), fitted to how a leaf reflects and passes light and what its pigments absorb: S. Jacquemoud and F. Baret (1990), PROSPECT, Remote Sensing of Environment 34; J.-B. Féret, A. A. Gitelson, S. D. Noble and S. Jacquemoud (2017), PROSPECT-D, Remote Sensing of Environment 193; computed from the prospect R package, J.-B. Féret and F. de Boissieu (2024), Journal of Open Source Software 9(94), 6027. PROSPECT-D also gives the seen leaf below its scattering.
  • The tree seen from the floor camera (komorebi-tree-view.js): a leaf as two faces of one Kubelka–Munk slab, M. Hébert and J.-M. Becker (2008), Journal of Optics A 10, 035006; its surface's index, L. Bousquet, S. Lachérade, S. Jacquemoud and I. Moya (2005), Remote Sensing of Environment 98; its two faces measured, T. W. Brakke, J. A. Smith and J. M. Harnden (1989), Remote Sensing of Environment 29, and T. Brakke (1994), Agricultural and Forest Meteorology 71; the bark's reflectance, J. Juola, A. Hovi and M. Rautiainen (2022), Ecology and Evolution 12, e8718.
  • Leaves on shoots, by light (komorebi-shoots.js): R. A. Gregory (1980), Canadian Journal of Forest Research 10, sugar maple's shoots; S. Dupré, B. Thiébaut and E. Teissier du Cros (1986), Annales des Sciences Forestières 43, and D. Lemoine, S. Jacquemin and A. Granier (2002), Annals of Forest Science 59, beech's short and long shoots in sun and shade; I. Planchais and H. Sinoquet (1998), Agricultural and Forest Meteorology 89, leaf angle in sun and shade; the light from above, after Pałubicki et al. (2009).
  • Leaf-out, the spring half (komorebi-season.js): R. A. Gregory (1980), Canadian Journal of Forest Research 10, a sugar maple leaf's growth; the University of Vermont's Forest Ecosystem Monitoring Cooperative, sugar maple bud break and leaf-out at Proctor Maple Research Center; X. Yang, J. Tang, J. F. Mustard et al. (2016), Remote Sensing of Environment 179, a young leaf's pigments over the spring; M. N. Merzlyak, O. B. Chivkunova, A. E. Solovchenko and K. R. Naqvi (2008), Journal of Experimental Botany 59, the red of young Norway maple leaves.

Informing the work in progress (sun and shade leaves, and the light inside a crown)

  • R. Habel, A. Kusternig and M. Wimmer (2007), Eurographics Symposium on Rendering: a leaf's translucency.
  • H. A. Bahamonde, L. Gil and V. Fernández (2018), Frontiers in Plant Science 9: sun and shade leaves of beech and oak.
  • A. Hovi, P. Forsström, G. Ghielmetti, M. E. Schaepman and M. Rautiainen (2020), ISPRS Journal of Photogrammetry and Remote Sensing 169: light scattered within a crown.
  • J. Juola, A. Hovi and M. Rautiainen (2020), Silva Fennica 54(4): the colour of bark.
  • F. E. Putz, G. G. Parker and R. M. Archibald (1984), American Midland Naturalist 112: crown shyness.

About

sunlight leaking through trees

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages