Collections

A collection is a user-defined collection of scene objects. A collection has to contain at least one object and is considered to be an entity (objects are also entities). Collections are useful when referring to several objects like a robot for instance. V-REP supports calculations based not only on objects, but also on collections. For instance the collision detection module allows registering following collision pair: (collection A; object B). The collision checking algorithm will then check whether the collection A (any object composing it) collides with object B.

Collections are collidable, measurable, detectable, cuttable and renderable 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.
  • can be cut by mills.
  • can be detected or seen by vision sensors.
  • Even if a collection is collidable, measurable, detectable, cuttable and renderable, this doesn't mean that all objects contained in the collection are collidable, measurable, detectable, cuttable or renderable:

  • 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.
  • Only the cuttable objects of a collection (subset of the collection) can be cut by mills.
  • Only the renderable objects of a collection (subset of the collection) can be detected by vision sensors.
  • A collection can however override the collidable, measurable, detectable, cuttable and renderable properties of its objects. Refer to the collection dialog for more details.

    A collection has to be composed by at least one element. Following elements are supported:

  • All scene objects
  • Loose objects
  • Tree, base included
  • Tree, base excluded
  • Chain, tip included
  • Chain, tip excluded
  • A combination of above elements


  • All scene objects

    The element is made up of all scene objects as can be seen in following figure (arrows indicate: is child of):

    [Element made up of all scene objects]


    Above element doesn't have any defining objects and can't exist by itself. Combine it with other types of elements.


    Loose objects

    This is a loosely definable combination of scene objects as can be seen in following figure (arrows indicate: is child of):

    [Element made up of loose objects]


    In above example, if object 2, object 3, object 4 and object 7 are removed from the scene, the element is not valid anymore and will also be removed. Object 2, object 3, object 4 and object 7 are the element's defining objects.


    Tree, base included

    This includes an object and all of its children (and children's children, etc.) as can be seen in following figure (arrows indicate: is child of):

    [Element made up of a tree, with base included]


    In above example, if object 1 is removed from the scene, the element is not valid anymore and will also be removed. Object 1 is the element's defining object.


    Tree, base excluded

    This includes all children (and children's children, etc.) of an object, without the object itself as can be seen in following figure (arrows indicate: is child of):

    [Element made up of a tree, with the base excluded]


    In above example, if object 1 is removed from the scene, the element is not valid anymore and will also be removed. Object 1 is the element's defining object.


    Chain, tip included

    his includes an object and all of its parents (and parent's parents, etc.) as can be seen in following figure (arrows indicate: is child of):

    [Element made up of a chain, with the tip included]


    In above example, if object 6 is removed from the scene, the element is not valid anymore and will also be removed. Object 6 is the element's defining object.


    Chain, tip excluded

    This includes all parents (and parent's parents, etc.) of an object, without the object itself as can be seen in following figure (arrows indicate: is child of):

    [Element made up of a chain, with the tip excluded]


    In above example, if object 6 is removed from the scene, the element is not valid anymore and will also be removed. Object 6 is the element's defining object.


    Combination of elements

    Within a collection, elements can be additive or subtractive. Following figure shows a collection defined by three elements:

    [(1) three elements, (2) resulting collection composed by the three elements]


    In above example, the resulting collection contains two objects. If a new object is attached to object 2 or object 4, it won't be included in the collection (since it will be part of the tree defined in element 2, which is subtractive). If a new object becomes parent of object 5, object 3 or object 1, it will not be included in the collection (since it will be part of the chain defined in element 3, which is subtractive). Otherwise, new objects are automatically included in the collection. Collections are dynamic entities and are automatically recalculated or updated. When an object, which is also a defining object of a collection is copied or saved, the related collection will also automatically be copied or saved.

    Use collections wisely and only when no other alternative can be found. If, for instance, you wish to test your mobile robot for collision against all other objects in the scene, you could define a robot collection (tree starting at the robot base) and an obstacles collection (All scene objects - tree starting at the robot base), then test collection robot against collection obstacles for collisions. This works just fine, but the obstacles collection is not really needed: indeed, the collision detection module allows specifying a Check against all other collidable objects in the scene item.

    When all objects contained in a collection are selected, the collection will be highlighted in pink (default color that can be adjusted in the user settings dialog) as can be seen in following figure.

    [Collection selection]


    Collections can be defined in the collection dialog.


    Recommended topics

  • Objects
  • Entities
  • Collection dialog