Animation merger

Animmerger stitches 2D images together into either a static image or an animation, while attempting to preserve a global frame of reference (static background).
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, a set of different pixel methods, and a simulated infinite 2D canvas — a 2D canvas that extends infinitely to all four directions (well, as infinite as 32-bit integers can get…)

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

An alternative implementation of "average" is also provided: "tinyaverage" (option -A). It requires less memory to store, but is less accurate to calculate.

If you want the color averages to be calculated through the YUV colorspace rather than the RGB colorspace, add the --yuv option (not supported by tinyaverage).

The "actionavg" method attempts to fix the faintness problem with "average" method by keeping track separately of the background (using the "mostused" method) and adding it only once to the average of moving actors.

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

If you want the color averages to be calculated through the YUV colorspace rather than the RGB colorspace, add the --yuv option.

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

The "last" method is a simpler implementation of the MostUsed 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

The "first" method is analogous to "last". It shows whatever first appeared in a particular pixel location.

The turtles are distorted, because they moved while the screen scrolled.
It is the same effect as if you move the paper in a desktop scanner during the scanning.

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

The "solid" method is an experimental light-weight replacement to the "mostused" method. It simply ignores anything that moves and retains whatever stays still for the longest time.
Unlike "mostused", it does not sum separate appearances together; it only finds the maximum length of consecutive sameness.

As seen here, it has shortcomings, too.

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

The "firstnmost" method is analogous to "first" and "mostused"; it chooses the most common pixel of first N pixel values. Set N with the --firstlast (-f) option.
If N is 0, instead gets last uncommon pixel.
If N is negative, using least common values rather than most common.

Most common of first 4:

Most common of first 10:

Most common of first 16:

First uncommon:

Least common of first 10:

Produced with commandline:
# for f in 4 10 -10 16 0; do
#   animmerger -pF -f$f snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
#   mv tile-0000.png demo/method-Ff$f.png
# done

The "lastnmost" method is analogous to "last" and "mostused"; it chooses the most common pixel of last N pixel values. Set N with the --firstlast (-f) option.
If N is 0, instead gets last uncommon pixel.
If N is negative, using least common values rather than most common.

Most common of last 10:

Last uncommon:

Least common of last 10:

Produced with commandline:
# for f in 4 10 -10 16 0; do
#   animmerger -pL -f$f snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
#   mv tile-0000.png demo/method-Lf$f.png
# done

The "least used" method is analogous to "most used".
It can be used to find graphical artifacts and teleporting actors, but for the most part, the output is not very useful.

Produced with commandline:
# animmerger -pe snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
# mv tile-0000.png demo/method-e.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 MostUsed 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 --gif -pc snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
# 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 background for ChangeLog is normally generated with the MostUsed method, but it can be explicitly controlled with the --bgmethod0 and --bgmethod1 options.
Here is how the above animation (HUD-less) looks like with --bgmethod0 first --bgmethod1 last:

Note that the --bgmethod0 and --bgmethod1 options only affect the ChangeLog method, and only when motion blur is not used.

The changelog method also supports motion blur. Use the --motionblur (-B) option to set it. Value 0 disables motion blur (default: 0).

Blur length 1:

Blur length 4:

Blur length 20:

Produced with commandline:
# for b in 1 4 20;do
#   rm tile-*.png tile-*.gif
#   animmerger --gif -B$b -pc snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
#   gifsicle -O2 -o demo/method-cB"$b".gif -l0 -d3 tile-*.gif
# done

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 (94895 bytes):

10 frames (66738 bytes):

4 frames (40372 bytes):

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

It is also called "loopinglast" mode (option -s) to differentiate from "loopingavg".

The loopinglog method also supports motion blur. Use the --motionblur (-B) option to set it. Value 0 disables motion blur (default: 0).

The "loopingavg" method combines the "loopinglog" and "actionavg" methods. Use the -l option to set the loop length in frames.
The most important difference to "loopinglog" is that overlapping action is averaged rather than explicitly choosing one of the acting pixels.
It looks slightly better, but may require GIF palette reduction.
In comparison, "loopinglog" only uses pixel colors present in the original images.

30 frames (file size depends on selected palette size):

10 frames:

4 frames:

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

If you want the color averages to be calculated through the YUV colorspace rather than the RGB colorspace, add the --yuv option.
In most cases, the difference is neglible though.

The loopingavg method also supports motion blur. Use the --motionblur (-B) option to set it. Value 0 disables motion blur (default: 0).

Loop length 30 frames, blur length 20:

Loop length 30 frames, blur length 20, with YUV calculations:

Loop length 30 frames, blur length 20, with YUV calculations, and diversity-quantized palette of 16 colors:

Loop length 10 frames, blur length 4:

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

Method name	Static or animated	Composes new colors	Obeys YUV option	Memory size per pixel*	Primary use
First	Static	No	No	4	Maps
Last	Static	No	No	4
FirstNMost	Static	No	No	As ChangeLog
· FirstUncommon	Static	No	No	As ChangeLog
· FirstNLeast	Static	No	No	As ChangeLog
LastNMost	Static	No	No	As ChangeLog
· LastUncommon	Static	No	No	As ChangeLog
· LastNLeast	Static	No	No	As ChangeLog
MostUsed	Static	No	No	12…16 + 6×number of unique colors	Maps
LeastUsed	Static	No	No	As MostUsed
Solid	Static	No	No	12	Maps
Average	Static	Yes	Yes	16
Tinyaverage	Static	Yes	No	8
ActionAvg	Static	Yes	Yes	As MostUsed
ChangeLog	Animated (movie)	If blur	For blur	12…16 + 8×number of content changes	Animations
LoopingLog	Animated (loop)	If blur	For blur	As ChangeLog
LoopingAvg	Animated (loop)	Yes	Yes	As ChangeLog	Fun

*) These numbers are estimates. Actual memory size per pixel depends on the exact selection of pixel methods requested and the memory allocation overhead. Animmerger strives to always select the smallest combination of pixel methods (memoryconsumptionwise) that can implement all the requested methods.

Masked areas can be removed with a number of different methods. To best demonstrate them, I added an extra huge mask in the middle of the image.
It is best seen in the "black" masking, below.

These images were produced with this commandline:
# for method in censor hole interpolate extrapolate; do
#   rm *-*.gif *-*.png
#   ./animmerger -r4,4 --mvrange 0,0,4,0 --bgmethod0=first --bgmethod1=last \
#   -u$method -p* snaps/*.png \
#   -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF \
#   -m3,128,250,72 -m0,73,256,2
#   gifsicle -O2 -o demo/mask-$method.gif -l0 -d3 ChangeLog-*.gif
#   cp -p Average-0000.png demo/mask-$method.png
# done

This method shows clearly which areas were affected by the mask. Specifically, the HUD, and a huge rectangle, and a narrower line extending from the very left edge to the very right edge of the screen at all times, effectively blocking the contents of the entire scanline from ever being seen.

Animation:

Averaged:

This method is what animmerger does by default. The transparent regions are simply treated as holes; there is no content on the affected areas. If the hidden content becomes available when the camera moves, then those pixels are recorded.

Animation:

Averaged:

This method removes the content with a circular blur pattern. The method is almost identical to the delogo filter that can be used in MPlayer to remove a tv station logo from video. Content that coindices with the removed part is replaced with interpolated surrounding pixels; original pixels of the affected area are not sampled.

Animation (palette-reduced and dithered with -Qd,16 in order to make the 1.5 MB GIF file smaller):

Averaged:

The extrapolate filter tries to extrapolate the content of the masked areas by detecting repeating tile patterns outside the masked area, and extrapolating those patterns over the masked area. The results of this method vary a lot from frame to frame, so it is not very suitable to be used over large unknown areas. For small areas, it works nicely.

Note that this algorithm is rather slow on large areas like this.

Animation:

Averaged:

Animmerger can create its output files in GIF or PNG format, regardless of whether you are creating an animation or not.
GIF files however are limited to a palette of 256 colors, while it is possible that animmerger creates images with more colors than 256. Therefore, the colormap must be reduced before the GIF image can be generated. animmerger supports a number of different color reduction methods, which are listed below.
If no method is chosen, whatever is libGD default will be used.

The images in this section were generated by making a 30-frame LoopingAvg animation with blur length of 20, rendering it with different palettization parameters and picking the 11th frame.

The exact commandline to produce the images was:
# for m in m d b o q; do
#  for q in 2 4 8 16 32 64 128; do
#   rm tile-*.png tile-*.gif
#   dither="-Dy2 --dr 2 --dc 16"
#   if [ $q -gt 16 ]; then dither="-Dy1i --dr 1.2 --dc 16"; fi
#   animmerger --gamma 2.2 $dither \
#           --gif -Q"$m",$q -B20 -l30 -pv snaps/*.png \
#           -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF
#   gifsicle -O2 -k128 -o demo/method-vl30yB20Q"$m"$q.gif -l0 -d3 tile-*.gif
#   convert tile-0010.gif -quality 100 demo/quant-"$m"$q.png
#  done
# done

Palette reduction methods can be chained in order to take benefits of the differently-appearing strengths of the different methods, but in this test set, each method was used alone.

When palette reduction methods have been explicitly selected, animmerger always uses an ordered-dithering method (crosshatch artifacts) to optimize the rendering. This is better for animation than other methods such as Floyd-Steinberg are, because the dithering patterns do not jitter between frames.

Heckbert median-cut quantization method repeatedly splits the palette into two roughly equal-proportion sections ("low" and "high" part in any of red/green/blue channels) until the desired number of sections have been generated; the palette is generated by averaging the values in each section together.
It is good at generating relevant palettes, but at smallest palette sizes, it suffers from a blurring problem.

4 colors:

8 colors:

16 colors:

32 colors:

Diversity quantization method alternates between choosing the most popular remaining color in the image for a "seed" and choosing of the remaining colors the one that is most distant to any colors selected so far.
The result is generally a very good representation of the original image's colors.
At the smallest palette sizes, the colors are of course off, but the contrast is still sharp.

4 colors:

8 colors:

16 colors:

32 colors:

The blend-diversity method is a variation to the diversity method; after the colors have been chosen, they are merged together with the remaining colors that are most similar to the chosen one.

4 colors:

8 colors:

16 colors:

32 colors:

The NeuQuant method, developed by Anthony Dekker in 1994, uses a Kohonen self-balancing neural network to quickly come up with an optimized palette. It is especially powerful with optimizing smooth gradients, such as the motion-blur trails in this pictureset.

4 colors:

8 colors:

16 colors:

32 colors:

Dithering is a technique by which the human eye can be tricked into perceiving more colors than there actually is, by putting different-colored pixels adjacent next to each others in varying proportions.

Animmerger knows a number of different dithering algorithms, including a set of dithering algorithms devised by Joel Yliluoma. These algorithms are categorised as an ordered, positional, patterned dithering method that is very well suited for animations, and often even more eye-pleasing than the random noise patterns generated by error diffusion dithers.

Animmerger's dithering can be controlled with the following parameters:

--ditherror, --de <float>

Color error spectrum factor is a parameter that controls how strongly the ditherer will attempt to find the next color value to mix with the previous ones. A value of 0 will effectively disable dithering, and a value of 1 is the algorithm working at full power. Values in the between have effect that depends on the particular palette.

--dithmatrix, --dm <x>,<y>[,<time>]

Bayer matrix dimensions define very straightforwardly the visual appearance of the dithering. A small matrix appears very regular and a larger matrix looks more random. The matrix dimensions should generally be powers of two in both directions, though this is not required.
An additional third dimension can be specified: This dimension is time. If dithering along the time axis (temporal dithering) is requested, then flickering will be used to achieve the desired average colortone over time rather than over spatial distance. The value is the number of frames over which to extend the dithering. A negative value can be given; in this case, the dithering will be performed from the higher-order bits (most prominent) rather than the lowest-order bits (least prominent).

--dithcount, --dc <int>

Sets the maximum number of palette colors to mix when attempting to reproduce a color. Value should be at least 1 (1 disables dithering) and at most the size of the dithering matrix.

--dithcombine, --dr <float>[,<combinationlimit>[,<changeslimit>]]]

The contrast parameter is used to control how palette colors are pre-mixed as candidates for the in-render color chooser to use. A larger value will produce more pre-mixed candidates (with a coarser appearance), a smaller value will inhibit these candidates.

Generated with:
# for gamma in 0.1 0.2 0.5 1.0 1.5 2.0 2.2 2.5 3.0 10.0; do
#   animmerger gamma_in.png -Q../cga0-pal.gif --dm 8x8 --dc 64 --gamma $gamma
#   mv tile-0000.png demo/gamma-$gamma.png
# done

Note that animmerger's gamma correction algorithm is somewhat disputable. For instance, although the former example looks good, if we try the same with the EGA palette, where mid-gradient values (0%, 33%, 66% and 100% white) actually exist in the palette, we get the latter, odd-looking result.

Conclusion: Your mileage may vary.

To demonstrate dithering, let us consider this example picture. It has been assigned a customized palette to go with it.

It is a subset (cropped portion) of a larger picture seen on the page where the algorithm is explained in detail, hence the odd inclusion of blue in it.

The error spread factor provides a very fine-grained control over the final appearance of the dithered image. Though the upper limit of the value is 1.0, higher values can be used for artistic purposes.

The matrix shape directly controls the manner in which the different-color spots are dispersed. The temporal dithering option can be used for improving the perceived quality of colors (at the cost of flickering), and for artistics effects.

Unless the --dithcount (--dc) option was given manually, setting the matrix size also sets the former. (To the size of matrix, or 32, whichever is smaller.)

Note that when making GIF animations, you usually do not want flickering, because it will inflate the file sizes at a very high rate. With H.264, it is perfectly fine, especially if you use the frameref setting. (No, Animmerger does not have H.264 output. I was just referring to the hypothetical scenario that you would use animmerger to create a video that will be encoded in H.264.)

The candidate count option directly controls how colors are mixed together in the dithering process. A higher value always results in higher quality, however, there is no sense in making the value larger than the matrix size is. Also, a combination of a large matrix and a small count can be used to simulate a small dithering matrix.

Also note that the rendering speed is directly proportional to the number of dither color candidates generated. (It also depends on the size of the palette of both input and output images, and on the dither contrast limiter.)

Specifying 0 for the contrast usually works nicely, especially if the palette is good, but sometimes you will have to put a higher value there. Such situations may happen if the palette contains a combination of colors that produces the exact color required in the input picture when mixed, but also a closeby color that is not exact. Without the aid of the contrast option, the ditherer will not find the combination and will just use the closerby color that might not look as good. Overdoing it, however, will result in a lot of overly sharp local contrast, which looks mostly bad. Animation is shown in the last frame for the sake of demonstration, because it improves the spatial color resolution.

Note that using nonzero --dr with --gamma that differs from 1.0 is currently broken. Please avoid that combination.

In dithering, a color compare algorithm is used. The same algorithm is also used in the diversity and blend-diversity quantization options. Animmerger supports a few different algorithms for comparing colors.

Here are two example truecolor* pictures, and the web-safe palette.

I quantized it using the websafe palette and dithered using --dm 1x1 --dc 1 --dr 0 (i.e. no dithering), and varied the color compare method using the --deltae option.

These tests intend to show how each color-compare method identifies colors that most closely match the original. Note: I used gamma correction for these images. Consequently, I disabled the --dr option because these do not mix well together.

Produced with commandline:
# for e in rgb cie76 cie94 cmc ciede2000 bfd; do
#   # Render the chroma&luma test image without dithering:
#   animmerger deltae_base.png -Qdeltae_pal.png -vv \
                  --dm=1x1 --dc=1 --dr=0 --deltae=$e --gamma 2.0
#   mv tile-0000.png demo/deltae_$e.png
#
#   # Create four-frame temporal-dithered animation of the testcard:
#   animmerger tksmall{,,,}.png --noalign -Qdeltae_pal.png -vv \
                  --dm 1x1,-4 --dc 4 --deltae=$e -pc --gif --gamma 2.0
#   gifsicle -O2 -o demo/tk-$e.gif -l0 -d4 tile-000[0-3].gif
#
#   # Create an average of those four frames:
#   animmerger tile-000[0-3].gif -pa --noalign
#   mv tile-0000.png tk-a4-$e.png
# done

*) It is truecolor, but it is also dithered. I found 24-bit RGB inadequate for this picture in preventing hard edges in smooth gradients, so I dithered it for this webpage. The input to these tests was undithered.

Three pictures are shown: The two testcases rendered with this color filter, and the third is a four-frame average of the preceding picture, showing exactly which average color perception the dithering was getting at.

RGB. Calculated as a simple euclidean difference: √(ΔR² + ΔG² + ΔB²)

It is very fast and does not usually cause any nasty surprises. However, in dithering, it usually is overly conservative and fails to account for psychovisuals, i.e. when some color is "close enough", and consequently, fails to achieve a pleasing result.

CIE L*a*b*, where delta-E calculated as a simple euclidean difference: √(ΔL² + Δa² + Δb²)

It is fast and very often an improvement to RGB.

CIE L*a*b* with C_ab=√(a²+b²),
where delta-E calculated using a much more refined formula (CIE94):
√(ΔL² + ΔC_ab²÷S_C² + ΔH÷S_h²)
with ΔH = (Δa² + Δb² − ΔC_ab²),
and S_C = (1 + 0.048×√(C_1ab×C_2ab)),
and S_h = (1 + 0.014×√(C_1ab×C_2ab)).

Note: Animmerger uses the deltaE squared rather than the deltaE itself, which is why the formula may seem different to what it is in reference material. (There may still be genuine errors though.)

CIE L*a*b* based extremely complicated formula called CIEDE2000.

CIE L*a*b* based quite complicated formula called CMC l:c, with l=1.5 and c=1.0.

Interestingly, this operator seemed to have a huge issue with black colors; animmerger has a special workaround for that problem, though the darker green region looks weird too. In general, this has the appearance of being the weakest of all of these operators. Use it only if you are looking for a specific type of special effect.

CIE L*a*b* based extremely complicated formula called BFD l:c, with l=1.5 and c=1.0.

RGB to LAB conversions are subject to a lot of perception based science. A concept of "illuminant matrix" plays a significant role here.

Animmerger knows three illuminant matrices:

CIE E illuminant: 0.488718, 0.176204, 0.000000 0.310680, 0.812985, 0.0102048 0.200602, 0.0108109, 0.989795

Adobe D65 illuminant: 0.576700, 0.297361, 0.0270328 0.185556, 0.627355, 0.0706879 0.188212, 0.0752847, 0.99124

Unidentified D65-based illuminant, found in Imagemagick: 0.412453, 0.357580, 0.180423 0.212671, 0.715160, 0.072169 0.019334, 0.119193, 0.950227

Animmerger uses illuminant #3 for CIE76, and illuminant #1 for all other CIE based compare methods, because illuminants #2 and #3 have serious issues with blue and purple tones when any other compare method than CIE76 is used (specifically, they suggest that black is the overwhelmingly best substitute for those colors).

Animmerger converts a RGB value into CIE L*a*b* and CIE L*C*h* using the following formula:
X = (i0 × R + i3 × G + i6 × B) ÷ 255 ÷ (i0+i1+i2)
Y = (i1 × G + i4 × G + i7 × B) ÷ 255 ÷ (i3+i4+i5)
Z = (i2 × B + i5 × G + i8 × B) ÷ 255 ÷ (i6+i7+i8)
f(v) = v ≤ 6329−3 ? 4÷29 + v × 2926−23−1 : v1÷3
L = 4×29 × f(Y) - 42
a = 500 × (f(X) - f(Y))
b = 200 × (f(Y) - f(Z))
C = √(a² + b²)
h = atan2(b, a)
Where i0…i8 are the values from the illuminant matrix.

Mathematical transformations can be applied to individual pixels of the resulting image, using the --transform option.

In this example, the overall color tone of the image was changed and a lens flare effect was added:

Produced with:
# ./animmerger --gif snaps/*.png -m0,8,256,16,020202,A64010,D09030,006E84,511800,FFFFFF \
#         -pv -l25 --deltae=2000 -Qq,36 -Qd,32 --dr 0 --dm 8x8 --dc 32 -Dky -vv \
#         --transform "luma:=r*.299+g*.587+b*.114; px:=238;py:=135;" \
#         --transform "xy:=(abs(x-px)*abs(y-py)/200^2);" \
#         --transform "rad:=hypot(x-px,y-py)^1.3/(1.8+0.02*cos(((frameno/25+.5)%1)^2*-2*pi));" \
#         --transform "v:=luma+(300-min(300,rad))+(200-min(300,(xy+1e-6)^0.6*7e3));" \
#         --transform r="r*v/(255*0.299*2.2)" \
#         --transform g="g*pow(v,1.2)/(255*0.587*3.1)" \
#         --transform b="b*v/(255*0.114*1.7)+50*(1.35+cos(1+(y+x*.2)*pi/100))"
# gifsicle -O2 -o demo/trans.gif -d3 -l0 tile-????.gif

Parallax motion is bad. When animating video game content, please ensure that all background layers are synchronized. Note that this will likely require you to hack the emulator that is used to produce the video frames.

If different background layers are moving at different speeds with respect to the camera, animmerger will sync into one of them (probably the one that occupies the largest screen area), and the rest will appear to be moving with respect to the chosen background.

Example:

This scene is from Super Mario World. The HUD layer is disabled, but otherwise it is an intact animation. The palette was reduced and fps halved to make the file slightly smaller for web distribution.
You can easily see the problem with parallax motion: Sometimes the image alignment syncs to the platforms, sometimes it syncs to the stalactite background. When it syncs to the platforms, the other background can be seeing moving as a distinct layer.	In this version, the background layers move in unison with respect to the camera. As such, the image alignment is perfect. This was achieved with the following patch to snes9x: --- ppu.cpp~ 2010-08-17 23:46:11.022843689 +0300 +++ ppu.cpp 2010-08-17 22:34:52.000000000 +0300 @@ -416,2 +416,3 @@ PPU.BG[0].HOffset = (Byte<<8) | PPU.BGnxOFSbyte; + PPU.BG[1].HOffset = (Byte<<8) | PPU.BGnxOFSbyte; PPU.BGnxOFSbyte = Byte; @@ -423,2 +424,3 @@ PPU.BG[0].VOffset = (Byte<<8) | PPU.BGnxOFSbyte; + PPU.BG[1].VOffset = (Byte<<8) | PPU.BGnxOFSbyte; PPU.BGnxOFSbyte = Byte; @@ -429,3 +431,3 @@ case 0x210F: - PPU.BG[1].HOffset = (Byte<<8) | PPU.BGnxOFSbyte; + //PPU.BG[1].HOffset = (Byte<<8) | PPU.BGnxOFSbyte; PPU.BGnxOFSbyte = Byte; @@ -436,3 +438,3 @@ case 0x2110: - PPU.BG[1].VOffset = (Byte<<8) | PPU.BGnxOFSbyte; + //PPU.BG[1].VOffset = (Byte<<8) | PPU.BGnxOFSbyte; PPU.BGnxOFSbyte = Byte;

The commands used to produce these animations were:
# rm tile-*.gif; animmerger -v -r12x12 -bl -pc -a -4,-3,6,9 pano5/*.png
# rm tile-???[13579].gif # Delete 50% of frames to reduce fps in half
# gifsicle -O2 -o demo/pano5-cl.gif --crop 8,8+480x400 --use-colormap smwpalette.gif -l0 -d6 tile-????.gif
# rm tile-*.gif; animmerger -v -r12x12 -bl -pc -a -4,-3,6,9 pano5b/*.png
# rm tile-???[13579].gif # Delete 50% of frames to reduce fps in half
# gifsicle -O2 -o demo/pano5-fl.gif --crop 8,8+480x400 --use-colormap smwpalette.gif -l0 -d6 tile-????.gif

The palette file was customized by hand, by taking a representative snapshot of the movie, and then progressively merging near-identical entries in the colormap in GIMP manually until only the minimal set of unique colors/tones remain.

The image aligning engine is confused by anything that globally changes the screen brightness. This includes any pain-red-tinting, white-explosion flashes, fog clouds, etc. Please try to avoid them.

Example:
TODO: Add successful Super Metroid animation

TODO: Add example of how image alignment suffers when using the power bomb in Super Metroid

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

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

Merges (stitches) animation frames together.

General options:
 --help, -h
     Short help on usage. Use --longhelp or --fullhelp for more/all options.

Canvas affecting options:
 --method, -p <mode>
     Select pixel type (average/actionavg/mostused/changelog/loopingavg)
     See full help for details.
 --looplength, -l <int>
     Set loop length for the LOOPINGxx modes

Image aligning options:
 --noalign
     Disable automatic image aligner. Useful if you only want to
     utilize the dithering and quantization features of animmerger,
     or your images simply don't happen to form a nice 2D map.
     This option is identical to --forcealign 0-N=0,0 where N=movie length.

Output options:
 --output, -o <filename/pattern>
     Output to given filename. The filename may also be a pattern. (See longhelp for details.)
 --quantize, -Q <method>,<num_colors> or <file> or <R>x<G>x<B>[x<I>]
     Reduce/load/synthesize palette. See full help for details.
 --dithmethod, -D <method>[,<method>]
     Select dithering method(s) (ky/y2/floyd). See full help for details.
 --gamma [=<value>]
     Select gamma to use in dithering. Default: 1.0

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.

• pngout for making PNG files considerably smaller.
• gifsicle for creating and optimizing GIF animations

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