Unlike node groups, the nodes in a bundle may be from different node networks.
For example, the same bundle may contain /obj/geo1
and /obj/subnet1/geo2
.
Node groups are primarily used to organize and display very large networks,
while node bundles are normally used to track which objects are lit by
a light, which objects are visible in a scene, etc.
There are two types of node bundles: regular and smart. You can add and remove individual nodes to and from a regular bundle. The nodes in a smart bundle, on the other hand, are determined from a pattern stored in the bundle. As nodes matching the pattern are created or deleted in Houdini, the contents of the bundle will update automatically. You can use hou.NodeBundle.pattern to determine if the bundle is a smart bundle or a regular one.
When a node matches the pattern in a smart bundle, that node and its children
will be added to the bundle. For example, if the pattern in "/obj/*"
and
/obj/box_object1
is a geometry object, all the nodes inside
/obj/box_object1
will be added to the bundle, recursively. Carets (^
) in
the pattern can be used to remove nodes; for example, "/obj/* ^/obj/geo1"
will match everything in /obj
except for /obj/geo1
.
A bundle may also have a filter to specify what types of nodes may be in
the bundle. See hou.nodeTypeFilter for the possible filters. If
you try to add a node to a regular bundle but the node does not match the
filter, Houdini will fail to add the node. For smart bundles, the filter
is applied after doing any pattern matching. For example, if the pattern
is "/obj/*"
and the filter is hou.nodeTypeFilter.Obj
, the bundle will
contain only the objects in /obj
, without any SOPs, etc. inside them.
Because the pattern is applied recursively, however, any objects inside object
subnets will also be in the bundle.
To specify a bundle in a node parameter that expects a list of nodes, prefix
the bundle name with @
. For example, you can enter @bundle1
in the
light mask parameter of an object so it is lit by the nodes inside the bundle
named bundle1
.
You can view and edit node bundles in Houdini’s Bundle List pane. Use hou.nodeBundle() and hou.nodeBundles() to access existing node bundles, and hou.addNodeBundle() to create a new bundle.
Methods ¶
name() -> str
Return the name of the bundle.
setName(name)
Change the name of the bundle.
Raises hou.OperationFailed if the name contains non-alphanumeric
characters other than _
, or if a bundle with that name already exists.
destroy()
Remove this bundle.
pattern()
→ str
or None
Return None if this bundle is a regular bundle, or a string pattern if the bundle is a smart bundle.
See the class documentation for more information on smart bundles. Note
that if a node matches the pattern, all its subchildren will be in the
bundle, as long as they match the filter. For example, if the pattern is
"/obj/*"
and the filter is hou.nodeTypeFilter.NoFilter, the bundle will
contain all nodes under /obj
, recursively.
setPattern(pattern_or_none)
Change the pattern of this bundle.
Setting the pattern to None changes the bundle into a regular bundle. In this case, the bundle’s contents are unchanged, but Houdini will no longer do pattern matching to determine the bundle’s contents.
If the pattern is a string, the bundle becomes a smart bundle and its contents immediately change to match the pattern. The bundle’s contents will update as nodes are created and deleted in Houdini.
See hou.NodeBundle.pattern and the class documentation for more information.
findBestFilter()
→ hou.nodeTypeFilter enum value
Return the most restrictive bundle filter that matches all the nodes in the bundle.
See hou.nodeTypeFilter for the possible filters.
hou.nodeTypeFilter.NoFilter
is a special value to indicate that there
is no filtering.
filter()
→ hou.nodeTypeFilter enum value
Return the bundle’s filter. For smart bundles, the filter is applied after matching nodes to the pattern, and nodes whose types do not match the filter are removed from the bundle.
See hou.nodeTypeFilter for the possible filters.
hou.nodeTypeFilter.NoFilter
is a special value to indicate that there
is no filtering.
See the class documentation for more information about filtering.
setFilter(node_type_filter)
Set this bundle’s filter to a hou.nodeTypeFilter enumerated value.
Use hou.nodeTypeFilter.NoFilter
to clear the filter.
See hou.NodeBundle.filter and the class documentation for more information.
nodes()
→ tuple of hou.OpNode
Return a tuple of the nodes in this bundle.
containsNode(node)
→ bool
Return True if the node is in the bundle and False otherwise. node
must
be a hou.OpNode object.
This method is a shortcut for node in bundle.nodes()
. For bundles with
many nodes, this method will be slightly faster.
addNode(node)
Add a node to the bundle.
Raises hou.OperationFailed if this bundle is a smart bundle, since the contents of smart bundles are automatically determined by their pattern.
removeNode(node)
Remove a node from the bundle.
Raises hou.OperationFailed if this bundle is a smart bundle, since the contents of smart bundles are automatically determined by their pattern.
clear()
Remove all nodes from the bundle.
Raises hou.OperationFailed if this bundle is a smart bundle, since the contents of smart bundles are automatically determined by their pattern.
isSelected()
→ bool
Return True if the bundle is selected in the bundle list pane and False otherwise.
setSelected(on, clear_all_selected=false)
Select this bundle in the bundle list pane. If clear_all_selected
is
True, only this bundle will remain selected. Otherwise, this bundle will
be added to the existing selection.
convertToNormalBundle()
Convert the bundle into a normal bundle. The smart bundle pattern is removed.
Do nothing if the bundle is already a normal bundle.
convertToSmartBundle()
Convert the bundle into a smart bundle. A regular expression is constructed from the contents of the bundle and then set as the bundle pattern.
Do nothing if the bundle is already a smart bundle.