# Nodes¶

The following sections describe available nodes in technical terms. Refer to the rendering guidelines for usage details.

Overview of nsi nodes

Node

Function

root

The scene’s root

global

Global settings node

set

Expresses relationships of groups of nodes

attributes

Container for generic attributes (e.g. visibility)

transform

Transformation to place objects in the scene

instances

Specifies instances of other nodes

plane

An infinite plane

mesh

Polygonal mesh or subdivision surface

faceset

Assign attributes to part of a mesh, curves or paticles.

curves

Linear, b-spline and Catmull-Rom curves

particles

Collection of particles

procedural

Geometry to be loaded or generated in delayed fashion

volume

A volume loaded from an OpenVDB file

environment

Geometry type to define environment lighting

camera

Set of nodes to create viewing cameras

outputdriver

A target where to output rendered pixels

outputlayer

Describes one render layer to be connected to an outputdriver node

screen

Describes how the view from a camera node will be rasterized into an outputlayer node

## The Root Node¶

The root node is much like a transform node. With the particularity that it is the end connection for all renderable scene elements. A node can exist in an nsi context without being connected to the root note but in that case it won’t affect the render in any way. The root node has the reserved handle name .root and doesn’t need to be created using NSICreate. The root node has two defined attributes: objects and geometryattributes. Both are explained under the transform node.

## The Global Node¶

This node contains various global settings for a particular nsi context. Note that these attributes are for the most case implementation specific.

This node has the reserved handle name .global and does not need to be created using NSICreate. The following attributes are recognized by 3Delight:

global node optional attributes

Name

Type

Description/Values

numberofthreads

threads.count (!)

integer

Specifies the total number of threads to use for a particular render:

• A value of 0 lets the render engine choose an optimal thread value. This is is the default behaviour.

• Any positive value directly sets the total number of render threads.

• A negative value will start as many threads as optimal plus the specified value. This allows for an easy way to to decrease the total number of render threads.

renderatlowpriority

priority.low (!)

integer

If set to 1, start the render with a lower process priority. This can be useful if there are other applications that must run during rendering.

texturememory

texture.memory (!)

integer

Specifies the approximate maximum memory size, in megabytes, the renderer will allocate to accelerate texture access.

bucketorder

bucket.order (!)

string

Specifies in what order the buckets are rendered. The available values are:

horizontal

Row by row, left to right and top to bottom. This is the default.

vertical

Column by column, top to bottom and left to right.

zigzag

Row by row, left to right on even rows and right to left on odd rows.

spiral

In a clockwise spiral from the centre of the image.

circle

In concentric circles from the centre of the image.

frame

integer

Provides a frame number to be used as a seed for the sampling pattern. See the screen node.

lightcache

integer (1)

Controls use of the renderer’s light cache. Set this to 0 to switch the cache off.

When this is switched on, each bucket is visited twice during rendering.

WARNING: display drivers that do not request scanline order need to make sure they handle this gracefully.

 networkcache.size integer Specifies the maximum network cache size, in gigabytes (GB, not GiB), the renderer will use to cache textures on a local drive to accelerate data access. networkcache.directory string Specifies the directory in which textures will be cached. A good default value is /var/tmp/3DelightCache on Linux systems. networkcache.write integer Enables caching for image write operations. This alleviates pressure on networks by first rendering images to a local temporary location and copying them to their final destination at the end of the render. This replaces many small network writes by more efficient larger operations.
 license.server string Specifies the name or IP address of the license server to be used. license.wait integer When no license is available for rendering, the renderer will wait until a license is available if this attribute is set to 1, but will stop immediately if it is set to 0. The latter setting is useful when managing a renderfarm and other work could be scheduled instead. license.hold integer By default, the renderer will get new licenses for every render and release them once it is done. This can be undesirable if several frames are rendered in sequence from the same process process. If this option is set to 1, the licenses obtained for the first frame are held until the last frame is finished.
 maximumraydepth.diffuse diffuse.ray.depth.max (!) integer Specifies the maximum bounce depth a ray emitted from a diffuse closure can reach. A depth of 1 specifies one additional bounce compared to purely local illumination. maximumraylength.diffuse diffuse.ray.length.max (!) double Limits the distance a ray emitted from a diffuse closure can travel. Using a relatively low value for this attribute might improve performance without significantly affecting the look of the resulting image, as it restrains the extent of global illumination. Setting this to a negative value disables the limitation. maximumraydepth.reflection reflection.ray.depth.max (!) integer Specifies the maximum bounce depth a reflection/glossy/specular ray can reach. Setting reflection depth to 0 will only compute local illumination resulting in only surfaces with an emission closure to appear in reflections. maximumraylength.reflection reflection.ray.length.max (!) double Limits the distance a reflection/glossy/specular ray can travel. Setting this to a negative value disables the limitation. maximumraydepth.refraction refraction.ray.depth.max (!) integer Specifies the maximum bounce depth a refraction ray can reach. The default value of 4 allows light to shine through a properly modeled object such as a glass. maximumraylength.refraction refraction.ray.length.max (!) double Limits the distance a refraction ray can travel. Setting this to a negative value disables the limitation. maximumraydepth.hair hair.ray.depth.max (!) integer Specifies the maximum bounce depth a hair ray can reach. Note that hair are akin to volumetric primitives and might need elevated ray depth to properly capture the illumination. maximumraylength.hair hair.ray.length.max (!) double Limits the distance a hair ray can travel. Setting this to a negative value disables the limitation. maximumraydepth.volume volume.ray.depth.max (!) integer Specifies the maximum bounce depth a volume ray can reach. maximumraylength.volume volume.ray.length.max (!) double Limits the distance a volume ray can travel. Setting this to a negative value disables the limitation.
 quality.shadingsamples shading.samples (!) integer Controls the quality of BSDF sampling. Larger values give less visible noise. quality.volumesamples volume.samples (!) integer Controls the quality of volume sampling. Larger values give less visible noise. show.displacement shading.displacement (!) integer When set to 1, enables displacement shading. Otherwise, it must be set to 0 to ignore any displacement shader in the scene. show.atmosphere shading.atmosphere (!) integer When set to 1, enables atmosphere shader(s). Otherwise, it must be set to 0 to ignore any atmosphere shader in the scene. show.multiplescattering shading.multiplescattering (!) double This is a multiplier on the multiple scattering of VDB nodes. This parameter is useful to obtain faster draft renders by lowering the value below 1. The range is 0 to 1. show.osl.subsurface shading.osl.subsurface (!) integer When set to 1, enables the subsurface() ᴏsʟ closure. Otherwise, it must be set to 0, which will ignore this closure in ᴏsʟ shaders.

For anti-aliasing quality see the screen node.

global node optional attributes for statistics

Name | Type | Description/Values

statistics.progress

integer

When set to 1, prints rendering progress as a percentage of completed pixels.

statistics.filename

string

Full path of the file where rendering statistics will be written. An empty string will write statistics to standard output. The name null will not output statistics.

## The Set Node¶

This node can be used to express relationships between objects.

An example is to connect many lights to such a node to create a light set and then to connect this node to an outputlayer’s lightset attribute (see also light layers).

It has the following attributes:

set node optional attributes

Name

Type

Description/Values

members

member (!)

«connection(s)»

This connection accepts all nodes that are members of the set.

## The Plane Node¶

This node represents an infinite plane, centered at the origin and pointing towards $$\mathrm{Z+}$$. It has no required attributes. The UV coordinates are defined as the X and Y coordinates of the plane.

## The Mesh Node¶

This node represents a polygon mesh or a subdivision surface. It has the following required attributes:

mesh node required attributes

Name

Type

Description/Values

P

point

The positions of the object’s vertices. Typically, this attribute will be indexed through a P.indices attribute.

nvertices

vertex.count (!)

face.vertex.count (!)

integer

The number of vertices for each face of the mesh. The number of values for this attribute specifies total face number (unless nholes is defined).

To render a mesh as a subdivision surface, at least the subdivision.scheme argument must be set. When rendering as a subdvision surface, the mesh node accepts these optionalattributes:

mesh node as subdivision surface optional attributes

Name

Type

Description/Values

subdivision.scheme

string

A value of "catmull-clark" will cause the mesh to render as a Catmull-Clark subdivision surface.

subdivision.cornervertices

subdivision.corner.index (!)

integer

A list of vertices which are sharp corners. The values are indices into the P attribute, like P.indices.

subdivision.cornersharpness

subdivision.corner.sharpness (!)

float

The sharpness of each specified sharp corner. It must have a value for each value given in subdivision.cornervertices.

subdivision.smoothcreasecorners

subdivision.corner.automatic (!)

integer

This tag requires a single integer argument with a value of 1 or 0 indicating whether or not the surface uses enhanced subdivision rules on vertices where more than two creased edges meet.

With a value of 1 (the default) the vertex is subdivided using an extended crease vertex subdivision rule which yields a smooth crease. With a value of 0 the surface uses enhanced subdivision rules where a vertex becomes a sharp corner when it has more than two incoming creased edges.

Note that sharp corners can still be explicitly requested using the subdivision.corner.index & subdivision.corner.sharpness tags.

subdivision.creasevertices

subdivision.crease.index (!)

integer

A list of crease edges. Each edge is specified as a pair of indices into the P attribute, like P.indices.

subdivision.creasesharpness

subdivision.crease.sharpness (!)

float

The sharpness of each specified crease. It must have a value for each pair of values given in subdivision.creasevertices.

The mesh node also has these optional attributes:

mesh node optional attributes

Name

Type

Description/Values

nholes

hole.count (!)

integer

The number of holes in the polygons.

When this attribute is defined, the total number of faces in the mesh is defined by the number of values for nholes rather than for nvertices. For each face, there should be (nholes + 1) values in nvertices: the respective first value specifies the number of vertices on the outside perimeter of the face, while additional values describe the number of vertices on perimeters of holes in the face.

The example below shows the definition of a polygon mesh consisting of three square faces, with one triangular hole in the first one and square holes in the second one.

clockwisewinding

clockwise (!)

integer

A value of 1 specifies that polygons with clockwise winding order are front facing.

The default is 0, making counterclockwise polygons front facing.

Below is a sample ɴsɪ stream snippet showing the definition of a mesh with holes.

 1Create "holey" "mesh"
2SetAttribute "holey"
3  "nholes" "int" 3 [ 1 2 0 ]
4  "nvertices" "int" 6 [
5    4 3                 # Square with 1 triangular hole
6    4 4 4               # Square with 2 square holes
7    4 ]                 # Square with no hole
8  "P" "point" 23 [
9     0 0 0    3 0 0    3 3 0    0 3 0
10     1 1 0    2 1 0    1 2 0
11
12     4 0 0    9 0 0    9 3 0    4 3 0
13     5 1 0    6 1 0    6 2 0    5 2 0
14     7 1 0    8 1 0    8 2 0    7 2 0
15
16    10 0 0   13 0 0   13 3 0   10 3 0 ]


## The Faceset Node¶

This node is used to provide a way to attach attributes to parts of another geometric primitive, such as faces of a mesh, curves or particles. It has the following attributes:

faceset node attributes

Name

Type

Description/Values

faces

face.index (!)

integer

A list of indices of faces. It identifies which faces of the original geometry will be part of this face set.

 1Create "subdiv" "mesh"
2SetAttribute "subdiv"
3  "nvertices" "int" 4 [ 4 4 4 4 ]
4  "P" "point" 9 [
5    0 0 0    1 0 0    2 0 0
6    0 1 0    1 1 0    2 1 0
7    0 2 0    1 2 0    2 2 2 ]
8  "P.indices" "int" 16 [
9    0 1 4 3    2 3 5 4    3 4 7 6    4 5 8 7 ]
10  "subdivision.scheme" "string" 1 "catmull-clark"
11
12Create "set1" "faceset"
13SetAttribute "set1"
14  "faces" "int" 2 [ 0 3 ]
15Connect "set1" "" "subdiv" "facesets"
16
17Connect "attributes1" "" "subdiv" "geometryattributes"
18Connect "attributes2" "" "set1" "geometryattributes"


## The Curves Node¶

This node represents a group of curves. It has the following required attributes:

curves node required attributes

Name

Type

Description/Values

nverts

vertex.count (!)

integer

The number of vertices for each curve. This must be at least 4 for cubic curves and 2 for linear curves. There can be either a single value or one value per curve.

P

point

The positions of the curve vertices. The number of values provided, divided by nvertices, gives the number of curves which will be rendered.

width

float

The width of the curves.

It also has these optional attributes:

curves node optional attributes

Name

Type

Description/Values

basis

string

The basis functions used for curve interpolation. Possible choices are:

b-spline

B-spline interpolation.

catmull-rom

Catmull-Rom interpolation. This is the default value.

linear

Linear interpolation.

hobby (!)

Hobby interpolation.

N

normal

The presence of a normal indicates that each curve is to be rendered as an oriented ribbon. The orientation of each ribbon is defined by the provided normal which can be constant, a per-curve or a per-vertex attribute. Each ribbon is assumed to always face the camera if a normal is not provided.

extrapolate

integer

By default, when this is set to 0, cubic curves will not be drawn to their end vertices as the basis functions require an extra vertex to define the curve. If this attribute is set to 1, an extra vertex is automatically extrapolated so the curves reach their end vertices, as with linear interpolation.

Attributes may also have a single value, one value per curve, one value per vertex or one value per vertex of a single curve, reused for all curves. Attributes which fall in that last category must always specify NSIParamPerVertex.

Note

A single curve is considered a face as far as use of NSIParamPerFace is concerned. See also the faceset node.

## The Particles Node¶

This geometry node represents a collection of tiny particles. Particles are represented by either a disk or a sphere. This primitive is not suitable to render large particles as these should be represented by other means (e.g. instancing).

particles node required attributes

Name

Type

Description/Values

P

point

The center of each particle.

width

float

The width of each particle. It can be specified for the entire particles node (only one value provided), per-particle or indirectly through a width.indices attribute.

It also has these optional attributes:

 N normal The presence of a normal indicates that each particle is to be rendered as an oriented disk. The orientation of each disk is defined by the provided normal which can be constant or a per-particle attribute. Each particle is assumed to be a sphere if a normal is not provided. id integer This attribute has to be the same length as P. It assigns a unique identifier to each particle which must be constant throughout the entire shutter range. Its presence is necessary in the case where particles are motion blurred and some of them could appear or disappear during the motion interval. Having such identifiers allows the renderer to properly render such transient particles. This implies that the number of id’s might vary for each time step of a motion-blurred particle cloud so the use of is mandatory by definition.

## The Procedural Node¶

This node acts as a proxy for geometry that could be defined at a later time than the node’s definition, using a procedural supported by . Since the procedural is evaluated in complete isolation from the rest of the scene, it can be done either lazily (depending on its boundingbox attribute) or in parallel with other procedural nodes.

The procedural node supports, as its attributes, all the arguments of the NSIEvaluate API call, meaning that procedural types accepted by that api call (ɴsɪ archives, dynamic libraries, Lua scripts) are also supported by this node. Those attributes are used to call a procedural that is expected to define a sub-scene, which has to be independent from the other nodes in the scene. The procedural node will act as the sub-scene’s local root and, as such, also supports all the attributes of a regular node. In order to connect the nodes it creates to the sub-scene’s root, the procedural simply has to connect them to the regular .root.

In the context of an interactive render, the procedural will be executed again after the node’s attributes have been edited. All nodes previously connected by the procedural to the sub-scene’s root will be deleted automatically before the procedural’s re-execution.

Additionally, this node has the following optional attribute :

procedural node optional attribute

Name

Type

Description/Values

boundingbox

point[2]

Specifies a bounding box for the geometry where boundingbox[0] and boundingbox[1] correspond, respectively, to the ‘minimum’ and the ‘maximum’ corners of the box.

## The Environment Node¶

This geometry node defines a sphere of infinite radius. Its only purpose is to render environment lights, solar lights and directional lights; lights which cannot be efficiently modeled using area lights. In practical terms, this node is no different than a geometry node with the exception of shader execution semantics: there is no surface position P, only a direction I (refer to for more practical details). The following optional node attribute is recognized:

environment node optional attribute

Name

Type

Description/Values

angle

double

Specifies the cone angle representing the region of the sphere to be sampled.

The angle is measured around the $$\mathrm{Z+}$$ axis. If the angle is set to $$0$$, the environment describes a directional light.

Tip

To position the environment dome one must connect the node to a transform node and apply the desired rotation(s).

This node represents an ᴏsʟ shader, also called layer when part of a shader group. It has the following required attribute:

Name

Type

Description/Values

shaderfilename

string

This is the name of the file which contains the shader’s compiled code.

shaderobject

string

This contains the complete compiled shader code. It allows specifying shaders without going through files.

All other attributes on this node are considered arguments of the shader. They may either be given values or connected to attributes of other shader nodes to build shader networks. ᴏsʟ shader networks must form acyclic graphs or they will be rejected. Refer to the guidelines for instructions on ᴏsʟ network creation and usage.

## The Attributes Node¶

This node is a container for various geometry related rendering attributes that are not intrinsic to a particular node (for example, one can’t set the topology of a polygonal mesh using this attributes node). Instances of this node must be connected to the geometryattributes attribute of either geometric primitives or nodes (to build ). Attribute values are gathered along the path starting from the geometric primitive, through all the transform nodes it is connected to, until the is reached.

When an attribute is defined multiple times along this path, the definition with the highest priority is selected. In case of conflicting priorities, the definition that is the closest to the geometric primitive (i.e. the furthest from the root) is selected. Connections (for shaders, essentially) can also be assigned priorities, which are used in the same way as for regular attributes. Multiple attributes nodes can be connected to the same geometry or transform nodes (e.g. one attributes node can set object visibility and another can set the surface shader) and will all be considered.

This node has the following attributes:

attributes node attributes

Name

Type

Description/Values

surfaceshader

shader.surface (!)

«connection»

The shader node which will be used to shade the surface is connected to this attribute. A priority (useful for overriding a shader from higher in the scene graph) can be specified by setting the priority attribute of the connection itself.

displacementshader

shader.displacement (!)

«connection»

The shader node which will be used to displace the surface is connected to this attribute. A priority (useful for overriding a shader from higher in the scene graph) can be specified by setting the priority attribute of the connection itself.

volumeshader

shader.volume (!)

«connection»

The shader node which will be used to shade the volume inside the primitive is connected to this attribute.

ATTR.priority

integer

Sets the priority of attribute ATTR when gathering attributes in the scene hierarchy.

visibility.camera

visibility.diffuse

visibility.hair

visibility.reflection

visibility.refraction

visibility.shadow

visibility.specular

visibility.volume

integer

These attributes set visibility for each ray type specified in ᴏsʟ. The same effect could be achieved using shader code (using the raytype() function) but it is much faster to filter intersections at trace time. A value of 1 makes the object visible to the corresponding ray type, while 0 makes it invisible.

visibility

integer

This attribute sets the default visibility for all ray types. When visibility is set both per ray type and with this default visibility, the attribute with the highest priority is used. If their priority is the same, the more specific attribute (i.e. per ray type) is used.

matte

integer

If this attribute is set to 1, the object becomes a matte for camera rays. Its transparency is used to control the matte opacity and all other shading components are ignored.

regularemission

emission.regular (!)

integer

If this is set to 1, closures not used with quantize() will use emission from the objects affected by the attribute. If set to 0, they will not.

quantizedemission

emission.quantized (!)

integer

If this is set to 1, quantized closures will use emission from the objects affected by the attribute. If set to 0, they will not.

bounds

boundary

«connection»

When a geometry node (usually a mesh node) is connected to this attribute, it will be used to restrict the effect of the attributes node, which will apply only inside the volume defined by the connected geometry object.

## The Transform Node¶

This node represents a geometric transformation. Transform nodes can be chained together to express transform concatenation, hierarchies and instances.

A transform node also accepts attributes to implement hierarchical attribute assignment and overrides.

It has the following attributes:

transform node attributes

Name

Type

Description/Values

tranformationmatrix

matrix (!)

doublematrix

This is a 4×4 matrix which describes the node’s transformation. Matrices in ɴsɪ post-multiply so column vectors are of the form:

$\begin{split}\left[ \begin{array}{cccc} w_{1_1} & w_{1_2} & w_{1_3} & 0 \\ w_{2_1} & w_{2_2} & w_{2_3} & 0 \\ w_{3_1} & w_{3_2} & w_{3_3} & 0 \\ Tx & Ty & Tz & 1 \end{array} \right]\end{split}$

objects

object (!)

«connection(s)»

This is where the transformed objects are connected to. This includes geometry nodes, other transform nodes and camera nodes.

geometryattributes

attribute (!)

«connection(s)»

This is where attributes nodes may be connected to affect any geometry transformed by this node.

See the guidelines on attributes and instancing for explanations on how this connection is used.

## The Instances Node¶

This node is an efficient way to specify a large number of instances. It has the following attributes:

instances node attributes

Name

Type

Description/Values

sourcemodels

object (!)

«connection(s)»

The instanced models should connect to this attribute.

Connections must have an integer index attribute if there are several, so the models effectively form an ordered list.

transformationmatrices

matrix (!)

doublematrix

A transformation matrix for each instance.

 modelindices object.index (!) integer An optional model selector for each instance. disabledinstances disable.index (!) [integer; …] An optional list of indices of instances which are not to be rendered.

## The Outputdriver Node¶

An output driver defines how an image is transferred to an output destination. The destination could be a file (e.g. “exr” output driver), frame buffer or a memory address. It can be connected to the outputdrivers attribute of an node. It has the following attributes:

outputdriver node attributes

Name

Type

Description/Values

drivername

string

This is the name of the driver to use. The api of the driver is implementation specific and is not covered by this documentation.

imagefilename

string

Full path to a file for a file-based output driver or some meaningful identifier depending on the output driver.

embedstatistics

integer

A value of 1 specifies that statistics will be embedded into the image file.

Any extra attributes are also forwarded to the output driver which may interpret them however it wishes.

## The Outputlayer Node¶

This node describes one specific layer of render output data. It can be connected to the outputlayers attribute of a screen node. It has the following attributes:

outputlayer node attributes

Name

Type

Description/Values

variablename

string

This is the name of a variable to output.

variablesource

string

Indicates where the variable to be output is read from. Possible values are:

shader

computed by a shader and output through an ᴏsʟ closure s (such a outputvariable() or debug()) or the Ci global variable.

attribute

retrieved directly from an attribute with a matching name attached to a geometric primitive.

builtin

generated automatically by the renderer (e.g. z, alpha N.camera, P.world).

layername

string

This will be name of the layer as written by the output driver. For example, if the output driver writes to an EXR file then this will be the name of the layer inside that file.

scalarformat

string

Specifies the format in which data will be encoded (quantized) prior to passing it to the output driver. Possible values are:

int8

Signed 8-bit integer.

uint8

Unsigned 8-bit integer.

int16

Signed 16-bit integer.

uint16

Unsigned 16-bit integer.

int32

Signed 32-bit integer.

half

IEEE 754 half-precision binary floating point (binary16).

float

IEEE 754 single-precision binary floating point (binary32).

layertype

string

Specifies the type of data that will be written to the layer. Possible values are:

scalar

A single quantity. Useful for opacity (alpha) or depth (Z) information.

color

A 3-component color.

vector

A 3D point or vector. This will help differentiate the data from a color in further processing.

quad

A sequence of 4 values, where the fourth value is not an alpha channel.

Each component of those types is stored according to the scalarformat attribute set on the same outputlayer node.

colorprofile

string

The name of an OCIO color profile to apply to rendered image data prior to quantization.

dithering

integer

If set to 1, dithering is applied to integer scalars. Otherwise, it must be set to 0.

It is sometimes desirable to turn off dithering, for example, when outputting object IDs.

withalpha

integer

If set to 1, an alpha channel is included in the output layer. Otherwise, it must be set to 0.

sortkey

integer

This attribute is used as a sorting key when ordering multiple output layer nodes connected to the same output driver node. Layers with the lowest sortkey attribute appear first.

lightset

«connection(s)»

This connection accepts either light sources or set nodes to which lights are connected. In this case only listed lights will affect the render of the output layer. If nothing is connected to this attribute then all lights are rendered.

outputdrivers

outputdriver (!)

«connection(s)»

This connection accepts nodes to which the layer’s image will be sent.

filter

string (blackmann- harris)

The type of filter to use when reconstructing the final image from sub-pixel samples. Possible values are:

• box

• triangle

• catmull-rom

• bessel

• gaussian

• sinc

• mitchell

• blackman-harris (default)

• zmin

• zmax

• cryptomattelayer%u Take two values from those present in each pixel’s samples.

filterwidth

double

Diameter in pixels of the reconstruction filter. It is ignored when filter is box or zmin.

Filter

Suggested Width

box

1.0

triangle

2.0

catmull-rom

4.0

bessel

6.49

gaussian

2.02.5

sinc

4.08.0

mitchell

4.05.0

blackman-harris

3.04.0

backgroundvalue

float

The value given to pixels where nothing is rendered.

Any extra attributes are also forwarded to the output driver which may interpret them however it wishes.

## The Screen Node¶

This node describes how the view from a camera node will be rasterized into an output layer node. It can be connected to the screens attribute of a camera node.

For an exmplanation of coordinate systems/spaces mentioned below, e.g. NDC, screen, etc., please refer to the Open Shading Language specification

screen node attributes

Name

Type

Description/Values

outputlayers

outputlayer (!)

«connection(s)»

This connection accepts nodes which will receive a rendered image of the scene as seen by the camera.

resolution

integer[2]

Horizontal and vertical resolution of the rendered image, in pixels.

oversampling

integer

The total number of samples (i.e. camera rays) to be computed for each pixel in the image.

crop

float[2][2]

The region of the image to be rendered. It is defined by a two 2D coordinates. Each represents a point in NDC space:

• Top-left corner of the crop region.

• Bottom-right corner of the crop region.

prioritywindow

integer[2][2]

For progressive renders, this is the region of the image to be rendered first. It is defined by two coordinates. Each represents a pixel position in raster space:

• Top-left corner of the high priority region.

• Bottom-right corner of the high priority region.

screenwindow

double[2][2]

Specifies the screen space region to be rendered. It is defined by two coordinates. Each represents a point in screen space:

• Top-left corner of the region.

• Bottom-right corner of the region.

Note that the default screen window is set implicitely by the frame aspect ratio:

$\begin{split}screenwindow = \begin{bmatrix}-f & -1\end{bmatrix}, \begin{bmatrix}f & 1\end{bmatrix} \text{for } f=\dfrac{xres}{yres}\\\end{split}$

pixelaspectratio

float (1)

Ratio of the physical width to the height of a single pixel. A value of 1 corresponds to square pixels.

staticsamplingpattern

integer (0)

This controls whether or not the sampling pattern used to produce the image changes for every frame.

A nonzero value will cause the same pattern to be used for all frames. A value of 0 will cause the pattern to change with the frame attribute of the global node.

## The Volume Node¶

This node represents a volumetric object defined by OpenVDB data. It has the following attributes:

volume node attributes

Name

Type

Description/Values

vdbfilename

filename (!)

string

The path to an OpenVDB file with the volumetric data.

colorgrid

string

The name of the OpenVDB grid to use as a scattering color multiplier for the volume shader.

densitygrid

string

The name of the OpenVDB grid to use as volume density for the volume shader.

emissionintensitygrid

string

The name of the OpenVDB grid to use as emission intensity for the volume shader.

temperaturegrid

string

The name of the OpenVDB grid to use as temperature for the volume shader.

velocitygrid

double

The name of the OpenVDB grid to use as motion vectors. This can also name the first of three scalar grids (i.e. “velocityX”).

velocityscale

double (1)

A scaling factor applied to the motion vectors.

## Camera Nodes¶

All camera nodes share a set of common attributes. These are listed below.

camera nodes shared attributes

Name

Type

Description/Values

screens

screen (!)

«connection(s)»

This connection accepts nodes which will rasterize an image of the scene as seen by the camera. Refer to for more information.

shutterrange

double[2]

Time interval during which the camera shutter is at least partially open. It is defined by a list of exactly two values:

• Time at which the shutter starts opening.

• Time at which the shutter finishes closing.

shutteropening

double[2]

A normalized time interval indicating the time at which the shutter is fully open (a) and the time at which the shutter starts to close (b). These two values define the top part of a trapezoid filter.

This feature simulates a mechanical shutter on which open and close movements are not instantaneous. Below is an image showing the geometry of such a trapezoid filter.

An example shutter opening configuration with $$a=\frac{1}{3}$$ and $$b=\frac{2}{3}$$.

clippingrange

double[2]

Distance of the near and far clipping planes from the camera. It’s defined by a list of exactly two values:

• Distance to the near clipping plane, in front of which scene objects are clipped.

• Distance to the far clipping plane, behind which scene objects are clipped.

lensshader

«connection»

An ᴏsʟ shader through which camera rays get sent. See lens shaders.

### The Orthographiccamera Node¶

This node defines an orthographic camera with a view direction towards the $$\mathrm{Z-}$$ axis. This camera has no specific attributes.

### The Perspectivecamera Node¶

This node defines a perspective camera. The canonical camera is viewing in the direction of the $$\mathrm{Z-}$$ axis. The node is usually connected into a node for camera placement. It has the following attributes:

perspective node attributes

Name

Type

Description/Values

fov

float

The field of view angle, in degrees.

depthoffield.enable

integer (0)

Enables depth of field effect for this camera.

depthoffield.fstop

double

Relative aperture of the camera.

depthoffield.focallength

double

Vertical focal length, in scene units, of the camera lens.

depthoffield.focallengthratio

double (1.0)

Ratio of vertical focal length to horizontal focal length. This is the squeeze ratio of an anamorphic lens.

depthoffield.focaldistance

double

Distance, in scene units, in front of the camera at which objects will be in focus.

depthoffield.aperture.enable

integer (0)

By default, the renderer simulates a circular aperture for depth of field. Enable this feature to simulate aperture “blades” as on a real camera. This feature affects the look in out-of-focus regions of the image.

depthoffield.aperture.sides

integer (5)

Number of sides of the camera’s aperture. The mininum number of sides is 3.

depthoffield.aperture.angle

double (0)

A rotation angle (in degrees) to be applied to the camera’s aperture, in the image plane.

 depthoffield.aperture.roundness double (0) This shapes the sides of the polygon When set to 0, the aperture is polygon with flat sides. When set to 1, the aperture is a perfect circle. When set to -1, the aperture sides curve inwards. depthoffield.aperture.density double (0) The slope of the aperture’s density. A value of 0 gives uniform density. Negative values, up to -1, make the aperture brighter near the center. Positive values, up to 1, make it brighter near the edge. depthoffield.aperture.aspectratio double (1) Circularity of the aperture. This can be used to simulate anamorphic lenses.

### The Fisheyecamera Node¶

Fish eye cameras are useful for a multitude of applications (e.g. virtual reality). This node accepts these attributes:

fisheye camera node attributes

Name

Type

Description/Values

fov

float

The field of view angle, in degrees.

mapping

string (equidistant)

Defines one of the supported fisheye mapping functions. Possible values are:

equidistant

Maintains angular distances.

equisolidangle

Every pixel in the image covers the same solid angle.

orthographic

Maintains planar illuminance. This mapping is limited to a 180 field of view.

stereographic

Maintains angles throughout the image. Note that stereographic mapping fails to work with field of views close to 360 degrees.

### The Cylindricalcamera Node¶

This node specifies a cylindrical projection camera and has the following attibutes:

cylindrical camera nodes shared attributes

Name

Type

Description/Values

fov

float

(90)

Specifies the vertical field of view, in degrees. The default value is 90.

horizontalfov

fov.horizontal (!)

float

(360)

Specifies the horizontal field of view, in degrees. The default value is 360.

eyeoffset

float

This allows to render stereoscopic cylindrical images by specifying an eye offset

### The Sphericalcamera Node¶

This node defines a spherical projection camera. This camera has no specific attributes.

A lens shader is an ᴏsʟ network connected to a camera through the lensshader connection. Such shaders receive the position and the direction of each tracer ray and can either change or completely discard the traced ray. This allows to implement distortion maps and cut maps. The following shader variables are provided:
P — Contains ray’s origin.
I — Contains ray’s direction. Setting this variable to zero instructs the renderer not to trace the corresponding ray sample.
time — The time at which the ray is sampled.
(u, v) — Coordinates, in screen space, of the ray being traced.