docerator automatically creates Mac OS X document icons given an application icon and one or several file extensions. It is a tool for application authors that don't have the time or the money to create a docicon, but already have an application icon. It's also useful if you need to create many document icons.

docerator takes some care to create great-looking docicons at all sizes: The text on the 32x32 icons generated by docerator is readable, which is not the case if you draw a 512x512 doc icon and then drop this on Icon Composer to create all variants (see examples below).

GUI Usage

New in 2.0 Docerator now includes a GUI, contributed by Sveinbjorn Thordarson. To create document icons in the GUI:

1. Drag in the icns file that contains your application's app icon.
2. Select the sizes you want to create your document icons in.
3. Add the document icon labels on the right, and optionally add shorter labels for the smaller (32x32, 16x16) resolutions.
4. Click "Create Icons" and select a folder. Your document icons will be written to that folder.

Done!

Basic Script Usage

If you only want to create a single icon, use:

python docerator.py --appicon myapp.icns --text TEXT

This creates 'myapp-TEXT.icns' with the same sizes that your app's icon has.

If you want to create several docicons:

python docerator.py --appicon myapp.icns --text TEXT --text RTF

Due to caching, it is much faster to create several docicons in a single docerator call instead of invoking docerator once for each docicon.

If you want to have a different text on the two small variants:

python docerator.py --appicon myapp.icns --text PYTHON,PY

Texts can be empty. Hence, to omit text on the 16x16 variant:

python docerator.py --appicon myapp.icns --text PYTHON,PY,

To create certain sizes:

python docerator.py --appicon myapp.icns --text TEXT --sizes 128,32,16

--sizes defaults to the intersection of variants in both background and icon.

Examples

These are the icons generated by python docerator.py --sizes 512,256,128,32,16 --appicon /Applications/Preview.app/Contents/Resources/preview.icns --text DDS:

This example shows how docerator takes care to produce great small-sized icons. The left 32x32 icon shows the output generated by docerator, the right one shows Acorn's old 32x32 icon:

The text is readable in docerator's version, and the border is crisp.

This was generated by the script in the "Advanced" section below.

Advanced Script Usage

If you want to clean up the icon generated by docerator a bit (recommended at smaller sizes), you can first let docerator create a document icon without text:

python docerator.py --appicon myapp.icns

Then do your cleanups, and then let docerator add texts to the cleaned up version:

python docerator.py --background myapp-Generic.icns --text FOO --text BAR

If you are not content with the placement of your app icon, you can supply your own app icon rect if you use docerator from a python program. It's easy:

import docerator
# for each size, have a (translation_x, scale_x, translation_y, scale_y) tuple:
acornRects = {
     16: ( -0.3762,   0.5597,  -0.1590,   0.4453),
     32: ( -0.5967,   0.5431,  -0.3632,   0.5662),
    128: ( -3.0761,   0.6025,  -2.0524,   0.6073),
    256: ( -6.3940,   0.6081,  -4.3167,   0.6117),
    512: (-13.0499,   0.6110,  -8.8612,   0.6132),
}
docerator.makedocicon(appicon='/Applications/Acorn/Contents/Resources/Acorn.icns', text='Acorn', rects=acornRects)

You can pass a comma-separated string for text, or a dict for more control.

If you want to create several icons, use the plural version:

import docerator
rects = ...  # as above
docerator.makedocicons(appicon='myapp.icns', texts=['PNG', 'JPG'], rects=rects)

If you already have a document icon but want to recreate it with docerator (because you want crisp small-sized icons for example), you can use the flow program that comes with docerator. It takes your current docicon and appicon and automatically computes the right rects for your docicon (using the Lukas-Kande computer vision algorithm (PDF)). In fact, the acornRects dict in the example above was created by running

./flow /Applications/Acorn.app/Contents/Resources/AcornDocIcon.icns \
    /Applications/Acorn.app/Contents/Resources/Acorn.icns 

in a temporary directory (flow creates lots of temporary files).

Real-World Use

Acorn's new document icon was created by docerator.

MacVim uses docerator to automatically create around 50 docicons every time MacVim is compiled. MacVim contains code to make docerator render custom 16x16 document icons:

Growl's new document icons were created by docerator.