hgtransform

Create transform object

Syntax

h = hgtransform
h = hgtransform('PropertyName',propertyvalue,...)
h = hgtransform(ax,...)


Properties

For a list of properties, see Transform Properties.

Description

h = hgtransform creates a Transform object and returns its handle.

h = hgtransform('PropertyName',propertyvalue,...) creates a Transform object with the property value settings specified in the argument list. For a description of the properties, see Transform Properties.

h = hgtransform(ax,...) creates the Transform object in the axes specified by ax instead of in the current axes (gca). The option ax can precede any of the input argument combinations in the previous syntaxes.

Transform objects can contain other objects, which lets you treat the Transform object and its children as a single entity with respect to visibility, size, orientation, etc. You can group objects by parenting them to a single Transform object (i.e., setting the object's Parent property to the transform object's handle):

h = hgtransform;
surface('Parent',h,...)

The primary advantage of parenting objects to a Transform object is that you can perform transforms (for example, translation, scaling, rotation, etc.) on the child objects in unison.

The parent of a Transform object is either an Axes object or another Transform object.

Although you cannot see a Transform object, setting its Visible property to off makes all its children invisible as well.

Exceptions and Limitations

• A Transform object can be the parent of any number of axes child objects belonging to the same axes, except for light objects.

• Transform objects can never be the parent of axes objects and therefore can contain objects only from a single axes.

• Transform objects can be the parent of other transform objects within the same axes.

• You cannot transform Image objects because images are not true 3-D objects. Texture mapping the image data to a surface CData enables you to produce the effect of transforming an image in 3-D space.

• Transforms do not affect text objects unless the text object uses data units. If a Text object has a position specified in data units, then the transform moves the lower left corner of the text. The transform does not affect the font size or orientation. To change the font size and orientation, use text properties.

Note

Many plotting functions clear the axes (remove axes children) before drawing the graph. Clearing the axes also deletes any Transform objects in the axes.

Examples

Transforming a Group of Objects

This example shows how to create a 3-D star with a group of surface objects parented to a single transform object. The transform object then rotates the object about the z-axis while scaling its size.

Create an axes and adjust the view. Set the axes limits to prevent auto limit selection during scaling.

ax = axes('XLim',[-1.5 1.5],'YLim',[-1.5 1.5],'ZLim',[-1.5 1.5]);
view(3)
grid on

Create the objects you want to parent to the transform object.

[x,y,z] = cylinder([.2 0]);
h(1) = surface(x,y,z,'FaceColor','red');
h(2) = surface(x,y,-z,'FaceColor','green');
h(3) = surface(z,x,y,'FaceColor','blue');
h(4) = surface(-z,x,y,'FaceColor','cyan');
h(5) = surface(y,z,x,'FaceColor','magenta');
h(6) = surface(y,-z,x,'FaceColor','yellow');

Create a transform object and parent the surface objects to it. Initialize the rotation and scaling matrix to the identity matrix (eye).

t = hgtransform('Parent',ax);
set(h,'Parent',t)

Rz = eye(4);
Sxy = Rz;

Form the z-axis rotation matrix and the scaling matrix. Rotate group and scale by using the increasing values of r.

for r = 1:.1:2*pi
    % Z-axis rotation matrix
    Rz = makehgtform('zrotate',r);
    % Scaling matrix
    Sxy = makehgtform('scale',r/4);
    % Concatenate the transforms and
    % set the transform Matrix property
    set(t,'Matrix',Rz*Sxy)
    drawnow
end
pause(1)

Reset to the original orientation and size using the identity matrix.

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

Transforming Objects Independently

This example creates two transform objects to illustrate how to transform each independently within the same axes. A translation transformation moves one transform object away from the origin.

Create and set up the axes object that will be the parent of both transform objects. Set the limits to accommodate the translated object.

ax = axes('XLim',[-3 1],'YLim',[-3 1],'ZLim',[-1 1]);
view(3)
grid on

Create the surface objects to group.

[x,y,z] = cylinder([.3 0]);
h(1) = surface(x,y,z,'FaceColor','red');
h(2) = surface(x,y,-z,'FaceColor','green');
h(3) = surface(z,x,y,'FaceColor','blue');
h(4) = surface(-z,x,y,'FaceColor','cyan');
h(5) = surface(y,z,x,'FaceColor','magenta');
h(6) = surface(y,-z,x,'FaceColor','yellow');

Create the transform objects and parent them to the same axes. Then, parent the surfaces to transform t1. Copy the surface objects and parent the copies to transform t2. This figure should not change.

t1 = hgtransform('Parent',ax);
t2 = hgtransform('Parent',ax);

set(h,'Parent',t1)
h2 = copyobj(h,t2);

Translate the second transform object away from the first transform object and display the result.

Txy = makehgtform('translate',[-1.5 -1.5 0]);
set(t2,'Matrix',Txy)
drawnow

Rotate both transform objects in opposite directions.

Rotate 10 times (2pi radians = 1 rotation)

for r = 1:.1:20*pi
    % Form z-axis rotation matrix
    Rz = makehgtform('zrotate',r);
    % Set transforms for both transform objects
    set(t1,'Matrix',Rz)
    set(t2,'Matrix',Txy*inv(Rz))
    drawnow
end