Animation merger

Animmerger converts a 2D animation from local-frame-of-reference into global-frame-of-reference. That is, for a movie that follows an actor around (and the background scrolls to follow them), it creates a movie that has a fixed background, and the camera moves around in the scene.

It does this with a motion detection algorithm, and a set of different pixel methods.

As a sample, here is the original animation (712100 bytes). The animation was created literally by taking a screenshot from the NES emulator every frame. (I hacked the emulator to automatically produce a screenshot after every frame.) What follows below, is a list of the pixel methods supported by animmerger, along with example images demonstrating what that pixel method does. The -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF parameter was given to animmerger to remove the HUD that is 256x16 wide and begins at 0,8. The hexadecimal numbers listed are these colors: 020202 A64010 D09030 006E84 511800 FFFFFF This removes the text (white) as well as the blinking coin.

The graphics material comes from Super Mario Bros.
Mario, Super Mario Bros, and The Nintendo Entertainment System (NES) are registered trademarks of Nintendo of America Inc. But you knew that, right?

The "average" method produces a "motion blur" effect of the entire input, reducing it into a single frame.

You can see a faint trace of all animated actors that appeared in the animation. Mario moved very fast so his trace is quite difficult to spot.

Produced with commandline:
# animmerger -pa snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
# mv tile-0000.png demo/method-a.png
# pngout-hard demo/method-a.png

The "most used" method produces what might be the background image for the entire animation.

Note: If there is an actor that sits in a certain location for a long time, it is also recorded.
In this example, there were none though.
This mode does not thus remove all actors, but it does remove anything that wanders around.

Produced with commandline:
# animmerger -pm snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
# mv tile-0000.png demo/method-m.png
# pngout-hard demo/method-m.png

The "last" method is a simpler implementation of the "most used" method, simply recording the last pixel value in any location.

Produced with commandline:
# animmerger -pl snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
# mv tile-0000.png demo/method-l.png
# pngout-hard demo/method-l.png

The "changelog" method records the entire animation (121995 bytes in this example).
It takes considerably less disk space (and is faster to load) than the original animation, because now the background does not scroll.

You see some artifacts in the turtle and in Mario when they appear near the top of the screen. This is because they were behind the HUD (the text "WORLD 8-2" for instance), which was removed.
In the case of the turtle, the turtle's white pixels were also removed, because the HUD removal was based on color as well as coordinates.
Horizontal disappearance of the actors is because of the viewport scrolling past them. They do not exist outside those parameters in the original animation either.

Here is how the animation looks like, if the HUD is not removed. (246643 bytes)

Exteriors, i.e. content outside the "current" viewport of the animation are colored as in the "most used" pixel method.
This is evident in the trails left by the HUD as it scrolls by at different speeds.

Produced with commandline:
# rm tile-*.png tile-*.gif
# animmerger -pc snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
# mogrify -format gif tile-*.png
# gifsicle -O2 -o demo/method-c.gif -l0 -d3 tile-*.gif
The version with HUD intact was created with the same commandline, except with the -m option removed.

The "loopinglog" method records the entire animation, but reuses existing frames. Use the -l option to set the loop length in frames.
The smaller value you use, the shorter the animation is in the number of frames, but the more pronounced is the "lemmings" effect.

30 frames (99755 bytes):

10 frames (73850 bytes):

4 frames (49890 bytes):

Produced with commandline:
# for l in 4 10 30; do
#   rm tile-*.png tile-*.gif
#   animmerger -l$l -po snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
#   mogrify -format gif tile-*.png
#   gifsicle -O2 -o demo/method-ol"$l".gif -l0 -d3 tile-*.gif
# done

animmerger v1.2.0 - Copyright (C) 2010 Joel Yliluoma (http://iki.fi/bisqwit/)

Usage: animmerger [<options>] <imagefile> [<...>]

Merges animation frames together with motion shifting.

 --help, -h             This help
 --mask, -m <defs>      Define a mask, see instructions below
 --method, -p <mode>    Select pixel type, see below
 --bgmethod, -b <mode>  Select pixel type for alignment tests
                        Tip: Use -bl for some memory usage reduction
 --looplength, -l <int> Set loop length for the LOOPINGLOG mode
 --version, -V          Displays version information
 --refscale, -r <x>,<y> Change the grid size that controls
     how many samples are taken from the background image
     for comparing with the input image, for image alignment.
     Smaller grid = more accurate but slower aligning.
     Default: -r32,32
     Set to e.g. -r8,8 if you experience misalignment problems.
 --mvrange, -a <xmin>,<ymin>,<xmax>,<ymax>
     Change the limits of motion vectors.
     Default: -9999,-9999,9999,9999
     Example: --mvrange -4,0,4,0 specifies that the screen may
     only scroll horizontally and by 4 pixels at most per frame.
 --gif, -g              Save GIF frames instead of PNG frames

animmerger will always output PNG files into the current
working directory, with the filename pattern tile-####.png
where #### is a sequential number beginning from 0000.

AVAILABLE PIXEL TYPES

  AVERAGE, long option: --method=average , short option: -pa
     Produces a single image. Each pixel
     is the average of all frames addressing that pixel.
  LAST, long option: --method=long , short option: -pl
     Produces a single image. Each pixel
     records the latest color addressing that pixel.
  MOSTUSED, long option: --method=mostused, short option: -pm
     Produces a single image. Each pixel
     records the color that most often occured in that location.
     Use this option for making maps!
  CHANGELOG, long option: --method=changelog, short option: -pc
     Produces an animation.
  LOOPINGLOG, long option: --methods=loopinglog, short option: -po
     Produces a time-restricted animation.
     Also called, "lemmings mode".
     Use the -l option to set loop length in frames.

DEFINING MASKS

  You can use masks to block out HUD / splitscreens
  so that it will not intervene with the animation.
  To define mask, use the --mask option, or -m for short.
  Mask syntax: x1,y1,width,height,colors
  Examples:
    -m0,0,256,32
       Mask out a 256x32 wide section at the top of screen
    -m0,0,256,32,FFFFFF
       From the 256x32 wide section at the top of screen,
       mask out those pixels whose color is white (#FFFFFF)
    -m16,16,8,40,000000,483D8B
       From the 8x40 wide section at coordinates 16x16,
       mask out those pixels whose color is either
       black (#000000) or dark slate blue (#483D8B)

TIPS

Converting tile-*.png into a GIF animation:
   mogrify -format gif tile-????.png
   gifsicle -O2 -o animation.gif -l0 -d3 tile-????.gif

Converting a GIF animation into individual frame files:
   gifsicle -U -E animation.gif
   animmerger <...> animation.gif.*

animmerger has been written by Joel Yliluoma, a.k.a. Bisqwit,
and is distributed under the terms of the General Public License (GPL).

GNU make and C++ compiler is required to recompile the source code.
libgd is also required.

The official home page of animmerger is at http://iki.fi/bisqwit/source/animmerger.html.
Check there for new versions.

Additionally, the most recent source code (bleeding edge) for animmerger can also be downloaded by cloning the Git repository by:

• git clone git://bisqwit.iki.fi/animmerger.git
• git checkout origin/release -b release
• git checkout origin/master -b master