If you want to understand the vrrotvec2mat function, you need to know how axis-angle representations of rotations work before we delve into this function. Specifically, you're looking at understanding the Rodrigues Rotation formula, which is also known as the axis-angle rotation formula. I'll explain this to you with some introduction first.
In Linear Algebra, the most standard way to rotate a point, whether it's 2D or 3D is to use a rotation matrix where you pre-multiply (i.e. y = A*x where x is your point represented in a column vector) the 2D or 3D coordinate with this rotation matrix. This rotates the point around the origin of the coordinate system. You can also think of this as rotating a vector v where the tail is at the origin and the head is at the point in 2D or 3D space.
However, another way to do this is to provide what is known as the axis-angle representation which is only valid in 3D space. The axis is described by a unit vector k that describes an axis of rotation about which the vector v rotates by an angle around this axis by the right-hand rule.
Here's a pictorial example I got from Wikipedia:
Source: Rodrigues' Rotation formula
The vector k in our case is pointing straight up and the vector v is pointing on a 45 degree angle northwest. We wish to rotate this vector by an angle of 180 degrees around the axis defined by the vector k, and so if you do this, vrot is the resulting vector. v|| and v_|_ are the parallel and perpendicular projections of v with respect to the vector k. These are shown to derive the Rodrigues formula, which I won't go through here. I'll refer you to the article if you want a full derivation.
The reason why the Rodrigues rotation formula was proposed to rotate things is because very frequently, there are applications where you are rotating about an axis that is not centred at the origin, nor are you rotating with respect to a standard x,y and z axis.
In fact, if you look at the Wikipedia article, you don't need to convert to the matrix form to rotate things. You can use the unit vector and rotation angle directly to rotate your vector, which leads us to his rotation formula:
Source: Rodrigues' Rotation formula
The reason why vrrotvec2mat exists is because you can convert between the axis-angle representation of rotating a vector and a rotation matrix with a rotation with respect to the origin in Linear Algebra. You can then apply the same Linear Algebra theory to rotate a vector/point in 3D space given this rotation matrix. You can convert back and forth between a normal rotation matrix and the Rodrigues formula representation by using vrrotvec2mat and vrrotmat2vec respectively.
The axis-angle representation is essentially a 4 element vector where the first three elements are the x,y and z components of the unit vector k that defines your rotation axis and the last element is the rotation angle theta that rotates your vector with respect to this axis. vrrotvec2mat is no different here and requires a 4 element vector in the order that I just talked about. However, having a quick look at the source, theta is defined in radians.
If you want a concrete example of seeing this work, let's use the above diagram as an example. The unit vector k is pointing upwards on the z axis, and so the first three components are (0,0,1). We wish to rotate by 180 degrees, and so the fourth argument is pi... and so:
>> M = vrrotvec2mat([0 0 1 pi])
M =
-1.0000 -0.0000 0
0.0000 -1.0000 0
0 0 1.0000
This exactly defines a rotation of 180 degrees around the z-axis if you take a look at the standard rotation matrix in Cartesian space around the z axis. If you recall the rotation matrix for this, it's:
If you substitute theta = pi in the above matrix, you will get the same thing as M as seen in the vrrot2vec2mat function. However, ignore the sign of the first row, second column as it's due to numerical precision... which leads us to the second parameter options. Basically, when computing the rotation matrix values using the Rodrigues Rotation formula, there will be times where values in the matrix will be quite small. The options structure has a field called epsilon, where you can specify anything smaller than this threshold is considered zero after the matrix has been calculated. The default of 1e-12 is quite suitable IMHO.
If you'd like to change the default epsilon, simply create a structure that has a single element epsilon that changes this threshold and call the function with this additional second argument... so something like:
>> options.epsilon = 1e-15;
>> M = vrrotvec2mat([0 0 1 pi], options);
In any case, going back to what we were talking about, let's say our given vector v is with respect to the above figure and that it's pointing northwest - specifically at (x,y,z) = (1,0,1). If we use this rotation matrix and rotate this point, we should get it to be parallel to the xz plane and pointing in the opposite direction, and so we should get (x,y,z) = (-1,0,1):
>> M*[1;0;1]
ans =
-1.0000
0.0000
1.0000
You can also get the same result by using the Rodrigues Rotation formula:
>> v = [1;0;1];
>> k = [0;0;1];
>> theta = pi;
>> vrot = v*cos(theta) + cross(k,v)*sin(theta) + k*(k.'*v)*(1-cos(theta))
vrot =
-1.0000
0.0000
1.0000
All in all, it's just another way of rotating a vector around an arbitrary axis, not just limited to the standard x, y or z.
