| 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:
|
|
string |
The directory containing the file associated with the work item, without the filename or extension. |
|
|
string |
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. |
|
|
string |
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. |
Parameters ¶
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.
File Types
File types to pattern match.
Files Only
Match only files.
Directories Only
Match only directories.
All
Match both files and directories.
Pattern
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.
Note
$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.
Recursive
When on, the node looks for matching filenames in sub-directories of the path specified by the Pattern parameter.
Follow Symlinks
When Recursive is enabled, this parameter determines whether or not the node should recursive into directories pointed to by symbolic links.
No Match Behavior
Determines what to do when the file pattern fails to match any files.
Ignore
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.
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.
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.
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.
File Attribute
The name of the attribute created on each work item that contains the base file name, assuming the file is not a directory. This parameter is only available when Split Files into Separate Items is enabled.
Directory Attribute
The name of the attribute created on each work item that references the directory containing the file. This parameter is only available when Split Files into Separate Items is enabled.
Extension Attribute
The name of the attribute created on each work item that contains the file extension, if the file has one. This parameter is only available when Split Files into Separate Items is enabled.
File Size Attribute
When enaabled, this parameter contains the name of the attribute created on each work item to store the file size. This parameter is only available when Split Files into Separate Items is enabled.
Mod Time Attribute
When enaabled, this parameter contains the name of the attribute created on each work item to store the last modified time. This parameter is only available when Split Files into Separate Items is enabled.
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.
Examples ¶
FindFiles Example for File Pattern TOP node
This example demonstrates how to use File Pattern to load files using a match expression.
| See also |
File Copy
File Remove
File Rename
