siemens_to_ismrmrd converter

---

The siemens_to_ismrmrd converter is used to convert Siemens raw data into the ISMRMRD format.

Differences to the original ISMRMRD project

• Coordinates are expressed in the physical coordinate system (XYZ) instead of the patient coordinate system (SAG/COR/TRA)
• Coordinates are in basic SI units (m)
• Phase increments to achieve field-of-view shifts are undone during the conversion, except for spiral sequences.
• New style sheets to map additional parameters
  • triggerToAcquisitionDelay (Trigger to ADC time: imaging scans )
  • skopeMinimalTR (Suggested minimal TR for skope monitoring system)
  • skopeInterleaveTR (Suggested interleave TR for skope monitoring system)
  • skopeAqDur (Suggested skope field probe acquisition duration)
  • skopeGradientFreeInterval (Gradient free interval for field probe excitation)

---

Dependancies:

• 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 dependancies:

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

Installing ISMRMRD:

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

$ tar -zxvf ismrmrd.tar.gz

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

Install ISMRMRD

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

Set the ISMRMRD environmental variable:

$ echo "export ISMRMRD_HOME=$HOME/Documents/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/SkopeMagneticResonanceTechnologies/siemens_to_ismrmrd.git

Install siemens_to_ismrmrd:

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

Windows 10 installation:

In order to simplify the installation of the converter on Windows, a PowerShell script is available here.

Prerequisites

• Windows 10
• 7-Zip installed
• Visual Studio 2017 Community installed

The script must be run with administrator rights. By default, the execution of scripts is not permitted on Windows, therefore run the following command in a PowerShell with administrator rights:

Set-ExecutionPolicy RemoteSigned

The script installs the ISMRMRD format, the siemens_to_ismrmrd converter and all other dependencies:

• cmake (v3.11.1)
• Git for Windows (2.17.0-64-bit)
• HDF5 (1.8.9)
• FFTW (3.3.5-dll64)
• BOOOST (1.67.0)
• iconv (1.14-win32-x86_64)
• libxml2 (2.9.3-win32-x86_64)
• libxslt (1.1.28-win32-x86_64)
• mingwrt (5.2.0-win32-x86_64)
• zlib (1.2.8-win32-x86_64)

---

Short manual:

Using the converter (basic case)

In the most basic case, only a Siemens dat file is neeeded as input for the converter (option -f). The file will, by default, be stored as output.h5 .

Example for converting the file meas_MID00832.dat:

$ siemens_to_ismrmrd -f meas_MID00832.dat

Using the converter (advanced case)

There are multiple options that can be set in order to perform the data conversion in a more specific way. To view all the available options, run the converter with no arguments (or use -h for help):

$ siemens_to_ismrmrd -h

produces:

Allowed options:
  -h [ --help ]          Produce HELP message
  -f [ --file ]          <SIEMENS dat file>
  -z [ --measNum ]       <Measurement number>
  -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>
  -i [ --ignoreSegments] <Ignore segments>

---

Important files

There are three different types of files that are important for the conversion and must be specified by the user:

• Siemens dat file:

  This is the file that is being converted. The user should supply it using the option -f. The Siemens dat file can be a VB or VD file. If the VD file contains multiple measurements, the user can specify which measurement to convert by using the option -z. The default value for this option is 1.

  In this example, the user is converting the second measurement contained in the meas_MID00832.dat file and storing the result 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 measurement header buffer and to put them in the XML structured file (xml_raw.xml). The file xml_raw.xml can be extracted and viewed by the user by running the converter 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 usefull for the ISMRMRD header. It is applied on the xml_raw.xml file. After the stylesheet is applied, the resulting XML file (processed.xml) is used to create the ISMRMRD header. The file processed.xml can also be extracted by using the converter in the debug mode.

Embedded files

Multiple parameter maps (XML) and parameter stylesheets (XSL) files are embedded in the converter. To see a list of all the embedded files, the user should run the converter with the option -l:

$ 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_EPI_skope.xsl
    IsmrmrdParameterMap_Siemens_PreZeros.xsl
    IsmrmrdParameterMap_Siemens_T1Mapping_SASHA.xsl
    IsmrmrdParameterMap_Siemens_VB17.xml
    IsmrmrdParameterMap_Siemens_skope.xsl

Any of these files can be extracted and saved locally by running the converter with the -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:

1. The user can choose not to provide XML and XSL files explicitly, but to use the default files that are embedded in the converter.

   $ siemens_to_ismrmrd -f meas_MID00832.dat -o resulting_file.h5

   Default XML file for the VB scan is: IsmrmrdParameterMap_Siemens_VB17.xml.
   Default XML file for the VD scan is: IsmrmrdParameterMap_Siemens.xml.
   Default XSL file is: IsmrmrdParameterMap_Siemens.xsl.

2. 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

3. The user can choose to extract embedded files from the converter (option -e)

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

   to modify them and to use the modified files (options --user-map and --user-stylesheet)

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