diff --git a/doc/source/devel/bv_formats.rst b/doc/source/devel/bv_formats.rst new file mode 100644 index 0000000000..50adbeccff --- /dev/null +++ b/doc/source/devel/bv_formats.rst @@ -0,0 +1,95 @@ +######################### +BrainVoyager file formats +######################### + +With notes on nibabel support. + +PR for some BrainVoyager support at https://github.com/nipy/nibabel/pull/216. + +******** +Overview +******** + +See : +* All files are little-endian byte order regardless of byte-order on the + machine writing the data; +* BV apparently provides a "BVQXtools" library for reading writing BV files in + MATLAB; + +.. _bv-internal-axes: + +*********************** +BV internal format axes +*********************** + +BV files have a internal format that has axes named `X`, `Y` and `Z`. Quoting +from the `VMR format definition`_:: + + BV X front -> back = Y in Tal space + BV Y top -> bottom = Z in Tal space + BV Z left -> right = X in Tal space + +Put another way |--| the correspondence of BV XYZ to Talairach axes is: + +* BV X corresponds to Anterior to Posterior; +* BV Y corresponds to Superior to Inferior; +* BV Z corresponds to Left to Right. + +or: + +* BV X -> Talairach -Y; +* BV Y -> Talairach -Z; +* BV Z -> Talairach X; + +Nice! + +***************** +Types of BV files +***************** + +There appear to be 38 BV file types at the time of writing of which 18 appear +to have a page of description on the `BV file format index page`_. + +Here are some examples of BV formats: + +* FMR |--| "FMR project files are simple text files containing the information + defining a functional project created from raw MRI data". This text file + contains meta-data about the functional time course data, stored in one or + more STC files. See the `FMR format definition`_. +* STC |--| "A STC file (STC = "slice time course") contains the functional + data (time series) of a FMR project." The time-course data of a 4D + ("single-slice") format STC file are stored on disk in + fastest-to-slowest-changing order: columns, rows, time, slice. STC files + can also contain the data for one single slice ("multi-slice format"), in + which case the data are in fast-to-slow order: columns, rows, time. This is + a raw data file where the relevant meta-data such as image size come from an + associated FMR format file. See `STC format definition`_; +* VTC |--| "A VTC file contains the functional data (time series) of one + experimental run (one functional scan) in the space of a 3D anatomical data + set (VMR), e.g. in Talairach space.". See `VTC format definition`_; + This is a different format to the STC (raw data in native-space) format. + The file is a header followed by ints or floats in + fastest-to-slowest-changing order of: time; BV X; BV Y; BV Z; where BV X, BV + Y, BV Z refer to the :ref:`bv-internal-axes`, and therefore Talairach -Y, + -Z, X. +* NR-VMP |--| "A native resolution volume map (NR-VMP) file contains + statistical results in 3D format.". See `NR-VMP format definition`_ +* AR-VMP |--| "An anatomical-resolution VMP (volume map) file contains + statistical results in 3D format." at anatomical scan resolution. See `AR-VMP format definition`_; +* VMR |--| 'high-resolution anatomical MR' - see `VMR format definition`_. +* MSK |--| mask file. Only documentation appears to be + http://www.brainvoyager.com/ubb/Forum8/HTML/000087.html +* SMP |--| 'surface map'. See `SMP format definition`_. Contains one or more + "maps", where a map is a ``NrOfVertices`` (number of vertices) length vector + of float64 values. + +.. _BV file format index page: http://support.brainvoyager.com/automation-aamp-development/23-file-formats.html +.. _AR-VMP format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/376-users-guide-23-the-format-of-ar-vmp-files.html +.. _NR-VMP format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/377-users-guide-23-the-format-of-nr-vmp-files.html +.. _VTC format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/379-users-guide-23-the-format-of-vtc-files.html. +.. _BV file format overview: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/382-developer-guide-26-file-formats-overview.html +.. _STC format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/384-developer-guide-26-the-format-of-stc-files.html +.. _vmr format definition: http://support.brainvoyager.com/automation-aamp-development/23-file-formats/385-developer-guide-26-the-format-of-vmr-files.html +.. _SMP format definition: : http://support.brainvoyager.com/automation-aamp-development/23-file-formats/476-the-format-of-smp-files.html. + +.. include:: ../links_names.txt