Applications Note
ST-4X/5/6/7/8 Image File Format

This application note describes the file formats used to save ST-4X thru ST-8 images on both the IBM PC and compatible computers and the Macintosh computers. The files contain the image data as well as header information describing the image in terms of exposure time, telescope, etc. The files come in two varieties: Compressed and Uncompressed. In addition the file format has evolved throughout the development of these CCD cameras and has finally settled down to the "Type 3" format described herein.

Type 3 Format

The Type 3 format starts with a 2048 byte header of ASCII information followed by the image data in one of two varieties: Compressed or Uncompressed. The ASCII information for Type 3 files consists of a line showing the type of camera used to acquire the image and the variety of image data (Compressed or Uncompressed) as shown in the example below:

ST-6 Compressed Image<lf><cr>

or

ST-6 Image<lf><cr>

where <lf> and <cr> represent the linefeed (hex 0A) and carriage return (hex 0D) characters. Other camera images replace the "ST-6" with the camera name ("ST-4X", ST-5", "ST-7" or "ST-8") in the lines above respectively. After the 1st line are several lines of parameters in the format:

Parameter = Value<lf><cr>

where "Parameter = " is a string describing the parameter and "Value" is a string containing the value of the parameter. At the end of all the parameters is the line:

End<lf><cr><ctrl-z>

used to signify the end of the of the image information. The <ctrl-z> is used to tell DOS commands like type to stop and not display any further data. The remainder of the 2048 bytes in the header are unused. The parameters for a Type 3 file are shown below in Table 1:

Table 1
Type 3 Parameters

ST-6 Compressed Image
File_version = 1
Data_version = 1
Exposure = xxx
Focal_length = xx.xxx
Aperture = xx.xxx
Response_factor = xx.xxx
Note = xxxxxxxx
Background = xxx
Range = xxx
Height = xxx
Width = xxx
Date = xx/xx/xx
Time = xx:xx:xx
Exposure_state = xx
Temperature = xx.xx
Number_exposures = xx
Each_exposure = xx
History = xxxxxx
Observer = xxxxxxxx
X_pixel_size  = xx.xx
Y_pixel_size = xx.xx
Pedestal =xx
E_gain = x.xx

The following parameters are optional and may be present:

User_1 = xxxxxxxx
User_2 = xxxxxxxx
User_3 = xxxxxxxx
User_4 = xxxxxxxx
Filter = xxxxxxxx
Readout_mode = xx
Track_time = xxx
Sat_level = xxx
End

Table 2 below describes each of the parameters found in the Type 3 header.

Table 2
Parameter Descriptions

ST-? Compressed Image

This indicates the type of camera used to take the image and the fact that the data is compressed as described below. The ST-? will be ST-4X, ST-5, ST-6, ST-7 or ST-8.

ST-? Image

This indicates the type of camera used to take the image and that the image data is not compressed. Uncompressed data is saved as N rows of M pixels where N and M are specified by the Height and Width entries in the header. The pixels are two byte unsigned integers each, with the least significant byte before the most significant byte. The pixels are written with pixel (1,1) first, proceeding in left-to-right order to pixel (1,M), followed by the subsequent N-1 rows of pixel data.

File_version

This field should be 3 to indicate the file is Type 3.

Data_version

This field describes the version of the image data and will be 1.

Exposure

This field indicates the exposure time in 1/100ths of a second.

Focal_length

This field indicates the focal length in inches of the telescope used to capture the image.

Aperture

This field indicates the aperture area in square-inches of the telescope used to capture the image.

Response_factor

This field specifies the CCDs response calibration factor.

Note

This field is the annotation attached to the image.

Background

This is the value of the Background parameter used to display the image when it was last saved.

Range

This is the value of the Range parameter used to display the image when it was last saved.

Height

This is the height of the image in pixels.

Width

This is the width of the image in pixels.

Date

This field shows the date the image was captured.

Time

This field shows the time the image was captured.

Exposure_state

This field contains sets of bits indicating whether ABG was active during the exposure, whether Double Correlated Sampling was used and whether DC Restore was used.

Temperature

This field indicates the temperature of the CCD in deg.C at the end of the exposure.

Number_exposures

This field indicates how many images were co-added to produce a composite image.

Each_exposure

For composite images this field indicates the exposure time of the individual exposures in 1/100ths of a second.

History

This is a string of characters indicating which image processing functions have peen performed on the image. The following is the mapping between individual characters in the string and the operation performed:

     @ - Modifications made before history   A - Co-addition of image.               
         established.                                                                    
     B - Image linearly scaled.              D - Image dark subtracted.              
     E - Cool pixels removed.                F - Flat field corrected.               
     G - Image smoothed.                     H - Image sharpened.                    
     I - Image pseudo flat field corrected.  J - Image quantized or posterized to    
                                                 less than 16 bits precision.            
     K - Warm pixels removed.                L - Image flipped horizontally.         
     M - Image flipped vertically.           N - Image zoomed with pixel             
                                                 interpolation.                          
     O - More than 40 operations performed.  P - Image log scaled.                   
     Q - Pixels combined.                    R - Image auto dark subtracted.         
     S - Image zoomed with pixel             T - Image clipped and filled            
         replication.                            (ST6COLOR)                              
     U - Image converted to 8 bit log        V - Image merged to color using 2       
         format (ST6COLOR).                      color merge (ST6COLOR).                 
     W - Image merged to color using 3       X - Image translated and back filled    
         color merge (ST6COLOR).                 (ST6COLOR)                              
     Y - Image pixels inverted.              Z - Image sharpened with unipolar       
                                                 algorithm.                              
     [ - Image sharpened with one-sided      \ - Image modernized by replacing       
         sharpening.                             ST6COLOR history characters1            
     ] - Image resampled to make square      ^ - Image averaged.                     
         pixels.                                                                         
     _ - Constant added to or subtracted     ` - Constant multiplied by or divided   
         from image.                             into image.                             
     0 - (Zero) The history string is set    a - Image enlarged 2X by pixel          
         to '0' for new images.  This is         interpolation.                          
         not a C null string, it is actually
         the '0' character.                                                                      
     b - Image reduced 2X by pixel           c - Column or Row repair.               
         combining.                                                                      
     d - Adaptive dark subtraction.                                                  

Please note the SBIG reserves the use of the characters '@' through '~' (decimal 64 through 126) for their use, and that any other characters added to the history string by other users should not use those characters. [1]

Observer

This string contains the name of the observer who captured the image.

X_pixel_size

This field indicates the width in millimeters of the pixels in the image.

Y_pixel_size

This field indicates the height in millimeters of the pixels in the image.

Pedestal

This field indicates any pedestal (constant value) that has been subtracted from each pixel in the image.[2]

E_gain

This field gives the conversion factor between pixel values and electrons of charge in the CCD. The units are e^-/count.

The following fields are optional. They may or may not be present in the header. As the CCDOPS software has evolved these fields have been added to the header a few at a time. If present they will be in the order shown:

User_1 through User_4

These fields are for the use of non-SBIG software packages and can be up to 64 characters in length each, terminated with the <lf><cr> characters. SBIG software will ignore and preserve the settings of these 4 user parameters when reading and writing files. Either all 4 should be present or none of them should be present. If present and any one of them is blank then a single dash character ("-") should be written before the <lf><cr> characters. Finally, SBIG uses the User_1 field to indicate the version of CCDOPS software used to capture the image.

Filter

This field is a 10 character text string indicating the name of the optical filter used when taking the image.

Readout_mode

This field indicates the readout mode the CCD camera's internal firmware utilized in capturing the image.

Track_time

This field, when non-zero, indicates the exposure used for the Tracking CCD in Self-Guided images.

Sat_level

This field indicates the maximum level you should expect in the pixel data. The ST-4X and ST-5 are 14 bit cameras for example and this setting will be 16383. Note that this level can increase as images are co-added or with Track and Accumulate images.

Image Compression

Type 3 images can be saved using a simple form of image compression. The image compression consists of saving the differences between adjacent pixels and using single bytes for small differences rather than double bytes.

Each line of compressed image data starts with a two-byte integer (least significant byte first) indicating the compressed length of the line in bytes followed by the compressed image data. The 1st pixel of the actual image data is written using two-bytes and is the actual pixel value. Subsequent pixels are written as follows depending on the difference between that pixel and the previous pixel:

Delta = Pixel(m,n) - Pixel(m, n-1)

If -127 <= Delta <= 127 then write Delta as a single byte in 2's complement format, otherwise write hex 80 (-128) followed by the actual pixel value using two-bytes (least significant byte first).

The last caveat to the compressed image data is that if any line after being compressed has as many or more bytes than if it were stored uncompressed then that line is stored uncompressed with the 2 bytes of length followed by the actual pixel values written using 2-bytes per pixel (least significant byte first).

Note also that the compression algorithm described above used in saving images is similar though different than the compression algorithm used in downloading images from the CPU. You can not simply read a compressed image from the CPU and write it to file, adding a header. You must the CPU data and then compress the file data. This unfortunate consequence stems from the desire to have the CPU compression occur on the fly to keep the image throughput up.