Created: 6/5/2000
Last Modified: 6/16/2000
Version: cpmed 03d
Page from cpmed notes, Jim Nash, Synergy Research Inc.
Back to Contents
Our AFNI reader was derived from inspection of the AFNI header file (.HEAD) of a dataset generated by the program "to3D". The definition of attributes in the AFNI header file was found by inspecting the body of AFNI source code. There is little documentation on the AFNI file structure. We had the choice of using existing AFNI source files and routines they contain, or reading the file directly. Robert Cox supports the writing of AFNI plug-ins which use AFNI routines to access file elements. But he does not document the file structure. Adding all the AFNI files and routines to support reading files appeared complex compared with interpreting the AFNI header file directly. The negative side of this is that Dr. Cox makes no promises about the data structure remaining static.
The AFNI BRIK data set consists of two files having extensions .BRIK and .HEAD. BRIK files contain pixels and is otherwise a flat file. HEAD files are text files containing a long list of "attributes".
The following files are of use to the programmer who wants to extend AFNI file reading.
3ddata.h - AFNI file that lists all of the attribute names in C #define statements. Given an attribute that looks interesting in a known AFNI dataset, one can find the attribute in the dataset's .HEAD file, then search 3ddata.h for the symbol name, and then search the AFNI source code for use of the attribute. From all that inference can be made about the format of the .HEAD attribute.
thd_dsetblk.c - a large number of attributes are read by this file.
The AFNI .HEAD file is self contained, including a description of the type of data, its name and its value.
Attribute - describes some feature of the image. Each attribute includes type, name, count and value.
Type - the type of data contained in the attribute (integer, float, string).
Name - the name of the attribute (DATASET_DIMENSIONS, DELTA, etc.).
Count - The number of characters in the string value of a string attribute or the number of numbers in the values of an integer or float attribute.
Value - a string value begins with a single quote (') which indicates that a string follows and ends with a tilde (~) which substitutes for the nul character. A string value may contain return characters. Numeric values are separated by spaces. Typically there are five values per line,in the case of numeric attributes having a count of greater than five.
Only 3D and 3D+time AFNI datasets are supported. The AFNI program 'to3D' is our reference standard. 3ddup datasets are not supported. The .HEAD and .BRIK files must have the same name (before the extension). You can refer to the .HEAD or the .BRIK file when copying.
| type | name | count | description |
| string | HISTORY_NOTE | variable | 'some AFNI string~ |
| string | IDCODE_DATE | variable | 'date and time of acquistion~ |
| string | DATASET_NAME | variable | structured: "user+code.ext" where code is "orig", "acpc", "tlrc", "rgst" |
| integer | SCENE_DATA (note that view duplicates DATASET_NAME and type duplicates TYPESTRING) |
8 | view, func, type -999 -999 ... view values: func values: type values: |
| integer | DATASET_RANK | 8 | 3100 0000 on write. First values are #dimensions, #bricks in file. Attributes that start with "BRICK_" have #bricks values. |
| integer | DATASET_DIMENSIONS | 5 | x, y, z, 0, 0 (last two values reserved) |
| integer | TAXIS_NUMS | 8 | tsize, nsl, units, 0,0,0,0,0 - not supported tsize = the number of bricks in time, should agree with DATASET_RANK |
| float | TAXIS_FLOATS | 8 | start, delta, duration, 0,0,0,0,0 - not supported start = start time in time units |
| integer | ORIENT_SPECIFIC | 3 | set to 0 3 4 on write. The three numbers refer to x,y,z and have the following values: {RL=0, LR, PA, AP, IS, SI} where |
| float | DELTA | 3 | voxel spacing (xVox, ...) |
| float | ORIGIN | 3 | location of upper left voxel |
| float | BRICK_STATS | 2x#bricks | voxel value minimum and maximum |
| int | BRICK_TYPES | #bricks | type of each of n bricks in file. 0=byte, short, long, float, double, complex. |
| string | BYTEORDER_STRING | 10 | 'LSB FIRST~ |
BRICK_STATS - array of pairs of values, imageMin, imageMax, can be an array so that each subbrick can have its own min/max pair. Cpmed finds the widest min-max range on read and writes the same pair of values to all bricks on write. There is also a field named "MINMAX" but I have not seen it in a file yet.
DATASET_RANK - 8 values (#dims, #values, 0 0 0 0 0 0) rank is not often used, but is required. values refers to number of subbricks which could be (is usually or always?) interpreted as time. Currently we ignore this on read but write the fixed values 3 1 0 0 0 0 0 0.
BRICK_TYPES - is an array matching length given by second value of DATASET_RANK. Used for multiple subbrick data types (byte, short, float, etc). Cpmed requires that all types in a file are the same (no mixed image types).
| type | name | count | description |
| string | TYPESTRING | variable | Allowed values: "3DIM_HEAD_ANAT" ... on write |
| string | IDCODE_STRING | variable | must be 'MCW_random letters~ |
| string | LABEL_1 | variable | set to file name on write |
| string | LABEL_2 | variable | set to 'Elvis Lives~ as per AFNI example |
| int | MARKS_XYZ | 30 | -999999 in all values of example, ignored |
| string | MARKS_LAB | some label, ignored | |
| string | MARKS_HELP | some help text (long in example), ignored | |
| int | MARKS_FLAGS | 8 | 1100 0000 in example, ignored |
| float | BRICK_FLOAT_FACS | #bricks | 0.0 |
| float | TAXIS_OFFSET | nsl | time offsets to each slice in time units |
Notes:
BRICK_FLOAT_FACS - 0.0, an array like BRICK_TYPE, of factors that maps integer pixel data to float, made up data
NIAAA_xxx - a number of fields from SRIPimg that I did not want to throw
out. This list is not stable and may change or disapear.