Houdini 20.5 Nodes TOP nodes

HDA Processor TOP node

Creates work items that cook a digital asset

On this page
Since 17.5

This node generates work items that cook an HDA using hython.

You can specify the values of the HDA’s parameters in the HDA Parameters tab of the node, which are then applied as attributes on the node’s work items and used in the job environment to configure the HDA before cooking.

The HDA Processor node currently supports Object, SOP, COP2, and LOP-type HDAs.

Tip

  • The $HH/help/files/pdg_examples/top_roaderbuilder example shows how you can use this node to write out geometry defined in a digital asset.

  • The $HH/help/files/pdg_examples/top_feedbackhda example shows how you can use this node inside of a feedback loop.

TOP Attributes

This node creates attributes on work items for all spare parms added to the HDA Parameters folder on the node.

Additionally, it also creates the following built-in attributes:

batchmode

integer

Determines the Batch Mode setting.

  • 0 = Off

  • 1 = All Items in One Batch

  • 2 = Custom Batch Size

connectiontimeout

integer

The connection timeout limit (ms) when using the HDA Processor service.

cookwhen

integer

Determines the Cook Batch When setting.

  • 0 = All Items are Ready

  • 1 = First Item is Ready

hda

string

The path to the digital asset that is cooked by the work item’s job.

operatortype

string

The operator type within the digital asset.

If you do not specify an operator type using the Operator Type parameter, then this attribute is set to the empty string and the work item will use the first operator in the .hda.

createfileinput

integer

Determines the Create File Inputs setting.

  • 0 = Do not create file inputs

  • 1 = Create file inputs

missinginput

integer

Determines the Missing Input setting.

  • 0 = Raise Error

  • 2 = Ignore

fileinputs

integer

Specifies the number of file inputs that are input to the HDA.

writeoutput

integer

Determines the Write Outputs setting.

  • 0 = Do not write outputs

  • 1 = Write outputs

dumpdebug

integer

Determines whether or not to save a debug .hip file.

  • 0 = Do not save .hip file

  • 1 = Save .hip file

debughipfile

string

If dumpdebug is set, this attrbiute determines the path that the debug .hip file will be saved to

dumpperf

integer

Determines whether or not the performance monitor should be run while cooking the .hda.

perffile

string

If dumpperf is enabled, this specifies the path that the performance monitor output is saved to. If this attribute is empty, performance monitor output goes to the work item’s log instead.

debugoutputs

string

Determines whether debug output files like the performance monitor or saved scene should be reported as work item outputs.

inputpath

string

A list of paths to the file inputs that are input to the HDA.

outputfiles

integer

Specifies the number of output files that are written from the HDA.

hdasopname

string

When cooking an Object-level HDA, this specifies the name of the SOP that is the source of the output file(s) to write out.

If this empty, then the HDA Processor job attempts to find a valid node to output and issue a warning in the job log.

outputpath

string

A list of paths that specify the files to be written out.

outputtag

string

A list of file tags that specify the result tag for each output file.

hdaparms_floats

string

A list of names for all the float attributes that specify an HDA Parameter float value.

hdaparms_ints

string

A list of names for all the integer attributes that specify an HDA Parameter integer value.

hdaparms_strings

string

A list of names for all the string attributes that specify an HDA Parameter string value.

hdaparms_buttons

string

A list of names for all the integer attributes that specify an HDA Parameter button value.

Note

Buttons are converted into toggles within the HDA Parameters tab. When a toggle is on, it means that the HDA Processor will press the button before cooking.

Parameters

Generation

Asset

Template Node

Selects an instance of a digital asset within the current Houdini session.

All the template node’s non-default parameter values are applied to the HDA Processor’s HDA Parameters.

HDA File

Specifies the path of the HDA to cook.

This path can be absolute or it can be relative to HOUDINI_PATH. For example, if an asset like myasset.hda is in a sub-directory otls in hou.homeHoudiniDirectory(), you can specify that HDA’s path as otls/myasset.hda.

Any HDAs that are added to this node’s File Dependencies are automatically copied to the $PDG_TEMP/otls directory. Any nested HDAs that are required by the HDA being cooked and are not otherwise available in the user’s HOUDINI_PATH also need to be added as a File Dependency.

Add HDA Parameters

This menu controls how HDA Parameters and their values are added to the work item as attributes. The HDA Parameter attributes on the work item are used to set the node’s parameter values during the cook. The names of HDA Parameters are specified in four string attributes: hdaparms_floats, hdaparms_ints, hdaparms_strings, and hdaparms_buttons. For any parameter names specified in these attributes, there must be a corresponding attribute with the same name which specifies the values of the parameter.

Automatically

The node will automatically add the necessary work item attributes by inspecting the parameters within the HDA Parameters tab.

Manually

When this option is selected, the necessary HDA Parameter work item attributes must be manually added by an upstream node. This option is useful when the HDA is procedurally specified and is therefore cooking different HDAs that have different parameters.

Specify Operator Using

Determines how the operator type should be specified.

First Definition in Asset

The operator is chosen automatically, using the first definition in the asset.

Custom String

The operator type is set using a custom string.

Operator Type

The name of the operator type to select from within the digital asset. If the operator type is invalid or unset, the HDA Processor will pick the first type it finds when cooking the asset.

This parameter is only available when Specify Operator Using is set to Custom String.

Update HDA Parameters

Updates the parameters listed in the HDA Parameters tab.

Filter HDA Parameters

Opens the Filter HDA Parameters window.

You can use this window to configure which parameters from the asset should be included in the HDA Parameters tab. Any parameters that are included in HDA Parameters will have their values set when the HDA Processor cooks the HDA.

Work Items

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.

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.

Delete HDA Instance after Cooking: #id: inprocesscleanup

When Cook Type is set to In Process, this parameter determines whether or not work items should clean up instances of the .hda that they create while cooking. If this parameter is enabled, each work item will create and destroy an instance of the HDA when it cooks. Otherwise, if the parameter is disabled the HDA instances will not be deleted after cooking. Additionally, work items will attempt to reuse existing instances when possible.

Batch Mode

Determines how batch jobs are submitted by the node.

Off

No batching is performed. Each work item is submitted as its own individual job.

All Items in One Batch

All work items are submitted as a single batch job and take place in a single Hython session.

This option can significantly increase the speed at which the node finishes cooking, especially if the HDA has a relatively quick cooking time such that the time to start up a Hython process is longer than the time it takes to cook the HDA.

Custom Batch Size

Work items are submitted as batch jobs that are the size specified by the Batch Size parameter.

This option can significantly increase the performance of the node since it allows for various optimizations to be performed. For example, like only having to instantiate the HDA once per batch job.

Batch Size

This parameter is only available when Batch Mode is set to Custom Batch Size.

Specifies the size of each batch. If there is underflow in the last batch, then the size of the last batch is the remaining work items.

Cook Batch When

This parameter is only available when Batch Mode is not set to Off.

Determines when batches of work items are scheduled.

By default, the batch is scheduled once the dependencies for all work items are cooked. However, it is also possible to schedule the batch as soon as the first work item can run.

All Items are Ready

The batch is only scheduled once all dependencies on all work items in the batch are satisfied.

First Item is Ready

The batch is scheduled as soon as the dependencies for its first work item are ready. The HDA Processor wrapper script used by PDG communicates back to PDG as the job is running to check the status of the dependencies before cooking each work item in the batch. This incurs slightly more network overhead, and requires ongoing communication between the job and PDG.

Asset Inputs

Create File Inputs

When on, one or more file nodes are instantiated and wired as inputs to the asset. You can use this to chain multiple HDA Processor nodes together more easily.

When using this parameter, the HDA type must be able to support file inputs. For example, Object-level HDAs would not work with this parameter.

Input File Source

This parameter is only available when Create File Inputs is on.

Determines the source of the input files.

Upstream Output Files

The upstream output files with the tag specified by the File Tag parameter are used as inputs to the HDA.

This option is particularly useful when the number of inputs vary.

Custom File Paths

The files you specify with the Number of Inputs multi-parm are used as inputs to the HDA.

Missing Input

This parameter is only available when Create File Inputs is on.

Determines how HDA Processor behaves when one or more of its inputs are missing.

Raise Error

If an input is missing on an input File node, then the File node will error out and cause the cook to fail.

Ignore

If an input file is missing from disk, the File nodes are set to produce No Geometry and no error is be raised.

File Tag

This parameter is only available when Create File Inputs is on.

Specifies the file tag of the upstream output files to use.

Number of Inputs

This parameter is only available when Input File Source is Custom File Paths.

Specifies the number of input file nodes to create.

Input File #

This parameter is only available when Input File Source is Custom File Paths.

Specifies the path to the input file that will be loaded in by the created File node.

Asset Outputs

HDA Type

Identifies the type of asset you are working with: Object, Sop, Lop, or Cop2.

HDA Processor automatically sets the HDA Type based on the type of HDA you selected and deactivates any Asset Output parameters that are not required for the asset type.

Write Outputs

When on, HDA Processor outputs geometry to disk from the display node in the asset.

If your asset contains a COP network or a ROP network, then it would be useful to turn off this parameter.

Sop Path

This parameter is only available when HDA Type is Auto or Object.

Specifies the operator path or SOP name for the geometry that HDA Processor will output.

We recommend that you use an operator path specified relative to the top-level node of the HDA. For example, if you have an Object-level asset with a geometry node inside it named geometry_to_export, and you want to write out the geometry of that node to a file, then you should specify the SOP path as ./geometry_to_export.

Number of Outputs

Specifies the number of outputs. SOPs can have more than 1 output.

Output File Name #

Specifies the name of the output file.

Output Tag #

Specifies the result tag assigned to the result file.

Debugging

Enable Performance Monitor Logging

When on, the performance monitor is started when the .hda begins cooking, and stopped when the cook completes. The performance monitor stats are logged to the work item output or to a file on disk, depending on whether Performance File is enabled.

Performance File

When enabled, performance monitor data is written to the path specified by this parameter.

Save Debug HIP File

When enabled, this parameter specifies the filepath of the debug HIP file that will be written to disk.

Report Debug File as Outputs

When this parameter is enabled, the output files specified by Save Debug HIP File and Performance File are added as work item outputs when the work item finishes cooking.

Report Nested Node Errors

When this parameter is enabled, error messages will be retrieved and logged for all nodes that are in an error state. When it is disabled, only the top level node error will be logged.

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.

HDA Parameters

The parameters in this tab section of the node are automatically filled in based on the parameter interface of the current digital asset. The parameters you set here are copied to work item attributes and applied to the asset when it is cooked.

Files

File Dependencies

A list of files that should be copied to the PDG working directory before the first work item in this node is executed. This can be used to ensure that supporting files like digital assets and custom scripts are available for the work item job.

The specified paths can be absolute or relative to HOUDINI_PATH.

Examples

example_top_hdaprocessor Example for HDA Processor TOP node

This example demonstrates how to use the HDA Processor TOP.

See also

TOP nodes