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, text and ASCII 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.
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.qt.record
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.qt.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.qt.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.qt.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.qt.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 Window.
and messages cause the
Both techniques described in this section are available to the jit.matrixset
object as well, and function in similar ways.
object offers two export methods you can use to save movie frames as QuickTime still images, rather than movies. The first method exports single frames as image files. The second method exports an entire movie as a sequence of image files, called an Image Sequence
You may find this way of working preferable if you're using images you generate with Jitter for page layout, or if you're using the images in conjunction with other graphic processing software like Photoshop or GraphicConverter.
object can export and import QuickTime movies in a number of non-movie formats. For the purposes of this Tutorial, we're only going to cover still image export. For a more comprehensive listing of import and export options available in jit.qt.movie
, please consult the object's Object Reference entry and help file.
Let's start with the simpler of the two methods: the jit.qt.movie
. Using , we can save the current movie frame as an image file. This method allows you to save your image in one of several standard graphic formats, including JPEG, PNG and TIFF.
• Click the message
box to read in a QuickTime movie. Use the number
box to navigate to a frame you'd like to export as a still image.
• Click on the umenu
object. The object contains a list of the still image file types available. Choosing one of these items will send the message to jit.qt.movie
(by way of the pak
object), with your chosen file type as an argument. A file Dialog Box will appear, where you can enter a file name for the image file you're about to create. The jit.qt.movie
object will automatically append the correct file name extension (.png, .jpg, .tif, etc.) to the filename when it exports the image, so you don't need to add them. Click Save to continue.
• That's it. To verify that your export was successful, look in the Max Window. The jit.qt.movie
object sends the message from its right outlet after a successful operation ( is the file name you chose). If was unsuccessful, the number will not be 1. You can either reopen the file in Max, by reading it into jit.qt.movie
, or switch to the Finder and open it in your favorite image viewing application.
• The message
box to see it. First, you'll be prompted for a file name. Then, before exporting the image file, the Dialog will appear, where you have the option to change the file type, and set file type-specific options for the operation.
message takes an optional argument to call up the export Dialog Box. Click on the
The full format of the
message is . All of the arguments are optional. If you omit the file type and dialog flag, the operation will use the last file type you specified. PNG is the default if there is no saved file type.
General Export from jit.qt.movie
We can also use jit.qt.movie
to save an entire movie file as an Image Sequence
—a series of still images, one for each frame. This process relies on a slightly more complicated export mechanism.
In QuickTime, every movie can potentially have a different set of available exporters—for example, you might want to export the sound tracks in a QuickTime movies as CD audio or AIFF files. Or you may be able to export your Photo-JPEG video tracks as a DV stream. Some movies might permit several image export formats, while others are limited to just a few. Because of this potentially shifting landscape of options, we've attempted to make exporting in jit.qt.movie
as flexible as possible. And that added flexibility will require a little extra explanation.
• Click the message
box , to read in that file. We're using this movie because it's only one second long. You may use the number
box to navigate around the movie, if you like.
• Click on the message
box . This causes jit.qt.movie
to send a list of available exporter components from its right outlet, preceded by the word . Our patch breaks that list up and places the list into an umenu
object for easy access.
• Click on the umenu
to view the list. Our list contains entries like AIFF, BMP, FLC, HEURIS MPEG and several others. You probably recognize several of the formats offered. Choose the item. This causes the message
box to send the Image Sequence exporter's index number (which is the same as its position in the umenu
item list) to jit.qt.movie
Important Detail: Since each movie could potentially support different exporters, this index number might change from movie to movie for the same exporter component.
• Click on the message
box . A file Dialog Box will appear, prompting you for a file name. We'd suggest that you create a new folder for saving the sequence, since the operation generates several files. Enter a valid file name and click Save.
• You should now see a special Dialog Box appear, permitting you to adjust the options specific to the exporter you chose, such as file type and frame rate, in the case of the Image Sequence exporter. (Notice that the same file type options are available as with the
Each exporter may have its own options. This Dialog Box will only appear when there is a operation.) If you leave the frame rate field empty, the operation will use the movie's native frame rate to generate the images. (which we call the options flag
) at the end of the message to jit.qt.movie
. The message also accepts an optional file name before the options flag.
You should only need to use the jit.qt.movie
object will remember the options after you've specified them the first time. Try clicking the message
box now. No Dialog Box will appear for the exporter options, and the file will be exported with the same options as before.
message once, whenever you start using a new exporter. While you're using the same exporter, the
• You should see a progress Dialog Box appear briefly. When it disappears, you can check in the Max Window to verify that the operation was successful—jit.qt.movie
will send the message if it was. (The number will not be if there was a problem.) If you switch to the Finder and look in the folder where you chose to save the Image Sequence, you should see several files, named sequentially. You've successfully exported your movie as an Image Sequence. Open a couple of the files up and verify that they show different frames.
• Returning to Max, click on the message
box . The argument is another flag to the message, telling jit.qt.movie
to open the full QuickTime export dialog, which permits you to set file name, exporter and exporter options all at once.
Technical Detail: When you use the jit.qt.movie
won't know which exporter you chose while inside the Dialog Box. In order for jit.qt.movie
to remember what your current exporter is, you must use the message.
Had enough? Sorry—there's more, but let's take a little break from image data.
Jitter matrices can be used to manage all sorts of data, including text. The jit.textfile
object provides a convenient interface for importing and exporting text files to and from Jitter. Once you've imported a text file, you can edit it, or send it to other objects for further processing or display as you would with any Jitter matrix. Or you might export a Jitter- generated text file, and continue to work on it in your word processor. In this section, we're going to take a quick look at the jit.textfile
object's import and export abilities.
You may recall from the What Is A Matrix? chapter that one of Jitter's data types, char, is the size of a single character. With the notable exception of certain complex character sets (such as Japanese), most languages use the char type for computer representation. The correspondence between the numbers and letters has been standardized in the American Standard Code for Information Interchange, usually referred to as ASCII.
One of the interesting things about the ASCII code is that the regular characters used in the English alphabet can be represented in less than half of the space available to the char type (26 uppercase plus 26 lowercase plus 10 numerals is only 62 characters, compared to the 256 different values that chars can represent). Furthermore, all of these regular characters fall in the first half of the char range (specifically, between 32 and 126). The following example patch will take advantage of that fact.
This patch sends encoded text messages via Jitter matrices. Here's how to use it:
• Let's begin by encoding a message. Choose an encode key—a password that will be used for encoding (and later, decoding) your message. Enter your encode key in the textedit
object labeled . Enter the message you want to encode in the larger textedit
object labeled , at the top of the patch. For the purposes of this example, you should limit your message to regular English language characters—no accented characters, please.
• Press the button
labeled to encode your text. This causes the contents of the two textedit
objects to be sent to two jit.str.fromsymbol
objects. These two objects convert the contents of their respective textedit
objects from Max symbols into matrices. The resulting two matrices are then added using the addition mode of the jit.op
object, producing a new encoded matrix that is then sent to the jit.textfile
It doesn't matter that the two pieces of text (and therefore the two matrices) are different sizes. Jitter automatically scales the right-hand matrix of jit.op
to the size of the left-hand matrix, stretching it or shrinking it as necessary. You might modify the test patch and use a jit.print
object to view the output of each object, and then compare it against the output of jit.op
, to see exactly what's happening.
• Double-click on the jit.textfile
object. This causes the object's text editor window to open, displaying the encoded message.
• To verify that the encoding was successful, enter your encode key into the textedit
object labeled , and click on the button
labeled . Your original message will appear in the textedit
object at the bottom of the patch. We'll look at this process in a moment.
• Click the message
box that says to save the message to disk so you can retrieve it later to send to your secret message buddy (don't forget to give them the encode key!). A file Dialog Box will open, where you can enter a file name and click Save to save your message to a text file. You can open this text file with any text editor application. The message takes an optional argument to specify a file name.
• There's a secret message waiting for you, too. Click the message
box . The message reads a text file from disk. In this case, we're using its optional file name argument. Without that argument, a file Dialog Box would open, allowing you to locate a text file on your disk drive.
• Double-click on the jit.textfile
object again, and verify that there's a new encoded message in the editor window. Close the editor window when you're ready. You can decode this message by entering the decode key Jitter
in the textedit
object labeled , and clicking on the button
labeled . Did you get our message?
• Like Max's text
will output a single line in response to the message. In Jitter, the line will be sent as a string matrix
. A string matrix is a matrix using the char data type with one dimension and one plane. The matrix is composed of a sequence of characters ending with a zero ( ). This is the format generated by jit.str.fromsymbol
, and the format expected by jit.str.tosymbol
. We're using the message to output the first line of jit.textfile
(our encoded text) and send it to the jit.op
object for decoding.
• The decoder simply reverses the encoding process—we use the subtraction mode of the jit.op
object to subtract the key matrix from the encoded message matrix, leaving the original text. The decoded matrix, containing all the letters of the decoded text, is then sent to the jit.str.tosymbol
object, where it is converted back into the form of an ordinary Max message, suitable for display in the textedit
• If we wanted this patch to work properly with extended Roman characters, such as accented letters, we'd need to make a couple of modifications. For extra credit, you might try to figure out a way to do that. Hint: the secret is in the jit.op
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.qt.record
object's message. The jit.matrix
objects also support the Jitter binary (.jxf) format— an uncompressed format specially suited to Jitter matrices. The jit.qt.movie
object's message lets you export a matrix as a single frame image in any of a number of image formats, and the message lets you store video frames as an Image Sequence.
In addition to images, Jitter matrices can be used to manage other kinds of data, such as text. The jit.textfile
object provides a convenient interface for importing and exporting text files to and from Jitter matrices. The jit.str.tosymbol
objects provide conversion between Max symbols and string matrices. These objects provide one of the means by which data can be translated to and from Jitter's matrix data format.