Tutorial 20: Importing and Exporting Single Matrices
This tutorial shows how you can export a single matrix to disk from Jitter. We'll demonstrate the variety of options available, including QuickTime still picture formats and Jitter's own .jxf file format.
In the previous Tutorial, we learned how to save a sequence of matrices as a QuickTime movie—and we can save a single matrix using the same techniques. Since the data that Jitter works with can describe much more than series of images, it makes sense that there should be several additional options for exporting individual matrices.
Import and Export from the jit.matrix object
The jit.matrix object offers two types of single-matrix import/export: QuickTime movie and Jitter binary (.jxf). Both formats permit import and export of a single matrix. We'll discuss both, starting with the movie format.
QuickTime export and import
The QuickTime movie format is identical to the format we learned about in the last tutorial—Recording QuickTime Movies. The only difference is that, in this case, an exported output movie will be exactly one frame long. We can also import a single frame of a movie, regardless of the movie's length. The messages jit.matrix object. The message conveniently uses the same format as the jit.record object's message.
and are used to import and export a single matrix from the
In fact, when you use the jit.matrix
object's message, the jit.matrix
object is briefly creating an internal instance of a jit.record
object, and sending a message to it with the arguments you've specified for . Although that shouldn't change the way you think about it, it's pretty nifty.
• Click the message
box that says to load a movie into the jit.movie
object. Since we're only interested in a single frame, there's no metro
in the patch. You'll also notice that there is a new attribute set for the jit.movie
object— Setting this attribute means that our movie will not begin playing automatically. We can choose a frame of the loaded movie we want to export, using the number
box connected to the message
box containing the message .
• Why are the colors all messed up? They're messed up because we're using the jit.matrix
to remap the planes of the incoming movie from 0 1 2 3 (alpha, red, green, blue) to 0 3 2 1 (alpha, blue, red, green). We'll see why in a few moments.
• Click the message
box to export the frame as a QuickTime movie. As with jit.record
, we're specifying the frame rate and codec ( and ). We're also specifying a file name, . The message automatically closes the file after writing the frame to it.
• To load the single frame we've just exported , we'll use the jit.matrix
object first. Click on the message
box that says . This message clears the matrix and then outputs it to the jit.pwindow
, which should now appear entirely black.
message. Since we want to be certain that we're really importing the frame we just exported, we'll clear the
• Now, click the message
box that says . A file Dialog Box should appear, and you should locate and read myframe.mov
. The movie should have been saved in the same folder as the Tutorial patch. If you can't find it there, use the Finder's Find... command to locate the file on your disk drive. The frame you just exported should now be back in the jit.pwindow
. The message takes an optional first argument which specifies a file name.
• You're probably wondering what that second jit.matrix
, the object assumes that you want the first frame, unless you specify a time value that you'd prefer. In this example, we've asked for time value 600 whichis one second in from the beginning of a normal QuickTime movie—remember from Tutorial 4 that most QuickTime movies use a timescale of 600, which means they have 600 time values per second.
message is for. If you try to import a multi-frame movie into
• Try reading another QuickTime movie by clicking on the message
box . The jit.pwindow
should now be showing a frame from one second into that movie. You'll notice that the colors in the frame are not switched around this time. This is because we are importing an image matrix directly into the object
. Since the jit.matrix
object's attribute only affects matrices that arrive via its inlet, no plane remapping occurred.
Jitter binary export and import
Jitter offers its own binary format for single-matrix export, called .jxf. The Jitter binary format is simpler to use than the QuickTime format, and .jxf stores your data without any of the data losses associated with the various codecs you need to use with the QuickTime format. Additionally, the .jxf format supports matrices of all types, dimensions and planecounts, whereas the QuickTime format is only capable of storing 4-plane char matrices (images).
The patch shown above uses the Jitter binary format, which is selected using the
and messages. While it is very similar to the previous example patch, there are some important differences:
message only takes a single argument that specifies the name of the output file. Since the .jxf format is always a single matrix of uncompressed data, we don't need any other arguments.
message doesn't need a time argument (since a .jxf file will only have a single matrix in it). Like the message, will take an optional argument for the file name.
• The jit.matrix
object to send confirmation messages out the object's right outlet. We've connected that outlet to a print
object, so you can see those messages in the Max Console.
and messages cause the
Both techniques described in this section are available to the jit.matrixset
object as well, and function in similar ways.
Jitter offers several methods for importing and exporting single matrices from and to disk. The jit.matrix object (and the jit.matrixset object, not demonstrated in this chapter) allow single matrices to be saved as single-frame QuickTime movies, using the same parameters as the jit.record object's message. The jit.matrix and jit.matrixset objects also support the Jitter binary (.jxf) format— an uncompressed format specially suited to Jitter matrices.