​

​

​

What is the objet jit.matrix for?

 

 

FIGURE :  The jit.matrix object in Max 8

 

The jit.matrix has a large amount of uses in Jitter.  The object jit.matrix is probably the most used object when working with images in Max.  This object  allows us to allocate an array data on the computer's memory.  This data can be later displayed as a 2D image : a still image or a video sequence.   A jit.matrix object can also contain data related to a 3D shape, for example : the position and dimensions of a sphere, its color, and much more. Let's see an example :  the image bellow shows how an array of data can be displayed as an image.  Number 0 represents black and number 255 represents white. 

 

 

FIGURE :  Image representation in Jitter : a monochrome image where zero is interpreted as black and 255 as white.   

 

Dimensions

A matrix is similar to a table : it has rows, columns and cells.  Let's use a simple analogy to understand how this object works.  Let's say that the data contained in a matrix is organised in a table, where we have rows, columns and cells.  As in an Excel spreadsheet, the data is located inside the table's cells. Well, from now we will call this table a matrix.  The matrix has cells. In Jitter, we will call dimensions the total number of cells that a matrix has. So, keep this term in your memory : 

Dimensions: the total number of cells that a matrix has
 

 

Understanding dimensions 

In the example below, we see a matrix with 4 cells, its dimensions are given in terms of "rows" and "columns". So, the dimensions of this matrix are : 2 x 2.

 

 

 

A matrix which dimensions are  3x2 . It contains 6 cells ( 3 * 2 = 6)

 

 

 

A matrix which dimensions are  2x2 . It contains 4 cells ( 2 * 2 = 4)

 

 

Why is that relevant in Jitter ? 

With time, you will learn that the dimensions of a matrix play an important roll on the look of your visuals, and more. For now, as a simple example, let's compare 2 images.  Image a  is displaying data of a 4 x 4 matrix; Image b displays data of a matrix with dimensions of 4 x 30 and image c, displays data from a matrix with dimensions of 4 x 100, and so on.  

 

 

 

 

Image a. Matrix dimensions : 4x4

Image b. Matrix dimensions : 4x30

Image c. Matrix dimensions : 4x100

Image d. Matrix dimensions : 9x100

Image f. Matrix dimensions : 37x100

Image g. Matrix dimensions :100x100

 

FIGURE :  Six images generated from the data of 6 matrices, each with different dimensions.

 

 

Planes

So far, we have seen that a matrix can take different dimensions.  Now we will concentrate on the contents of the matrix.  Each cell in a matrix can contain one value (one number), or an array of values (more than one number).  For example, the figure below shows matrix a, which contains one value in each cell, matrix b. which contains 4 values in cell, and matrix c, which contains 3 values in cell.

 

 

FIGURE :  Matrix a. Contains a value in each cell,  matrix b. Contains 4 values in each cell, and matrix c. Contains 3 values in each cell

 

 

In Jitter, the number of "planes" of a matrix, will correspond  number of values found in its cells. So, a matrix with a number of planes = 1 will have one value in each cell, a matrix with 4 planes will have an array of 4 values in each cell, and a matrix with 3 planes will have an array of 3 values in each cell.

 

 

FIGURE :  in Jitter, the number of "planes" of a matrix, will correspond  number of values found in its cells

 

Why do I need to know this ? 

You may be wondering why you need to know this, if you want to create visuals. Well, the number of planes that a matrix has, will determine the type of graphics that we are going to generate.

For example, a matrix that will be used to define the colors of an image, will have 4 planes, i.e. four numbers in each cell, which will represent the amount of transparency, red, green and blue on the image.  We will see this topic in detail in the lesson "color synthesis".

 

 

FIGURE : A matrix with 4 plane is needed to represent colors. The 4 numbers in each cell represent the ARGB planes ( Alpha, Red, Green and Blue).   

The matrix that we will use to determine the position of a 3D graphic, has 3 planes, that is, three numbers in each cell, where each number will represent the position of a point in a 3D space given in x, y, z coordinates.

 

 

FIGURE : A composition of 100 spheres where the position of each sphere is given by a matrix which dimensions are 10x10.  A matrix with 3 planes is needed to represent positions in a 3D scene. The 3 numbers in each cell represent the x,y,z  planes. The position of each small sphere is given in x,y,z coordinates. Notice that we have a total of 100 spheres, that corresponds to the number of cells in this matrix which dimensions are 10x10. 
 

 

We will study these topics in detail later, for now, just know that a Jitter matrix is useful for many things, and that its function will depend on its content.

 

Type

So far, we have learned that a Jitter matrix has dimensions (total number of cells in a matrix), and planes (number of values within each cell). Now, we will concentrate on the type of data inside the cells.

When creating a jitter matrix we need to define the data type we are going to use, the options are :
 

• char , in a range from 0 to 255

• float32, in a range from - 2 147 483 648. to 2 147 483 648.

• float62, in a range from - 2 147 483 648. to 2 147 483 648.

• long, in a range from - 2 147 483 648. to 2 147 483 648
   

We will choose which data type to use depending on the type of graphics we are going to generate. For example, to represent colors, or text it is common to work with the char type. To generate elements of a 3D scene, then, we usually use float32, or float64 or long, if we want to have higher resolution.

 

The arguments of the jit.matrix object

So far we have learned what the dimensions, planes and type of a matrix are. Now we are ready to create our first jit.matrix object with all its arguments. 

 

 

FIG. The jit.matrix object

 

The jit.matrix object can take 4 arguments.  These are :  name ( it can be whatever name you want to use al solng as it is one single word),  number of planes, type and dimensions.  Let's locate each argument, the image bellow shows the location of each argument . You need to write them in this specific order. 

 

 

FIG. The arguments of the jit.matrix object

We already learned what means each of these arguments in this lesson. Let's remind it seeing the image bellow : 

 

FIG. Description of the arguments of the jit.matrix object

 

As an analogy , we can say that, when you create a jit.matrix object with all its arguments, it is like creating an empty table ready to be filled. It has specific number of cells , or dimensions :  for example 4 x4 = 8 cells. It will contain, in each cell, a specific number of values, ( corresponding to the number of planes), and these values will be of a specific type.   

 

Examples of uses of the jit.matrix object 

​

Now that you know how to create a matrix and what their arguments are, you are ready to create more exiting visuals.  For example : 

By performing math operations between matrices we can obtain original visual results. For instance : 

​

• Mixing or blending two 2D images : like in a VJ software. 

• Mixing  two 3D shapes. How that would look like ? You could, for example,  perform a "morphing" between a cube and a sphere and then, you'll see the cube gradually to become a sphere.  Dope! right? 

•  Varying the color of a video sequence.

• Modifying the position of a 3D shape on a 3D scene. 

​

Since a matrix is the most important piece when building patches in Jitter, then we need to understand in depth what a matrix is.  

If you want to learn more about the matrix in Jitter, you can read the next article, by Cycling74. For this course, 

 

https://docs.cycling74.com/max8/tutorials/jitterchapter00a_whatisamatrix