====== VTC (BrainVoyager QX's volume-based time-course) file format ======

===== Motivation =====
Most neuroimaging programs store functional data as a series of 3D volumes (separate files) or as a four-dimensional array, where still time is the slowest increasing index (in Matlab this refers to the last index). While this makes it convenient to display one of the volumes out of a time series, it usually makes regressing or plotting (averaged) timecourses a little more computational.

BrainVoyager QX's main developer, Rainer Goebel, thus decided for his software that storing data differently, such that time is the fastest increasing index, would be more suitable for data that is, in its most common application, used to either compute regression coefficients or being plotted against a time axis.

===== General setup =====
BrainVoyager's binary files are stored in little-endian byte ordering (for all platforms!) so as to allow cross-platform file exchange. Strings are stored as \0-terminated sequences of 8-bit integer values (ASCII charset, and not as either fixed-length or flag-specified-length strings).

The types in the list of fields are given as [[Matlab datatypes|Matlab type]] (not in C notation).

===== Fields =====
^ Loop / Condition  ^ Field                   ^ Field type       ^ Dimensions         ^ Comment  ^
|                   | FileVersion             | uint16           | ''1x1''            | indicates which file version is used for a particular file (and thus which fields are stored in it)  |
|                   | NameOfSourceFMR         | string           | ''\0-terminated''  | stores the filename of the [[xff - FMR format|FMR-file]] which was used to sample the data in VTC space  |
| FileVersion > 2   | NrOfLinkedPRTs          | uint16           | ''1x1''            | indicates how many [[xff - PRT format|PRT files]] are referenced in the VTC header, for ''FileVersion'' up to ''2'' this defaults to ''1''  |
|                   | NameOfLinkedPRT         | string           | NrOfLinkedPRTs ''\0-terminated'' strings  | stores the filenames of the linked [[xff - PRT format|PRT files]], for ''FileVersion'' up to ''2'' this can only store one filename, if no file is linked, set to empty string (a single 8-bit zero value)  |
| FileVersion > 2   | NrOfCurrentPRT          | uint16           | ''1x1''            | indicates which (out of multiple) linked PRT files is the currently active one  |
| FileVersion > 2   | DataType                | uint16           | ''1x1''            | indicates the data type used to store the functional data: ''1'' refers to ''uint16'', ''2'' refers to ''single'' (32-bit float), for ''FileVersion'' up to ''2'', this defaults to ''1'' (VTC files can only store ''uint16'' data!)  |
|                   | NrOfVolumes             | uint16           | ''1x1''            | gives the number of volumes (timepoints) stored in the data field (with a maximum of 65535 volumes)  |
|                   | Resolution              | uint16           | ''1x1''            | indicates the spatial resolution in mm of the data (VTC files must store data in iso-metric resolution with an integer size argument; commonly supported values are ''1'', ''2'', and ''3'' representing 1mm-, 2mm-, and 3mm-resolution data; higher resolutions might not be fully supported by BrainVoyager)  |
|                   | XStart                  | uint16           | ''1x1''            | gives the X-coordinate (in BrainVoyager's internal coordinate system, this goes from front to back of the brain) where the data "starts" in space (a value between ''0'' and ''255'')  |
|                   | XEnd                    | uint16           | ''1x1''            | gives the X-coordinate (in BrainVoyager's internal coordinate system, this goes from front to back of the brain) where the data "ends" in space (a value between ''0'' and ''255'' that must be greater than XStart), **together with XStart and Resolution gives the number of voxels in X direction by the formula ''DimX = (XEnd - XStart) / Resolution''**  |
|                   | YStart                  | uint16           | ''1x1''            | gives the Y-coordinate (in BrainVoyager's internal coordinate system, this goes from the top to the bottom of the brain) where the data "starts" in space (a value between ''0'' and ''255'')  |
|                   | YEnd                    | uint16           | ''1x1''            | gives the Y-coordinate (in BrainVoyager's internal coordinate system, this goes from the top to the bottom of the brain) where the data "ends" in space (a value between ''0'' and ''255'' that must be greater than YStart), **together with YStart and Resolution gives the number of voxels in Y direction by the formula ''DimY = (YEnd - YStart) / Resolution''**  |
|                   | ZStart                  | uint16           | ''1x1''            | gives the Z-coordinate (in BrainVoyager's internal coordinate system, this goes from the right to the left side of the brain) where the data "starts" in space (a value between ''0'' and ''255'')  |
|                   | ZEnd                    | uint16           | ''1x1''            | gives the Z-coordinate (in BrainVoyager's internal coordinate system, this goes from the right to the left side of the brain) where the data "ends" in space (a value between ''0'' and ''255'' that must be greater than ZStart), **together with ZStart and Resolution gives the number of voxels in Z direction by the formula ''DimZ = (ZEnd - ZStart) / Resolution''**  |
| FileVersion > 2   | Convention              | uint8            | ''1x1''            | indicates the spatial convention in which the data is stored/to be displayed (radiological or neurological; **this flag is not heeded by NeuroElf, which expects data to be stored according to the original standard of BrainVoyager**)  |
| FileVersion > 2   | ReferenceSpace          | uint8            | ''1x1''            | indicates the type of reference space of the data (raw/native data space, AC/PC space, TAL space; **NeuroELf does not heed this flag either, and data is simply shown at the locations indicated by the X/Y/ZStart/End fields**)  |
| FileVersion < 3   | HemodynamicDelay        | int16            | ''1x1''            | gives the number of milliseconds for the hemodynamic response function's delay parameter (no longer used, dropped in FileVersion 3)  |
|                   | TR                      | single           | ''1x1''            | gives the temporal resolution (time-of-repetition, TR) in milliseconds  |
| FileVersion < 3   | HrfDelta                | single           | ''1x1''            | gives the HRF delta parameter (no longer used, dropped in FileVersion 3)  |
| FileVersion < 3   | HrfTau                  | single           | ''1x1''            | gives the HRF tau parameter (no longer used, dropped in FileVersion 3)  |
| FileVersion < 3   | SegmentSize             | uint16           | ''1x1''            | gives the size of one "segment" (block length) in volumes for protocol overlay (no longer used, dropped in FileVersion 3)  |
| FileVersion < 3   | SegmentOffset           | int16            | ''1x1''            | gives the offset of the first "segment" (block) in volumes for protocol overlay (no longer used, dropped in FileVersion 3)  |
| DataType == 1     | VTCData                 | uint16           | ''NrOfVolumes-x-DimX-x-DimY-x-DimZ''  | uint16-based data with time being the innermost (fastest increasing) index/loop  |
| DataType == 2     | VTCData                 | single           | ''NrOfVolumes-x-DimX-x-DimY-x-DimZ''  | float-based data with time being the innermost (fastest increasing) index/loop  |