Collections

A collection is a user-defined collection of scene objects. Both collections and scene objects are entities. Collections are useful when referring to several objects like a robot for instance, when performing a specific operation, such as checking for collision between two robots: if a collision detection pair was defined as (collectionRobot1; collectionRobot2), then the collision checking algorithm would check whether any object from the first collection interferes with any object from the second collection.

Collections are collidable, measurable and detectable entities. This means that collections:

  • can be used in collision detections against other collidable entities.
  • can be used in minimum distance calculations with other measurable entities.
  • can be detected by proximity sensors.

    • Even if a collection is collidable, measurable and detectable, this doesn't mean that all objects contained in the collection are collidable, measurable and detectable:

  • During collision detection, only the collidable objects of a collection (subset of the collection) are tested against another collidable entity.
  • During distance measurement, only the measurable objects of a collection (subset of the collection) are measured against another measurable entity.
  • Only the detectable objects of a collection (subset of the collection) can be detected by proximity sensors.

    • A collection can however override the collidable, measurable and detectable properties of its objects.

    A collection is defined by one or several items that can be combined in an additive or subtractive manner. Following items are supported:

  • a single object
  • a tree of objects: this item represents all descendants of a single object (located at the tree root). If the tree grows or shrinks, the item will dynamically grow/shrink too.
  • a chain of objects: this represents all objects encountered when following all ancestors of a single object, If the chain grows or shrinks, the item will dynamically grow/shrink too.
  • all scene objects

    • A collection is not static, and is constantly evaluated/updated to determine its containing objects. A given collection can also be defined in many different ways, depending on specific needs:

    [Example collection containing 4 objects (the colored objects]


    Above collection could be defined as a combination of 4 items, resulting in following code:

    #python # Collection defined as: <object2> + <object4> + <object6> + <object7> object2 = sim.getObject('/object2') object4 = sim.getObject('/object4') object6 = sim.getObject('/object6') object7 = sim.getObject('/object7') collectionHandle = sim.createCollection(0) sim.addItemToCollection(collectionHandle, sim.handle_single, object2, 0) sim.addItemToCollection(collectionHandle, sim.handle_single, object4, 0) sim.addItemToCollection(collectionHandle, sim.handle_single, object6, 0) sim.addItemToCollection(collectionHandle, sim.handle_single, object7, 0) --lua -- Collection defined as: <object2> + <object4> + <object6> + <object7> local object2 = sim.getObject('/object2') local object4 = sim.getObject('/object4') local object6 = sim.getObject('/object6') local object7 = sim.getObject('/object7') collectionHandle = sim.createCollection(0) sim.addItemToCollection(collectionHandle, sim.handle_single, object2, 0) sim.addItemToCollection(collectionHandle, sim.handle_single, object4, 0) sim.addItemToCollection(collectionHandle, sim.handle_single, object6, 0) sim.addItemToCollection(collectionHandle, sim.handle_single, object7, 0)

    But a similar collection could also be defined as a combination of following 3 items too:

    #python # Collection defined as: <all objects> - <tree starting at object1> + <object6> object1 = sim.getObject('/object1') object6 = sim.getObject('/object6') collectionHandle = sim.createCollection(0) sim.addItemToCollection(collectionHandle, sim.handle_all, -1, 0) sim.addItemToCollection(collectionHandle, sim.handle_tree, object1, 1) sim.addItemToCollection(collectionHandle, sim.handle_single, object6, 0) --lua -- Collection defined as: <all objects> - <tree starting at object1> + <object6> local object1 = sim.getObject('/object1') local object6 = sim.getObject('/object6') collectionHandle = sim.createCollection(0) sim.addItemToCollection(collectionHandle, sim.handle_all, -1, 0) sim.addItemToCollection(collectionHandle, sim.handle_tree, object1, 1) sim.addItemToCollection(collectionHandle, sim.handle_single, object6, 0)

    See also the API functions related to collections.