Rendering extra image planes (deep rasters)

Overview

You can include “extra” image planes (also called deep rasters) containing image representations of VEX (the mantra shading language) global variables, or exported variables/parameters from any surface or fog shader.

You can even output extra planes per light if you assign the exported variable inside an illuminance loop.

When rendering to a .pic (Houdini image format) or .exr (OpenEXR) format image (or the special ip name, which outputs to MPlay instead of a file) you can include the extra planes in the same multi-plane image as the main render. You can also specify that extra planes go into multiple separate files (or put multiple extra planes in a separate multi-plane file from the main render).

Examples

For example, you can export the value of the global variable N (surface normal) for each pixel to an image.

The rendered color plane: a torus lit from above.

The N plane, showing the surface normals as color.

(You can view the extra plane(s) in MPlay using the popup menu in the top left under the toolbar.)

Another example: Houdini’s basic surface shader exports a variable named paintExport, containing the shader’s color contribution before lighting. This can be very useful information to have during compositing.

The rendered color plane: a torus lit from various angles, with point colors.

The paintExport plane, showing the surface shader’s original color contribution before lighting and shadows.

How to

To...	Do this
Set up a render node to export an extra plane	Select the mantra render output node. In parameter editor, click the Properties tab, then click the Output sub-tab. Scroll down to the Extra image planes parameter and click the + button next to it to add a new plane. You can add as many extra planes as you need by increasing the Extra image planes parameter. See below for how to set up the plane’s parameters.
Output a global variable	Set up an extra plane as shown above. Click the popup menu button on the right side of the VEX variable parameter and choose a global variable.
Output a shader variable	For VOP networks, set up a Parameter node for the variable and set its Export parameter to Always. For VEX code, mark the variable as exported. Set up an extra plane as shown above. In the extra plane’s parameters on the mantra render node, set the VEX variable parameter to the name of the parameter you exported.
Output a variable per-light	For VOP networks, create an Illuminance node to loop through the lights in the scene. For VEX code, use an illuminance loop. Inside the illuminance loop, assign to an exported value. In VOPs, you can create a Parameter node inside the Illuminance node and set its Export parameter to Always. Connect to its input to export a value from the illuminance loop. If you simply want to export a global variable (such as light color, `Cl`), you must assign it to an exported variable. For example, in VOPs you would connect the `Cl` output of a Globals VOP to the exported parameter VOP. In VEX code, you would use something like `C = Cl;` (where `C` is an exported variable). Set up an extra plane for each light. Set the VEX variable to the name of the exported variable. Set Light export to the path of the light to export into this plane. Set the Channel name to a unique name for this variable on this light. For example, if you have an exported variable named `C` and you want to export it into per-light planes for two lights `/obj/light1` and `/obj/light2`, you would create two extra planes. On the first extra plane, set VEX variable to `C`, Light export to `/obj/light1`, and Channel name to `light1C` (or something similar). On the second plane, set VEX variable to `C`, Light export to `/obj/light2`, and Channel name to `light2C`.

Parameters

Extra Image Planes

Any number of extra image planes may be generated simultaneously. If the primary output image format supports multiple image planes, the plane name will be used to define the name of the deep raster plane. If the primary output device does not support multiple image planes, each image plane will be output to an individual file, with the name of the plane defining the file name. The formats that support multiple image planes are OpenEXR and Houdini .pic (including the “ip” device).

Image Plane

The name of the plane.

VEX Variable

The VEX variable to be output to the image plane. The variable must be either a global variable, or an exported parameter.

Note

When the N variable is output, its value may not be normalized resulting in either very small or very large values.

VEX Type

The correct type of the variable must also be specified.

Channel name

Name of the channel to write the variable data to in the output file (if the file format supports multiple named channels). Leave this field blank to use the VEX variable name as the channel name.

Different file

Turn on the checkbox next to this field to write the variable data to an output file other than the rendered image.

Note

You can specify the same “Different file” for multiple extra image planes with different channel names (if the file format supports multiple named channels).

Quantize

The storage type for the output.

Sample Filter

Opacity Filtering	Transparent surfaces will be composited using Of.
Closest Surface	Only the value of the closest surface will be output, regardless of the opacity of the surface.

Pixel Filter

Specifies the pixel filter used to combine sub-pixel samples to generate the value for the single pixel.

Gamma

Specifies the gamma correction for the image.

Gain

Each color value is multiplied by the gain prior to being quantized.

Dither

The dither amount to be applied. The dither is specified as a fraction of the quantization step (i.e. 0.5 will be one half of a quantization step). The option is ignored for floating point output.

White point

The white-point of the image used during quantization.

Light Export

Mantra supports export of variables from within illuminance loops. If the light export field is set to the name of a light object (as it appears in the IFD), and the shader is written to assign the value of the export parameter inside an illuminance loop, then the image plane will contain the value of the export parameter at the time the illuminance loop was run for the given light source. It allows the contribution of individual lights to be output into separate image planes for easy adjustment in post-compositing.

Tip

You can output the object ID and/or primitive IDs to deep raster planes, and then use them to easily select objects or primitives in the compositor.

To output the object or primitive ID, set up the following parameters:

Variable name = Op_Id (or Prim_Id)
File/Plane name = Op_Id (or Prim_Id)
Channel depth, Variable type = Floating point
Sample filter = closest surface
Pixel filter = minmax idcover (a special filtering mode for ID channels)