Rants of the Q

NOTE: I’m working on MacOS X 10.4.11 and the issues detailed below are a direct result of that. The newer version of Quartz Composer released with MacOS X 10.5 takes care of several of these issues.

The Quest:

When I first got my AppleTV a year ago I fell in love with the “images drifting thru space” screen saver that came with it. I use it all the time and just point it at a folder containing every digital photo I’ve ever taken. My family’s entire lives scroll by on our TV daily and we stop frequently to watch a photo of a great memory scroll by while walking through the room. I wanted that same screen saver to put on my Mac. I figured this would be a piece of cake since plenty of people have hacked the AppleTV to installed full OS’s on it, or grabbed pieces of it’s OS to put on Mac Mini’s to make them look like AppleTVs etc.

Something’s Wrong Here:

A quick search of the internet turns up some files snatched from hacked AppleTVs, most notably one called, “FloatingPhotos.qtz.” Many people on the net say things like, “Here’s the screen saver from AppleTV it’s a Quartz file and should work fine on regular Macs.” WRONG. Dead wrong. Opening the Quartz file in Quartz Composer (QC) and running the program results in a black window with nothing happening in it. Further investigation reveals that the program is written based around a list structure consisting of file URLs and x and y coordinates. However, the the program gets the structure from somewhere outside of the qtz file, therefore no images are rendered; and even if you feed photos to the code via a “Folder Images” patch, it still won’t work because the structure returned from “Folder Images” is a list of file references without coordinates so that code still does nothing. To make matters worse, if you wack the code long enough and do manage to get it to draw images you end up with 3 of them. Yep, that’s right: one back image, one center image, and one front image. They don’t scroll, but they do rotate every “X” number of seconds. Oh and did I mention that the photos don’t change their image and that the programming environment has a bug in it’s image code that makes it impossible for it to do so as it’s architected. Whew, this was not going to be as easy as I thought...

Rolling up the Sleeves:

At this point I doubled my attempts to find somebody that has done this. There seem to be enough people asking for it, and there seem to be groups of Quartz Composer developers, but there doesn’t seem to be a connection between the two that I could find. So, once I knew I had the rotational transform code (which definitely seemed to be the hardest part) I figured what the hell, let’s learn a new tool and new programming language, and a new way of “coding” altogether!

Quartz Composer is a Visual Programming Language (VPL). That means that instead of laying out your program using psuedo-english words in a VERY particular syntax you do it by dragging rectangles around and connecting them with wires or patch cords to show the logic and execution flow (see Figure 1). Despite the fact that I assume VPLs were invented to make programming more accessible to non-programmers, I found QC to be advanced level software. While a motivated but uninformed person could probably get something cool out of it, I’m guessing it would be an incredibly frustrating experience for them. I’ve been coding for 20+ years and have learned half a dozen languages or more so I was able to pick it up within a day or two and start coding. Once I started coding I had the project finished within 12 hours.

Saturday, October 25, 2008

Looping structures are not allowed when connecting your patches in QC. Instead they have a concept that is familiar to programmers called iterators. An iterator is an object whose job it is to traverse a list of stuff and return the individual items while also keeping track of where it is in the list. The problem for this project lies in the fact that without looping the structures visually you NEED iterators to walk a list of files in a folder to get the job done, but QC has a bug in it that stops you from being able to load different images from within an iterator. Even though everything in your program says it’s working fine and it’s loading the next picture, when you ask QC to render it, it will just render the same old one it’s had laying around. This was almost the end of my adventure, as I found plenty of people complaining about this issue, but the only solution seemed to be to upgrade my OS to a newer version, which seemed like a lot to do for a screen saver.

Not knowing the language at all, I’m sure I could have been missing something, and nobody seemed to have any solutions to my problems, but I found a guy that seemed to have something close to a working version. Richard Das’ website contains a QC sample that looks close to AppleTV’s screen-saver (http://richarddas.com/portfolio/). Seeing this left me determined to find a way to make this work. His version used 15 copies of the same image instead of a seemingly random collection of photos scrolling by. But he does seem to have gotten around the image changing issue (though he does it different than AppleTV does... Apple never let’s you see the image change, the new one just scrolls onto the screen) and his images do scroll. His sample project was large and didn’t seem like it could be converted to look like the Apple version with my little bit of knowledge.

Having a fresh dose of encouragement from Richard’s work I kept searching though, and my next find was a patch called “Spooky Patch”. Spooky patch is a plugin written in a lower level language like C or C++ and it’s job is to take a value (any value) and deliver it anywhere else in your program via a standard output port. Spooky patch gets us around the looping issue and the “Can’t change images in an iterator” bug. Spooky patch kicks ass. If you are doing any QC programming you must check it out along with it’s host site Kineme Interactive Media. This is a fantastic source of info for QC stuff, even better than Apple’s in my experience.

With Spooky Patch, Richard’s sample and the original FloatingPictures.qtz file in hand I set out to write a newer, better version. The basic approach I took was to use FloatingImages.qtz as a starting point since it knew how to do the 3D transformation and it knew about the 3 layers of photos (Front, Middle, Rear) that I would need.

Looking at Apple’s screen saver I determined I could probably replicate it’s look by having two photos in the foreground, four in the middle layer and 6-8 in the rear layer. Then I could scroll the images up from “under” the bottom of the screen until they scrolled off the top of the screen. Once an image goes out of view off of the top of the screen I use that as a cue to load the next randomly selected image from the user defined image folder. The scrolling is done using a Low Frequency Oscillator (LFO) which is a fancy way to say, “machine that generates numbers between x and y values”. Using an upward sawtooth curve and varying the durations (which controls the speed that the photos scroll) I can use the value that the LFO generates as Y coordinates for my photos. The downside is that I need one for each photo, but performance on my old machine seems decent so I haven’t worked to convert to just one LFO. Likewise, I can use the “offset” field of the LFO to stagger the photos vertically on the screen as they scroll. The offset value just causes the waveform to be shifted down the timeline by “x” amount. Using values from 0-360 as offsets allows me to stagger the images vertically and give the illusion that they are randomly placed. The “x” coordinates for the photos are currently hard coded to look random, but with a little more work you could probably generate true random “x” values for each photo.

Spooky patch passes the values that the LFO’s generate thru to the drawing code within the iterator (which is buried several layers deeper). The LFO’s values give us the Y position of each image but they are also used to generate an index into the list of images we’re using. The method is a little convoluted but basically I walk thru the list of files one at a time, but instead of picking the one I’m on the index of I generate a random number and add that to the index then use modular arithmetic to clip the resulting value to the lists’ size - thereby randomly selecting from each and every image within the image folder.

(Iterating over a folder of images is a common problem QC programmers have. While QC makes it very easy to generate a list of images within a folder and to suck them out and render them, it does not seem to allow for an easy way to loop CONTINUOUSLY over that list. Resetting your loop counter to 0 once you’ve reached the last element doesn’t seem to be possible. I’m sure some smart QC programmer with years of experience has a bunch of solutions to this, but from my web searches I just found people asking how to get around it. My random/modulus solution may not be the easiest solution, but it does seem to work.)

The Payoff

A few hours of hacking away in QC resulted in what I consider to be a successful (though not exact) reproduction of the AppleTV screen saver. While not identical to Apple’s, it certainly gives the user the same feel as Apple’s does. My version currently seems to use less photos then Apple’s does and I just need to take some more time to add more to my version should I want a more dense look. Furthermore, Apple’s seems to be truly random whereas I simulate randomness in at least 2 ways in my version. My version also has a blemish as it stands right now that I’m not sure I will bother to fix. When the screen saver first loads all images are the same, until the system gets primed and running. Much like the iTunes screen saver goes thru a 5-10 second startup period when it first starts loading it’s data, QTV need to load everything up too and getting the show started early seemed like a decent solution. If you name your favorite photo so that it’s the first you’ll just get a nice large dose of it before things get rolling properly. That didn’t seem so bad to me, but I’m interested in what others think. Actually, it seems better than the way my AppleTV does it... it locks up solid for about 20 seconds while loading the images and refuses to even hear input from the remote.

Installation (Download the Files with Links Below):

The worst part of my solution is the fact that installing my screen saver requires putting two files in the correct locations instead of just one.

1)Place the QTV.tqz file within your “/Library/Screen Savers/” folder.
2)If running on MacOS X 10.4 (Tiger) place the SpookyPatch.plugin file in the “/Library/Graphics/Patches/” folder. On MacOS X 10.5 (Leopard) place the SpookyPatch.plugin file in the “/Library/Graphics/Quartz Composer Patches/” folder (NOT the plug-ins folder). The folder may not exist yet and YOU MAY NEED TO CREATE THE FOLDER YOURSELF.
3)Select “System Preferences” from your “Apple” menu. Select “Desktop and Screen Saver.” Scroll down until you see QTV and select it. Then click the “Option…” button to assign your preferences (including which folder of images you would like to use)

Settings

I’ve provided as many customizable settings as I thought would be useful. I allow you to select the folder of images of course, but I also let you adjust the back, center, and front layer scroll speeds, pick between left rotates and right rotates (the UI sucks, but you have the choice), pick how often the spin occurs, choose wether to have shadows on the front two layers of photos or not, and if it should render the background sun and copyright notice.

If you have any questions about this screen saver or about my QC experience feel free to contact me using the “Email Me” or the “Add a Comment” buttons below.

Troubleshooting

Q) QTV doesn’t show up in the preference window, what’s wrong?
A) The QTV.qtz file is not in the screen savers folder (or is in the wrong “Screen Savers” folder).

Q) The screen is all black (or just a purple sun scrolls across the screen), what’s wrong?
A) There are no pictures in the image folder that is selected in the “Options” dialog. Make sure the path given in the dialog is correct. Make sure there are actually pictures within that folder. It may help to hit tab to move out of the “Pictures Folder” edit field so that the OS knows you changed the value before clicking the “Done” button.
Q) Just one picture shows up multiple times & they all spin, but they don’t scroll, what’s wrong?
A) The “Spooky Patch.plugin” file is not in the correct folder. Please read Step 2 above carefully and be sure you have the folder named correctly for the version of the operating system you are using. If you’re using MacOS >= 10.5 make sure the plugin is in the folder “ Quartz Composer Patches” not the plugins folder.

Q) There’s a couple of tiny lines of text in the back of all the pictures that I can’t read. What is it?
A) That’s my copyright notice, which looks nice on my iMac 24” screen, but gets trashed at other screen sizes. It’s a bug I need to fix. If it annoys you, turn off the “Show Copyright” checkbox in the “Options” dialog.

Q) I’m using MacOS X 10.5 and your solution seems overly complex and slow, why is that?
A) That’s because I’m using 10.4.11 and wanted to find a solution for that operating system that would also work on 10.5 and newer systems. I may try to do a streamed lined 10.5 version that isn’t Spooky Patch dependent and works more efficiently.
Q) I want to modify your code, but I can’t make heads or tails of it, why is that?
A) I normally comment code like a mad man, but since I was learning the language as I was working, commenting wasn’t possible. If I get any feedback about this I’ll spend the time to comment up the file, but it’s not a great coding example anyway as it is the result of morphing prototyping style coding rather than a well thought out and designed project.
Q) I want to modify your code and distribute it, can I?
A) This doesn’t bother me at all as long as you give me credit for my portion of the work and you are giving your product away for free. I ask that you please send me a copy of your derivative work though.

Scott Quillen is not responsible for any damage or loss of information that may occur as a result of using the software provided. Use this software at your own risk. Realistically, it just draws pictures so what could go wrong?

Figure 1