Basic Concepts

Holes are special collision geometries that can be combined with regular collision geometries in order to create a hole inside the latter.  Three shapes of holes are available: Spherical, Cylindrical and Box holes.

Here is an example of a box hole in a box, containing a small sphere with the contact display on :

Creating Holes

Holes can be created either via the Vortex Editor or in Python code. Both ways are described in the following sections.

Creating Holes using the Vortex Editor

To create a hole, instantiate the shape of hole you want and place it under a composite collision geometry along with any other collision geometries that will contain the hole.  Holes can only be added to parts, as is the case for regular collision geometries.

In the case of Cylinder Holes and Box Holes, you get additional parameters to remove faces from the hole, positive and negative Z for Cylinder Holes and all 6 directions for Box Holes.  Only faces along a single axis can be removed at any time. The axis can be specified by choosing the 'Remove axis' option. The two parameters, 'Remove positive face' and 'Remove negative face' can be selected to remove the faces in the positive and negative directions respectively, along the specified axis in the local frame of the hole.

Removing the face of hole, allows opening up the collision geometry in which the hole is contained. For example, creation of a hollow tube is possible this way with an ordinary solid Cylinder geometry containing a Cylinder Hole geometry. This can be achieved by opening the hole's top and bottom faces and making sure that the top and bottom faces of the hole coincide with the top and bottom faces of the cylinder.

To this end, a new action on Composite Collision Geometries that contain a hole was added, called "Snap Holes To Surface". It can be accessed by right-clicking on the composite collision geometry:

This action will move the holes in the composite geometry to match the closest, flat surfaces of any other solid geometry which is in the composite. Performing this action ensures the best results with holes for the case in which hole faces are removed. In accordance with the example of the cylindrical tube above, this action would move the faces of the Cylinder Hole to coincide with the closest faces of the solid Cylinder geometry.

Creating Holes in Python

Holes can be created programmatically in Python the same way any other extension is created : by using the extension factory.  There is also a helper function on the hole itself, called create(), that does this for you.  Note that the restrictions explained above also hold for holes created in code; they must be under a composite geometry

Here's a Python code snippet showing how to create a hollow box using the Box and BoxHole geometries:

composite = CompositeCollisionGeometry.create()

box = Box.create()
box.parameterDimension.value = VxVector3(4,4,4)
box.inputLocalTransform.value = createTranslation(0,0,2)
composite.addCollisionGeometry(box)

boxHole = BoxHole.create()
boxHole.parameterDimension.value = VxVector3(1,1,1)
boxHole.inputLocalTransform.value = createTranslation(0,0,4)
composite.addCollisionGeometry(boxHole)
composite.snapHolesToSurfaces()

partWithHole = Part.create()
partWithHole.inputLocalTransform.value = createTranslation(0,0,0)
partWithHole.inputControlType.value = Part.kControlStatic
partWithHole.addCollisionGeometry(composite)

First the composite collision geometry itself is created, then added to this, is a box collision geometry, and a boxhole collision geometry. The snapHolesToSurfaces() function is called to ensure that the face of the boxhole overlaps the face of the containing box collision geometry. Lastly, a part is created that has this composite collision geometry. 

Limitations with Holes

There are a few notable limitations when it comes to holes. These limitations are listed below. Any violation of these limitations is unsupported and may result in unexpected behaviour.