Skip to content

Grouping Items#

Groups are a special type of items used to define a collection of items which can be procedurally generated using rules. They are an essential part of the workflow since every time you can specify a list of items in Clarisse, you can use a group in the list. Groups are used for many different purposes such as to name a few:

  • Setting the content of a Combiner
  • Setting a group of items as instances for the Scatterer
  • Defining the item visibility of a render layer

Note

A group is simple a list of items. They don't have any transforms and their content can't be directly rendered. Group item membership isn't exclusive: items can be part of any number of groups.

Creating groups#

Like any other items, you can create a new empty Group using the Create menu. It is also possible to directly create a new Group from a selection of items. To create group from a selection, go to Edit > Group... or press Ctrl+Shift+G to create a new group in the current context.

Deleting groups#

Groups are deleted like any other items in Clarisse. Deleting a group doesn't delete the items listed by the group!

Input Context#

The Input Context attribute of the group defines which context the group will use for item lookup and rule resolution. Setting this attribute is only mandatory when the group is directly created in the build.

Adding items#

There are two ways to specify which items a group contains. You can either explicitly include items using the Inclusion Items list and use also a rule to the Inclusion Rule attribute in order to dynamically populate the list based on item name pattern matching.

The most straightforward way to add items to groups is to select which items to add by clicking the Add... button located under the Inclusion Items attribute in the Attribute Editor. To remove items from a group in item list, simply use the Edit > Remove Selection option located above the item list. All selected item in the list of item will be removed from the group.

Alternatively, items can be procedurally by using a rule. Please refer to Rule-based item Inclusion/Exclusion for more information.

Note

The final list of items actually referenced by the group can be seen in the Reference list attribute in the Attribute Editor.

Excluding items#

There are two ways to exclude items from a Group. You can either explicitly exclude items using the Exclusion Items list and use also a rule to Exclusion Rule attribute in order to dynamically remove items from the list based on item name pattern matching.

The most straightforward way to remove items to groups is to select which items to remove by clicking the Add... button located under the Exclusion Items attribute in the Attribute Editor.

Alternatively, items can be procedurally removed by using a rule. Please refer to Rule-based item Inclusion/Exclusion for more information.

Note

The final list of items actually referenced by the group can be seen in the Reference list attribute in the Attribute Editor.

Item class filtering#

It is possible to specify a class filter to restrict the class of the items a group can contain. This restriction is set by using the Filter attribute. Changing the Filter value may cause some items to be removed from group as they may not match the class filter anymore.

Important

Setting a proper filter is key as it can avoid unnecessary evaluation. For example, creating a group of lights with a Filter set to Project Item can lead to include unnecessary items in the group specially when using rules. For example, you could end up adding geometries in a group of lights so that each time one of the geometry is modified the modification is propagated resulting eventually to an unnecessary re-evaluation.

Rule-based item Inclusion/Exclusion#

Instead of explicitly adding or removing items in groups, it is possible to use simple pattern name matching rules to dynamically populate groups content. When a group defines such rules, items matching the patterns are automatically added or removed from the group so that:

  • If items match the rules set in Inclusion Rule, they are automatically added to the group.
  • If items match the rules set in Exclusion Rule, they are automatically removed from the group.

Note

In any case, only items matching the class Filter are tested against the rules.

Rule Syntax#

The syntax of rules is based on a simple wildcard pattern matching.

Rule Description
* gather all items starting from the root of the project. This rule is strictly equivalent to project://*
project://context/* gather all items starting from context project://context
*box* gather any items that have box in their name (starting from the project root). This rule is strictly equivalent to project://*box*
project://ctx*/*/table* gather all items that have their name starting with table and that are located in all the sub-contexts of any root contexts that have their name starting with ctx

For performance reasons, it is best to avoid rules starting by *. Indeed, such rules force the group to evaluate its rules against all items of the project every single time an item is added or deleted.

Relative Paths#

For convenience, it is possible to relative paths in rules when the rule starts with ./ By default, the rules are relative to the parent context of the group. However, it is possible to specify a list of alternate locations by creating a Search Path item and connecting it to the Search Paths attribute.

Rule Description
./* gather all items starting from the parent context of the Group
./*box* gather all items that having box in their name starting from the parent context of the Group.

Note

It is possible to set a Search Path item to the group to relocate the location of ./

Multiple Rule Syntax#

Multiple rules can be combined separated by a semicolon ;. For example: *box*;*sphere* gathers all the objects with either box or sphere in their name.

Update mode#

By default, rules are automatically resolved when an item is added, moved/removed, renamed in the project. Depending on the complexity of the scene, the rule resolution can take quite some time to resolve. This is why, it is possible to stop the automatic resolution of rules by setting the Update Mode attribute to Manual. In that case, groups are no longer automatically updated. To resolve the content of the group, you must then explicitly click on Refresh button in the Attribute Editor.

To set the Update Mode to automatic, just set Update Mode to Automatic.

Note

When a group is set to Manual, the final list defining the content of the group is saved in the project/build file. This way, when the project/build is reloaded, rules are not evaluated so the content of the group stays consistent to the one that was defined when the file was saved.

Result Filter#

The Result Filter attribute allows you to post-filter the content of a group which is very useful when you want to isolate specific items. By default, Result Filter is set to *. This means doesn't filter out any items. Changing this attribute to something else allows you to post process the item list to include only specific parts of items supposedly linked by the group.

For example, a group can link to a comprehensive hierarchy of items defining a robot using inclusion rules or explicit linking. By using Result Filter you can decide to only keep in the group items having the name left in their full name. This is be achieved very easily by setting Result Filter to *left*.

Note

Unlike rules in Clarisse, Result Filter rules applies only to the list of items linked by the group. In other words, the wildcard * doesn't mean everything in the project, but everything in the item list.