CEL Reference

Collection Expression Language (CEL) is a generalized grammar for selecting subsets of objects organized within hierarchies.

In Katana, CEL statements are most often used specify the scene graph locations on which an operation or assignment will act. CEL statements can also be used to define “collections” which may then be referenced in other CEL statements.

Katana tries to represent the most common CEL operations within the GUI for CEL parameters or attributes. It also allows direct access to the full capabilities of the language with its “Custom” CEL statement pane.

Selecting Objects by Name

A path within CEL is called a “Pattern List”. Any name within a path may contain a wildcard “*” and may be specified as recursive.

Explicitly select the object at a path:

/root/world/cam_main

Select all immediate children of /root/world whose names start with “lgt”:

/root/world/lgt*

Select all objects recursively beneath /root/materials:

/root/materials//*

Select all objects named “shape” anywhere within the scene:

//shape

Combining Sets

The result of a Pattern List is a set of objects or a “Set”. Sets are combined in CEL with union (+), difference (-) and intersection (^) operations.

Adjacent sets without any operator are implicity unioned. This statement selects both of those paths:

/root/world/lgt_key /root/world/lgt_fill

This statement is equivalent to the last:

/root/world/lgt_key + /root/world/lgt_fill

Select all of the immediate children of /root/world except for “lgt_rim”:

/root/world/lgt* - /root/world/lgt_rim

This example demonstrates that set operations are evaluated from left to right. This results in only /root/world/b:

/root/world/a + /root/world/b - /root/world/a

Parentheses may be used to control the order of evaluation. This example results in all immediate children of /root/world whose names begin with “cam” or “lgt” but which aren’t named “cam_main”, “cam_taco” or “lgt_rim”:

(/root/world/cam* - (/root/world/cam_main /root/world/cam_taco)) +
(/root/world/lgt* - /root/world/lgt_rim)

Select all immediate children of /root/world whose name contains both “a” and “b” in any order:

/root/world/*a* ^ /root/world/*b*

Value Expressions

The results of any Pattern within a Pattern List or any set may be filtered through a “value expression.” Value Expressions may query information and attributes about each object in order to include or exclude it from the set.

Selects all immediate children of /root/world whose “type” attribute has a value of “camera”:

/root/world/*{ attr( "type" ) == "camera" }

Select all objects recursively beneath /root/world which have a local attribute named “textures.Colmap”:

/root/world//*{ hasattr("textures.ColMap") }

Select all objects recursively beneath /root/materials whose names contain either “cheese” or “taco” and who have or inherit an attribute named “material.surfaceParams.Kd” with a value which is greater than 0.5 and less than 0.75. This demonstrates that groupings of sets may be filtered in the same way as individual patterns:

( /root/materials*cheese* /root/materials*taco* ){
globalattr("material.surfaceParams.Kd") > 0.5 and
globalattr("material.surfaceParams.Kd") < 0.75 }

Collections

All CEL statements search within the context of and are defined relative to an object within the scene. A Collection is a CEL selection (often a CEL statement itself) stored on the scene graph. It may reference things at or below the object on which it’s defined. In Katana, Collections which live at the root of the scene are represented as scene graph locations beneath /root/collections. This can be thought of as “global” or “scene-wide” Collections. Collections are typically defined with a CollectionCreate node in Katana.

A Collection (and its contents) may be referenced by any CEL statement.

Reference the contents of a global collection named “my_collection”. This would appear in the scene graph as /root/collections/my_collection:

/$my_collection/*

Collections may also be defined at arbitrary locations of the scene graph. Their paths are expressed relative to the object in which their defined. For example, in a scene with this topology:

root
`-- world
    `-- taco
        |-- a
        |-- b
        `-- c
            `-- d

A CEL statement which defines a Collection at /root/world/taco that selected /root/world/taco/a and /root/world/taco/c/d could be expressed as: /a c/d

Assuming that Collection was named “my_collection”, it could be referenced in an assignment node with /root/world/taco/$my_collection/*.