Collaboration diagram for Collision Filter Groups:

The Principle

A collision filter group represents collision filtering by defining a collection of collision elements. That group then defines "ignore" relationships with other groups. A collision element's membership in a group does not guarantee inclusion in any filtered collision pairs. This group must be included in at least one group's ignore list; inclusion in its own ignore list would be sufficient.)

A collision-filter-group-based filtering system's unique benefit arises from thinking about classes of collision elements. It serves as a short hand for communicating that no collision element in one class can collide with elements belonging to another class. Each unique collision filter group defines such a class.

This can be used to indicate that two different models cannot collide. Simply create two collision filter groups, assigning all of the collision elements of one model to the first group, and all elements of the second model to the second group. Set either group to ignore the other (or both, redundancy doesn't hurt).

The Implementation

Collision filter groups are implemented as a pair of fixed-width bitmasks, stored with each collision element. Each collision filter group corresponds to a single bit. One bitmask represents the set of groups a collision element belongs to. The second represents the groups that this collision element ignores. When a pair of collision elements are considered for collision, the membership mask of each is ANDed with the ignore mask of the other. If either operations produces a non-zero result, the pair is filtered. The cost of the comparison is constant, but related to the bitmask width.

The width is defined at compile time and is defined by drake::multibody::collision::kMaxNumCollisionFilterGroups. The fixed width is a performance optimization but it means that there is a finite number of collision filter groups available in the system. Each RigidBodyTree instance has its own space of collision filter group identifiers.

Collision filter groups are instantiated by specifying them in URDF files as follows:

    <collision_filter_group name="group1">
        <member link="body1">
        <member link="body2">
        <ignored_collision_filter_group collision_filter_group="group2">
        <ignored_collision_filter_group collision_filter_group="group3">

This XML-snippet illustrates the syntax for declaring a collision filter group. It declares a collision filter group named group1. It has two members, body1 and body2 (although it could have any number of links). This is short-hand for communicating that the collision elements of body1 and body2 belong to group1. Furthermore, group1 ignores two groups: group2 and group3. It is not considered an error to ignore a non-existing group, but it is considered an error to reference a link that hasn't been defined.

By default, all elements belong to a common, universal group which corresponds to bit zero. A collision element can be rendered "invisible" by assigning it to a group that ignores this universal group.

Beyond instantiating the collision filter groups from parsing a URDF file, there is currently no interface for programmatically altering group membership or ignore relationships.

Next topic: Relationship Between Collision Filter Implementations