makehgtform

Create 4-by-4 transform matrix

Syntax

M = makehgtform

M = makehgtform("scale",s)

M = makehgtform("xrotate",r)

M = makehgtform("yrotate",r)

M = makehgtform("zrotate",r)

M = makehgtform("axisrotate",[rx ry rz],r)

M = makehgtform("translate",[tx ty tz])

M = makehgtform("translate",tx,ty,tz)

Description

Identity Matrix

M = makehgtform returns an identity transform matrix. Applying an identity transform matrix to a Transform object resets its child objects to their original orientation, position, and size.

Scaling Matrix

M = makehgtform("scale",s) returns a transform matrix that scales a Transform object.

• If s is a scalar, the transform matrix scales uniformly by s along the x-, y-, and z-axes.

• If s is a row vector [sx sy sz], the transform matrix scales along the x-axis by sx, along the y-axis by sy, and along the z-axis by sz.

Rotation Matrix

M = makehgtform("xrotate",r) returns a transform matrix that rotates a Transform object counterclockwise around the x-axis by r radians.

M = makehgtform("yrotate",r) returns a transform matrix that rotates a Transform object counterclockwise around the y-axis by r radians.

M = makehgtform("zrotate",r) returns a transform matrix that rotates a Transform object counterclockwise around the z-axis by r radians.

M = makehgtform("axisrotate",[rx ry rz],r) returns a transform matrix that rotates a Transform object counterclockwise around an axis [rx ry rz] by r radians.

Translation Matrix

M = makehgtform("translate",[tx ty tz]) returns a transform matrix that translates a Transform object along the x-axis by tx units, along the y-axis by ty units, and along the z-axis by tz units. To avoid translation along a particular axis, specify the corresponding translation distance as 0. For example, makehgtform("translate",[0 0 5]) creates a transform matrix that translates only along the z-axis by 5 units.

M = makehgtform("translate",tx,ty,tz) specifies the x, y, and z translation distances as separate arguments.

Note

You can specify multiple transformations using two or more of the input argument combinations in the listed syntaxes. For example, makehgtform("xrotate",pi,"scale",4) scales uniformly by 4 and rotates around the x-axis by pi radians. You can specify any number and order of transformations, and makehgtform applies those transformations in the reverse order. For more information about how the order of specified transformations affects the resulting transform matrix, see Apply Multiple Transformations.

Examples

Scale Object

You can scale a graphics object by using a scaling transform matrix.

Start by creating the axes and adjusting the view. Display grid lines and label the axes.

ax = axes("XLim",[-1.5 1.5],"YLim",[-1.5 1.5],"ZLim",[-1.5 1.5]);
view(3)
grid on
xlabel(ax,"x-axis");
ylabel(ax,"y-axis");
zlabel(ax,"z-axis");

Create a sphere.

[x,y,z] = sphere;
s = surface(x,y,z);

Create a Transform object and parent the sphere to it so that you can apply transformations to the sphere.

h = hgtransform;
s.Parent = h;

Create a transform matrix to scale the sphere to be 50% larger. Apply the transform matrix to the sphere by setting the Matrix property of the Transform object h.

S = makehgtform("scale",1.5);
h.Matrix = S;

Rotate Object Around Specified Axis

You can rotate a graphics object around a specified axis of rotation by using a rotation transform matrix.

Start by creating the axes and adjusting the view. Display grid lines and label the axes.

ax = axes("XLim",[-5 20],"YLim",[0 20],"ZLim",[-5 20]);
view(3)
grid on
xlabel(ax,"x-axis");
ylabel(ax,"y-axis");
zlabel(ax,"z-axis");

Create a Transform object. Then create a blue rectangle and parent it to the Transform object so that you can apply transformations to it.

h = hgtransform;
r = rectangle(ax,Position=[0 10 5 10],FaceColor="b");
r.Parent = h;
hold on

Define an axis of rotation by specifying a point (rx,ry,rz). The axis is the line that passes through the origin and this point. Plot the line to visualize the rotation of the rectangle around it.

rx = 10;
ry = 15;
rz = 10;
plot3(ax,[0 rx],[0 ry],[0 rz])
hold off

Create an animation that rotates the rectangle around the axis of rotation by pi radians. Define a transform matrix that rotates the rectangle. Apply this rotation matrix to the Transform object, incrementing the angle of rotation at each iteration of the loop.

for r=0:0.3:pi
    R = makehgtform("axisrotate",[rx ry rz],r);
    h.Matrix = R;
    drawnow
    pause(0.1)    
end

Translate Object

You can translate a graphics object by using a translation transform matrix.

Start by creating the axes and adjusting the view. Display grid lines and label the axes.

ax = axes("XLim",[-1.5 1.5],"YLim",[-1.5 1.5],"ZLim",[-1.5 1.5]);
view(3)
grid on
xlabel(ax,"x-axis");
ylabel(ax,"y-axis");
zlabel(ax,"z-axis");

Create a sphere.

[x,y,z] = sphere;
s = surface(x,y,z);

Create a Transform object and parent the sphere to it so that you can apply transformations to the sphere.

h = hgtransform;
s.Parent = h;

Then create a transform matrix to translate the sphere 0.5 unit along the x-axis and 0.5 unit along the z-axis. Apply the transform matrix to the sphere by setting the Matrix property of the Transform object h.

Txz = makehgtform("translate",[0.5 0 0.5]);
h.Matrix = Txz;

Combine Multiple Transforms

You can specify multiple transformations in one call to makehgtform. MATLAB® returns a transform matrix that is a composition of all specified transformations. In this example, you rotate graphics around both the x- and y-axes.

Start by creating the axes and adjusting the view. Display grid lines and label the axes.

ax = axes("XLim",[-1.5 1.5],"YLim",[-1.5 1.5],"ZLim",[-1.5 1.5]);
view(3)
grid on
xlabel(ax,"x-axis");
ylabel(ax,"y-axis");
zlabel(ax,"z-axis");

Create the Surface objects you want to rotate, and store them in an array, s.

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

Create a Transform object and parent the Surface objects to it.

h = hgtransform;
set(s,"Parent",h)

Create a rotation matrix that performs a rotation first around the x-axis and then around the y-axis. When you specify multiple transforms in a single call to the makehgtform function, the transforms are applied right-to-left. Apply the transform matrix by setting the Matrix property of the Transform object h.

m1 = makehgtform("yrotate",pi/2,"xrotate",pi/2);
h.Matrix = m1;

You can obtain the same transform matrix by creating two separate rotation matrices and multiplying them together.

mx = makehgtform("xrotate",pi/2);
my = makehgtform("yrotate",pi/2);
m2 = my*mx; 
h.Matrix = m2;

Input Arguments

s — Scale factor

scalar | three-element row vector

Scale factor, specified as a scalar or three-element row vector. To create a transform matrix that scales a Transform object uniformly along the x-, y-, and z-axes, set the scale factor to a scalar value. Set the scale factor to a row vector with three values—sx, sy, and sz—to designate the scaling along the x-, y-, and z-axes, respectively.

r — Rotation angle in radians

scalar

Rotation angle in radians, specified as a scalar. The function creates a transform matrix that rotates a Transform object counterclockwise around an axis by r radians.

[rx ry rz] — Rotation axis

three-element row vector

Rotation axis, specified as a three-element row vector. The rotation axis is defined by the axes origin and point (rx,ry,rz). For more information, see Axis of Rotation.

[tx ty tz] — Translation distances

three-element row vector

Translation distances, specified as a three-element row vector. Set the translation distances with three values—tx, ty, and tz—to designate the translation along the x-, y-, and z-axes, respectively.

tx — x translation distance

scalar

x translation distance, specified as a scalar. The specified value defines the distance to translate along the x-axis.

ty — Translation y distance

scalar

y translation distance, specified as a scalar. The specified value defines the distance to translate along the y-axis.

tz — z translation distance

scalar

z translation distance, specified as a scalar. The specified value defines the distance to translate along the z-axis.

Output Arguments

M — Transform matrix

4-by-4 matrix

Transform matrix, returned as a 4-by-4 matrix. Perform transformations on graphics objects by setting the Matrix property of their parent Transform object to this transform matrix. For more information about transform matrices, see Transforms Supported by hgtransform.

Data Types: double

More About

Apply Multiple Transformations

Transform operations are defined in absolute terms rather than relative to the current transform, so if you apply separate transforms to a Transform object, the transformations are always performed with respect to the original orientation, position, and size of the object. To apply multiple transformations consecutively, multiply the transform matrices returned by makehgtform.

When multiplying transform matrices, the transforms are applied right-to-left, so the order of multiplication is important. In general, apply transformations in this order:

1. Scaling transforms

2. Rotation transforms

3. Translation transforms

Because transformations are performed with respect to the origin of the current axes, this order of applying multiple transformations preserves the origin for scaling and rotations before translations of a Transform object.

For example, rotating and then translating a Transform object produces a different result compared to the reverse order because the translation alters the distance between the Transform object and the origin. This code creates a transform matrix that applies two rotations and a translation.

Rx = makehgtform("xrotate",pi/2);
Ry = makehgtform("yrotate",pi/2);
T = makehgtform("translate",[4 0 0]);
C = T*Ry*Rx

Applying C to a Transform object first rotates it around the x-axis by pi/2 radians, then rotates it around the y-axis by pi/2 radians, and finally translates it 4 units along the x-axis. For an additional example, see Combine Multiple Transforms.

Axis of Rotation

The axis of rotation is defined by the origin and a point. In Cartesian coordinates, this point is specified as [x,y,z]. The axis of rotation is the line that connects the axes origin and this point.

Version History

Introduced before R2006a