ILDA - International Laser Display Association

Written by Paul Bourke
June 2002


The IDLA image data transfer format (file extension .ild) was designed by the International Laser Display Association to facilitate the transfer of laser show content between sites and systems. It supports the storage of not just individual frames/objects but time varying sequences (animations). It is a binary format employing the so-called "big endian" byte ordering (typically SGI, Macintosh, Amiga,....opposite to Intel processor based machines).

A ILDA file can describe three different types of data: 2D coordinates, 3D coordinates, and index colour palettes. Each data type is represented in a ILDA file by a header followed by the data. These types (sections) can appear in any order except that colour palette data is supposed to precede the 2D or 3D data it applies to.

Header

The following table will describe the format of the header section that precedes each data section. The header contains enough information to determine the size of the following data section and so data sections not recognised can be skipped over until the next header is reached.

Bytes Name Comments
1 to 4 Signature ("ILDA") This makes a positive identification that this is the start of a header section, it should be the ASCII characters "ILDA". It can also be used to quickly identify a file as a valid ILDA file since the first section of such a file must be a header section.
5 to 7 Not used Supposed to be set to 0
8 Format type This indicates the type of data section that will follow the header. This must be either 0 (3D coordinate section), 1 (2D coordinate section), or 2 (colour palette section). The structure of these is described in more detail later.
9 to 16 Name This 8 byte string indicates the name (if there is one) of the current frame for format type 0 and 1, and the palette name for format type 2. If no name is appropriate then all the bytes should be set to 0.
17 to 24 Company name The name of the company who created the frame or palette. If no name is appropriate then all the bytes should be set to 0.
25 and 26 Total number of entries in data section For coordinates this is the number of points in the following data section, for colour palettes it is the number of entries in the palette. Using this along with the known size for the data section entries allows a parsing program to skip over sections they weren't interested.
27 and 28 Current frame number For files that contain a number of frames, eg: library of graphical shapes, collection of colour palettes, or an animation sequence, this is the current number. It ranges from 0 up to one the total number of frames minus 1.
29 and 30 Total number of frames The total number of frames and is not used for colour palette format types. This is set to 0 in a "null header" to indicate the end of the ILDA file.
31 Scanner head Used for systems with multiple scanners or heads, otherwise set to 0 for the default device.
32 Not used Supposed to be set to 0

While not strictly necessary for the successful parsing of a ILDA file, it seems conventional to place a "null header" at the end of the file. A null header has the "total points" fields set to 0.

Data

The data section that appears after any header section is one of three types depending on the value in the "format code" in the header. The three possible data sections are described below.

Format type: 0 - 3D Coordinates

Each entry in a 3D coordinate section is 8 bytes long consisting of three signed short integers for the (x,y,z) point, a single byte that is used to set the laser state, and a single byte for the colour index. The laser state byte uses the top two bits to blank the laser (turn it off) and to indicate the end of the sequence. For the blanking a 0 indicates the laser is on, 1 is blanked. The end point indicator is set to 1 to indicate the end. The unused bits 0 to 5 in the state byte are supposed to be set to 0. Code to read the 3D coordinate data might be something like this (error checking removed)

   int i;
   short x,y,z;
   int status;
   int colour,blanking,lastpoint;

   for (i=0;i<number_of_points;i++) {
      fread(&x,sizeof(short),1,fptr);
      if (swapendian)
         FIX_SHORT(x);
      fread(&y,sizeof(short),1,fptr);
      if (swapendian)
         FIX_SHORT(y);
      fread(&z,sizeof(short),1,fptr);
      if (swapendian)
         FIX_SHORT(z);
      status = fgetc(fptr);
      colour = fgetc(fptr);
      blanking = (status & 0x40) >> 6;
      lastpoint = (status & 0x80) >> 7;
      // do something with this point
   }
Format type: 1 - 2D Coordinates

This is exactly the same as for 3D coordinates except the third z coordinate is missing. Each item of a 2D coordinate section is therefore only 6 bytes. Note that most software seems to be written to create 3D sections even for 2D data, the z coordinate is just set to 0.

Format type: 2 - Index Colour Palette

Each item in the colour palette is 3 bytes, one byte for each red, green, and blue. The first item is the r,g,b value for colour index 0, the second item in the colour palette is the r,g,b value for the second colour index 1, etc.

   int i;
   short r,g,b;

   for (i=0;i<number_of_colours;i++) {
      r = fgetc(fptr);
      g = fgetc(fptr);
      b = fgetc(fptr);
      // Do something with this colour   
   }

Since the colour index in the 2D or 3D data section is restricted to 1 byte, the maximum number of entries in the colour palette is 256. It is good form to provide full colour palettes even if some entries aren't used. So a monochromatic system should specify 2 colour, a 4 bit system all 16 colours and a 8 bit or full colour system all 256 colours. Note that by convention colour index 0 and 1 should be set to black (and is used when blanking is on) and white respectively and are often assumed to be so.

For most systems one can assume a default colour palette (except of course this is makes the data less portable). For many systems with a limited palette only one colour palette is needed and would generally appear at the beginning, the system that reads an ILDA file with a colour palette (which may contain colours it can't represent) is obliged to choose to the closest colour to the ones requested. For laser projection systems that can represent a very wide spectrum, while this file format is limited to 256 colours at any one time, potentially a different colour palette can precede each data section.

Changing endian

If an ILDA file is being read on a machine with the opposite endian then the following C macros will conveniently change all short integers.

#define SWAP_2(x) ( (((x) & 0xff) << 8) | ((unsigned short)(x) >> 8) )
#define FIX_SHORT(x) (*(unsigned short *)&(x) = SWAP_2(*(unsigned short *)&(x)))

Default palette

The default palette is given below, it consists of different sections.

   0         0       0       0      Black/blanked (fixed)
   1         255       255       255      White (fixed)
   2         255       0       0      Red (fixed)
   3         255       255       0      Yellow (fixed)
   4         0       255       0      Green (fixed)
   5         0       255       255      Cyan (fixed)
   6         0       0       255      Blue (fixed)
   7         255       0       255      Magenta (fixed)
   8         255       128       128      Light red
   9         255       140       128     
   10         255       151       128     
   11         255       163       128     
   12         255       174       128     
   13         255       186       128     
   14         255       197       128     
   15         255       209       128     
   16         255       220       128     
   17         255       232       128     
   18         255       243       128     
   19         255       255       128      Light yellow
   20         243       255       128     
   21         232       255       128     
   22         220       255       128     
   23         209       255       128     
   24         197       255       128     
   25         186       255       128     
   26         174       255       128     
   27         163       255       128     
   28         151       255       128     
   29         140       255       128     
   30         128       255       128      Light green
   31         128       255       140     
   32         128       255       151     
   33         128       255       163     
   34         128       255       174     
   35         128       255       186     
   36         128       255       197     
   37         128       255       209     
   38         128       255       220     
   39         128       255       232     
   40         128       255       243     
   41         128       255       255      Light cyan
   42         128       243       255     
   43         128       232       255     
   44         128       220       255     
   45         128       209       255     
   46         128       197       255     
   47         128       186       255     
   48         128       174       255     
   49         128       163       255     
   50         128       151       255     
   51         128       140       255     
   52         128       128       255      Light blue
   53         140       128       255     
   54         151       128       255     
   55         163       128       255     
   56         174       128       255     
   57         186       128       255     
   58         197       128       255     
   59         209       128       255     
   60         220       128       255     
   61         232       128       255     
   62         243       128       255     
   63         255       128       255      Light magenta
   64         255       128       243     
   65         255       128       232     
   66         255       128       220     
   67         255       128       209     
   68         255       128       197     
   69         255       128       186     
   70         255       128       174     
   71         255       128       163     
   72         255       128       151     
   73         255       128       140     
   74         255       0       0      Red (cycleable)
   75         255       23       0     
   76         255       46       0     
   77         255       70       0     
   78         255       93       0     
   79         255       116       0     
   80         255       139       0     
   81         255       162       0     
   82         255       185       0     
   83         255       209       0     
   84         255       232       0     
   85         255       255       0      Yellow (cycleable)
   86         232       255       0     
   87         209       255       0     
   88         185       255       0     
   89         162       255       0     
   90         139       255       0     
   91         116       255       0     
   92         93       255       0     
   93         70       255       0     
   94         46       255       0     
   95         23       255       0     
   96         0       255       0      Green (cycleable)
   97         0       255       23     
   98         0       255       46     
   99         0       255       70     
   100         0       255       93     
   101         0       255       116     
   102         0       255       139     
   103         0       255       162     
   104         0       255       185     
   105         0       255       209     
   106         0       255       232     
   107         0       255       255      Cyan (cycleable)
   108         0       232       255     
   109         0       209       255     
   110         0       185       255     
   111         0       162       255     
   112         0       139       255     
   113         0       116       255     
   114         0       93       255     
   115         0       70       255     
   116         0       46       255     
   117         0       23       255     
   118         0       0       255      Blue (cycleable)
   119         23       0       255     
   120         46       0       255     
   121         70       0       255     
   122         93       0       255     
   123         116       0       255     
   124         139       0       255     
   125         162       0       255     
   126         185       0       255     
   127         209       0       255     
   128         232       0       255     
   129         255       0       255      Magenta (cycleable)
   130         255       0       232     
   131         255       0       209     
   132         255       0       185     
   133         255       0       162     
   134         255       0       139     
   135         255       0       116     
   136         255       0       93     
   137         255       0       70     
   138         255       0       46     
   139         255       0       23     
   140         128       0       0      Dark red
   141         128       12       0     
   142         128       23       0     
   143         128       35       0     
   144         128       47       0     
   145         128       58       0     
   146         128       70       0     
   147         128       81       0     
   148         128       93       0     
   149         128       105       0     
   150         128       116       0     
   151         128       128       0      Dark yellow
   152         116       128       0     
   153         105       128       0     
   154         93       128       0     
   155         81       128       0     
   156         70       128       0     
   157         58       128       0     
   158         47       128       0     
   159         35       128       0     
   160         23       128       0     
   161         12       128       0     
   162         0       128       0      Dark green
   163         0       128       12     
   164         0       128       23     
   165         0       128       35     
   166         0       128       47     
   167         0       128       58     
   168         0       128       70     
   169         0       128       81     
   170         0       128       93     
   171         0       128       105     
   172         0       128       116     
   173         0       128       128      Dark cyan
   174         0       116       128     
   175         0       105       128     
   176         0       93       128     
   177         0       81       128     
   178         0       70       128     
   179         0       58       128     
   180         0       47       128     
   181         0       35       128     
   182         0       23       128     
   183         0       12       128     
   184         0       0       128      Dark blue
   185         12       0       128     
   186         23       0       128     
   187         35       0       128     
   188         47       0       128     
   189         58       0       128     
   190         70       0       128     
   191         81       0       128     
   192         93       0       128     
   193         105       0       128     
   194         116       0       128     
   195         128       0       128      Dark magenta
   196         128       0       116     
   197         128       0       105     
   198         128       0       93     
   199         128       0       81     
   200         128       0       70     
   201         128       0       58     
   202         128       0       47     
   203         128       0       35     
   204         128       0       23     
   205         128       0       12     
   206         255       192       192      Very light red
   207         255       64       64      Light-medium red
   208         192       0       0      Medium-dark red
   209         64       0       0      Very dark red
   210         255       255       192      Very light yellow
   211         255       255       64      Light-medium yellow
   212         192       192       0      Medium-dark yellow
   213         64       64       0      Very dark yellow
   214         192       255       192      Very light green
   215         64       255       64      Light-medium green
   216         0       192       0      Medium-dark green
   217         0       64       0      Very dark green
   218         192       255       255      Very light cyan
   219         64       255       255      Light-medium cyan
   220         0       192       192      Medium-dark cyan
   221         0       64       64      Very dark cyan
   222         192       192       255      Very light blue
   223         64       64       255      Light-medium blue
   224         0       0       192      Medium-dark blue
   225         0       0       64      Very dark blue
   226         255       192       255      Very light magenta
   227         255       64       255      Light-medium magenta
   228         192       0       192      Medium-dark magenta
   229         64       0       64      Very dark magenta
   230         255       96       96      Medium skin tone
   231         255       255       255      White (cycleable)
   232         245       245       245     
   233         235       235       235     
   234         224       224       224      Very light gray (7/8 intensity)
   235         213       213       213     
   236         203       203       203     
   237         192       192       192      Light gray (3/4 intensity)
   238         181       181       181     
   239         171       171       171     
   240         160       160       160      Medium-light gray (5/8 int.)
   241         149       149       149     
   242         139       139       139     
   243         128       128       128      Medium gray (1/2 intensity)
   244         117       117       117     
   245         107       107       107     
   246         96       96       96      Medium-dark gray (3/8 int.)
   247         85       85       85     
   248         75       75       75     
   249         64       64       64      Dark gray (1/4 intensity)
   250         53       53       53     
   251         43       43       43     
   252         32       32       32      Very dark gray (1/8 intensity)
   253         21       21       21     
   254         11       11       11     
   255         0       0       0      Black (cycleable/changeable)