hgtransform

Create hgtransform graphics object

Syntax

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

Properties

For a list of properties, see Transform Properties.

Description

h = hgtransform creates an hgtransform object and returns its handle.

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

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

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

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

The parent of an hgtransform object is either an axes object or another hgtransform.

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

Exceptions and Limitations

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

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

  • hgtransform objects can be the parent of other hgtransform 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.

    Note   Many plotting functions clear the axes (i.e., remove axes children) before drawing the graph. Clearing the axes also deletes any hgtransform 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 hgtransform object. The hgtransform then rotates the object about the z-axis while scaling its size.

  1. 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; axis equal
  2. Create the objects you want to parent to the hgtransform 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');

  3. Create an hgtransform object and parent the surface objects to it. The figure should not change from the image above.

    t = hgtransform('Parent',ax);
    set(h,'Parent',t)
    
  4. Select a renderer and show the objects.

    set(gcf,'Renderer','opengl')
    drawnow

  5. Initialize the rotation and scaling matrix to the identity matrix (eye). Again, the image should not change.

    Rz = eye(4);
    Sxy = Rz;
  6. 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 hgtransform Matrix property
        set(t,'Matrix',Rz*Sxy)
        drawnow
    end
    pause(1)

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

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

Transforming Objects Independently

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

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

    ax = axes('XLim',[-2 1],'YLim',[-2 1],'ZLim',[-1 1]);
    view(3); grid on; axis equal
  2. 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');

  3. Create the hgtransform objects and parent them to the same axes. The figure should not change.

    t1 = hgtransform('Parent',ax);
    t2 = hgtransform('Parent',ax);
  4. Set the renderer to use OpenGL®.

    set(gcf,'Renderer','opengl')

  5. Parent the surfaces to hgtransform t1, then copy the surface objects and parent the copies to hgtransform t2. This figure should not change.

    set(h,'Parent',t1)
    h2 = copyobj(h,t2);
  6. Translate the second hgtransform object away from the first hgtransform object and display the result.

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

  7. Rotate both hgtransform objects in opposite directions. The final image for this step is the same as for step 6. However, you should run the code to see the rotations.

    % 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 hgtransform objects 
    	set(t1,'Matrix',Rz)
    	set(t2,'Matrix',Txy*inv(Rz))
    	drawnow
    end
Was this topic helpful?