This document describes the format of VICAR files. It applies to files created with version 8.0 or later of VICAR. Files created earlier may not have some sections (like property labels) or some system label items (like the various HOST-related items), but they still conform to this specification. The proper application of defaults given below will ensure that all VICAR files may be read using this spec. Any VICAR files written out must include all the system label items defined below.
The basic structure of a VICAR file is shown below.
A VICAR file consists of two major parts: the labels, which describe what the file is, and the image area, which contains the actual image. The labels are potentially split into two parts, one at the beginning of the file, and one at the end. Normally, only the labels at the front of the file will be present. However, of the EOL keyword in the system label (described below) is equal to 1, then the EOL labels (End Of file Labels) are present. This happens if the labels expand beyond the space allocated for them.
The VICAR file is treated as a series of fixed-length records, of size RECSIZE (see below). The image area always starts at a record boundary, so there may be unused space at the end of the label, before the actual image data starts.
The label consists of a sequence of "keyword=value" pairs that describe the image, and is made up entirely of ASCII characters. Each keyword-value pair is separated by spaces. Keywords are strings, up to 32 characters in length, and consist of uppercase characters, underscores (_), and numbers (but should start with a letter). Values may be integer, real, or strings, and may be multiple (e.g. an array of 5 integers, but types cannot be mixed in a single value). Spaces may appear on either side of the equals character (=), but are not normally present.
The first keyword is always LBLSIZE, which specifies the size of the label area in bytes. LBLSIZE is always a multiple of RECSIZE, even if the labels don't fill up the record. If the labels end before LBLSIZE is reached (the normal case), then a 0 byte terminates the label string. If the labels are exactly LBLSIZE bytes long, a null terminator is not necessarily present. The size of the label string is determined by the occurrence of the first 0 byte, or LBLSIZE bytes, whichever is smaller.
If the system keyword EOL has the value 1, then End-Of-file Labels exist at the end of the image area (see above). The EOL labels, if present, start with another LBLSIZE keyword, which is treated exactly the same as the main LBLSIZE keyword. The length of the EOL labels is the smaller of the length to the first 0 byte or the EOL's LBLSIZE. Note that the main LBLSIZE does not include the size of the EOL labels. In order to read in the full label string, simply read in the EOL labels, strip off the LBLSIZE keyword, and append the rest to the end of the main label string.
The label is divided into three logical parts: System labels, Property labels, and History labels, in that order. These parts are described later in this section.
The label values may be of three types: integer, real, or string.
A keyword may have more than one value by enclosing the values in parentheses and separating the values with commas. The collection of values is treated like an array for that keyword. All values in a multi-valued label item must be of the same type. Spaces may exist around the parentheses or the commas, but are not normally present.
LBLSIZE=1024
FORMAT='BYTE'
LATITUDE=45.3
COORDS=(5.7,-3.2E+2)
COMMENTS=('Wow, this is a comment!', 'This can''t be real')
EXTRA_SPACES = ( 1, 2,3, 4 , -5 )
System labels describe the format of the image and how to access it. They are always the first labels in the file. The system labels extend from the beginning of the file until the first PROPERTY or TASK keyword, or until the end of the label (if there are no property or history labels).
Any program attempting to read a VICAR file should be able to accept (and ignore) system label items it doesn't understand, as new system label items are added from time to time.
Some system label items are mandatory, while others are optional. The mandatory ones are mentioned in the descriptions below. However, when writing a new file, all system label items should normally be included.
The currently defined system label items are listed below. They generally appear in the order listed, but there is no guarantee that the items will be in any particular order, except that LBLSIZE must always be first. So, any program that reads the label must be able to handle any order of label items.
The following values are obsolete, but may appear in some older images:
The three organizations are depicted graphically below.
The system label for a typical file is shown below. Although carriage returns have been inserted for clarity, none actually exist in the file.
LBLSIZE=1024 FORMAT='BYTE' TYPE='IMAGE' BUFSIZ=20480 DIM=3 EOL=0 RECSIZE=512 ORG='BSQ' NL=512 NS=512 NB=1 N1=512 N2=512 N3=1 N4=0 NBB=0 NLB=0 HOST='VAX-VMS' INTFMT='LOW' REALFMT='VAX' BHOST='VAX-VMS' BINTFMT='LOW' BREALFMT='VAX' BLTYPE=''
Property labels describe properties of the image in the image domain. Property labels do not describe the physical layout of the image; that is handled by the system labels. They do contain other current information about the file, such as the map projection used, a lookup table, or latitude/longitude information for the image.
Property labels are divided into named sets called properties. Each property is made up of zero or more label items that contain the actual property information. The name space for each property is independent, so the same label item keyword may be used in more than one property. Only one property of a given name may exist.
Property labels are located between the system and the history labels. They start with the first occurrence of the keyword PROPERTY, and end with the first occurrence of the keyword TASK or the end of the labels (if there are no history labels). It is quite possible that no property labels exist in a file, in which case there would be no PROPERTY keywords.
Each property begins with a PROPERTY keyword, which has a string value. This value is the name of the property set. The PROPERTY keyword is followed by the label items that make up the property. The set continues until the next PROPERTY keyword, or the end of the property labels.
Label items within a property must not use the keywords DAT_TIM, LBLSIZE, PROPERTY, TASK, or USER.
Any program attempting to read a VICAR file should be able to accept (and ignore) properties or property label items it doesn't understand, as new properties and label items are added from time to time. A simple display program could ignore the property labels completely.
The valid property names, and the keywords that make up each property, are defined in a name registry maintained by the VICAR system programmer. As of this writing, no names have been registered, as property labels are a recent addition to VICAR files.
Below is an example of what a property label with two properties might look like. IMPORTANT: This is not a real property label! The property names and items shown below have not been standardized. This is an example only! Also, carriage returns have been inserted for clarity, and do not exist in the label.
PROPERTY='MAP' PROJECTION='mercator' LAT=34.2 LON=177.221 PROPERTY='LUT' RED=(1,2,3,4,5,6,7,8) GREEN=(8,7,6,5,4,3,2,1) BLUE=(1,1,1,3,5,7,8,8)
History labels describe the processing history of the image. Each processing step has an entry (called a task) in the history label. Each task can optionally have label items further describing the task (such as parameters to the program). History labels do not describe the physical layout of the image; that is handlded by the system labels. They should contain only historical information; however, they often contain current state information that should be in a property label, since property labels are new and not yet well utilized.
History labels are divided into sets called tasks. Each task is made up of three mandatory label items, and zero or more label items that contain additional history information. The name space for each task is independent, so the same label item keyword may be used in more than one task. Each task has a task name associated with it, which is the name of the program that created that part of the history label. However, the task names are not unique. Several tasks may have the same name. Each occurrence of the task name is called an instance, so the task name and the instance combine to uniquely identify the task set.
History labels are located after the system and the property labels. They start with the first occurrence of the keyword TASK, and end with the end of the labels. It is possible, although highly unlikely, that no history labels exist in a file, in which case there would be no TASK keywords.
Each history task begins with a TASK keyword, which has a string value. This value is the name of the task. The instance is derived by counting the number of previous TASK keywords with the same task name; it is not stored explicityl in the label. The TASK keyword is followed by a USER and a DAT_TIM keyword. USER is a string specifying the username of the account that ran the program. The machine the program was run on is not available; it is assumed that the username is enough to identify the user. DAT_TIM is a string specifying the date the program was run, in the format Www Mmm dd hh:mm:ss yyyy, where Www is the three-letter day of the week, Mmm is the three-letter month, and the rest are digits. Time is in 24-hour format, and day of the month (dd) must be two digits (although the first may be a blank instead of a zero).
Following the USER and DAT_TIM keywords are the optional label items with further history information. The task set continues until the next TASK keyword, or until the end of the labels. The actual contents of the additional keywords are application-defined.
Label items within a task must not use the keywords DAT_TIM, LBLSIZE, PROPERTY, TASK, or USER.
Any program attempting to read a VICAR file should be able to accept (and ignore) tasks or task label items it doesn't understand, as new tasks and label items are added frequently. A simple display program could ignore the history labels completely.
Below is an example of a typical history label with several tasks in it. Although carriage returns have been inserted for clarity, none actually exist in the file.
TASK='GEN' USER='RGD059' DAT_TIM='Thu Sep 24 17:31:50 1992' IVAL=0.0 SINC=1.0 LINC=1.0 BINC=1.0 MODULO=0.0 TASK='COPY' USER='RGD059' DAT_TIM='Thu Sep 24 17:31:54 1992' TASK='LABEL' USER='RGD059' DAT_TIM='Thu Sep 24 17:32:54 1992' TASK='F2' USER='RGD059' DAT_TIM='Thu Sep 24 17:33:07 1992' FUNCTION='in1+10' TASK='STRETCH' USER='RGD059' DAT_TIM='Thu Sep 24 17:33:55 1992' PARMS='AUTO-STRETCH: 0 to 0 and 138 to 255'
Following the labels (or between the label parts if there are EOL labels) is the image area. The structure and content of the image area are described in this section.
The image area is made up of records RECSIZE in length. Each record contains one line of data (for BSQ), i.e. one set of N1 pixels, plus the binary prefix, if any. If NBB=0, the binary prefix does not exist. A set of N2 records comprises a band (for BSQ), and a set of N3 bands makes up the image. The image is optionally preceded by NLB records of binary header. If NLB=0, the binary header does not exist.
The structure of the image area is shown below.
Image pixels are always represented in a binary format, not in ASCII. This makes reading and writing the image more efficient, but makes it harder to transfer images between different machines. The pixel representation is determined by two factors: the data type (FORMAT label), and the host representation (INTFMT and REALFMT labels). For binary labels, the data type is application-defined, while the host representation is specified in the BINTFMT and BREALFMT labels (which may be different than INTFMT and REALFMT).
Data is typically stored in the native host representation for whatever machine the image was created on. Any program that reads a VICAR file must be able to translate that representation into the one used by the machine the program is running on. A program that writes a VICAR file does not need to do translation; it can write out in the native format (although it can translate if desired). The VICAR Run-Time Library typically performs the input translation automatically.
The integer data types are BYTE, HALF, and FULL. In both currently supported INTFMTs (HIGH and LOW), BYTE is a single-byte, unsigned value in the range 0-255. HALF is a two-byte, two's-complement signed value in the range -32768 - +32767, while FULL is a four-byte, two's-compelement signed value in the range -2147483648 - +2147483647. For INTFMT=HIGH, the high-order byte is first for HALF and FULL, while for INTFMT=LOW the low-order byte is first and all the bytes are swapped (i.e. 4321 instead of 1234). The representations for BYTE are identical in HIGH and LOW.
The floating-point data types are REAL, DOUB, and COMP. Type COMP is for complex numbers, and consists of two REAL numbers in the order (real, imaginary). There are three currently supported REALFMTs, IEEE, RIEEE, and VAX. IEEE is the IEEE-754 standard floating point format. REAL is a single-precision value, while DOUB is a double-precision value. See the IEEE-754 documentation for a definition of the standard. RIEEE is exactly like IEEE, except the bytes are stored in reverse order (as in HIGH vs. LOW, so they are in the order 4321 or 87654321 instead of 1234 or 12345678). VAX is the floating-point format used by Digital Equipment Corp.'s VAX series of computers. REAL is stored in VAX F floating-point format, while DOUB is stored in VAX D floating-point format. See the documentation provided by DEC for a definition of the floating-point formats.
Binary labels are the least well-defined part of the VICAR file format. Binary labels consist of two parts: binary headers, which occur once at the top of the file, and binary prefixes, which occur before every image record. For most purposes, especially for simple display programs, binary labels can be ignored. Most of the time, they are not even present.
The data types and semantics of information in the binary label are defined by the application programs that use them. The user has to know what kind of binary label is present in order to use the correct application to make use of it. An attempt has been made to solve this problem through the addition of the BLTYPE system label item, but it is new and not yet in use at the time of this writing.
No attempt in this document is made to describe the various kinds of binary label. The documentation for the individual programs involved will describe the format used.
The data in a binary label is usually stored in a binary format, although an application could, of course, decide to store it in ASCII. All the binary label data must be in a single host representation, given by the BINTFMT and BREALFMT system labels. It is important to realize that the host for the pixels is not necessarily the same as the host for the binary labels, so make sure BINTFMT and BREALFMT are used instead of INTFMT and REALFMT for interpreting binary labels. As with pixels, any program that reads a binary label must be able to do host translation, while a program that writes a binary label does not have to translate (although some kinds of binary labels may be defined to be in VAX format for backwards compatibility).
Last Update: September 25, 1992
Questions about the VICAR file format can be directed to Bob Deen.
Operational Science Analysis
Document Review: CL 96-0842 on 22-May-96 by Charlotte Marsh