Siemens to ISMRMRD Converter

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

Installation

The converter can be easily installed in a conda environment using:

conda install -c ismrmrd siemens_to_ismrmrd

Alternatively, the Dockerfile in this repository demonstrates how to build the converter on Ubuntu 22.04.

Usage

siemens_to_ismrmrd

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

Example: To convert a Siemens dat file called meas_MID00832.dat:

$ siemens_to_ismrmrd -f meas_MID00832.dat -o converted.ismrmrd

If an output file is not specified with the -o flag, the converter will write the ISMRMRD data stream to stdout.

There are multiple options that configure how the converter behaves (see the -h/--help flag):

$ siemens_to_ismrmrd --help
Allowed options:
  -h [ --help ]          Produce HELP message
  -v [ --version ]       Prints converter version and ISMRMRD version
  -f [ --file ]          <SIEMENS dat file (defaults to stdin)>
  --VB                   <Input file is from VB instead of VD>
  -z [ --measNum ]       <Measurement number (with negative indexing)>
  -Z [ --allMeas ]       <Extract all measurements>
  --skipSyncData         <Skip syncdata (PMU) conversion>
  --attachTrajectory     <Attach trajectories using vds design>
  -m [ --pMap ]          <Choose embedded parameter map XML>
  -x [ --pMapStyle ]     <Choose embedded parameter stylesheet XSL>
  --user-map             <Provide a parameter map XML file>
  --user-stylesheet      <Provide a parameter stylesheet XSL file>
  -o [ --output ]        <ISMRMRD output file (defaults to stdout)>
  -l [ --list ]          <List embedded files>
  -e [ --extract ]       <Extract embedded file>
  -X [ --debug ]         <Debug XML flag>
  -F [ --flashPatRef ]   <FLASH PAT REF flag>
  -H [ --headerOnly ]    <Produce ISMRMRD XML header only>
  -B [ --bufferAppend ]  <Append Siemens protocol buffers (base64) to user
                         parameters>
  --studyDate            <User can supply study date, in the format of
                         yyyy-mm-dd>

Important files

There are three different types of files that affect the conversion:

• Siemens dat file:

  The file to be converted, specified using the option -f, or streamed via stdin. 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). Each measurement will be serialized sequentially to the output ISMRMRD stream.

  $ siemens_to_ismrmrd -f meas_MID00832.dat -o all_measurements.ismrmrd -Z

  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 extracted and converted:

  $ siemens_to_ismrmrd -f meas_MID00832.dat -o measurement_2.ismrmrd -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 converter in the debug mode (option -X).

  $ siemens_to_ismrmrd -f meas_MID00832.dat -o result.ismrmrd -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 converter 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 converter with -l option specified:

$ siemens_to_ismrmrd -l
Embedded Files:
    IsmrmrdParameterMap.xml
    IsmrmrdParameterMap.xsl
    IsmrmrdParameterMap_Siemens.xml
    IsmrmrdParameterMap_Siemens.xsl
    IsmrmrdParameterMap_Siemens_B0REF.xsl
    IsmrmrdParameterMap_Siemens_EPI.xsl
    IsmrmrdParameterMap_Siemens_EPI_FLASHREF.xsl
    IsmrmrdParameterMap_Siemens_NX.xsl
    IsmrmrdParameterMap_Siemens_PreZeros.xsl
    IsmrmrdParameterMap_Siemens_T1Mapping_SASHA.xsl
    IsmrmrdParameterMap_Siemens_VB17.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.

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 result.ismrmrd

   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.

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

3. 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.ismrmrd

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

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

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

ismrmrd_to_siemens

The ismrmrd_to_siemens converter is used to convert streams of ISMRMRD images into Siemens-compatible image data.

NOTE: This tool does NOT produce Siemens dat files.