Houdini 20.0 Nodes TOP nodes

File Pattern TOP node

Creates work items based on files that match a certain pattern.

On this page
Since 17.5

This node generates a work item for each file or directory name that matches a pattern in a directory or all sub-directories. This node also has two modes for generating work items, and which mode it uses is determined by the Split Files into Separate Items parameter.

Whenever this node is asked to generate items, like when it cooks or when you ask nodes to pre-generate static items, the node checks if the pattern matches different files from the last cook and if the modification times have changed on any files. If the answer is yes, then the node updates the changed items and marks them dirty. So when the directory contents change, usually only the changed items need to be recooked.

TOP Attributes

When the Split Files into Separate Items parameter is on, the node sets the following attributes on each work item:



The directory containing the file associated with the work item, without the filename or extension.



The extension of the file associated with the work item.

This attribute is not set when File Types is set to Directories Only or when the matched path is a directory.



The name of the file.

This attribute is not set when File Types is set to Directories Only or when the matched path is a directory.



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.


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.

File Types

File types to pattern match.

Files Only

Match only files.

Directories Only

Match only directories.


Match both files and directories.


Specifies the path to start searching in as well as the pattern to match. For example, $PDG_DIR/geo/*.bgeo would look in the geo directory inside the project working directory and find all files ending in .bgeo.

Pattern allows wild cards such as ? (match any character), * (match any string of characters), and [abc] (match any one of the characters inside the square brackets). For example, *.png matches any file that ends with .png.

Pattern is always expanded on the machine where the network cooks, not on a remote host on the render farm. The expanded filenames should still be under the working directory in the shared network file system. This node will automatically convert local matched file paths to paths that are relative to the working directory.


$F does not work like you would expect. The pattern expression is evaluated in the context of a work item, which has a particular frame value. Please use the File Range TOP node instead.


When on, the node looks for matching filenames in sub-directories of the path specified by the Pattern parameter.

No Match Behavior

Determines what to do when the file pattern fails to match any files.


Does not generate work items for missing files.

Set Node Error

Sets an error on the node.

Create Work Items

Creates a work item and sets an attribute indicating that it is missing.

File Exists Attribute

Specifies the name of the attribute to create on each work item which will indicate whether or not the file was found.

Work Items

Include Extensions in Filename Attribute

When this toggle is enabled the full filename including the extension is saved to an attribute on the work item. If the toggle is disabled only the base file name, without the an extension, is stored to the attribute.

Split Files into Separate Items

When on, the node creates separate work items for each matched name and stores the filename data in the attributes. This parameter is on by default. When off, the node creates one work item with the matching file paths set as the item’s output results. Turning off this parameter can be useful when the node you're wiring this node into operates on results data.

Inherit Upstream Work Item Index

When Split Files into Separate Items and this parameter are enabled, generated work items will inherit the upstream work item’s index. When this parameter is disabled and Split Files into Separate Items is enabled, the work item’s index is based on its file’s position within the list of discovered files.


Output Attribute

By default, files that match the Pattern are stored as work item outputs. When this parameter is enabled, the files are instead stored to a file attribute with the specified name.

Output File Tag

When on, assigns this file tag to the output file paths. When off, the node guesses appropriate file tags based on filename extensions.

Copy File(s) to Working Directory

Indicates that the globbed files should be copied from their source location to the scheduler’s working directory when this work item cooks.

Enabling this toggle sets the pdg.attribFlag.Transfer attribute flag on the work item’s output file list.


FindFiles Example for File Pattern TOP node

This example demonstrates how to use File Pattern to load files using a match expression.

See also

TOP nodes