|
1 | | -# three.js-Volume-Renderer |
2 | | -A customizable volume renderer for three.js. |
| 1 | +# three.js Volume Renderer |
| 2 | + |
| 3 | +A lightweight volume renderer for [three.js](https://threejs.org/) that uses raymarching to render procedurally defined or data-driven 3D volumes in real time. |
| 4 | + |
| 5 | +**Try the demo on GitHub pages:** [https://donitzo.github.io/three.js-volume-renderer](https://donitzo.github.io/three.js-volume-renderer) |
| 6 | + |
| 7 | +## Description |
| 8 | + |
| 9 | +The volume renderer is implemented as a single `VolumeRenderer` class that extends `THREE.Mesh` with a raymarching fragment shader. You can either provide your own 3D volumetric data or supply a custom function in GLSL to create complex procedural shapes or surfaces. The example 3D texture is the soot visibility from a smoke simulation rendered using the [Fire Dynamics Simulator](https://pages.nist.gov/fds-smv/). |
| 10 | + |
| 11 | +The renderer works as a fullscreen postprocessing effect which renders on top of existing geometry. |
| 12 | + |
| 13 | +The volume renderer features: |
| 14 | + |
| 15 | +- Normal estimation for lighting. |
| 16 | +- Depth testing. |
| 17 | +- Color palettes with transparent cutoff range. |
| 18 | +- Extinction coefficients for translucency. |
| 19 | +- Rendering of static or animated 3D volume data atlas texture. This could for example be an MRI or smoke. |
| 20 | + |
| 21 | +## Samples |
| 22 | + |
| 23 | +Below are some sample outputs generated by different distance functions and the volumetric smoke data. Each row shows an animated view alongside its corresponding “normals” rendering.. |
| 24 | + |
| 25 | +| Name | Animation |Normals | |
| 26 | +|------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------| |
| 27 | +| Soot Visibility |  |  | |
| 28 | +| Pulsing Sphere |  |  | |
| 29 | +| Square Sphere |  |  | |
| 30 | +| Doughnut |  |  | |
| 31 | +| Rings |  |  | |
| 32 | +| Twister |  |  | |
| 33 | +| Gyroid |  |  | |
| 34 | +| Tunnel |  |  | |
| 35 | +| Mandelbulb |  |  | |
| 36 | +| Wobbly Sphere |  |  | |
| 37 | +| Surface |  |  | |
| 38 | +| Smoke |  |  | |
| 39 | +| Sine Flow |  |  | |
| 40 | + |
| 41 | +## What is Raymarching? |
| 42 | + |
| 43 | +Raymarching is a rendering technique where, for each pixel, we cast a ray into a scene and advance it in small steps. At each step along the ray, we sample volume data (e.g. density, extinction coefficient, distance function) and accumulate it (e.g., via alpha blending or by estimating a mean value) until the ray exits the volume. Unlike surface-based raymarchers that stop at the first hit, this approach processes the entire volume along the ray. |
| 44 | + |
| 45 | +When alpha blending is used, an extinction coefficient determines how much light is absorbed at each step, allowing you to see through semi-transparent volumes like smoke or mist. If lighting is enabled, we also estimate a normal at each step by computing the forward difference of the volume data, letting you illuminate the volume with directional or point lights for more realistic shading. |
| 46 | + |
| 47 | +In other words, raymarching gives you a flexible way to render volumetric effects—whether that means blending partial transparency for smoke-like objects or simply accumulating a mean value for diagnostic or statistical visualization. |
| 48 | + |
| 49 | +## Instructions |
| 50 | + |
| 51 | +1. Import the VolumeRenderer (update the three.js import in the file) |
| 52 | + ```js |
| 53 | + import VolumeRenderer from './VolumeRenderer.js'; |
| 54 | + ``` |
| 55 | + |
| 56 | +2. Add a VolumeRenderer instance to the scene |
| 57 | + ```js |
| 58 | + const volumeRenderer = new VolumeRenderer(); |
| 59 | + scene.add(volumeRenderer); |
| 60 | + ``` |
| 61 | + |
| 62 | +3. Load or define volume data |
| 63 | + - **Option A**: Call `volumeRenderer.createAtlasTexture(...)` to set up a 3D texture for your data, then fill it with actual values using `volumeRenderer.updateAtlasTexture(...)`. |
| 64 | + - **Option B**: Provide a custom distance function in `volumeRenderer.updateMaterial({ customFunction: myGLSLFunction })`. |
| 65 | + |
| 66 | +4. Update shader defines and uniforms |
| 67 | + - The shader’s behavior is configured by defines, which you can set via `volumeRenderer.updateMaterial(...)`. |
| 68 | + - There are many different uniforms to configure under `volumeRenderer.uniforms`. Look in the class for the documentation. |
| 69 | + - If you want animated effects (like pulsing or noise dithering), you can update these uniforms every frame in your render loop: |
| 70 | + ```js |
| 71 | + // In your animation loop: |
| 72 | + const dt = clock.getDelta(); // or however you track delta time |
| 73 | + volumeRenderer.uniforms.time.value += dt; |
| 74 | + volumeRenderer.uniforms.random.value = Math.random(); |
| 75 | + ``` |
| 76 | + |
| 77 | +## Feedback & Bug Reports |
| 78 | + |
| 79 | +If there are additional variations you would find useful, or if you find any bugs or have other feedback, please [open an issue](https://github.com/Donitzo/three.js-volume-renderer/issues). |
0 commit comments