13 May, 2011

TUTORIAL: Structures and Index Members in Quartz Composer

This tutorial will outline basic use of Structures and the Index Member patch in Quartz Composer.

A structure is simply a way of organising data. It can be thought of as a series of labeled folders containing files, like a folder with pictures of your summer vacation that contains subfolders organised by date.

Even though we might not notice it, in Quartz Composer we deal with structures in many ways: any time we load something from a folder, when we create groups of values dynamically with Iterators, when building a 3d mesh etc.
It’s probably easier to just show you, so in this tutorial we will outline a simple way of displaying RSS feeds in Quartz Composer.

We begin by loading a patch called RSS Importer.  As the name implies, this takes an internet RSS feed and downloads the contents much like any other reader does.

This patch receives as input the feed URL and an “update signal” boolean. It outputs the feed information and the articles, plus the download progress and a quick pulse signal when the download is done.

The output of this patch is where we start dealing with structures. Rather than giving us a huge block of text, the output will be structured the same way as when we read it on the website (title, date, content, author etc.). 
The article list will be a structure, and each article will itself be a structure made of the individual elements of the article.

In order to view the contents we need a way to display the text. We do this by loading the Image with String patch. This is an extremely useful patch that allows us to display text in Quartz Composer as an image. We can change the font, alignment, size etc. 
We drag in a Sprite patch to display the output of the Image with String patch.

As a test, we can try to connect the “Article List” output to the “String” input of the Image with String patch, and the “Image” output from there to the Sprite "Image" input. All we get is a pretty blurry <QCStructure> bit of text. 
This is because no actual text is loaded, and the Image with String is just passing the output type information. So the RSS patch is outputting a structure, and we need to separate the individual elements of the structure to pass it to the IWS (Image with String) patch. 

Before we do anything else, let’s clean up the image output of the patches so that it’s readable. We select the settings tab for the IWS patch, and change the dimensions from "Fixed" to "Dynamic". This will allow us to deal in pixels rather than units. 

Next we connect the “Display Width” and “Display Height” outputs from the IWS patch to the "Width" and "Height" inputs of the Sprite patch.

The text is now clearer but still small, so we change the “Font Size” input in the IWS patch to 20. The text is now big and readable.

We’re still seeing the old bit of text, so let’s get to the article data. As we said, the RSS importer outputs structures, and we need to separate the various elements in order to display them.
To separate the elements we make use of the Structure Index Member patch. 
This patch takes in a structure and only selects the member of the structure we need from the index.

We need to connect the Article List output from the RSS patch to the Structure input of the SIM (Structure Index Member) patch. We then connect its Member output to the String input of the IWS patch.

Despite doing this, we’re still displaying the same text. To check what the RSS patch is actually sending out, we can hover with our mouse pointer over the Article List output connector.

As you can see, this lets us view the actual contents of the feed and understand how the structure is organised. We can see the number of elements in the structure and the contents of the sub-structures. This will help us decide how to use the SIM patch.
As an example, let’s say that we want to display the text from my recent blogpost. We need to extract the first element in the list from the main article structure (0), and then we need the article description, indexed at (1) in the sub-structure.

First we select Index 0 in the SIM patch. We rename this patch to “Article List”.

We now need a second SIM patch, in order to extract the specific element we need from the first structure. We create a new one and rename it “Article Description”. We connect the "Member" output of the first SIM to the "Structure" input of the second SIM, and connect the output of this one to the "String" input of the IWS patch.

If we look at our viewer, we are now displaying the Title of the articles. This is because the second SIM patch is still set on index member (0). When we change the index to (1), we finally get the text we needed.

The text however is being displayed in a long horizontal line. This is because we haven’t specified the dimensions of the image that is being passed from the IWS patch to the Sprite. To do this, we need the Rendering Destination Dimensions patch. This patch contains all the information about the dimensions of our viewer destination, and can be used to resize images so that they fit the final rendering area.

In our case, we are going to feed the info to the IWS patch, since it’s the one generating the image. We’re dealing in pixels, so we connect the “Pixels Wide” and “Pixels High” outputs from to the Rendering Destination Dimensions patch to the “Image Width” and “Image Height” inputs of the IWS.

As you can see,the text is now displayed correctly within the viewer bounds and is clear and readable. This is a very basic use of this method, but with more time one could format it in a very attractive way with different fonts and colors for the various elements.

Hopefully this has provided a valid introduction to the use of Structures and Index Members in Quartz Composer. We have also seen how versatile a tool QC really is, as in no time we have created the foundation for a customised RSS reader that can be easily extended. 

(This tutorial was requested by reader "instrumentality". Leave a comment here to request new tutorials)