The Flying Meat Wiki: Acorn Plugin Documentation

Acorn Plugin Documentation

The different types of plugins:
Acorn provides a simple Cocoa plugin API for you to alter the current bitmap layer, or perform actions with the current image.

You can write your plugins in either Objective-C, or Python. Objective-C plugins are compiled and loaded up from bundles placed in the ~/Library/Application Support/Acorn/Plug-Ins/ folder. Python plugins are text files ending with .py. You can find some examples of Python plugins on the AcornPlugins page. You can also download example Objective-C plugins from here: SampleAcornPlugins.zip∞

How plugins are loaded:
At startup Acorn looks in the ~/Library/Application Support/Acorn/Plug-Ins/ folder for two types of files.

Objective-C bundles, ending with .acplugin. For example "Grayscale.acplugin".
Python files, ending with .py. For example "Grayscale.py"

The ObjC plugins must implement the ACPlugin protocol, and register themselves with Acorn to show up in a menu. (The ACPlugin protocol is defined in the file ACPlugin.h in the examples download). When the plugin is loaded up, you are given an opportunity to say "Hey, I want to go in the XYZ filter menu, and I want you to call this selector when I'm to be used". When your method is called, you are given a CIImage, you perform whatever you want to do to the image, and then you return a CIImage to be replace what you were given.

So for example, if I wanted to write a quick ObjC plugin to convert the layer to grayscale, my plugin would look something something like this:

@implementation ACGrayscalePlugin

+ (id) plugin {
	return [[[self alloc] init] autorelease];
}

- (void) willRegister:(id<ACPluginManager>)pluginManager {
	
	[pluginManager addFilterMenuTitle:@"Grayscale"
	               withSuperMenuTitle:@"Color"
	                           target:self
	                           action:@selector(convertToGrayscale:userObject:)
	                    keyEquivalent:@""
	        keyEquivalentModifierMask:0
	                       userObject:nil];
	
}

- (CIImage*) convertToGrayscale:(CIImage*)image userObject:(id)uo {
	CIFilter *filter = [CIFilter filterWithName: @"CIColorMonochrome" keysAndValues: @"inputImage", image, nil];
	
	CIColor *color = [CIColor colorWithRed:0.5f green:0.5f blue:0.5f];
	
	[filter setDefaults];
	[filter setValue:color forKey:@"inputColor"];
	[filter setValue:[NSNumber numberWithFloat:1] forKey:@"inputIntensity"];
	
	return [filter valueForKey: @"outputImage"];
}

@end

If you don't want to return an image because you've got something else you want to do, just return nil.

You can also get a reference to the calling image by asking the document controller what the current document is:
[[NSDocumentController sharedDocumentController] currentDocument]

This returns a subclass of NSDocument (ACDocument), and you can use the various methods that NSDocument provides to find out information about the image. In addition, you can get different representations of the image as NSData like so:

NSDocument *theDoc = [[NSDocumentController sharedDocumentController] currentDocument];
NSData *tiffData = [theDoc dataRepresentationOfType:@"public.tiff"];

Other UTIs you can use: public.png, public.jpeg, public.tiff, com.compuserve.gif, com.microsoft.bmp, com.apple.icns, and com.adobe.pdf

Python Plugins

Python plugins work a lot like the Objective-C plugins, only they are a lot easier to write since you just put a text file ending with .py in the Plug-Ins folder. Visit the AcornPlugins page for examples written in Python.

Another big advantage of writing a plugin in Python, is that you don't need to stop and restart Acorn to modify an already loaded plugin. Just edit the file, and rerun it from Acorn.

Setting up the python plugin for the Filter menu.
To have your python plugin show up in the filter menu, you put some assignments at the top of the script. Check out the Quick Save plugin for it in action. Here's a quick description of what they mean, and valid values.

ACScriptSuperMenuTitle, The supermenu that the plugin should show up in.
ACScriptMenuTitle, The title of the plugin
ACShortcutKey, the shortcut key (a string)
ACShortcutMask, the name of the modifier(s) needed to invoke the plugin (control, option, command shift)
ACIsAction, (True | False). Wether or not the plugin should go in the File/Action menu.

Acorn Additions

Here are some various additions to Objective-C (and also useable from the Python side) that Acorn provides:

Additions to NSImage:
- (CIImage *)CIImage;

Additions to CIImage:
- (NSImage *)NSImage;
- (NSImage *)NSImageFromRect:(CGRect)r;

Additions to NSDocumentController:
- (id) newDocumentWithImageData:(NSData*)data; /* takes bitmap data, (PNG, TIFF) */

Back to AcornPlugins