siemens_to_ismrmrd convertor

The siemens_to_ismrmrd convertor is used to convert data from Siemens raw data format into ISMRMRD raw data format.

Dependencies:

HDF5 (version 1.8 or higher) libraries (http://www.hdfgroup.org/downloads/index.html)
Boost (http://www.boost.org/)
CodeSynthesis XSD (http://www.codesynthesis.com/products/xsd/)
TinyXML (http://sourceforge.net/projects/tinyxml/)
Libxslt (http://xmlsoft.org/libxslt/)
Libxml2 (http://xmlsoft.org/)
Xerces-C XML parser library (http://xerces.apache.org/xerces-c/)
Git (http://git-scm.com/)
Cmake build tool (http://www.cmake.org/)

Linux installation:

Installing dependencies:

The dependencies mentioned above should be included in most linux distributions. On Ubuntu, the user can install all required dependencies with:

$ sudo apt-get install g++ cmake git
$ sudo apt-get install libboost-all-dev xsdcxx libxerces-c-dev libhdf5-serial-dev h5utils hdf5-tools libtinyxml-dev libxml2-dev libxslt1-dev libpugixml-dev

Installing ISMRMRD:

Unpack the ismrmrd.tar.gz file or clone ISMRMRD from the repository:

$ tar -zxvf ismrmrd.tar.gz

$ git clone https://github.com/ismrmrd/ismrmrd.git

Install ISMRMRD

$ cd ismrmrd
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

Set the ISMRMRD environmental variable:

$ echo "export ISMRMRD_HOME=/usr/local/ismrmrd" >> $HOME/.bash_profile
$ source $HOME/.bash_profile

Installing siemens_to_ismrmrd:

Unpack the siemens_to_ismrmrd.tar.gz file or clone siemens_to_ismrmrd from the repository:

$ tar -zxvf siemens_to_ismrmrd.tar.gz

$ git clone https://github.com/ismrmrd/siemens_to_ismrmrd.git

Install siemens_to_ismrmrd:

$ cd siemens_to_ismrmrd
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

Short manual:

siemens_to_ismrmrd convertor is used to convert data from the Siemens raw data format to the ISMRMRD raw data format.

Using the convertor (basic case)

To use the convertor in the quick and simple way, the user only have to provide the Siemens dat file (option -f). Converted file will, by default, be stored in the output.h5 file.

Example of converting meas_MID00832.dat file:

$ siemens_to_ismrmrd -f meas_MID00832.dat

Using the convertor (advanced case)

There are multiple options that can be set in order to run the convertor in the more specific way. Running the convertor with no command line parameters (or using -h for help)

$ siemens_to_ismrmrd -h

will result in listing all allowed options:

Allowed options:
  -h [ --help ]           Produce HELP message
  -f [ --file ]           <SIEMENS dat file>
  -z [ --measNum ]        <Measurement number>
  -Z [ --allMeas ]        <All measurements flag>
  -M [ --multiMeasFile ]  <Multiple measurements in single file flag>
  -m [ --pMap ]           <Parameter map XML>
  -x [ --pMapStyle ]      <Parameter stylesheet XSL>
  --user-map              <Provide a parameter map XML file>
  --user-stylesheet       <Provide a parameter stylesheet XSL file>
  -o [ --output ]         <HDF5 output file>
  -g [ --outputGroup ]    <HDF5 output group>
  -l [ --list ]           <List embedded files>
  -e [ --extract ]        <Extract embedded file>
  -X [ --debug ]          <Debug XML flag>
  -F [ --flashPatRef ]    <FLASH PAT REF flag>

Important files

There are three different types of files that have important role in the process of conversion, and that the user should specify:

Siemens dat file:

This is the file that is being converted. The user must supply it using the option -f. Siemens dat file can be a Numaris/4 VB/VD/VE or Numaris/X file. In case of a file that contains multiple measurements, all measurements can be exported using the -Z option (default off) into separate files appended by the measurement number. In this example, multi-measurement file meas_MID00832.dat file has 2 measurements and two output files resulting_file_1.h5 and resulting_file_2.h5 are created:
```
$ siemens_to_ismrmrd -f meas_MID00832.dat -o resulting_file.h5 -Z
```
The "all measurements" -Z can be combined with the -M to create a multi-measurement output file where different measurements are stored in separate groups. In this example, multi-measurement file meas_MID00832.dat file has 2 measurements, stored in HDF5 groups dataset_1 and dataset_2 respectively in output file resulting_file.h5:
```
$ siemens_to_ismrmrd -f meas_MID00832.dat -o resulting_file.h5 -Z -M
```
A single measurement can be specified using the option -z (default value 1). Primary measurement data is usually stored as the last measurement, with earlier measurements being dependencies. In this example, the second measurement from the meas_MID00832.dat file is converted and stored in the resulting_file.h5 file:
```
$ siemens_to_ismrmrd -f meas_MID00832.dat -o resulting_file.h5 -z 2
```
Parameter map XML file:

This file is used to extract all parameters from the Siemens file measurement header buffer and to put them in the XML structured file (xml_raw.xml). File xml_raw.xml can be extracted and viewed by the user by running the convertor in the debug mode (option -X).
```
$ siemens_to_ismrmrd -f meas_MID00832.dat -o resulting_file.h5 -X
```
Parameter stylesheet XSL file:

This is a stylesheet file that defines parameters that are useful for the ISMRMRD header. It is applied on the xml_raw.xml file. After the stylesheet is applied, resulting XML file (processed.xml) is used to create ISMRMRD header. File processed.xml can also be extracted if using the convertor in the debug mode.

Embedded files

Multiple Parameter map XML and Parameter stylesheet XSL files are embedded in converter. To see the list of all the embedded files, the user should run the convertor with -l option specified:

$ siemens_to_ismrmrd -l

Embedded Files:
    IsmrmrdParameterMap.xml
    IsmrmrdParameterMap.xsl
    IsmrmrdParameterMap_Siemens.xml
    IsmrmrdParameterMap_Siemens.xsl
    IsmrmrdParameterMap_Siemens_EPI.xsl
    IsmrmrdParameterMap_Siemens_EPI_FLASHREF.xsl
    IsmrmrdParameterMap_Siemens_VB17.xml
    RadialParameterMap.xml
    SpiralParameterMap.xml
    SpiralParameterMap_MSH.xml

Any of these files can be extracted and saved locally by running the converter with -e option and specifying the file name. For example:

$ siemens_to_ismrmrd -e IsmrmrdParameterMap_Siemens.xsl
IsmrmrdParameterMap_Siemens.xsl successfully extracted.

Ways of providing XML/XSL files

There are three different ways of providing XML and XSL files to the converter:

The user can choose not to provide XML and XSL files explicitly, but to use the default files that are embedded in convertor.
```
$ siemens_to_ismrmrd -f meas_MID00832.dat -o resulting_file.h5
```
Default XML file for Numaris/4 (VB) is: IsmrmrdParameterMap_Siemens_VB17.xml.

Default XML file for Numaris/4 (VD+) and Numaris/X is: IsmrmrdParameterMap_Siemens.xml.

Default XSL file for Numaris/4 is: IsmrmrdParameterMap_Siemens.xsl.

Default XSL file for Numaris/X is: IsmrmrdParameterMap_Siemens_NX.xsl.
The user can choose to use XML and XSL files from the list of embedded files. The files should be supplied using options -m and -x.
```
$ siemens_to_ismrmrd -f meas_MID00832.dat -m IsmrmrdParameterMap_Siemens.xml -x IsmrmrdParameterMap_Siemens.xsl -o result.h5
```

The user can choose to provide custom XML and/or XSL files using the --user-map and --user-stylesheet options respectively:

$ siemens_to_ismrmrd -f meas_MID00832.dat --user-map IsmrmrdParameterMap_Siemens_modified.xml --user-stylesheet IsmrmrdParameterMap_Siemens_modified.xsl -o result.h5

For multi-measurement files, if only a single XML/XSL is provided, it is used for all measurements. A list of different XML/XSL files can also be specified for each measurement. A blank value can be used to use the default file (as above in point 1). In this example, multi-measurement file meas_MID00832.dat file has 2 measurements, with IsmrmrdParameterMap_Siemens.xml used for both measurements, IsmrmrdParameterMap_Siemens.xsl (default) for the first measurement, and IsmrmrdParameterMap_Siemens_modified for the second measurement:

$ siemens_to_ismrmrd -f meas_MID00832.dat -m IsmrmrdParameterMap_Siemens.xml --user-stylesheet ",IsmrmrdParameterMap_Siemens_modified.xsl" -o result.h5

The embedded files can be extracted from the convertor using option -e:

$ siemens_to_ismrmrd -e IsmrmrdParameterMap_Siemens.xml
$ siemens_to_ismrmrd -e IsmrmrdParameterMap_Siemens.xsl

ismrmrd / siemens_to_ismrmrd

readme