Tools Documentation

Framage 1.02

Framage is a tool which converts large bitmap images containing multiple animation frames into multiple images each containing a single frame of animation. The utility has a reasonably intelligent algorithm to detect the frames in the large image, so it is not necessary to position the frames particularly carefully - as long as there is clear rectangular area occupied by each subframe, the utility should be able to catch each of the individual frames OK.

It has been fairly typical in the industry for animation artwork to be delivered as a single file containing all animations in the one image. This utility automatically detects the boundaries around these animations and converts each animation frame to a new image file.

History

Usage

This tool is DOS command-line driven. It takes graphics data (BMP, PNG, JPG) as input, and outputs multiple BMP images containing frames subdivided from the input file(s).

Command Line

Items enclosed in square brackets [...] are optional, and may appear zero or more times. Switches are described below. file is a graphics file of BMP, PNG, or JPG format. Wildcards ? and * can be used in the file name. All matching files are processed.

Command Line Switches Switch Function Default -bR,B,G Set the transparent colour (default is to use colour 0 of palette, whatever that is). By setting the transparent colour (8-bit Red, Green, Blue - eg: white= -b255,255,255) you are telling the tool which exact colour in the image is transparent. 0,0,0 -e Select the 'elegant' optimisation method, which detects non-overlapping frames. The two optimization algorithms are discussed below. connected-pixel method

Input

Input files may be .BMP, .JPG, or .PNG format.

Bugs

None known. If you'd like to report one, or suggest something, then please let us know!

Algorithm

There are two detection methods. The default method detects frames as 8-connected pixel areas in the original image. An 8-connected area is all those pixels which can be grouped by reason that they are connected to all others in the group through a non-transparent pixel in any of the 8 immediate pixels surrounding any pixel. That sounds complex - but in essence it means that a frame must be a solid - no extra fluffs of dust or trailing pixels are possible - these will be detected as different frames.

The '-e' switch causes detection to be performed using the original 'non-overlapping box' method. This method is quite slow - but the code was very elegant (hence, the -e switch). This detetion method does allow non-connecting pixels in a frame, but requires all frames to have a unique, non-overlapping bounding box of transparency. That is, frames are defined by the detection method's ability to find a non-overlapping transparent rectangle around them. The utility is quite versatile, and will allow non-aligned data - as long as it is not overlapping.

To assist in understanding what this second method is 'seeing', an image mask.bmp is output, clearly showing where the utility has detected frames. If you are finding that only some of the frames in your image are not successfully split up, then the likelyhood is that you have overlapping frame data - though this is sometimes difficult to see.

The default method is the fastest, and works for most cases.

Copyright

The Framage utility and documentation are Copyright ©2001 TwoHeaded Software.

The Framage executable are is supplied "AS IS". TwoHeaded Software disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The authors assume no liability for direct, indirect, incidental, special, exemplary, or consequential damages, which may result from the use of framage, even if advised of the possibility of such damage.

In short, use at your own risk.

Paintlib

Framage uses a public-domain library for reading graphics files. This library (Paintlib) is available at http://www.paintlib.de/paintlib/, and is an excellent package. Highly recommended, and a big thanks to Ulrich.