Hatched from an egg with a controller in hand

It’s often quite useful to pack multiple textures into one image – this can help to improve rendering performance by reducing the number of texture changes needed to draw a scene, or to more efficiently use space on systems that require power-of-two-sized textures.

I need atlasing for sprite the animation system that I’m working on for our Unity game. Here it is as a self-contained Python script because Python is awesome! It was inspired by the method used in this script over at the pygame site, but has a couple of extra features that you might find useful:

import Image
import sys
import optparse
import glob

def Atlas(filenames, outname, size):

    #open all of the images
    ims = [(f, Image.open(f)) for f in filenames]

    #sort by image area
    ims = sorted(ims, key = lambda im : im[1].size[0]*im[1].size[1], reverse=True)

    #Free boxes are empty space in our output image set
    #the freebox tuple format is: outidx, x, y, w, h
    freeboxes = [(0, 0, 0, size, size)]
    numoutimages = 1

    #Full boxes are areas where we have placed images in the atlas
    #the full box tuple format is: image, outidx, x, y, w, h, filename
    fullboxes = []

    #Do the actual atlasing by sticking the largest images we can have into the smallest valid free boxes
    for imageinfo in ims:
        im = imageinfo[1]
        if im.size[0] > size or im.size[1] > size:
            print "Error: image " + imageinfo[0] + " is larger than the atlas size!"
            sys.exit(2)

        inserted = False;

        while not inserted:
            for idx, fb in enumerate(freeboxes):
                #find the smallest free box that will contain this image
                if fb[3] >= im.size[0] and fb[4] >= im.size[1]:
                    #we found a valid spot! Remove the current freebox, and split the leftover space into (up to) two new freeboxes
                    del freeboxes[idx]
                    if fb[3] > im.size[0]:
                        freeboxes.append( (fb[0], fb[1]+im.size[0], fb[2], fb[3]-im.size[0], im.size[1]) )

                    if fb[4] > im.size[1]:
                        freeboxes.append( (fb[0], fb[1], fb[2]+im.size[1], fb[3], fb[4] - im.size[1]) )

                    # keep this sorted!
                    freeboxes = sorted(freeboxes, key = lambda fb : fb[3]*fb[4])
                    fullboxes.append( (im, fb[0], fb[1], fb[2], im.size[0], im.size[1], imageinfo[0]))
                    inserted = True
                    break;
            if not inserted:
                #oh crap - there isn't room in any of our free boxes, so we have to add a new output image
                freeboxes.append((numoutimages, 0, 0, size, size))
                numoutimages += 1

    #now that we've figured out where everything goes, make the output images and blit the source images to the approriate locations
    outimages = [Image.new("RGBA", (int(size),int(size))) for i in range(0,int(numoutimages))]
    for fb in fullboxes:
        outimages[fb[1]].paste(fb[0], (fb[2], fb[3]))        

    #save the output images
    for idx, outimage in enumerate(outimages):
        outimage.save(outname + "-" + str(idx) + ".png")

    #write out an xml file that says where everything ended up
    xmlfile = open(outname + ".xml", "w")
    xmlfile.write("<images>\n")

    for fb in fullboxes:
        xmlfile.write('\t<image name="{0}" file="{1}-{2}.png" x="{3}" y ="{4}" w="{5}" h="{6}" />\n'.format(fb[6],outname, fb[1], fb[2], fb[3], fb[4], fb[5] )) 

    xmlfile.write("</images>\n")
    print ("It all fit into " + str(numoutimages) + " images!")

def main(argv):
    parser = optparse.OptionParser(description='Combine multiple image files into a texture atlas')
    parser.add_option('-s', '--size', help="atlas size (length and width)", dest="size", default=512, type=float)
    parser.add_option('-o', '--output', help="output name", dest="output", default="atlas", type='string')
    (options, arguments) = parser.parse_args()

    if (len(arguments) == 0):
        print "Input file(s) not specified"
        sys.exit(2)

    infiles = []
    for f in arguments:
        infiles.extend(glob.glob(f))
    infiles = list(set(infiles))        

    print "Atlasing " + str(len(infiles)) + " files:"
    Atlas(infiles, options.output, options.size)

if __name__ == "__main__":
    main(sys.argv[1:])

The script takes a collection of images as input, and outputs one (or more) images of a specified square size that contain the input images packed (more or less) tightly. It also spits out an xml file describing the location of all of the subtextures, so that a client program can find them.

The next tech post will bring together this script and the previous timmer/obj maker to create a series of atlases containing the trimmed frames for a series of animations. We’ll have a proper image pipeline yet!

Unity is a great platform. You can get prototypes up and running very quickly, and you can make fancypants 3D worlds with shaders and shadows and all the trimmings. The platorm’s 2D support, however, is practically non-existant. Sure, you can pretty easily constrain your gameplay to a plane, and the included physics engine can be bent into shape to play nice with those constraints, but in terms of asset creation, you’re left to fend for yourself.

So that’s what I’ve been doing. I don’t have a 3d modelling program at home – I’ve used Maya before (years ago), but it’s too expensive for this project, and would be a massive case of overkill anyway.

To fake a sprite in 3D, you usually texture a qua, place it on one of the canonical planes, and then use an orthographic camera to view it. This works great in Unity, but you’re still left having to specify your plane somehow. The built in plane primitive that Unity provides is tesselated into many small triangles to make per-vertex lighting look better. Most 2D games don’t use that type of lighting anyway, so we need a way to make two-poly planes of an appropriate size. When working with 2D sprites it is also handy to specify a per-image registration point. This allows you to align sprites to each other without relying upon them all being the same size, so it saves you texture memory (which can be very important if you have a lot of animation).

I ended up making a simple Python script for converting images to registered and scaled .obj models. I’ve only recently begun exploring Python, and it is quickly becoming my go-to pipeline language – it has a great set of libraries, and offers way more functionality per-line-of-code than more traditional languages. Anyway, here’s the script:

import Image
import sys
import optparse

def trim(im):
    idx = 0
    width = im.size[0]
    height = im.size[1]

    top = height
    bottom = 0
    left = width
    right = 0

    x = 0
    y = 0
    for pix in im.getdata():
        if pix[3] != 0:
            if top > y:
                top = y
            if bottom < y:
                bottom = y
            if left > x:
                left = x
            if right < x:
                right = x

        x = x + 1
        if x == width:
            x = 0
            y = y +1

    box = (left, top, right, bottom)
    cropped = im.crop(box)
    cropped.load()
    return box, cropped

def main(argv):

    parser = optparse.OptionParser(description='Create an obj mesh and a cropped image from an input image file')
    parser.add_option('-s', '--scale', action="store", help="scale", dest="scale", default=1, type=float)
    parser.add_option('-o', '--output', action="store", help="outputname", dest="output", default="output", type='string')
    arguments = parser.parse_args()
    if (len(arguments[1]) != 1):
        print "Input file not specified"
        sys.exit(2)

    scale = arguments[0].scale
    outfile = arguments[0].output
    imagename = arguments[1][0]
    print "Converting image ", imagename, " to 3d billboard model ", outfile ," with scale ", scale
    im = Image.open(imagename)

    width = im.size[0]
    height = im.size[1]

    box, cropped = trim(im)
    cropped.save(outfile+"_cropped.tga")
    p0 = ( box[0] - width/2, -box[3]+height/2 )
    p1 = ( box[0] - width/2, -box[1]+height/2 )
    p2 = ( box[2] - width/2, -box[1]+height/2 )
    p3 = ( box[2] - width/2, -box[3]+height/2 )

    z = 0
    f = open(outfile + ".obj", "w")
    f.write ( 'v %(x)f %(y)f %(z)f\n'% {'x':p0[0]*scale, 'y':p0[1]*scale, 'z':z})
    f.write ( 'v %(x)f %(y)f %(z)f\n'% {'x':p1[0]*scale, 'y':p1[1]*scale, 'z':z})
    f.write ( 'v %(x)f %(y)f %(z)f\n'% {'x':p2[0]*scale, 'y':p2[1]*scale, 'z':z})
    f.write ( 'v %(x)f %(y)f %(z)f\n'% {'x':p3[0]*scale, 'y':p3[1]*scale, 'z':z})

    f.write ( 'vn 0 0 1\n')
    f.write ( 'vt 1 0\n')
    f.write ( 'vt 1 1\n')
    f.write ( 'vt 0 1\n')
    f.write ( 'vt 0 0\n')
    f.write ( 'f 1/1/1 2/2/1 3/3/1 4/4/1\n')

if __name__ == "__main__":
    main(sys.argv[1:])

It takes an image as input, trims it to it’s non-transparent bounding box, and saves out the new image and an optionally scaled .obj file with the right proportions. All you have to do to use it in Unity is to drag both of the output files into your library and associate them with each other. You’ll need to install the Python Imaging Library to make it run.

The next step that I will be working on is a script that will take a series of images, atlas them, and export the size and timing information to an xml file so that you can play an animation in Unity.