# GIFs in LaTeX
Using `GIFs` in `LaTeX/Beamer` can add animation to presentations, making them more engaging and visually appealing. Unfortunately, `LaTeX` does not seem to support `GIFs` natively. But it's possible to split a `GIF` into several images (frames) which are then uesd to create an animation. 

## Statement of Need
So that I can have fancy GIFs in my slides.

## Tools to Convert `GIFs` to Images

A useful tool is [ImageMagick](https://github.com/imagemagick/imagemagick), a free and open-source software for editing and converting image files. One of its features is to help create a GIF animation sequence from a group of images. It can also reverse this by creating images (e.g., `PNG` files) from a `.gif` GIF file.

To set up `ImageMagick`, see its [download guide](https://imagemagick.org/script/download.php). `ImageMagick` is available from packages like `APT` and `Brew`. 
```bash
$ sudo apt install imagemagick
```
(For Windows, a seemingly undocumented but easy way to set up is to use [`Chocolatey`](https://community.chocolatey.org/packages/imagemagick.app) --- `choco install imagemagick.app`.)

Alternative solutions here are online websites like [cleverpdf](https://www.cleverpdf.com/gif-to-png)'s gif-to-png converter.

<div class="admonition note">
  <p class="admonition-title">Other solutions</p>
    I have also tried other online solutions, but they usually do not work, giving weird behaviors like having only the first frame in the sequence correctly extracted while all remaining frames in the sequence are blacked out.
</div>


## Converting `GIFs` to Images

<figure>
  <a href="https://www.autodesk.com/research/publications/same-stats-different-graphs#:~:text=two%20decimal%20places.-,The%20Datasaurus%20Dozen,a%20picture%20of%20a%20dinosaur." target="_blank"><img src="AllDinosAnimated.gif" alt="Awesize gif by Matejka and Fitzmaurice"></a>
  <figcaption class="figsource">(Source: Matejka and Fitzmaurice)</figcaption>
</figure>

To convert a `GIF` file (for example, the one above) to a sequence of `PNG` using ImageMagick
```bash
$ magick convert -coalesce something.gif something.png
```
where `something.gif` is the `gif` file, and `something.png` is the output file(s) in `PNG`. The output is a sequence of *ordered* `PNG` files---e.g., something-0.png, something-1.png, something-2.png, ....
These sequences, combined in that order, would give the original `GIF` animation.

<div class="admonition tip">
  I found it neater first to prepare a folder for the `PNG` images (e.g., `mkdir png-sequences`) and then do<br>
  <code>
    $ magick convert -coalesce something.gif png-sequences/something.png
  </code>
  so that the sequences of images (can be as large as a few hundred) are all contained in one folder.
</div>

## Recovering Original Animation Speed
ImageMagick also helps recover properties about the `GIF`
```bash
$ magick identify something.gif
```
```text
something.gif[0] GIF 480x480 480x480+0+0 8-bit sRGB 128c 0.016u 0:00.011
something.gif[1] GIF 480x480 480x480+0+0 8-bit sRGB 128c 0.016u 0:00.015
something.gif[2] GIF 480x480 480x480+0+0 8-bit sRGB 128c 0.016u 0:00.015
...
```
showing frames and their corresponding resolution, aspect ratios, color spaces, timing, etc.

To get the frame rate
```bash
$ magick identify -verbose something.gif | grep 'Delay'
```
```bash
Delay: 10x100
Delay: 10x100
Delay: 10x100
...
```
So here, the frame rate is 10 frames per second.


## Embedding `GIFs` in `LaTeX`
The `animate` package in LaTeX provides a simple way to include animations, including GIFs, in LaTeX-compiled documents. It allows users to specify the frame rate and options for the animation, customizing its appearance and behavior. The `animate` package also supports most image formats, including `PNGs`.


Import it in the preamble using the typical
```latex
\usepackage{animate}
```

Now the `GIF` can be created by using the `\animategraphics` to reference the sequence of images.
```latex
\animategraphics[loop,controls,height=.85\textheight]{10}{./png-sequences/something-}{0}{237}
```
Unpacking the `\animategraphics` `LaTeX` macro:

* the `loop` option specifies non-stop looping of the `GIF` 
* `controls` option adds a control panel under the `GIF` (with start, pause, fast forward, speed adjustment, etc.)
* `height` option is the typical option to adjust height
* `10` is the frames per second we recovered from the `GIF` using ImageMagick (or whatever is preferred)
* `png-sequences/something-` is the path to the sequence of images
* `0` is the first image in the sequence
* `237` is the last image in the sequence

<div class="admonition note">
  <p class="admonition-title">Other solutions</p>
  Other potential solutions are the movie15 and media9 packages in LaTeX. Using movie15, for example, makes it possible to directly reference the GIF

    \usepackage{movie15}

    ...
    \includemovie{something.gif}

  But for GIFs, the recommended solution is to use animate. GIFs are usually short, and it might not make sense to load in an entire video embedding package like movie15 or media9 just for a GIF. The animate package is a more suitable lightweight solution.
</div>


## Gotcha with Size
Adding `GIFs` to `LaTeX` can make the compiled `pdf` swell up in size. Adding the above `GIF` to my `LaTeX` increases my `pdf` size from around 5 to 50 MB. Adding another `GIF` increases it to over 100 MB. This could be an issue if there are file size limits (to upload on a portal, for example).

One solution is to compress the sequence images. ImageMagick provides that utility too. For example, to shrink down an image, 
```bash
$ magick image.png -resize 60% out.png
```

<div class="admonition warning">
  <p class="admonition-title">Caution with Mogrify</p>
  The magick mogrify command is like the magick command, except that the former is designed to modify images in place. Hence, mogrify is dangerous as it can easily write over the original image.
</div>

For a batch of images, there is [`mogrify`](https://www.imagemagick.org/Usage/basics/#mogrify) to help shrink down batches of images at once.
```bash
$ magick mogrify -resize 60% "*.png"
```



<details>
  <summary>Show/Hide</summary>
  <div class="admonition warning">
    <p class="admonition-title">'Argument list too long' error</p>
    The quotes in "*.png" is needed because most shells limit the length of the command-line. So a batch task for many PNG files would lead to an 'Argument list too long' error. Enclosing the *.png in quotes lets magick take care of expanding the argument.
  </div>
</details>


## Gotcha with `GIFs` in `LaTeX`
Once compiled, I cannot see the GIF work in my local TeXstudio editor. To check that the `GIF` works, I would have to open it in a reader like Adobe Acrobat Reader. The `GIF` will not run in all readers. The `GIF` animation requires a `JavaScript`-supporting reader (e.g., Adobe Acrobat Reader, KDE Okular). Opening the `pdf` in chrome browser does not seem to work either. 


## Resources

* [ImageMagick](https://github.com/imagemagick/imagemagick)
* [Animate](https://ctan.org/pkg/animate?lang=en)
* [Best settings for PNG image compression](https://github.com/ImageMagick/ImageMagick/discussions/4436)
* [Mogrify -- in-place batch processing](https://www.imagemagick.org/Usage/basics/#mogrify)
* [SE - How to add a gif file to my LaTeX file?](https://tex.stackexchange.com/questions/7602/how-to-add-a-gif-file-to-my-latex-file)
* [SE - Getting GIF and/or moving images into a LaTeX presentation](https://tex.stackexchange.com/questions/240243/getting-gif-and-or-moving-images-into-a-latex-presentation)
* [SE - Is there any way to include an animated GIF directly?](https://tex.stackexchange.com/questions/5396/is-there-any-way-to-include-an-animated-gif-directly)
* [SE - using mogrify on lot of images gives error](https://stackoverflow.com/questions/29212249/using-mogrify-on-lot-of-images-gives-error)