Search Tips

Search is based on keyword.

`Ex: "Procedures"`

Do not search with natural language

`Ex: "How do I write a new procedure?"`

Give Feedback Support Portal

# Pattern-Based Collections with USD

Pattern-Based Collections (PBC) was introduced in USD 23.11 and is now fully integrated in Katana.

Similar to Katana’s pre-existing Collections and CEL, USD’s Pattern-Based Collections (PBC) allows you to:

• Use Paths, Collections and Custom statements as inputs.

• When multiple statements are set, use additional options to determine the relationship between them, such as Union, Difference, Intersect, and Complements.

Paths | These are explicit lists of scene graph paths. If you drag and drop locations from the Scene Explorer tab onto the Add Statements area of the PBC widget you are automatically given a Path statement.
Collections | A pre-defined named collection of Scene Explorer locations. Essentially these are arbitrary sets of locations that are handed off for use downstream in the pipeline. Collections can be created in a Katana scene using the UsdCollection node.
Custom | These allow complex rule-based expressions, such as using patterns with wildcards in the paths, or 'value expressions' that specify values that attributes must have for matches.

# Using Patterns

For example, rather than specifying rules for paths to include and exclude in the collection, you could provide a Path statement. This can contain patterns, operators, and references to other expressions, capturing the set of prims you want to match.

A pattern is a sequence of characters that follow a set of syntax rules, with the option to use glob-style wildcard characters.

## Useful Wildcard Characters:

Character | Function
* | Matches zero or more characters, but does not match path or property separators.
? | Matches exactly one character, but does not match path or property separators.
// | Matches any path hierarchy, allowing you to match a sequence of paths of any length.

For example:

/robot* can match /robot, /robotarm, but not /robot/arm or /robot.myAttribute.

/robo? can match /robot or /robos but not /robotarm or /robo.arm.

/robot//arm can match /robot/arm or /robot/child1/child2/arm.

## Useful Predicate Functions

You can also include a predicate function in a pattern, which let you add additional qualifiers for matching prims and properties, creating a value-based expression.

Here are some of the most useful built-in predicate functions, that are built-in to the USD CollectionAPI.

Predicate | Function
isa(typeName1, ... typeNameN, strict=false) | Matches prims that are any typed schema typeName1..N or subtypes. Disallow subtypes if strict=true.
hasAPI(typeName1, ... typeNameN, instanceName='') | Matches prims that have any of the applied API schemas 1..N. If instanceName is provided, the prim must have an applied API schema with that instanceName.
defined(bool=true) | Matches prims that are or are not defined.
specifier(specifier1, ... specifierN) | Matches prims with any of the given specifiers.

To use a predicate function with your pattern, specify the predicate function using the {predicate-name} format.

For example: //{isa:DiskLight} would match any DiskLight prim.

Note: For a full overview of supported Pattern-Based Collection Expressions, see OpenUSD's documentation: Collections and Patterns.

# Using PBC in Katana

• The PBC widget is available in the relevant USD nodes in Katana, such as the UsdActiveSet, the UsdVariantSet, the UsdRelationshipSet nodes and many more.
This allows you to target multiple prim paths at once using these nodes, using a set of rules, (such as Paths, Custom expressions or Collections).

Warning: PBC widgets no longer accept relationship-mode collections (membership determined by 'includes' and 'excludes' lists).

• Additionally, there is a PBC Scratch Pad tab that can be used in a similar way as the CEL Scratch Pad tab. When searchUnloadedPrims is enabled, the pattern is matched against collapsed primitives in the Scene Explorer. When disabled, the result only shows expanded locations.

• You will also need a UsdCollection node to define and modify USD collections - see reference guide page UsdCollection.

• You can see a list of the CEL and USD (PBC) Collections in your project in the Collections panel at the top of the Scene Explorer and via the Collection working set indicators . See Collections in the Scene Explorer.

Video: Discover how to create collections natively in USD and view them using the new Collections Working Set, and Scene Explorer panel - Katana 8.0 | Create collections natively with USD.

# PBC Scratch Pad - Example

We can use the PBC Scratch Pad tab to ‘sketch’ out patterns, collections and custom expressions, in a similar way as the CEL Scratch Pad tab.

An example workflow would be to use the PBC Scratch Pad to write and test Custom expressions for use in other nodes. The option ‘searchUnloadedPrims’ can come in handy here.

In the example shown below, we are using one of the example projects that can be found under Help > Example Projects > Native USD > Native USD Lighting Example.

Using PBC, we can make a selection of all the components that are part of the left eye. Here, we are grabbing all the primitives that include the letter ‘L’ but excluding the ones that are part of the hands.

/GEO/CHAR//*L - /GEO/CHAR/Robot_0?/BodyShell/HandL//

Characters | Function
…//*L… | To include any primitive under /GEO/CHAR/ that has ‘L’ in its name.
…-... | Subtract the result of the following pattern from the previous pattern.
…/Robot_0?/… | Include any primitive and its children if they match the pattern minus the last letter/number. In this case: Robot_01 and Robot_02.
…HandL//… | Include anything under the HandL primitive.