README.md 8.76 KB
Newer Older
Paolo Berto Durante's avatar
Paolo Berto Durante committed
1 2 3 4
# HydraNSI (hdNSI)

This repository contains a render delegate for Hydra using the NSI technology.

5 6
![](/uploads/8bc6d08ad137bea790682be25bd9f5f3/nsi_kitchen.png)

Paolo Berto Durante's avatar
Paolo Berto Durante committed
7

Paolo Berto Durante's avatar
Paolo Berto Durante committed
8 9
| Kitchen | Hair | Points |
| -------- | -------- | -------- | 
Paolo Berto Durante's avatar
Paolo Berto Durante committed
10
| ![](/uploads/c9e2fa6aa4f3cf0f559e6c71efd0b5e8/nsi_kitchen_detail.png) | ![](/uploads/53a9d2d71039d834649beeff557c1fb1/nsi_1M_hair.png)   | ![](/uploads/444a58398fd19d55e2dffd0520736e23/pointcloud-color-size.png)  |
Paolo Berto Durante's avatar
Paolo Berto Durante committed
11

Paolo Berto Durante's avatar
Paolo Berto Durante committed
12

Paolo Berto Durante's avatar
Paolo Berto Durante committed
13 14 15
![](https://assets.gitlab-static.net/uploads/-/system/project/avatar/7466299/nsi_logo_round.png)


Paolo Berto Durante's avatar
Paolo Berto Durante committed
16 17 18 19 20 21 22 23
## Background

**Hydra**
Pixar USD (Universal Scene Description) introduced a model/API called Hydra (allegedly named after the multi-headed monster in Greek mythology). Hydra allows different sources of graphic data (indeed called "heads") to produce images of a 3D scene via rendering backends which receive live data updates (scene edits).

> https://github.com/PixarAnimationStudios/USD

**NSI**
Paolo Berto Durante's avatar
Paolo Berto Durante committed
24
NSI (Nodal Scene Interface) is a simple and flexible scene description API which is purposely designed to communicate with a render engine. It is used by the new 3Delight NSI renderer together with OSL (Open Shading Language) for shading. One of the goals of NSI is interactive rendering of editable scene descriptions: this feature, as well as many other, make NSI a perfect candidate for a Hydra rendering backend which we call HydraNSI (*hdNSI*). 
Paolo Berto Durante's avatar
Paolo Berto Durante committed
25

26
> https://gitlab.com/3DelightOpenSource/HydraNSI/blob/master/nsi.pdf
Paolo Berto Durante's avatar
Paolo Berto Durante committed
27

Paolo Berto Durante's avatar
Paolo Berto Durante committed
28
HydraNSI can be easily compiled as a plug-in part of the USD toolset. It can naturally be used by any current and future application that implements the USD API as a data model, and which uses Hydra for visualization. As a practical example, it can be added to the USD viewing utility **usdview**.
Paolo Berto Durante's avatar
Paolo Berto Durante committed
29

30
## Demo Videos
31

Paolo Berto Durante's avatar
Paolo Berto Durante committed
32
![Demo Video](https://gitlab.com/3DelightOpenSource/HydraNSI/uploads/683abdd0535432b4483ff9135833ebcf/out.mp4)
33

34 35 36
And other 8 videos here:

https://gitlab.com/3DelightOpenSource/HydraNSI/wikis/Videos
Paolo Berto Durante's avatar
Paolo Berto Durante committed
37

38

39
## Building
Paolo Berto Durante's avatar
Paolo Berto Durante committed
40
> This code was tested with Pixar USD version **18.09**.
41
> The minimum 3Delight NSI version needed is **v13.4.15**.
42

43
Once  you are able to build Pixar USD, building HydraNSI is very easy:
44 45 46 47 48


1. Add the hdNSI folder to your USD distribution, the injection point being:
  https://github.com/PixarAnimationStudios/USD/tree/master/pxr/imaging/plugin
  
Paolo Berto Durante's avatar
Paolo Berto Durante committed
49
2. Make sure to use a CMAKE set to build *hdNSI*:
Paolo Berto Durante's avatar
Paolo Berto Durante committed
50 51 52 53

| CMAKE Variable       | Value     |
| -------------------- | --------- |
| PXR_BUILD_NSI_PLUGIN | 1         |
54 55

  
Paolo Berto Durante's avatar
Paolo Berto Durante committed
56
3. Obtain a copy of 3Delight | NSI containing the rendering library, include headers and OSL shaders, then set the following CMAKE variables:
Paolo Berto Durante's avatar
Paolo Berto Durante committed
57

Paolo Berto Durante's avatar
Paolo Berto Durante committed
58 59 60 61 62 63 64 65
| CMAKE Variable  | Value                       |         |                                                         |
| --------------- | --------------------------- | ------- | ------------------------------------------------------- |
| NSI_INCLUDE_DIR | /path/to/nsi-include-folder | Linux   | /usr/local/3delight-version/Linux_64/include            |
|                 |                             | macOS   | /Applications/3Delight/include                          |
|                 |                             | Windows | C:\Program Files\3Delight\include                       |
| NSI_LIBRARY     | /path/to/nsi-library-file   | Linux   | /usr/local/3delight-version/Linux_64/lib/lib3delight.so |
|                 |                             | macOS   | /Applications/3Delight/lib/lib3delight.dylib            |
|                 |                             | Windows | C:\Program Files\3Delight\lib                           |
66

67
## Features
68 69 70 71

Currently HydraNSI supports the following:

- Geometric primitives:
72 73
  - Polygon mesh
  - Subdivision surfaces
Paolo Berto Durante's avatar
Paolo Berto Durante committed
74
  - Points (particles/pointclouds)
75 76 77
  - Curves (hair/fur)
- Instancing of primitives
- Cameras
Paolo Berto Durante's avatar
Paolo Berto Durante committed
78 79 80
- Shading (PBR):
  - Polygons (and subdivisions) use a *dl3DelightMaterial* material which defaults to a mostly diffusive material (Oren-Nayar model) with a degree of glossy reflection (GGX model).
  - Points also use a *dl3DelightMaterial* material, with a higher reflection roughness. 
81
  - Curves are shaded with the *dlHairAndFur* material (Marschner-Chiang-d'Eon model).
Paolo Berto Durante's avatar
Paolo Berto Durante committed
82

Paolo Berto Durante's avatar
Paolo Berto Durante committed
83
  > Note that the shading network for points and curves have a *dlPrimitiveVariable* so to read per-point and per-curve-vertex color.
Paolo Berto Durante's avatar
Paolo Berto Durante committed
84

85
- Lighting:
Paolo Berto Durante's avatar
Paolo Berto Durante committed
86 87
  - Head light: a directional light that uses a *directionalLight* emitter which shines from the camera pov. It is always active. Note that in NSI directional lights are actual environment lights: when an angle of 0 degrees is specified they behave directionally. See nsi.pdf for more informations. 
  - Omni environment: this is another directional light that uses another *directionalLight* emitter. It is used when a file texture is *not* set to be used for environment in the configuration (see below). As per above this is an environment light, though when an angle of 360 degrees it behaves like a uniform environment.
88 89
  - HDRI environment: this is a small shading network using *uvCoordEnvironment --> file --> dlEnvironmentShape* which allows to optionally use a HDRI file texture for image-based lighting. It can be enabled via environment variable. Use the HDNSI_ENV_LIGHT_IMAGE environment variable pointing at the file location on disk (.tdl, .exr and .hdr formats are accepted). For more info see: https://gitlab.com/3DelightOpenSource/HydraNSI/blob/master/hdNSI/config.cpp. HDRI environment can be created by using data from http://gl.ict.usc.edu/Data/HighResProbes and then process them as tiled mipmaps using the following command: *tdlmake -envlatl filename.exr filename.tdl.tif*
  - Procedural Sky environment: this is a small shading network using *dlSky --> dlEnvironmentShape* which uses a HDRI procedural sky (Hosek-Wilkie model) for (procedural) image-based lighting. It is enabled by default and can be disabled by setting the HDNSI_ENV_USE_SKY environment variable set to. For more info see: https://gitlab.com/3DelightOpenSource/HydraNSI/blob/master/hdNSI/config.cpp.
90

91
## Testing
92 93 94

From an environment where both `usdview` and the NSI command-line renderer `renderdl` can be executed:

95 96 97 98 99 100
- On your terminal, launch `usdview`:
  
    ```bash
    usdview /path/to/file.usd
    ```
- Switch to View> Hydra Renderer: “NSI”.
Paolo Berto Durante's avatar
Paolo Berto Durante committed
101
- Try loading some USD or ABC files, e.g:
Paolo Berto Durante's avatar
Paolo Berto Durante committed
102 103 104
  - [Kitchen](http://graphics.pixar.com/usd/files/Kitchen_set.zip)
  - [Instanced city](http://graphics.pixar.com/usd/files/PointInstancedMedCity.zip)
  - [Apple USDZ examples](https://developer.apple.com/arkit/gallery) -- Note that USDZ is basically a zip file with no compression: you can rename the files from .usdz to .zip and unzip them to access the actual .usd files.
105
- In `usdview` you can set "View> Complexity: Medium" to enable subdivision surfaces. 
106
- Optionally configure HydraNSI settings via (see: https://gitlab.com/3DelightOpenSource/HydraNSI/blob/master/hdNSI/config.cpp).
107
- Further explore the source code and issues in this repository & contribute.
108

109
> Contributors may contact us at [support@3delight.com](mailto:support@3delight.com) to obtain a copy of 3Delight NSI for development purposes.
110 111


Paolo Berto Durante's avatar
Paolo Berto Durante committed
112 113
## A note about Alembic files and primitive variables

Paolo Berto Durante's avatar
Paolo Berto Durante committed
114
When reading Alembic files in usdview some variables that control the color and width of primitives will not be read even if the attribute naming matches the USD one. The USD Alembic plug-in reader should be improved by the USD team so to handle proper support of such primitive variables, it could additionally recognize typical primitive variables of DCC Apps (for example in Houdini *Cd*, *width* and *pscale* are standard names and if present they could be converted on-the-fly to the USD respective ones). Feel free to push Pixar in improving their Alembic plug-in (see [USD issue 569](https://github.com/PixarAnimationStudios/USD/issues/569)).  
Paolo Berto Durante's avatar
Paolo Berto Durante committed
115 116


117 118 119 120
## Future

We are looking for community contributions to implement the following:

Paolo Berto Durante's avatar
Paolo Berto Durante committed
121
- add **usdShade** schema support for 3Delight OSL materials: [Issue #1](https://gitlab.com/3DelightOpenSource/HydraNSI/issues/1)
122
- add **usdLux** schema support for 3Delight OSL lights: [Issue #2](https://gitlab.com/3DelightOpenSource/HydraNSI/issues/2)
Paolo Berto Durante's avatar
Paolo Berto Durante committed
123 124
- add upcoming **usdVolume** schema support for 3Delight OpenVDB volumes: [Issue #3](https://gitlab.com/3DelightOpenSource/HydraNSI/issues/3)
- add OSL matching shaders for **UsdPreviewSurface**: [issue #4](https://gitlab.com/3DelightOpenSource/HydraNSI/issues/4)
125 126 127 128


## Feedback & Contributions

129
Feel free to log issues or submit pull requests on this repository. Contributors will added to the be credits.
Paolo Berto Durante's avatar
Paolo Berto Durante committed
130

131
If you need to get in touch with us e-mail [support@3delight.com](mailto:support@3delight.com)
132 133 134 135 136 137


## Credits

This work was authored by:

Paolo Berto Durante's avatar
Paolo Berto Durante committed
138
**J Cube Inc.** — Marco Pantaleoni, Bo Zhou, Paolo Berto Durante
Paolo Berto Durante's avatar
Paolo Berto Durante committed
139

Paolo Berto Durante's avatar
Paolo Berto Durante committed
140
Copyright © 2018 Illumination Research Ptv Ltd.
141

Paolo Berto Durante's avatar
Paolo Berto Durante committed
142 143 144 145 146 147
### Contributors

We wish to thank the following contributors:

- Mark Tucker (Side Effects Inc)

148 149 150 151

## License

Apache 2.0