mrcalc: Docs: Combining mag&phase into complex data

cmd/mrcalc.cpp

@@ -248,7 +248,17 @@ EXAMPLES
              "This applies the spherical harmonic basis scaling factor: "
              "1.0/sqrt(4*pi), such that a single-tissue voxel containing the "
              "same intensities as the response function of that tissue "
-             "should contain the value 1.0.");
+             "should contain the value 1.0.")
+
+  + Example ("Produce a complex datatype image from Siemens magnitude & phase series",
+             "mrcalc DWI_MAG/ DWI_PHASE/ pi 4096 -div -mult -polar dwi_complex.mif",
+             "Phase images from Siemens scanners are typically not provided in Radians units, "
+             "but rather contain values in the range [-4096, +4094]. "
+             "This command usage pre-multiplies these phase values by (pi/4096) "
+             "to get them into units of Radians, "
+             "prior to using the -polar option "
+             "that combines magnitude & phase components at its input "
+             "to produce complex data.");
 
 ARGUMENTS
   + Argument ("operand", "an input image, intensity value, or the special keywords "

docs/reference/commands/mrcalc.rst

@@ -53,6 +53,12 @@ Example usages
 
     This applies the spherical harmonic basis scaling factor: 1.0/sqrt(4*pi), such that a single-tissue voxel containing the same intensities as the response function of that tissue should contain the value 1.0.
 
+-   *Produce a complex datatype image from Siemens magnitude & phase series*::
+
+        $ mrcalc DWI_MAG/ DWI_PHASE/ pi 4096 -div -mult -polar dwi_complex.mif
+
+    Phase images from Siemens scanners are typically not provided in Radians units, but rather contain values in the range [-4096, +4094]. This command usage pre-multiplies these phase values by (pi/4096) to get them into units of Radians, prior to using the -polar option that combines magnitude & phase components at its input to produce complex data.
+
 Options
 -------