Accelerating the pace of engineering and science

# Documentation Center

• Trial Software

## Grouping Objects Within Axes — hgtransform

### Introduction

MATLAB® provides two objects designed to group any of the objects normally parented to axes:

• Hggroup — Parent objects to an hggroup object when you want to reference the objects as a group, for example, to select or control visibility of all the group members.

• Hgtransform — This object also lets you transform (rotate, translate, etc.) the objects as a group.

### Translating Grouped Objects

This example shows how using a hierarchy of hgtransform objects makes it possible to translate the contained graphics objects both independently and as a group. The example creates a cross-like cursor with a text readout in the center, which displays data values.

Two surfaces, each contained in an hgtransform object to allow independent translation and overlap, construct the cursor. A third hgtransform object contains these two hgtransform objects as well as a text object. This third hgtransform (with handle T in the diagram and code) lets you transform the cursor as a group.

The following diagram shows the containment hierarchy for this example. The axes contains a line, which is used to plot the data that the cursor moves along. The axes also contains the hierarchy of hgtransform objects that construct the cursor.

 Note   If you are using the MATLAB Help browser, run this example run this example or open it in the MATLAB editoropen it in the MATLAB editor.

#### Set Up the Axes and Figure

The first step is to create a figure and ensure it uses the OpenGL® renderer. Then create an axes with fixed limits so MATLAB does not rescale the limits as the cursor moves along the line.

```figure('Renderer','opengl')
hAxes = axes('XLim',[-10 10],'YLim',[-5 5]);
```

#### Define the Transform Matrices and hgtransform Objects

The cross part of the cursor is formed from two surface objects, which are translated to overlap. Each surface is contained in its own hgtransform object (handles t1 and t2) because they are translated in different directions. Both hgtransform objects are themselves contained in another hgtransform object (handle T).

```% Create transform matrices
tmtx1 = makehgtform('translate',[-.5 0 0]);
tmtx2 = makehgtform('translate',[0 -.5 0]);

% Create hgtransform objects
T = hgtransform('Parent',hAxes); % Contains the cursor
t1 = hgtransform('Parent',T,'Matrix',tmtx1);
t2 = hgtransform('Parent',T,'Matrix',tmtx2);```

#### Create the Surface and Text Objects

The cursor is composed of two surface objects and a text object (to display data values). The two surfaces are parented to their respective hgtransform objects. The text is parented directly to the top-level hgtransform. The text object does not need coordinates because it is translated along with the surfaces in the top-level hgtransform object (T).

See cylinder, surface, text.

```% Define surfaces and text
[sx,sy,sz] = cylinder([0 2 0]); % Use cylinder to generate data
surface(sz,sy,sx,'FaceColor','green',...
'EdgeColor','none','FaceAlpha',.2,'Parent',t1);
surface(sx,sz./1.5,sy,'FaceColor','blue',...
'EdgeColor','none','FaceAlpha',.2,'Parent',t2);
hText = text('FontSize',12,'FontWeight','bold',...
'HorizontalAlignment','center',...
'VerticalAlignment','Cap','Parent',T);```

#### Generate Data and Plot a Line

This example uses a line plot of a mathematical function to create a path along which to move the cursor.

```% Plot the data x, y, and z
x = -10:.05:10;
y = cos(x) + exp(-.01*x).*cos(x) + exp(.07*x).*sin(3*x);
z = ones(length(x));
line(x,y,z)```

#### Translate the Cursor Along the Plotted Line

To move the cursor along the line, a new transform matrix is calculated using each set of x, y, and z data points and used to set the Matrix property of the top-level hgtransfrom T. At the same time, the text object String property is updated to display the value of the current y data point.

The surfaces and the text translate together because they are allcontained in the top-level hgtransform object.

```% Loop through the line data to move the cursor
for ind = 1:length(x)
set(T,'Matrix',...
makehgtform('translate',[x(ind) y(ind) z(ind)]))
set(hText,'String',num2str(y(ind)))
pause(.01)
end
```