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.

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.

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 importmovie and exportmovie are used to import and export a single matrix from the jit.matrix object. The exportmovie message conveniently uses the same format as the jit.qt.record object's write message.

Open the tutorial.

• Click the message box that says read 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—@autostart 0. 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 frame $1, bang.

• Why are the colors all messed up? They're messed up because we're using the planemap attribute of 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 exportmovie myframe.mov 30. jpeg to export the frame as a QuickTime movie. As with jit.qt.record, we're specifying the frame rate and codec (30. and jpeg). We're also specifying a file name, myframe.mov. The exportmovie message automatically closes the file after writing the frame to it.

• To load the single frame we've just exported , we'll use the importmovie message. Since we want to be certain that we're really importing the frame we just exported, we'll clear the jit.matrix object first. Click on the message box that says clear, bang. This message clears the matrix and then outputs it to the jit.pwindow, which should now appear entirely black.

• Now, click the message box that says importmovie, bang. 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 importmovie message takes an optional first argument which specifies a file name.

• You're probably wondering what that second importmovie message is for. If you try to import a multi-frame movie into 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.

• Try reading another QuickTime movie by clicking on the message box importmovie 600, bang. 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 planemap attribute only affects matrices that arrive via its inlet, no plane remapping occurred.

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 write and read messages. While it is very similar to the previous example patch, there are some important differences:

• The write 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.

• The read message doesn't need a time argument (since a .jxf file will only have a single matrix in it). Like the importmovie message, read will take an optional argument for the file name.

• The read and write messages cause 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.

The jit.qt.movie 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.

Let's start with the simpler of the two methods: the exportimage message to jit.qt.movie. Using exportimage, 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 read 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 exportimage 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 exportimage myfile 1 from its right outlet after a successful exportimage operation (myfile is the file name you chose). If exportimage 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 exportimage message takes an optional int argument to call up the export Dialog Box. Click on the message box exportimage 1 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 exportimage operation.

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 read garbage.mov, 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 getexporterlist. This causes jit.qt.movie to send a list of available exporter components from its right outlet, preceded by the word exporterlist. 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 Image Sequence item. This causes the message box exporter $1 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.

• Click on the message box export 1. 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 exportimage operation.) If you leave the frame rate field empty, the export operation will use the movie's native frame rate to generate the images.

• 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 export myfile 1 if it was. (The number will not be 1 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 export fulldialog. The fulldialog argument is another flag to the export 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.

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 encode key. Enter the message you want to encode in the larger textedit object labeled code text, 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 make code 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 object,

• 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 decode key, and click on the button labeled read code. 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 write 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 write message takes an optional argument to specify a file name.

• There's a secret message waiting for you, too. Click the message box read secret.txt. The read 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 decode key, and clicking on the button labeled read code. Did you get our message?

• Like Max's text object, jit.textfile will output a single line in response to the line 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 (0). This is the format generated by jit.str.fromsymbol, and the format expected by jit.str.tosymbol. We're using the line 0 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 object.

• 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 op attribute to 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 write message. The jit.matrix and jit.matrixset objects also support the Jitter binary (.jxf) format— an uncompressed format specially suited to Jitter matrices. The jit.qt.movie object's exportimage message lets you export a matrix as a single frame image in any of a number of image formats, and the export 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 and jit.str.fromsymbol 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.