The Descriptor File Format

Background. A descriptor file provides a means to read uncompressed images from practically any imaging modality without modification of the original images. It is a text file that gives the description of image file parameters needed to read images. The descriptor file was designed in accordance with ACR-NEMA requirements and is based on keyword-value pairs specifying image parameters. It was adopted by the Hayden Image Processing Group (HIPG - Boulder Colorado) as a general method to import/export images. It is one of the file types supported by the HIPG image processing software applications DIPStation[tm] (Macintosh) and Alice[tm] (Macintosh and Windows NT/95). The descriptor-file format is the principal means for reading and writing images for all Research Imaging Center software.

Naming Convention. A descriptor file is named using the base name of the file(s) it references. If the image volume(s) consists of multiple files, the file name of the first file is used. It is common practice to use a .des extension to help identify the descriptor file. In the table below all slices are in one file, and the filename is "E7020_06806_3min.des".

3-D Orientation. The orientation keyword was devised by the Research Imaging Center (RIC) to support loading of 3-D images in a consistent manner for RIC software. The coordinate system used is that of the 1988 Talairach Atlas (+x is right, +y is anterior, and +z is superior). The orientation process assigns a physical axis (x, y or z) to each of the three dimension in a 3-D image file array. The first index of a 3-D array is assumed to change most rapidly in moving from the beginning to the end the image file(s). The descriptor file refers to the first index as column number, the second index as row number, and the third index as slice number. (COMMENT: Most common image processing software will display column-indexed values moving from left to right and row-indexed values from top to bottom of the viewing screen.) The orientation keyword assigns an axis label to each of the column, row, and slice indices. It also provides the sense of the axes. For example, in the descriptor file in the table below the ORIENTATION keyword is XYZ­­­. This decodes as [COLUMN][ROW][SLICE][column sense][row sense][slice sense] so the x axis associates with columns, y axis with rows, z axis with slices. The negative sense for each axis indicates that as the index increases it is moving in the negative direction along its corresponding physical axis. This keyword format compactly encodes orientation, and software developers can quickly decode the physical orientation of a 3-D file and load it into their standard internal (memory) orientation. The standard memory orientation at the RIC is XYZ+--. Files saved using the standard orientation are z slices (or transaxial section images) and appear correctly oriented when using common image processing software. Images formatted using the standard orientation start at the most superior slice. When displayed by common image processing software they will be oriented so that anterior is at the top and body right at the right of the display screen. For files loaded and saved in this standard orientation, neither decoding or encoding routines are required.

New Keywords. A number of new keywords have been added to the original HIPG descriptor file without interfering with the old keywords. The keyword concept is such that older software will load images in the normal manner and ignore new keywords. New software can be designed to support descriptors files with or without the new keywords by assigning default values when needed keywords are missing or values are inconsistent with allowable ranges. In the table below each keyword is designated as Required, Default, or Optional. The required-type keywords will cause failure to load a file if not present. The default-type keywords will be assigned standard values (indicated in description field of table) if the keyword is missing or out of range. The optional-type keywords are not required by all software and applications developers are urged to prompt users for these values if needed and the descriptor file does not contain them. An example of a required keyword is the DATA keyword that references an image filename. An example of a default-type keyword is ROWVEC which is assumed to be unity if missing or if the keyword is 0. An example of an Optional-type keyword is IMAGE_MAX which is helpful at load time, and will have to be calculated each time the image is loaded if not present.

File Organization. The first keyword in all descriptor files is NEMA01. It should always be checked to insure that the file is a descriptor file. It can also be used to identify descriptor files when the ".des" file extension is missing. The descriptor file is roughly divided into a global section, a volume section(s), and an image section(s). The general rule is that keywords in the global section refer to parameters that do not change throughout the descriptor file. Additionally, keywords in the volume section(s) refer to parameters specific to each volume. Finally, keywords in the slice section(s) refer to parameters specific to each slice. The keywords for the volume and slice sections are special since they may occur multiple times within a file, and this is indicated by using $ symbol as the first character of these keywords. This file organization is hierarchical with the global section containing volume sections and volume sections containing slice sections. Since most files contain only one volume, the global section keywords are often put in the volume section (See table below). In this case the global and volume keywords are identical. The order of keywords within a section is not important; however, all required keywords must be present in a descriptor file. NOTE: The HIPG format did not strictly follow this hierarchical scheme therefore a required keyword may be in any section of the descriptor file so all sections should be read before attempting to load a file.

Keyword Format. The standard format for a keyword is KEYWORD=parameters(s). All keywords are written in UPPER case and followed by an equal sign. Spaces are allowed but not necessary. The parameter list may contain multiple values separated by commas. Since all parameters are ASCII the Table below can be consulted to determine the data type to associate with each parameter. If a parameter is surrounded by quotes it is explicitly text, and the quotation marks are required, as for the filename in the DATA keyword. A keyword-parameter list entry is terminated by a carriage return. Other data such as comments are not recommended, and their inclusion may lead to incompatibility problems with older software using descriptor files.

Notes. The descriptor file should be kept with the image files it describes. It is best to follow the suggested naming convention though the referenced file names can be found by reviewing the DATA keyword values of a descriptor file. The IEEE and IEEE_FLOAT both refer the same data type, usually a 32 bit floating point value.

Following is the listing of all keywords currently supported for use in descriptor files. The values of the keywords are typical of what might be seen in a dual-echo MRI study. Only two slices are illustrated in this example since other slices contain similar information. New keywords may be added in the future but old keywords will not be changed.

Keyword Type Description
NEMA01 R Keyword to identify the descriptor file
TOTAL_VOLUMES=1 R Number of 3-D image volumes (time, etc.)
$VOLUME=1 R Special Keyword indicating beginning of each volume
TOTAL_SCANS=32 R Number of Images (slice/sections) in the volume
PATIENT_NAME="" O Patient/Operator name
PATIENT_NUMBER="" O Patient number
SCANDATE="1996.06.21" O Date of scan
ROWS=157 R Number of rows per image
REPETITION_TIME1=500 O MRI - repetition time in milliseconds
ECHO1_TIME=20 O MRI - first echo time in milliseconds
ECHO2_TIME O MRI - second echo time in milliseconds
COLUMNS=157 R Number of columns per image
ROWVEC=1.64062,0.0,0.0 D Pixel spacing in mm for rows (default = 1)
COLVEC=0.0,1.64062,0.0 D Pixel spacing in mm for columns (default = 1)
SLICEVEC=0.0,0.0,0.5 D Pixel spacing in mm for slices (default = 1)
ORIENTATION=XYZ--- O Orientation of the image file data (See details)
XOFFSET=0 O X location of the Talairach origin (mm from left boundary)
YOFFSET=0 O Y location of the Talairach origin (mm from Anterior boundary)
ZOFFSET=0 O Z location of the Talairach origin (mm from Superior boundary)
IMAGE_MAX=12834 O Maximum pixel value in the image volume
IMAGE_MIN=0 O Minimum pixel value in the image volume
SPATIAL_UNITS=mm D Dimensions for all data (always in mm)
BITS_ALLOCATED=16 R Pixel depth in bits (8x2n for n>=0)
BITS_STORED=16 R Number of significant bits (used in case of masking)
HIGH_BIT=15 R Byte order of data.  If HIGH_BIT=BITS_STORED - 1 byte
order is like on Sun and Macintosh systems.
$SLICE=1 R Special keyword indicating beginning of each slice
IMAGE_POSITION=0.0,0.0,0.0 O Position in mm. Only the third dimension or slice position is supported.
DATA_SCALE=2.715296e+00 D Multiply image by this value at load time (default=1)
ECHO_NUMBER=1 O MRI - this slice is first echo image
SLICE_MIN=0 O Minimum pixel value within the slice
SLICE_MAX=12834 O Maximum pixel value within the slice (not calculated if = 0)
DATA="E7020_06806_3min.dat",0 R Filename for slice 1 (in quotes), file offset to data in bytes
$SLICE=2 R Special keyword indicating beginning of each slice
IMAGE_POSITION=0.0,0.0,5 O Note that slice2 is SLICEVEC=5 mm from slice 1
DATA_SCALE=2.675907e+00 D Multiply image by this value at load time (default = 1)
ECHO_NUMBER=2 O MRI - this slice is second echo image
SLICE_MIN=0 O Minimum pixel value within the slice
SLICE_MAX=8945 O Maximum pixel value within the slice
DATA="E7020_06806_3min.dat",49298 R Note the byte offset = ROWS x COLUMNS x BITS_ALLOCATED / 8
= 157 x 157 x 2
                Keyword Types: R = Required, D = Default, O = Optional.