# 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 identify transform matrix to a `Transform` object resets its child objects to their original orientation, position, and size.```

### Scaling Matrix

example

````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

example

````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.```

example

````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

example

````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

collapse all

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;```

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```

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;```

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

collapse all

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.

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.

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.

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.

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

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

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

## Output Arguments

collapse all

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`

collapse all

### 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