General tips for parsing ILDA (.ild) 
files for a laser projector
=====================================

--------------------------------------------------
Written by:
Michael Ivey
Josh Ibach-MacKeen

Group 9
Winter 2010
--------------------------------------------------


--------------------------------------------------
 INTRODUCTION
--------------------------------------------------

The International Laser Display Association (ILDA) is an organisation dedicated to 
advancing the art and technology of laser shows.  In serving that end, they have produced 
a specialized file format (.ild) for image display using laser projectors. These files 
contain images with multiple frames, which contain point information for drawing 
vectors using a laser.

The official specification for the ILDA files can be found at 
http://www.laserist.org/StandardsDocs/IDTF05-finaldraft.pdf .
This file contains detailed information for the specs of ILDA files.

This appnote outlines some tips and general information for quickly getting an ILDA 
parser off the ground for parsing ILDA files into an intermediate form for one's program 
to use.  For more detailed information, look at the official specification 
listed above - this guide simply condenses the key bits of information that would enable 
one to quickly be able to build an ILDA parser in whichever language.


--------------------------------------------------
1. READ IN THE FILE
--------------------------------------------------

ILDA files are stored using a binary file storage method - as such you need to 
read them in via bit-by-bit operations.  In C, for instance, you would initialize 
a FILE* parser and make use of the fread() command to read each set of bits as needed 
into the appropriate structure.  Every file is composed of a consecutive series of frames, 
with a new frame easily indicated by its first 4 bytes being the ASCII text "ILDA" - when 
we see these 4 characters we have a new frame.


--------------------------------------------------
2. OBTAINING THE TOTAL FRAMES/POINTS PER FRAME
--------------------------------------------------

Within each frame, the current frame number as well as the total number of frames 
in the sequence are stored at bytes 27-28 and 29-30 respectively.  The total number of 
points in a given frame is stored at bytes 25-26.  With these numbers, it thus becomes very 
easy to determine limits on our parser loops (so that we do not need to use 
a perpetual "while" loop, and can instead easily create arrays for storing the points.)


--------------------------------------------------
3. READING IN POINTS
--------------------------------------------------

Each frame is not of fixed size, given it has a variable number of points. Upon 
reaching the 33rd byte of a frame, the point information starts to be stored until 
we reach the beginning of a new frame (as indicated by the 'ILDA' header).  Furthermore, 
there is more than one possible configuration for an ILDA file - at the 5th to 8th bytes 
of each frame, there is a status code stored which indicates how these coordinates are stored.  
The predominant code throughout image files, 0000, indicates that there is an extra set 
of Z-coordinates stored in the point data (while the code 0001 indicates there are 
simply X and Y points).  If the code indicates a 3D frame, the coordinates will be stored 
in the format X,Y,Z, and status code (each consisting of a length of 2 bytes).  
In a 2D frame, the format is the same only without the Z coordinate being stored.  In a 
monochromatic laser pointer, the only important bit in the status code that we care about 
is the 14th bit, which indicates whether or not the laser is to be blanked at this point.


--------------------------------------------------
4. STORING THE POINTS
--------------------------------------------------

The most practical way to run an image parser is to run it in advance on whatever 
images we want to run on the laser projector.  If we know exactly what we want to 
display on the projector in advance, we can simply store these as arrays of fixed sizes 
(once we have parsed through the files, it is possible to statically allocate array sizes 
based on the totals we obtained earlier), each containing a series of X, Y, or 
blanking points for every frame.