Matrix Filter Tutorial

This tutorial demonstrates the various features of the Matrix Filter.

# A Simple Rotation

In this example we will use a Matrix Filter to apply a rotation to a set of points that form a circle in the $(x, y)$ plane. We first use a Sequence Source to create a sequence of angular values $\theta = 0,\ldots, 2\pi$ and connect it to a Function Filter to generate a point $(\cos{\theta}, \sin{\theta}, 0)$ for each value $\theta$. As seen below, this gives us a sequence of points $(x, y, 0)$ in the unit circle $x^2 + y^2 = 1$.

We wish to use a Matrix Filter to rotate this circle by $90^{\circ}$ from the $x$-axis to the $z$-axis. That is, we wish to compute the matrix transformation

(1)
\begin{align} \left(x, y, z\right) \left[\begin{array}{c c c} \cos{\frac{\pi}{2}} & 0 & \sin{\frac{\pi}{2}} \\ 0 & 1 & 0 \\ -\sin{\frac{\pi}{2}} & 0 & \cos{\frac{\pi}{2}} \end{array}\right] \end{align}

to create a new set of points $\left(x^{\prime}, y^{\prime}, z^{\prime}\right)$, all of which are contained in the unit circle $y^2 + z^2 = 1$ where $x = 0$.

To perform this operation, we first connect the output of the Function Filter to a Matrix Filter. Any values sent to this filter that are not included in an input vector to the transformation are simply passed through the filter unchanged. All parameters are also passed through the filter. Since a fresh Matrix Filter contains no input vectors, its output elements will match its input elements.

Since, in this case, we wish to use all three values from each row of input, we can click the "Use All Input Values" button to set up the appropriate input vector. This creates a single vector of length 3 that starts at index 0; hence it will contain the values v[0], v[1], and v[2] from the Function Filter.

By switching to the "Matrix Settings" tab, we can also see that a $3\times 3$ identity matrix has automatically been created to be applied to the input vector. Since this operation must be well-defined, the number of rows in the matrix is automatically updated to match the length of the input vectors. The number of columns, however, is up to the user. In this case, the "Use Square Matrix" box should be checked to ensure that a square matrix is used. Otherwise, the buttons to apply a symmetric fill or a rotation will be disabled.

We are now ready to perform the rotation. Clicking the "Add Rotation" button brings up a dialog box containing the necessary details. Since the Matrix Filter can perform rotations in any number of multiple dimensions, the axes of rotation are created with respect to the values in the input vectors. So, in this case, Axis 0 represents the $x$-axis, and Axis 2 represents the $z$-axis. Below is the Matrix Rotation dialog box containing the appropriate settings to perform our desired $90^{\circ}$ rotation.

When the "Apply Rotation" button is clicked, the filter creates the appropriate rotational matrix and multiplies it by the current transformation matrix, replacing it with the result. Had our original matrix been more than just the identity, the filter would have made the appropriate computations and simplifications. In this way, multiple operations can be composed in to a single matrix.

Clicking "Propagate Changes" will put the Matrix Filter to work. Below is its output, which contains the final result of the rotation.

# A More Practical Example

In this example we will apply a composition of rotations to both the position and velocity vectors of a list of particles. Suppose that we have a Function Filter which outputs the positions, velocities, and radii of 10 separate particles. The position and velocity of a given particle are represented in Cartesian coordinates. Below is the output.

We wish to use the Matrix Filter to rotate these particles first by $30^{\circ}$ from the $x$-axis into the $y$-axis and then by $45^{\circ}$ from the $y$-axis into the $z$-axis. Since these rotations must be applied to both the position and velocity of each particle, we must use two input vectors of length 3 in the Matrix Filter. Here we have created an input vector called "Position" which starts at index 0 and an input vector called "Velocity" which starts at index 3.

Under these settings, the "Position" vector includes the values v[0], v[1], and v[2], and the "Velocity" vector includes the values v[3], v[4], and v[5]. Since a rotation does not affect the radius of a particle, the value v[6] is not included in an input vector and as a result is passed through the filter unchanged.

We may now build the matrix necessary to perform this rotation. As in the previous example, we simply use the "Add Rotation" button to create each rotation, first from Axis 0 to Axis 1 by $30^{\circ}$ and then from Axis 1 to Axis 2 by $45^{\circ}$.

As multiple rotations are added one-at-a-time, they are all composed together into one transformation matrix which can be seen below.

The above matrix is applied to both the "Position" and "Velocity" input vectors and performs both desired rotations to each of them. Below is the final output.

The Matrix Filter also supports non-square matrices. Consider the example below in which a Matrix Filter is sent the positions and radii of a list of particles. We wish to project these positions onto the $(x, y)$ plane and calculate the norm squared of the resultant position vector. By using a non-square matrix, we can perform these operations all at once.
We first create an input vector of length 3 starting at index 0 that holds the position of each particle. We then create the actual matrix, which will contain four columns. As seen below, the first three columns of this matrix contain the appropriate entries to project the positions of each particle onto the $(x, y)$ plane. The fourth column is used to compute the norm squared $x^2 + y^2$ of the new position vector $(x, y, 0)$ for each particle.