compound

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 (or length, width, height), axis, up, opacity, shininess, emissive, and texture. Moreover, the display of a complicated compound object is faster than displaying the individual objects one at a time. (In GlowScript version 2.1 the details were somewhat different.)

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)

The size of the object: After creating the compound named "hammer", hammer.size represents the size of the bounding box of the object. The x, y, and z components of hammer.size can also be referred to as hammer.length, hammer.height, and hammer.width.

The position of the compound is hammer.pos: After creating the compound, hammer.pos is located at the center of the bounding box. Later changes to hammer.pos move the center of the extrusion to a new location.

No linkage of axis and size: After creating the hammer as a compound object, changing the axis rotates the combined object. Changing the axis does not affect the size.

Invisible objects are included: All objects in the list become part of the compound, even if they have visible = False. It is as though all the objects have visible set to True.

The individual objects in a compound are "frozen". You can't change their attributes such as positions or orientations except as a group.

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, vector(0,1,1), and the hammer color is yellow, vector(1,1,0), the blend results in vector(0*1, 1*1, 0*0) or vector(0,1,0), which is green. If you plan to vary the color after creating the compound object, start with the color being white, vector(1,1,1), which is the default.

Setting parameters when creating a compound

You can optionally specify parameters to be applied to a compound after its creation. The following statement is equivalent to creating the hammer, then changing the position and axis, where the resulting center of the compound will be at vector(3,2,0):

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 values of color, opacity, shininess, and emissive, 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. Also, a compound object can be cloned to make additional copies.

Limitation on the number of objects to compound: In the WebGL 3D graphics library that is used by VPython, a compound cannot have more than 65536 (2**16) vertexes (pos, normal, color), due to WebGL using 16-bit integers to reference the vertexes. For example, a box object has 8*3 = 24 vertex objects, because each corner requires three vertex objects, all with the same positions but with three different normals. That means that a list of boxes to compound must not contain more than int(65536/24) = 2730 boxes. A cylinder, in order to have smooth sides, requires 206 vertexes, so a list of cylinders to compound must not contain more than int(65536/206) = 318 cylinders. If you need to compound more than 2730 boxes, a way to deal with the limitation is to make several compounds, each with less than 2730 boxes (and it may be convenient to store these compounds in a list). You can compound a list of compound objects, but the total number of vertexes cannot exceed the limit.

Currently here are the number of vertexes in each of the basic objects: box 24, cylinder 206, sphere 991, simple_sphere 70, pyramid 16, cone 604, ring 1280. Consequently, at present the limits on the number of objects that can be compounded are these (if all the objects are boxes, or cylinders, etc.): box 2730, cylinder 318, sphere 66, simple_sphere 935, pyramid 4096, cone 108, ring 51.

An informative error message is given if the vertex limit is exceeded.