The compound object lets you group objects together and manage them as though they were one object, by specifying in the usual way pos, color, size (and length, width, height), axis, up, and texture. Moreover, the display of a complicated compound object is faster than displaying the individual objects one at a time. The object shown above is a compound of a cylinder and a box:
handle = cylinder( size=vector(1,.2,.2), color=vector(0.72,0.42,0) )
head = box( size=vector(.2,.6,.2), pos=vector(1.1,0,0), color=color.gray(.6) )
hammer = compound([handle, head])
hammer.axis = vector(1,1,0)
Note that after creating the hammer as a compound object, changing the axis rotates the combined object. The positions of the cylinder and box are relative to the origin, vec(0,0,0). If you set hammer.pos.x = 1, you move the hammer 1 unit to the right. The individual objects in a compound are "frozen". You can't change their attributes such as positions or orientations except as a group. It is often conceptually advantageous to create the objects near the origin, vector(0,0,0), and then after creating the compound move them by changing pos.
The size of a compound object
When you create a compound object, its size is vector(1,1,1), even if the actual length, width, and height are 10, 4, and 2. If you then set size to vector(2,1,1), the actual size of the object will be 20, 4, and 2. In other words, for a compound object size is a multiplier of the original size.
Changing axis doesn't change size, nor vice versa
When you change the size of an ordinary VPython object, the magnitude of the axis is changed to be the x component of the size, and when you change the axis, the x component of the size is changed to be the magnitude of the axis. These interactions between size and axis do not apply to compound objects.
Color blending
Setting hammer.color to something other than white makes a multiplicative blend of the overall color with the colors of the individual objects. For example, if the color of the handle is cyan, vec(0,1,1), and the hammer color is yellow, vec(1,1,0), the blend results in vec(0*1, 1*1, 0*0) or vec(0,1,0), which is green. If you plan to vary the color after creating the compound object, start with the color being white, vec(1,1,1).
Setting parameters when creating a compound
You can optionally specify parameters for a compound. The following statement is equivalent to creating the hammer, then changing the position and axis:
hammer = compound( [handle, head], pos=vector(3,2,0),
axis=vector(1,1,0) )
Compound and world coordinates
There are two functions for translating between compound and world coordinates, which may differ if the compound object has been moved or rotated. Suppose the name of the compound is c, c_pos is a position within that compound, and world_pos is the corresponding position in world coordinates:
world_pos = c.compound_to_world(c_pos)
c_pos = c.world_to_compound(world_pos)
Current restrictions
Currently objects in a compound can have their own colors and opacities but they cannot have individual textures or bumpmaps, which can only be specified for the combined object, and which affect all of the compounded objects.
Currently label objects, lights, and objects based on curve objects (curve, helix) cannot be compounded. However, triangles, quads, and even other compounds can be compounded.