The AAI file (.aai)

AAI is the internal image format of Dune HD media players, which a post on ImageMagick's forum describes as HDI's Dune media streamers. Dune's documentation calls it the format its devices use to represent images with transparency, and GraphicsMagick's format list gives icons for internet radio stations and channels as an example.

The format is as simple as an image file can be: the width, the height, and then 4 bytes per pixel, with nothing to decode. Dune published a free converter, AAImageGen, that turns BMP, PNG, JPG and PSD files into AAI.

AAI reached a wider audience through ImageMagick. A Dune user asked on the ImageMagick forum for support, describing AAI as a very simple format used by Dune media streamers; ImageMagick's developer noted it was very similar to ImageMagick's AVS format and added it. ImageMagick lists it as "AAI Dune image", and its format list is where most people first see the name.

Dune's own description is shorter still: two 32-bit integers for the width and height, then one 32-bit RGBA value per pixel, all little-endian, with images from 1 × 1 to 2047 × 2047 pixels. Storing the value 0xAARRGGBB least significant byte first gives the byte order B, G, R, A, the same order as in a 32-bit Windows BMP or TGA file.

That makes the size of a file entirely predictable: 8 + 4 × width × height bytes. A full-screen 1920 × 1080 image is 8,294,408 bytes, about 8.3 MB, whatever is in it; a PNG of a simple graphic that size is usually far smaller.

In almost every image format, an 8-bit alpha of 255 means fully opaque. In AAI, the value 255 is reserved and must never be used: Dune's documentation says alpha runs from 0 (fully transparent) to 254 (fully opaque), and recommends converting from the usual 0 to 255 range by leaving 0 to 254 alone and changing 255 to 254. It doesn't say what the reserved value is for.

• ImageMagick follows the rule both ways. Its writer turns every alpha of 255 into 254, and its reader turns 254 back into 255. A round trip through AAI and back to PNG gives the same image, except that a pixel whose alpha really was 254 comes back as 255.
• Other readers may not. Code that reads the bytes directly sees 254 as very slightly transparent: invisible on screen, but enough to make an image count as "has transparency" in software that checks.
• Writing your own files: clamp alpha to 254. A file with 255 in it may display wrongly on a Dune player.

Outside a Dune player, there's no reason to choose AAI. PNG stores the same pixels and transparency losslessly in a fraction of the space, carries metadata and opens everywhere. If you need raw, uncompressed pixels for a program of your own, a PAM file has a documented header and a magic number, or you can write the bytes with no header at all.

• One kind of device. It was made for Dune players' own graphics, not as a general format, and no operating system, browser or mainstream image editor adopted it.
• No compression. Every pixel takes 4 bytes, so files are many times larger than a PNG of the same picture.
• No signature. Nothing inside a file identifies it, so software can only trust the .aai extension. Most file-type detectors can't recognise an AAI file that has been renamed.
• No documentation beyond a README. The only description from Dune is a short text file that comes with its converter.

Most people who meet an AAI file today either own a Dune player or saw AAI in ImageMagick's list of formats and wondered what it was.

• ImageMagick (Windows, macOS, Linux) reads and writes AAI. This is the easiest way to view or convert one.
• GraphicsMagick lists read and write support too.
• AAImageGen, Dune's own converter, turns BMP, PNG, JPG and PSD into AAI, and an AAI back into BMP to check the result. Dune recommends an RGB source with an alpha channel and a single layer.
• Pillow, browsers and the built-in viewers of Windows and macOS can't open AAI.

# AAI to PNG, keeping the transparency
convert icon.aai icon.png          # ImageMagick 6
magick icon.aai icon.png           # ImageMagick 7

# PNG to AAI for a Dune player
convert icon.png icon.aai

# a file without the .aai extension: name the format
convert aai:icon.bin icon.png

Because the format is so simple, a reader takes a few lines of Python with Pillow:

import struct, sys
from PIL import Image

data = open(sys.argv[1], "rb").read()
width, height = struct.unpack_from("<II", data, 0)
img = Image.frombuffer("RGBA", (width, height), data[8:8 + 4 * width * height],
                       "raw", "BGRA", 0, 1)
img.save(sys.argv[2])

• "No decode delegate for this image format". ImageMagick picks the AAI reader from the file name. If the extension isn't .aai, put aai: in front of the file name.
• Red and blue are swapped. The pixels were read as R, G, B, A. AAI stores blue first.
• The image is slanted or garbage. The header was misread (for example as big-endian), or the file is truncated or not an AAI file at all. Check that the file size is exactly 8 + 4 × width × height.
• Transparency looks wrong on the player. The file contains alpha values of 255, which are reserved. Re-save it with ImageMagick or AAImageGen, both of which write 254 instead.

An AAI file can't contain anything executable. The risk is in readers: with no signature and no checksum, any file renamed to .aai is accepted, and its first 8 bytes become the dimensions. A reader should check them against the file size and a sensible limit before allocating memory. ImageMagick's AAI reader has had bugs of its own, such as a memory leak triggered by a crafted file (CVE-2017-8343, in version 7.0.5-5), so keep image libraries up to date if they handle uploads.