Houdini 20.5 Nodes TOP nodes

Python Processor TOP node

Generates work items using a Python script.

On this page
Since 17.5

This node lets you write custom processor logic using the Python API. PDG evaluates scripts on this node when it generates or cooks work items.

For a detailed explanation of each of the callback functions you can implement, see the Processor node API reference.

For use cases that require a single work item per upstream item that runs a Python Script, please use the simpler Python Script or Generic Generator TOP nodes.

Parameters

Processor

Save to Python Script

Saves the callbacks defined on this node to a Python script, which can be imported and registered with PDG. The parameter template associated with the node is also saved and embedded into the Python script. After saving the script is automatically imported and the node type is made available in the TAB menu.

Save to Digital Asset

Saves the callbacks defined on this node to a standalone Houdini Digital asset. The callbacks are stored inside the .hda itself and are registered with PDG as an embedded PDG node type.

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.

Command

The command line (executable and arguments) to run when the work item runs. If this field is empty the work item will not be scheduled, and will be instantly marked done once all of its dependencies finish.

Generate

onGenerate Callback

The script the node runs whenever it needs to generate new work items from upstream items or from nothing (if it has no inputs). You can use this script for generating both static and dynamic work items.

When generating static work items, a single call will be made to the script and it will receive the entire list of upstream static items in the upstream_items variable. When generating dynamic work items, the script is called once for each upstream item that has finished cooking.

The following variables are available:

self

The underlying PDG node associated with the TOP node. This is different from the TOP node itself, which is a standard Houdini operator.

Any spare parameters added to the TOP node’s parameter interface are also automatically added to the PDG node.

item_holder

The work item holder used to construct new work items. Items in the holder are committed to the node once the script has finished running. If the script fails, the items are discarded.

upstream_items

The list of upstream items.

generation_type

The type of work item generation the script is performing.

Regenerate

Use Custom Regenerate Implementation

When on, the script in onRegenerate Callback is used by the node instead of the built-in one.

onRegenerate Callback

This parameter is only available when Use Custom Regenerate Implementation: is on.

The script the node runs whenever it needs to generate items but already has existing items. You can uses this script to add new work items and dirty or delete existing ones.

The following variables are available:

self

The underlying PDG node associated with the TOP node.

item_holder

The work item holder used to construct new work items.

existing_items

The list of existing work items currently in the node.

upstream_items

The list of upstream work items.

generation_type

The type of work item generation the script is performing.

Add Internal Dependencies

onAddInternalDependencies Callback

The script the node calls when it wants to add dependencies between sibling work items. This script is called once for each call to onGenerate Callback. You can use this script to add dependencies between the items created in that callback invocation.

The following variables are available:

self

The underlying PDG node associated with the TOP node.

dependency_holder

The work item holder used to assign dependency pairs.

internal_items

The list of work items added by the last onGenerate Callback execution.

is_static

Boolean that is set to True if the last generation was static, else False.

Cook Task

onCookTask Callback

The script the node calls when it wants to cook an in-process work item. This script is called for each in-process item produced by onGenerate Callback when those items need to cook. You can create in-process work items when constructing a work item by passing the inProcess=True flag.

The following variables are available:

self

The underlying PDG node associated with the TOP node.

work_item

The work item that is cooking in-process.

Node Options

These parameters give you easy access to a selection of methods from the pdg.NodeOptions class.

Service Name

Specifies the name of the service that the node is using. Leave this field empty if your node is not using a service.

Always Regenerate

When on, the node regenerates work items every cook.

Dirty on Regenerate

When on, the node dirties all work items when it regenerates.

Dirty on Incomplete

When on, the node dirties itself every graph cook unless the node successfully cooked all work items on the previous cook.

Requires Generated Inputs

When on, the node requires that all its input nodes be fully generated before it can generate work items.

Requires Cooked Inputs

When on, the node requires that input work items are cooked before the it can generate work items.

Requires Scene File

When on, the node creates work items that require access to the current scene file.

Requires Input Data

When on, the node needs access to input file data in order to generate work items. Note that this is different from just needing to know the input file paths. You only need to turn on this parameter if your node actually reads the contents of input files when generating its work items.

Uses Dynamic Batching

When on, indicates that the node intends to create dynamic batch work items that expand in size when they cook.

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.

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.

Examples

PythonProcessor Example for Python Processor TOP node

This example demonstrates how to use the Python Processor TOP node to generate new work items.

See also

TOP nodes