35个版本

0.8.0 2023年11月12日
0.7.2 2023年4月19日
0.6.0 2020年12月28日
0.5.6 2020年11月23日
0.1.16 2020年3月30日

#89 in 图形API


用于 3 个crates (2 直接)

MIT OR Apache-2.0 OR Zlib

1MB
2.5K SLoC

ɴsɪ

为Illumination Research的节点场景接口提供高级Rust绑定 – ɴsɪ.

Build Documentation Crate Chat

这使得您可以使用Rust轻松访问最先进的3D离线渲染器 – 3Delight.

Moana Island, rendered with 3Delight|ɴsɪ The Moana Island Scene, provided courtesy of Walt Disney Pictures, rendered with 3Delight|ɴsɪ.

这是一个巨大的场景(72GB数据),由3100万个实例、7800万个多边形定义的分形表面几何体和2300个Ptex 纹理组成。上面的图像使用3Delight Cloud在不到两分钟(墙时间)内渲染完成。

示例

// Create a context to send the scene to.
let ctx = nsi::Context::new(None)
    .expect("Could not create NSI context.");

// Create a dodecahedron.

// 12 regular pentagon faces.
let face_index: [i32; 60] =
    [
         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,
    ];

// Golden ratio.
let phi: f32 = 0.5 * (1.0 + 5_f32.sqrt());

// Golden ratio conjugate.
let phi_c: f32 = phi - 1.0;

// 20 points @ 3 vertices.
let positions: [f32; 60] =
    [
         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.,     phi_c,  phi,    0.,     phi_c, -phi,
         0.,    -phi_c,  phi,    0.,    -phi_c, -phi,
         phi_c,  phi,    0.,     phi_c, -phi,    0.,
        -phi_c,  phi,    0.,    -phi_c, -phi,    0.,
         phi,    0.,     phi_c,  phi,    0.,    -phi_c,
        -phi,    0.,     phi_c, -phi,    0.,    -phi_c,
    ];

// Create a new mesh node and call it 'dodecahedron'.
ctx.create("dodecahedron", nsi::MESH, None);

// Connect the 'dodecahedron' node to the scene's root.
ctx.connect("dodecahedron", None, nsi::ROOT, "objects", None);

// 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]
        ),
    ],
);

还可以查看我的扩散限制聚集玩具多面体运算符以获取更多示例代码(演示渲染设置、将网格发送到渲染器、实例化、粒子渲染、OSL着色器、环境(灯光)以及将场景描述写入磁盘)。

欢迎提交PR!

获取像素

此crate支持通过回调(即闭包)从渲染器流式传输像素,这些回调在渲染期间或之后通过output模块执行。此模块通过同名功能启用。

有一个完整的示例显示颜色转换并将数据写入8位/通道PNG和32位/通道(浮点)OpenEXR格式。

依赖关系

此crate依赖于nsi-core,该依赖项要求一个实现ɴsɪ API以生成图像的渲染器。

目前唯一做到这一点的是3Delight,尽管它是商业软件,但自20多年前以来,它一直对个人用户免费。

注意: 3Delight免费版可在您的机器上使用最多12个核心进行渲染。对于更疯狂的项目,您可以使用他们便宜的云渲染服务,这将为您提供无限CPU核心的访问权限。当您注册时,您将免费获得1,000个云分钟,这并不算太差。

话虽如此——我希望这个库能够为其他编写渲染器的人提供灵感,尤其是那些在Rust中采用这个API进行场景描述的人。

先决条件

在您开始之前,建议您下载适用于您平台的3Delight包并进行安装(支持:Linux、macOS、Windows)。这将使您能够立即使用示例创建漂亮的图片。

它还将安装3Delight Display,您可以将渲染结果输出到它,作为将图像写入磁盘的替代方案。当与这个库一起工作时,这非常方便。

您可以跳过此步骤,并使用download_3delight功能进行构建。但是,这将下载3Delight的较旧版本,因此不建议这样做。

Cargo功能

  • output - 添加通过闭包从渲染器流式传输像素到调用上下文的支持。

  • jupyter - 添加对渲染到Jupyter笔记本的支持(当使用Rust Jupyter内核时)。

  • toolbelt - 向Context添加便利方法。

  • delight - 添加一些特定于3Delight的节点和着色器。

  • nightly - 启用一些不稳定的功能(如果您使用nightly工具链进行构建,则建议这样做)。

  • ustr_handles - 使用ustr进行节点句柄。如果您的节点名称在运行使用ɴsɪ的应用程序时没有更改,这将为您提供速度提升,但如果不这样做则不建议使用(ustr永远不会被释放)。

  • download_lib3delight & link_lib3delight - 请参阅下一节。

链接方式

3Delight动态库(lib3delight)可以在构建期间链接或在运行时加载。

默认情况下,库是在运行时加载的。

  • 在运行时加载lib3delight(默认)。这有几个优点

    1. 如果您发布应用程序或库,您可以不带库发布。它仍然可以运行,如果库无法加载,将打印一个有用的错误。

    2. 用户可以安装渲染器的更新版本,一切都会“正常工作”。

  • 动态链接到lib3delight

    • lib3delight成为依赖项。如果找不到它,您的库/应用程序将无法加载/启动。

    • 该功能称为link_lib3delight

    • 您应该禁用默认功能(default-features = false)。

    • 在这种情况下

      [dependencies]
      nsi = { version = "0.7", default-features = false, features = ["link_lib3delight"] }
      
  • 在构建期间下载lib3delight

    • lib3delight在构建期间下载。请注意,这可能是一个过时的版本。此功能主要存在于CI目的。

    • 该功能称为download_lib3delight

文档

库文档可以在docs.rs找到。

C、C++、Lua和Python绑定以及API的介绍和深入探讨可以在此处找到。

寻求帮助

我在3Delight Discord上(我在GitHub上的用户名相同)。在#lobby频道中@我或给我发私信。

此外,还有一个3Delight Slack,其中有一个专门仅限邀请的关于ɴsɪ的频道。

如果您有更高级的问题或希望将ɴsɪ API/export到ɴsɪ的功能添加到您的渲染器/DCC应用程序/等等,请与我联系,我会为您提供邀请。

依赖关系

~2–11MB
~110K SLoC