QLab 3 and Quartz Composer - Custom Image Filters


Table of Contents

    QLab 3 can interact with Quartz Composer in one of two primary ways; as a custom Video Effect or as an external application which uses Syphon to send information to or from QLab. Both of these instances will be covered in this Tutorial. Quartz Composer is a graphic programming environment that allows you to build and run custom video filters, effects, transitions, and more. For more in depth information on Quartz Composer specifically head over to http://kineme.net/ where you can search their vast database of questions, answers, sample code, plug-ins, and more.

    First off, most Quartz Composer needs can be handled with the built in effects provided with your version of QLab 3. Simply navigate to the Video Effects tab in the Inspector, click the radio button and select the effect type you want. Adjust the sliders as desired. If you want to animate that effect simply add a Fade Cue targeting the media you added the effect to and adjust the values and duration accordingly.

    This is great for basic effects in a tech situation where suddenly you realize it would all look way better if black and white or perhaps you want to add a simple pixelate or blur effect to a transition. However, sometimes you will want a more complex transition. Perhaps you want to start with a whiteout overexposure that is blurred in black and white and slowly resolves into a full color clear image. Well, then you will need to build a custom Quartz Patch. But don't worry, it is frighteningly simple.

    Quartz Composer is provided for free with Apple's developer tools in X-Code. Simply download X-Code from the Mac App Store, grab a cup of tea (it's a big long download), and then open Quartz Composer which will be found in Applications -> Graphics Tools.

    When you first open Quartz Composer you will be presented with a blank Composition as shown in the below screen shot.

    screen shot 1

    The Clear patch clears the frame buffer of any renderers and is not necessary for image filters so you can simply delete that. Now you have a blank canvas. What you will need in order to build an image filter for QLab is a composition that has published inputs and outputs for the media you will play back. You can download this sample file that when opened should look like the below screenshot.

    screen shot 2

    Congratulations! You now have an Image filter that will work with QLab and passes frames unchanged through Quartz Composer and back into QLab. Your next step will be adding patches. Over on the screen left side you will see your Library. This contains many patches and filters pre-built. Simply drag and drop the filters into your composition and connect the image output (right hand side of a patch) with an image input (left hand side of the patch). This will build your rendering path that each frame goes through.

    Once you are done with that you will probably want to have control over these values within QLab. To do this you will need to publish additional inputs. Don't worry, this does not involve getting an interview with Random House, it is just a mouse click. Control-Click on one of your patches. This opens a dialog box with a few options. Navigate to Publish Inputs and select one, perhaps the radius parameter on a blur patch. Keep doing this until all the parameters you want control over are published. Now when you load this patch into QLab you can control all these parameters directly from within QLab. Yay!

    For every parameter that you publish you will probably want to add an Input Splitter. This is another option in that Control-Click dropdown. Once you have added each of your splitters select the splitter and look at the Inspector within Quartz Composer. Under Settings in the Inspector you will see Minimum and Maximum Value fields. Enter your min/max values for each patch. Even though Quartz Composer accepts NaN for an unlimited value QLab seems to like real numbers so go ahead and enter them (no, really, do it - as in, none of your parameters will work in QLab 3, even if only one parameter does not sport min and max values). Don't worry you can make the numbers REALLY big and REALLY small to have enough working room.

    There you go. You are done. You will now have a Quartz Composition that looks something like this:

    screen shot 3

    Now save your composition and go back into QLab. In the Video Effects tab select Custom Composition and navigate to your file or drag and drop. Done!

    Note 1: Certain patches, like blur, can get a little odd on rendering if you don't do a little work to contain them. Here you will need to crop the blurred image back to the size of the original image. You can see below that the blurred image is routed to a Stretch Crop patch and then out to the published output. The Image Dimensions patch gets the dimensions of the original image served by QLab and tells QC what to do to the filtered image in terms of sizing.

    screen shot 4

    That's how to create a custom Quartz Patch for QLab 3.

    Note 2: QLab really does not like you editing Custom Patches in the background. Adjusting min/max values is not terrible, but adding new published Inputs or adding whole new patches with new published inputs can get a little, shall we say, awkward. Unless and until this is fixed be sure to have all your elements in place in your patch before you head in to tech. Better to add a couple effects that you never use than need them midway through tech and discover you now need to edit every single video and fade cue in your 100+ cue show.