Sunday, March 24, 2013

Exporting layers from Gimp as PNG files

Gimp for MacOSX is now a "native" (-ish) application, and is a great graphics tool for game developers - especially those who can't afford Photoshop.  I've always used it and wouldn't go for PhotoShop as I know GiMP so well now.

You can create animations in layers and Gimp allows you to preview your animations when you've done them as a bunch of layers, by simply invoking the handy "Animation" option in the menu:  "Filters" > "Animation" > "Playback..." - very nice.

But now how do you export those layers as a collection of separate PNG's so you can import them via TexturePacker into your game?

It turns out there is a handy Gimp plug-in to help you - but installing it is not for the faint-hearted.

Installing Plug-ins for GiMP on Mac OSX

On Windows or Linux the process is comparatively easy and is described in a nice tutorial.  If that article happens to be unavailable the GiMP registry lists a number of others.  On MacOSX where normally things "just work" for some reason its a lot more obscure.

The first insight is to know how to find your plugin folders.  Use the Preferences menu in GiMP to find the Folders item and choose "Plugins":


I didn't use the one for just my user name because I wanted the changes in GiMP to be available to anyone using the GiMP install on this computer.  Also it saves me a step as I don't have to create that folder.  I used the GiMP internal folders.  It also has the advantage that if I copy that GiMP to another machine, its plugins go with it.  Nice.

The second thing to know is that there is a laundry list of different types of things that you can install into GiMP, and this makes things more complex for the GiMP automation newbie.  You have "scripts" which are small helpers that can automate what GiMP already knows how to do.  Then you have "plugins" which are larger actual programs which extend GiMP's functionality.  And then there is modules, brushes and the list goes on.

Confusingly enough scripts are written in scheme, but if you want to write a script in python, that is considered a plugin.  Why?  Because the GiMP authors decided it would be so.  In any case if you want to install the export_layers Python script, you have to install it in the plugins folder.

Also since it is a plugin, it has to "look" like the other plugins which maybe complied C program binaries and so on - in other words it has to be executable.  If it isn't then it won't show up when you restart GiMP.  And also - note - restarting GiMP is required, since this is a "plugin": you cannot get it to show up by selecting the "Refresh" option from the script-fu menu in GiMP.

So first step - shut down GiMP.

On MacOSX using the Terminal its then an easy 3 step process:

cd ~/Desktop
curl -O http://gimp-registry.fargonauten.de/files/export_layers-0.6.py.txt
chmod a+x export_layers-0.6.py.txt
mv export_layers-0.6.py.txt /Applications/Gimp.app/Contents/Resources/lib/gimp/2.0/plug-ins/export_layers

If you have problems using the Terminal I really strongly suggest that you start getting over them.  Seriously.  You're missing out on a lot of what Mac has to offer - all the power of Unix just a few keystrokes away.  It's much faster and much easier to capture the process to repeat or modify it.  In some cases the Terminal is the only way to do things.

I use a mixture of UI dragging-and-dropping and always have the Terminal handy to do things that the Terminal is great for.  If your Terminal is not already running, type <cmd>-<space> in Finder and then type "Term" to get hold of it with Spotlight, then press Enter.  With your fingers on the keyboard you're ready for the Terminal to do your bidding.

Let me demystify the above a bit for those of you not keen on the Terminal:

  • First I change directory to the Mac desktop - we're going to temporarily store the downloaded plug-in there. 
  • Next we use the curl command that downloads stuff
    • I use the -O (that's a capital Oh) to say that the output file should be named 
      • curl will call it after what ever it was on the server I got it from.  
    • Try typing "man curl" to find out more about curl - its a handy tool
  • Then the script has to be made executable with the chmod command
    • if you've managed to get the Python script in the right folder but it still does not appear in GiMP - you probably missed this step.
  • Finally copy the script into place.

To do most of all this graphically is possible, but its a pain.  You'll need to
  • Go to the export_layers plugin web page and right-click on the link to download it to your Desktop.
  • Now you'll need to make the file executable
    • I know of no way to do that apart from the command line - so you'll need to open the Terminal for that.  
    • See the above "chmod" command, and first cd to wherever you downloaded the file to.
  • Click on the downloaded file and rename it to export_layers
  • Now go back to Finder and open two windows.
  • In one, navigate to your Gimp program in the Applications folder, right-click and
    • choose "Show Package Contents"
    • the Finder window will change to a view of the inside of the GiMP application bundle.
  • Navigate down to through these folders
    • Contents > Resources > lib > gimp > 2.0 > plug-ins
  • In the other window navigate to your desktop
  • Drag-n-drop the executable export_layers into place in the plug-ins folder in the other Finder window
Now when you restart GiMP you will find that you have a new menu option under the "File" menu with "Export Layers" > "as PNG" which will do what you need. Note you may find some oddness/bugginess with where it drops the generated files. If that happens, use Spotlight to find them - in my case they were dropped into my home folder.

Bonus Content

There are a bunch of Mac file name changer apps out there. If you're a Terminal master you don't need 'em.

After running the file export my original sprite sheet called "process-working.xcf" had resulted in a bunch of weirdly named files as a result of the Export Layers command. The names were like "process-working_xcf-working-1.png" - where the first part was the file name and the second parts were all the layer names.

for f in *; do g=${f#process-working_xcf-}; do mv -v $f $g; done

This command will strip off the leading characters "process-working_xcf-" part and just leave the layer names. The -v just gives verbose output so you can see what it's doing. You'll need to cd into the directory where the files are located before running it.

This is using the Terminal (well, the Bash shell's) ability to do substring mangling. To find out more at the Terminal, type "man bash" and then a forward slash "/" and then "substr". Press enter a few times until it gets to the stuff with the curly braces. As explained there you can use the % instead of # do strip stuff off the end of the string instead of the beginning. For more complex things you can go from just using to f and g, to h and j as well - and so on - successively picking apart the string as you go.

When experimenting with this stuff it pays to preview your command before you run it. You can do that by prefixing it with "echo" like this:

for f in *; do g=${f#process-working_xcf-}; do echo mv -v $f $g; done

Then you'll get a nice listing of all the "mv" commands that would be run, and you can inspect them to make sure your substring mangling did what you expected. Have fun!