Dictionary Image Format

About The DIF File Format

This page describes the DIF Image format, and is not finished yet.

Synopsis

The DIF, or Dictionary Image Format, image format is a text-based image format that can encode bitmap images. It supports compression, the definition of custom color palates, termed "dictionaries", and the potential inclusion of metadata.

Raw DIF Format

IMPORTANT NOTE
DIF files should always be encoded using ASCII, not Unicode.

The basic layout of a raw DIF file is below:

!DIF
!!HEAD
VERSION=1.0
WIDTH=10
HEIGHT=10
DEFSIZE=1
USEDICT=
!!DEF
b=0,0,0
w=255,255,255
!!IMG
bbbbbbbbbb
wwwwwwwwww
bbbbbbbbbb
wwwwwwwwww
bbbbbbbbbb
wwwwwwwwww
bbbbbbbbbb
wwwwwwwwww
bbbbbbbbbb
wwwwwwwwww
!!END

Every DIF file begins with the line !DIF. After this the file is broken up into three sections, HEAD, DEF, and IMG.

The HEAD Section

The HEAD section defines several important variables that can be defined in any order:

VERSION - the DIF format version
WIDTH - the width of the image, in pixels
HEIGHT - the height of the image, in pixels
DEFSIZE - the defsize, or the length of each color definition
USEDICT - the name of a color dictionary not defined in the image to use

IMPORTANT NOTE
If the DIF image does not utilise an external color dictionary, do not put a USEDICT variable in the image file.

IMPORTANT NOTE
If the DIF image references an external color dictionary through USEDICT, you must ignore all the color definitions set inside the DIF file.

IMPORTANT NOTE
Even if the DIF image references an external color dictionary through USEDICT, you must still set the DEFSIZE variable to the DEFSIZE of the color dictionary being referenced. If the two values do not match, the DIF image is invalid, and shouldn't be displayed.

If you would like, you can also defined other variables in this section for things like metadata using the format KEY=value. However, software may ignore these other variables.

The DEF Section

If no color dictionary is specified with USEDICT, then the color definitions must be specified the DEF section. Each line contains one color definition in the format definition=r,g,b, where definition is any string of ASCII characters that is the length of the image DEFSIZE, and r, g, and b are numbers between 0 and 255 that represent an RGB color (for example 0,0,0 is black and 255,255,255 is white).

IMPORTANT NOTE
If a color definition's length does not match the DIF image DEFSIZE, the image is invalid, and shouldn't be displayed.

The IMG Section

This section is where the color of each pixel is defined. Each line defines one row of the image, and every DEFSIZE characters is a pixel. In the example above, that means that each b and w is a pixel, a black and white one respectively. However, this is not true for the image below:

!DIF
!!HEAD
VERSION=1.0
WIDTH=10
HEIGHT=10
DEFSIZE=2
!!DEF
bb=0,0,0
ww=255,255,255
!!IMG
bbbbbbbbbbbbbbbbbbbb
wwwwwwwwwwwwwwwwwwww
bbbbbbbbbbbbbbbbbbbb
wwwwwwwwwwwwwwwwwwww
bbbbbbbbbbbbbbbbbbbb
wwwwwwwwwwwwwwwwwwww
bbbbbbbbbbbbbbbbbbbbh
wwwwwwwwwwwwwwwwwwww
bbbbbbbbbbbbbbbbbbbb
wwwwwwwwwwwwwwwwwwww
!!END

In this image, each bb and ww is a pixel, because the DEFSIZE is 2, not 1.

Color Dictionaries

While DIF images can and do contain custom color dictionaries within themselves, most times the use of an external color dictionary is opted for, because it is easier, and, when a DIF image uses many different colors, can reduce file size. In order to ensure that a wide variety of images can be displayed, the inclusion of certain color dictionaries is mandated (see the list below). There is also the special case of the Base 52 RGB dictionary.