Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Group Objects

Introduction

Group objects enable you to treat a number of axes child objects as one group. For example, you can make the entire group visible or invisible, select all objects when only one is clicked, or apply a transform matrix to reposition the objects by setting only one property on the group object.

There are two group objects:

  • hggroup — Use when you want to create a group of objects and control the visibility or selectability of the group based on what happens to any individual object in the group. Create hggroup objects with the hggroup function.

  • hgtransform — Use when you want to transform a group of objects. Transforms include rotation, translation, scaling, etc. See Transforming a Hierarchy of Objects for an example. Create hgtransform objects with the hgtransform function.

The difference between the hggroup and hgtransform objects is the ability of the hgtransform object to apply a transform matrix (via its Matrix property) to all objects for which it is the parent.

    Note   You cannot parent light objects to hggroup or hgtransform objects.

Creating a Group

You create a group by parenting axes children to an hggroup or hgtransform object:

hb = bar(rand(5)); % creates 5 barseries objects
hg = hggroup;
set(hb,'Parent',hg) % parent the barseries to the hggroup
set(hg,'Visible','off') % makes all barseries invisible

Group objects can be the parent of any number of axes children, including other group objects.

    Note   Many plotting functions clear the axes (i.e., remove axes children) before drawing the graph. Clearing the axes also deletes any hggroup or hgtransform objects in the axes.

Transforming Objects

The hgtransform object's Matrix property lets you apply a transform to all the hgtransform's children in unison. Typical transforms include rotation, translation, and scaling. You define a transform with a four-by-four transformation matrix, which is described in the following sections.

Creating a Transform Matrix

The makehgtform function simplifies the construction of matrices to perform rotation, translation, and scaling. See the Transforming a Hierarchy of Objects section for information on creating transform matrices using makehgtform.

Rotation

Rotation transforms rotate objects about the x-, y-, or z-axis, with positive angles rotating counterclockwise while sighting along the respective axis toward the origin. If the desired angle of rotation is [[THETA]], the following matrices define this rotation about the respective axis.

To create a transform matrix for rotation about an arbitrary axis, use the makehgtform function.

Translation

Translation transforms move objects with respect to their current locations. Specify the translation as distances tx, ty, and tz in data space units. The following matrix shows the location of these elements in the transform matrix.

Scaling

Scaling transforms change the sizes of objects. Specify scale factors sx,sy, and sz and construct the following matrix:

You cannot use scale factors less than or equal to zero.

The Default Transform

The default transform is the identity matrix, which you can create with the eye function. Here is the identity matrix:

See Undoing Transform Operations for related information.

Disallowed Transforms: Perspective

Perspective transforms change the distance at which you view an object. The following matrix is an example of a perspective transform matrix, which Handle Graphics® does not allow:

In this case, py is the perspective factor.

Disallowed Transforms: Shear

Shear transforms keep all points along a given line (or plane, in 3-D coordinates) fixed while shifting all other points parallel to the line (plane) proportional to their perpendicular distance from the fixed line (plane). The following matrix is an example of a shear transform matrix, which Handle Graphics does not allow:

In this case, sy is the shear factor and can replace any zero element in an identity matrix.

Absolute vs. Relative Transforms

Transforms are specified in absolute terms, not relative to the current transform. For example, if you apply a transform that translates the hgtransform object 5 units in the x direction and then you apply another transform that translates it 4 units in the y direction, the resulting position of the object is 4 units in the y direction from its original position.

If you want transforms to accumulate, you must concatenate the individual transforms into a single matrix. See Combining Transforms into One Matrix for more information.

Combining Transforms into One Matrix

It is usually more efficient to combine various transform operations into one matrix by concatenating (multiplying) the individual matrices and setting the Matrix property to the result. Matrix multiplication is not commutative, so the order in which you multiply the matrices affects the result. For example, suppose you want to perform an operation that scales, translates, and then rotates. You multiply the matrices as follows:

C = R*T*S % operations are performed from right to left

where S is the scaling matrix, T is the translation matrix, R is the rotation matrix, and C is the composite of the three operations. You then set the hgtransform object's Matrix property to C:

set(hgtransform_handle,'Matrix',C)

The following sets of statements are not equivalent:

set(hgtransform_handle,'Matrix',C)% Transform as above
set(hgtransform_handle,'Matrix',eye(4) ) % Undo transform

versus

C = eye(4)*R*T*S % Multiply identity matrix as last step
set(hgtransform_handle,'Matrix',C)

Concatenating the identity matrix to other matrices has no effect on the composite matrix.

Undoing Transform Operations

Since transform operations are specified in absolute terms (not relative to the current transform), you can undo a series of transforms by setting the current transform to the identity matrix. For example,

set(hgtransform_handle,'Matrix',eye(4))

returns the object hgtransform_handle to its untransformed orientation.

Rotations Away From the Origin

Since rotations are performed about the origin, it is often necessary to translate the hgtransform object so that the desired axis of rotation is temporarily at the origin. After applying the rotation transform matrix, you then translate the hgtransform object back to its original position. The following example illustrates how to do this.

Suppose you want to rotate a surface about the y-axis at the center of the surface (the y-axis that passes through the point x = 20 in this example).

  1. Create a surface and an hgtransform object. Parent the surface to the hgtransform object:

    h = surf(peaks(40)); view(-20,30)
    t = hgtransform;
    set(h,'Parent',t)

    The following picture shows the surface.

  2. Create and set a y-axis rotation matrix to rotate the surface by –15 degrees:

    ry_angle = -15*pi/180; % Convert to radians
    Ry = makehgtform('yrotate',ry_angle);
    set(t,'Matrix',Ry)

    Notice that the surface rotated –15 degrees about the y-axis that passes through the origin. However, to rotate about the y-axis that passes through the point x = 20, you must translate the surface in x by 20 units.

  3. Create two translation matrices, one to translate the surface –20 units in x and another to translate 20 units back. Concatenate the two translation matrices with the rotation matrix in the correct order and set the transform:

    Tx1 = makehgtform('translate',[-20 0 0]);
    Tx2 = makehgtform('translate',[20 0 0]);
    set(t,'Matrix',Tx2*Ry*Tx1)

Was this topic helpful?