Houdini 20.5 Nodes TOP nodes

USD Render Files TOP node

Creates work items that render a USD file.

On this page
Since 18.0

Overview

This node generates work items that render a USD file using Karma (by default). The render executes using the Houdini husk executable. This node has similar options to the USD Render ROP node.

Rendering uses the same USD interface (Hydra) as what is used to render Solaris in the viewport, but instead of displaying the generated pixel buffers, the renderer saves them to image files. You can render using any Hydra client registered with USD.

Configuration

Traditionally in Houdini, the renderer is configured using parameters on the render node. However in USD, render settings are stored in a RenderSettings primitive in the scene tree.

For more information about creating USD render settings, see the Render Settings LOP, Render Product LOP, and Render Var LOP nodes.

Available renderers

  • The list of renderers is filtered based on the data returned by the usdrenderers.py script. The husk utility, and by extension the USD Render node, only support renderers that can generate AOV buffers (that is, renderers whose aovsupport attribute is True).

  • To render to other delegates, such as Houdini GL and Storm, that do not support AOV generation, use the OpenGL ROP (this basically updates the viewport and takes a snapshot of its contents).

Tip

You need to make sure the render delegate is found by the USD plug-in search, using the PXR_PLUGINPATH_NAME environment variable.

You can also set the environment variable TF_DEBUG to PLUG_*, which causes the USD library to print out useful information as it scans for and loads plug-ins.

TOP Attributes

complexity

string

The complexity of the render as specified by the Complexity parameter.

outputimage

file

The path to the output image pattern for the render. This is what is passed to the husk, and it should contain symbols that can be expanded by the husk.

outputtag

string

If Output File Tag is enabled, this attribute is set to the custom file tag that should be assigned to output files produced by work items in the node.

range

float3

The start, end, and increment frame range values associated with the work item. If the work item is in a batch, these values refer to the range for the entire batch.

usdpath

string

The path to the .usd file.

huskcommand

string

The full husk command that is executed by the job. It is created when the Create Husk Command Attribute parameter is turned on, and it is added after the job cooks.

Parameters

Render

Generate When

Determines when this node will generate work items. You should generally leave this set to “Automatic” unless you know the node requires a specific generation mode, or that the work items need to be generated dynamically.

All Upstream Items are Generated

This node will generate work items once all of the input nodes have generated their work items.

All Upstream Items are Cooked

This node will generate work items once all of the input nodes have cooked their work items.

Each Upstream Item is Cooked

This node will generate work items each time a work item in an input node is cooked.

Automatic

The generation mode is selected based on the generation mode of the input nodes. If any of the input nodes are generating work items when their inputs cook, this node will be set to Each Upstream Item is Cooked. Otherwise, it will be set to All Upstream Items are Generated.

Cache Mode

Determines how the processor node handles work items that report expected file results.

Automatic

If the expected result file exists on disk, the work item is marked as cooked without being scheduled. If the file does not exist on disk, the work item is scheduled as normal. If upstream work item dependencies write out new files during a cook, the cache files on work items in this node will also be marked as out-of-date.

Automatic (Ignore Upstream)

The same as Automatic, except upstream file writes do not invalidate cache files on work items in this node and this node will only check output files for its own work items.

Read Files

If the expected result file exists on disk, the work item is marked as cooked without being scheduled. Otherwise the work item is marked as failed.

Write Files

Work items are always scheduled and the expected result file is ignored even if it exists on disk.

Cook Type

Determines how work items in the node should cook, e.g. if they should run in process, out of process, or using services.

Run on Service Block

Determines whether or not work items in this node should run on the parent service block, if one exists.

Always

Always run work items on the block’s service, regardless of any other service settings on this node.

Match

Only run work items on the block’s service if Service Name matches the service name that’s used by the block.

Never

Never run work items on the block’s service.

Service Name

When Cook Type is set to the Service, this parameter is used to specify the name of the service. For more information on using services, see the PDG Service Manager documentation.

Source

USD Path

Determines the source of the USD file.

Upstream Output File

The output file produced by the upstream work item is used as the path to the USD file.

Custom File Path

The custom file path specified by File Path is used as the path to the USD file.

File Tag

This parameter is only available when USD Path is set to Upstream Output File.

Specifies the data tag that is used to select the result from the upstream work item.

File Path

This parameter is only available when USD Path is set to Custom File Path.

Specifies the path to the USD file to be rendered.

Operation

Evaluate Using

Determines how the TOP node creates and executes work items.

When using the Single Frame option, the node creates one work item for each upstream frame. When using the Frame Range option, the node creates one work item per frame in the range for each upstream work item. When using the ROP Node Configuration option, PDG cooks the ROP without passing any frame range options and uses whatever configuration is set on the target ROP. When using the Automatic option, the node automatically configures the node based on whether or not it has any inputs.

Single Frame

The node creates a single work item per upstream item and sets the new work item’s frame to match the upstream item’s frame. If there are no input nodes, then the node creates a single work item set to frame 1. You can override the single frame value with the Override Frame parameter.

Frame Range

For each upstream work item, the node creates the full frame range of work items. If there are no upstream items, the node creates one set of items for the specified frame range.

Automatic

If the node has inputs, it generates one frame of work for each input. If the node does not have any inputs, it generates work items for the node’s full frame range.

ROP Node Configuration

For each upstream work item, the node creates a single work item that cooks the ROP Path and PDG does not pass any frame range settings to the ROP node. The number of frames to cook is determined by the parameters on the ROP itself.

Override Frame

When this parameter is enabled, it overrides the frame used with the Single Frame Evaluation mode.

Frame Range

The frame start, end and step size to use when Frame Generation is set to Frame Range.

All Frames in One Batch

When on, work items from the same frame range are grouped into a batch that is scheduled as a single job. This is used for simulations where each frame depends on the previous frame, and it is advantageous to keep everything in memory.

Frames per Batch

By default, when this parameter is at 1 each work item is cooked as a separate job. When this parameter is set to a value greater than 1, work items are grouped into batches.

Output

Create Intermediate Directories

Override Output

When on, the render is sent to the specified file path instead of the output location specified in the RenderSettings prim.

Variables are expanded in the string can be represented in various ways. See the list below.

  • Current frame number: \$F, \$FF, \$F4. (Must be escaped with a backslash)

  • The N’th frame in the sequence: \$N. (Must be escaped with a backslash)

  • Frame (<UDIM> style): <F>, <FF>, <F4>.

  • Frame (printf style): %d, %g, %04d.

Note

If you are rendering using a batch, do not use @pdg_frame or any other per-frame attributes in this file path. This is because husk has no way of evaluating the attributes when rendering multiple frames. Instead, you should use the symbols that husk understands, like <N> and %03d.

When off, the output files will not be added to the work item until the images are rendered. That is because this node has no way of knowing what the generated file paths will be. If you want to generate static items downstream from your output files, you should add them using an attributecreate.

Output File Tag

When on, this parameter specifies a custom file tag for outputs produced by work items from this node.

Expected Output From

Determines how the expected output file paths are added.

Since this node may not have access to the USD file during the generation phases of the PDG cook, you must supply the expected output file paths to the node if you want to make use of these paths downstream in other TOP nodes during generation.

These expected file outputs correspond to the RenderProduct prims that are resolved by USD. For more information, see the Render Product node.

None

No expected outputs are added.

Attribute

The given attribute name is evaluated and added as expected outputs. This can be a file or string array attribute.

File List

The given output file paths are added.

Attribute Name

When Expected Output From is set to Attribute, this parameter specifies the name of the attribute that contains the expected output file(s).

Index Attribute by Frame

When Expected Output From is set to Attribute, this parameter can be used to treat the attribute as an array that should be expanded across the range of work items in this node. Otherwise, if this toggle is disabled, then the list of files from the attribute will be added to each work item directly.

Husk Options

Purpose

Specifies the purpose for rendering.

This is a comma separated list of purposes (from {'geometry', 'guide', 'proxy', 'render'}).

Render Settings Prim

Specifies the scene graph path to the RenderSettings prim with which you want to render. You can specify a path relative to /Render.

If this parameter field is empty, the node looks for default render settings on the root prim. If the root prim has no render settings, the node uses default settings.

Complexity

Specifies the geometric complexity ({'low', 'medium', 'high', 'veryhigh'}).

Rendering Threads

Specifies which rendering threads this node should use.

Use All Processors

Use as many rendering threads as there are processors.

All Processors Except One

Use one less thread than the processor count.

Custom Thread Count

Use the specified custom number of rendering threads.

Other Delegate

When on, specifies the Hydra client to use to render your images. By default, the Hydra client is Karma.

You must register any alternate Hydra clients with Houdini’s USD libraries. For more information, see how the node gets the list of available renderers above.

Checkpoint Interval

When on, specifies the interval (in seconds) at which the renderer writes out a checkpoint file and partial image.

Command Prefix

Specifies a command to be executed instead of the husk executable. This command will be passed the full generated husk command line. To function properly this wrapper program should pass through the stdout from husk.

Extra Husk Arguments

Specifies any extra arguments to pass to the husk executable along with those determined by the parameters.

Create Husk Command Attribute

When on, creates a work item attribute with the value of the full husk command that is executed by the job. This attribute is created after the job cooks.

Time Limit

Seconds

When on, specifies the rendering time limit (in seconds).

Time Limit Is Per Frame

This parameter is only available when Seconds is on.

When on, the Seconds time limit applies to images rather than your whole sequence.

No Partial Results on Timeout

This parameter is only available when Seconds is on.

When on, partial results are not saved when the Seconds time limit is exceeded.

Verbosity

Level

Determines the amount of information to print out while rendering. A higher number means more information is printed during the render.

VEX Profiling

Allows you to use VEX profiling.

Off

VEX profiling is disabled.

VEX

VEX profiling is enabled.

VEX and NAN Checks

VEX profiling with NAN checks is enabled.

Warning

This parameter impacts performance.

Alfred Syle Progress

When on, the node writes print percentage complete values as files in the style expected by Pixar’s Alfred render queue.

Message Time Stamps

When on, time stamps are applied to messages.

Schedulers

TOP Scheduler Override

This parameter overrides the TOP scheduler for this node.

Schedule When

When enabled, this parameter can be used to specify an expression that determines which work items from the node should be scheduled. If the expression returns zero for a given work item, that work item will immediately be marked as cooked instead of being queued with a scheduler. If the expression returns a non-zero value, the work item is scheduled normally.

Work Item Label

Determines how the node should label its work items. This parameter allows you to assign non-unique label strings to your work items which are then used to identify the work items in the attribute panel, task bar, and scheduler job names.

Use Default Label

The work items in this node will use the default label from the TOP network, or have no label if the default is unset.

Inherit From Upstream Item

The work items inherit their labels from their parent work items.

Custom Expression

The work item label is set to the Label Expression custom expression which is evaluated for each item.

Node Defines Label

The work item label is defined in the node’s internal logic.

Label Expression

When on, this parameter specifies a custom label for work items created by this node. The parameter can be an expression that includes references to work item attributes or built-in properties. For example, $OS: @pdg_frame will set the label of each work item based on its frame value.

Work Item Priority

This parameter determines how the current scheduler prioritizes the work items in this node.

Inherit From Upstream Item

The work items inherit their priority from their parent items. If a work item has no parent, its priority is set to 0.

Custom Expression

The work item priority is set to the value of Priority Expression.

Node Defines Priority

The work item priority is set based on the node’s own internal priority calculations.

This option is only available on the Python Processor TOP, ROP Fetch TOP, and ROP Output TOP nodes. These nodes define their own prioritization schemes that are implemented in their node logic.

Priority Expression

This parameter specifies an expression for work item priority. The expression is evaluated for each work item in the node.

This parameter is only available when Work Item Priority is set to Custom Expression.

Local

Single

When on, only one single work item is executed at a time.

Examples

USDRender Example for USD Render Files TOP node

This example demonstrates how to render USD / LOPs content using the husk renderer with the USD Render TOP node.

See also

TOP nodes