Blog

Acorn scripting using Python

September 24, 2007

Gus Mueller, of VoodooPad fame, introduced Acorn last week. Amongst its features is Python scriptability. As the author of NodeBox, this sounds like something to have fun with. Check it out:

If you want to play with it yourself, here's the script:

acornscript.py

Place it in "/Users/username/Library/Application Support/Acorn/Plug-Ins/" to make it appear under File>Actions.

Following is a detailed rundown of what I did in order to crack open the program and play around with it.

How to extend Acorn using Python

I became interested in the scripting possibilities by reading the official plugin documentation. Acorn's scripting support was meant to make new filters and such, but since it includes the PyObjC classes, you can basically do everything you can in Cocoa through Python. It's a really fast and easy way to make native Mac OS X applications, or, as in our case, extend existing ones!

Generating documentation

If I was going to achieve anything, I needed documentation for Acorn's internals. I wrote a script that parsed the class attributes and generated HTML documentation for them. Finding out the classes was a matter of traversing the object space, and looking for names (with obj.class). The script filters out the superclass's methods, and only keeps methods defined in this class.

This gave me a nice HTML page with all method names. I didn't have the parameters, but I could guess based on the method name.

Download docfinder.py.

The scripting drawer

To get something going fast, the first thing I wanted to see was a scripting drawer. I ended up extending NSDrawer because of refcount issues.

class ScriptingController(NSDrawer):
    def initWithDocument_(self, doc):
        rootView = NSView.alloc().initWithFrame_( ((0, 0), (300, 300)) )
        self.setContentView_(rootView)
        win = doc.windowController().window()
        self.setParentWindow(win)
        self.open()

def main(image):
    doc = NSDocumentController.sharedDocumentController().currentDocument()
    sc = ScriptingController.alloc().initWithDocument_(doc)

I then added the text view and the run button (without using a NIB file, to minimize dependencies). Attaching a button in PyObjC is a bit weird:

runButton.setAction_(objc.selector(self.runScript_, signature="v@:@@"))

This is where the refcount bug hit me. You see, my "main" method creates the interface and then terminates. Once the interface is on screen, the "run" button refers to a method that is now out of scope. The only way to keep it in scope is by making sure Cocoa keeps a reference to it through its windowing system: hence the NSDrawer subclassing.

Running the script

Running a Python script is as simple as:

source = self.textView.string()
code = compile(source + '\n\n')
exec self.code

While this works, you really need to setup a namespace with some useful commands. My custom AcornContext can access the document's layers, and add shape layers (which you saw in the demo) and bitmap layers. Example:

for i in range(10):
    add_layer('/Users/enigmeta/Desktop/hdr/DSCN%04i.JPG' % i)

Wrapping the Acorn classes

Acorn's TSShapeLayer provides all the right methods, but I wanted something NodeBox-esque for drawing shapes. Therefore, I wrapped it in a custom class, to which I added "rect" and "circle" methods. Here's the rect method:

def rect(self, x, y, width, height, **kwargs):
    r = TSRectangle.alloc().init()
    r.setDrawsFill_(True)
    r.setBounds_(((x, y), (width, height)))
    self._colorize(r, **kwargs)
    self._layer.addInRectangles_(r)

The dangers of running code

Running other people's code is fraught with danger: the script could crash, or do an expensive operation (such as an infinite loop) and cause the system to lock up. Using threads doesn't help much, but I did found a way to make it work. The trick is to start a new Thread with the method userCancelledMonitor, that looks like this:

def runCode(self, code):
    self._scriptDone = False
    try:
        t = Thread(target=self._userCancelledMonitor, name="UserCancelledMonitor")
        t.start()
        exec code in self.ns
    finally:
        self._scriptDone = True

def _userCancelledMonitor(self):
    import time
    from signal import SIGINT
    from Carbon import Evt
    while not self._scriptDone:
        if Evt.CheckEventQueueForUserCancel():
            # Send a SIGINT signal to ourselves.
            # This gets delivered to the main thread,
            # cancelling the running script.
            os.kill(os.getpid(), SIGINT)
            break
        time.sleep(0.25)

This code is from PyEdit, which is the default editor for Mac Python installations. Some custom code (from NodeBox) wraps exceptions thrown inside of the user's code.

What's next

The upcoming version adds an output panel that displays errors and print statements. Right now, these are forwarded to the Console (/Applications/Utilities/Console.app), which is cumbersome.

In addition, the API needs some work, of course, and I really want to add some niceties to the interface.

Acorn hits the right note: it's obviously a simpler, faster version of Photoshop. Gus did the right thing by staying close to the original (the keyboard shortcuts are mostly the same) while improving on some key points: simplicity, speed and "nativeness". The Python scripting makes it my absolute favourite hackable image editor.