Contents || Index
09/01/2009

THE RAW FILE FORMAT

Note - the Lispix Raw File Format is not the same as the Raw Image files obtained from digital cameras, which are used to save all of the brightness levels (perhaps 12 or 14 bits worth) from the imaging chip, rather than just the 256 levels per color (8 bits) that the JPEG file format format supports.  These photographic file formats may be highly encoded and their structure is often propriatery, requiring software from the particular camera manufacturer to read them.

On the other hand, ...

Images and spectral images or data cubes that are written in the (Lispix) raw file format are just a continuous string of numbers – no header, no compression, no encoding to eliminate blocks of zeros, etc.  Data cubes can be stored image by image, or spectrum by spectrum.  Single images are stored row by row, vector cubes are stored row by row (each row spectrum by spectrum), image cubes are stored image by image.  All of the numbers are in the same format, such as 16 bit signed integer, IEEE 8-byte real, 8-bit unsigned byte, etc. 

A typical file name might be "image-001.raw".

The "raw" file will be accompanied by text file with the same name and ".rpl" extension. This file lists the characteristics of the raw file so that it can be loaded without human intervention.

RPL File

RPL stands for "Raw Parameter List", an ASCII text, tab delimited file in which Lispix records or reads the image parameters for a raw file.

The .rpl file or "Ripple" file, is a short ASCII (text) file listing the parameters that characterize a .raw file with the same name.  Whenever Lispix writes a raw file, it also writes a .rpl file with the same name so that Lispix can later open the raw file using the File / Open menu without recourse to the Import - Export Tool.  A typical file name might be "image-001.rpl".

 

To read a cube stored in raw format, either the user needs to know the various parameters of the cube, or there must be an accompanying *.rpl file (for “Raw Parameter List”) described below, which lists the parameters.

PARAMETERS

        Name        Description               
      ----------   ---------------------------------------- 
      Width        # pixels per row       integer  
      Height       # rows                 integer
      Depth        # images or spec pts   integer
      offset       # bytes to skip *      integer
      Data-type    signed, unsigned, or float 
      data-length  # bytes per pixel      1, 2, 4, or 8
      Byte-Order   big-endian, little-endian, or dont-care   
      Record-by    image, vector, or dont-care      

When data-length is 1, the byte order is not relevant as there is only one byte per darum, and byte-order should be dont-care.

When depth is 1, the file has one image, record-by is not relevant and should be dont-care.  For spectral images, record-by is vector.  For stacks of images, record-by is image.

Notes

  1. Rows, etc refer to the image and not the file, which is just one long string of bytes.
  2. Big endian:  Highest order byte first (in the file).  Mac and Moterola order.  Little endian - Lowest order byte first.  PC, Intel order.
  3. Floating point numbers can be IEEE 4-byte, or IEEE 8-byte.  Therefore if data-type is float, data-length must be 4 or 8.
  4. Lispix is not case sensitive to contents of the RPL file.
  5. Comment lines, beginning with a semi-colon ';' are allowed anywhere.
  6. The first non-comment line must have two collumn names, eg: 'key' <tab> 'value'.  Lispix doesn't check the names - other names would do.
  7. Parameters can be in any order.
  8. The parameter name is followed by one tab (spaces are ignored) eg:, 'data-length' <tab> '2'.  Note that what are spaces in the examples above should really be a single tab.  (My HTML editor doesn't allow tabs.)
  9. Other data and more tabs can follow the two items on each row, and are ignored.
  10. Other keys and values can be included in the file, and are ignored.
  11. Any number of spaces can go along with each tab.
  12. This format is compatable with the Excel spreadsheet program.  It is sometimes convenient to write the file in Excel and save it as 'text, tab
    delimited'.
  13. 9/1/09 Lispix now recognizes two additional x-ray related parameters,  ev-per-chan and detector-peak-width-ev, which you may add to an rpl file by hand (with a text editor).  Lispix will not write this information into a rpl file, in order to avoid compability issues with other software.  Lispix looks for these two parameters in vector cube and file cube rpl files, and, if necessary, will ask you for the values if they are not in the rpl file.  Lispix ignores extra parameters.

Example

This is an example RPL file. There are eight rows (lines) in the file, with two words or numbers per line, separated by a tab and any number of spaces.  The first line is "key <tab> value", for example.  The following lines list one parameter each, with the parameter name and the parameter value.

key         value
width       128  
height      96   
depth       101  
offset      0    
data-length 2    
data-type   signed     
byte-order  little-endian    
record-by   image

Note - spaces between key and value should include one tab character.  This example has no tabs, a restriction of vanilla HTML, in which this is written.