33 releases (4 breaking)
|0.6.0||Dec 28, 2020|
|0.5.6||Nov 23, 2020|
|0.5.1||Jul 31, 2020|
|0.1.16||Mar 30, 2020|
#24 in Graphics APIs
209 downloads per month
Used in 3 crates (2 directly)
High level Rust bindings for Illumination Research’s Nodal Scene Interface – ɴsɪ.
This puts one of the most advanced 3D production offline renderers at your fingertips in Rust – 3Delight.
The Moana Island Scene, provided courtesy of Walt Disney Pictures, rendered with 3Delight|ɴsɪ.
This is a huge scene (72GB of data) made of 31 million instances, 78 million polygons defining subdivison surface geometry and 2,300 Ptex textures. The above image was rendered in less than two minutes (wall time) using 3Delight Cloud.
// Create a context to send the scene to. let ctx = nsi::Context::new(&) .expect("Could not create NSI context."); // Create a dodecahedron. let face_index: [u32; 60] = // 12 regular pentagon faces. [ 0, 16, 2, 10, 8, 0, 8, 4, 14, 12, 16, 17, 1, 12, 0, 1, 9, 11, 3, 17, 1, 12, 14, 5, 9, 2, 13, 15, 6, 10, 13, 3, 17, 16, 2, 3, 11, 7, 15, 13, 4, 8, 10, 6, 18, 14, 5, 19, 18, 4, 5, 19, 7, 11, 9, 15, 7, 19, 18, 6, ]; let positions: [f32; 60] = // 20 points @ 3 vertices. [ 1., 1., 1., 1., 1., -1., 1., -1., 1., 1., -1., -1., -1., 1., 1., -1., 1., -1., -1., -1., 1., -1., -1., -1., 0., 0.618, 1.618, 0., 0.618, -1.618, 0., -0.618, 1.618, 0., -0.618, -1.618, 0.618, 1.618, 0., 0.618, -1.618, 0., -0.618, 1.618, 0., -0.618, -1.618, 0., 1.618, 0., 0.618, 1.618, 0., -0.618, -1.618, 0., 0.618, -1.618, 0., -0.618, ]; // Create a new mesh node and call it 'dodecahedron'. ctx.create("dodecahedron", nsi::NodeType::Mesh, &); // Connect the 'dodecahedron' node to the scene's root. ctx.connect("dodecahedron", "", ".root", "objects", &); // Define the geometry of the 'dodecahedron' node. ctx.set_attribute( "dodecahedron", &[ nsi::points!("P", &positions), nsi::unsigneds!("P.indices", &face_index), // 5 vertices per each face. nsi::unsigneds!("nvertices", &[5; 12]), // Render this as a subdivison surface. nsi::string!("subdivision.scheme", "catmull-clark" ), // Crease each of our 30 edges a bit. nsi::unsigneds!("subdivision.creasevertices", &face_index ), nsi::floats!( "subdivision.creasesharpness", &[10.; 30] ), ], );
Also check out my Diffusion Limited Aggregation play-thingy or Polyhedron Operators for more example code (demonstrates render settings, sending meshes to the renderer, instancing, particle rendering, OSL shaders, environment (lights) and dumping a scene description to disk).
PRs are most welcome!
The crate has support for streaming pixels from the renderer, via
callbacks (i.e. closures) during and/or after rendering via the
output module. This module is enabled through the feature of the
There is a full example showing color conversion and writing data out to 8bit/channel PNG and 32bit/channel (float) OpenEXR formats.
This crate depends on nsi-sys which in term requires a renderer that implements the ɴsɪ API. Currently the only renderer that does is 3Delight which, though commercial, has been and is free for personal use since over twenty years.
Note: The free version of 3Delight will render with up to 12 cores on your machine. For crazier projects you can use their cheap cloud rendering service that gives you access to unlimited CPU cores. When you register you get 1,000 cloud minutes for free which ain’t too shabby.
That being said – I hope this crate serves as inspiration for other people writing renderers, particularly in Rust, to adopt this API for scene description.
Before you start it is suggested that you download a 3Delight
package for your platform & install
it (supported: Linux, macOS, Windows). This will set the
environment variable that the build script is looking for to find
headers and the library to load/link against.
It will also install 3Delight Display which you can render to, progressively, as an alternative to writing images to disk. When working with this crate this is quite handy.
You can skip this step and build with the
However, this will download an older version of 3Delight so this is
output– Add support for streaming pixels from the renderer to the calling context via closures.
jupyter– Add support for rendering to Jupyter notebooks (when using a Rust Jupyter kernel).
toolbelt– Add convenience methods to
nightly– Enable some unstable features (suggested if you build with a
The 3Delight dynamic library (
lib3delight) can either be linked to
during build or loaded at runtime.
By default the lib is loaded at runtime.
lib3delighat runtime (default). This has several advantages:
- If you ship your application or library you can ship it without the library. It can still run and will print an informative error if the library can not be loaded.
- A user can install an updated version of the renderer and stuff will ‘just work’.
- Dynamically link against
lib3delightbecomes a dependency. If it can not be found your lib/app will not load/start.
- The feature is called
- You should disable default features (they are not needed/used)
- in this case:
[dependencies.nsi] version = "0.5.5" features = [ "link_lib3delight" ] default-features = false
lib3delightis downloaded during build. Note that this may be an outdated version. This feature mainly exists for CI purposes.
- The feature is called
Crate documentation can be found at docs.rs.
Docs for the C, C++, Lua & Python bindings as well as an introduction and deep dive into the API can be found here.
I hang out on the 3Delight Discord server
(I have the same user name as on GitHub). Look for me in the
There is also a 3Delight Slack which has a dedicated, invitation only channel about ɴsɪ. If you have more advanced questions or want to add support for the ɴsɪ API/export to ɴsɪ to your renderer/DCC app/whatever ping me and I get you an invite.