Merge pull request #966 from MRtrix3/update_documentation_for_tckconvert

tckconvert: update documentation for ascii handling, and add checks for output file

cmd/tckconvert.cpp

@@ -1,16 +1,16 @@
 /*
  * Copyright (c) 2008-2016 the MRtrix3 contributors
- * 
+ *
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/
- * 
+ *
  * MRtrix is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- * 
+ *
  * For more details, see www.mrtrix.org
- * 
+ *
  */
 
 
@@ -35,7 +35,16 @@ void usage ()
   + "Convert between different track file formats."
 
   + "The program currently supports MRtrix .tck files (input/output), "
-    "ascii text files (input/output), and VTK polydata files (output only).";
+    "ascii text files (input/output), and VTK polydata files (output only)."
+
+  + "Note that ascii files will be stored with one streamline per numbered file. "
+    "To support this, the command will use the multi-file numbering syntax, "
+    "where square brackets denote the position of the numbering for the files, "
+    "for example:"
+
+   + "$ tckconvert input.tck output-[].txt"
+
+   + "will produce files named output-0000.txt, output-0001.txt, output-0002.txt, ...";
 
   ARGUMENTS
   + Argument ("input", "the input track file.").type_text ()
@@ -61,7 +70,7 @@ void usage ()
       "if specified, the properties of this image will be used to convert "
       "track point positions from image coordinates (in mm) into real (scanner) coordinates.")
   +    Argument ("reference").type_image_in ();
-  
+
 }
 
 
@@ -127,7 +136,7 @@ class ASCIIReader: public ReaderInterface<float>
 {
 public:
     ASCIIReader(const std::string& file) {
-        auto num = list.parse_scan_check(file);
+      auto num = list.parse_scan_check(file);
     }
 
     bool operator() (Streamline<float>& tck) {
@@ -157,6 +166,8 @@ class ASCIIWriter: public WriterInterface<float>
     ASCIIWriter(const std::string& file) {
         count.push_back(0);
         parser.parse(file);
+        if (parser.ndim() != 1)
+          throw Exception ("output file specifier should contain one placeholder for numbering (e.g. output-[].txt)");
         parser.calculate_padding({1000000});
     }
 
@@ -206,7 +217,7 @@ void run ()
         throw Exception("Unsupported input file type.");
     }
 
-    
+
     // Writer
     std::unique_ptr<WriterInterface<float> > writer;
     if (has_suffix(argument[1], ".tck")) {
@@ -221,8 +232,8 @@ void run ()
     else {
         throw Exception("Unsupported output file type.");
     }
-    
-    
+
+
     // Tranform matrix
     transform_type T;
     T.setIdentity();
@@ -255,7 +266,7 @@ void run ()
         throw Exception("Transform options are mutually exclusive.");
     }
 
-    
+
     // Copy
     Streamline<float> tck;
     while ( (*reader)(tck) )

docs/reference/commands/dwinormalise.rst

@@ -22,7 +22,7 @@ Intensity normalise the b=0 signal within a supplied white matter mask
 Options
 -------
 
--  **-intensity value** normalise the b=0 signal to the specified value (Default: 1e+03)
+-  **-intensity value** normalise the b=0 signal to the specified value (Default: 1e+003)
 
 -  **-percentile value** define the percentile of the mask intensties used for normalisation. If this option is not supplied then the median value (50th percentile) will be normalised to the desired intensity value.
 

docs/reference/commands/mrconvert.rst

@@ -31,6 +31,15 @@ Options
 
 -  **-scaling values** specify the data scaling parameters used to rescale the intensity values. These take the form of a comma-separated 2-vector of floating-point values, corresponding to offset & scale, with final intensity values being given by offset + scale * stored_value. By default, the values in the input image header are passed through to the output image header when writing to an integer image, and reset to 0,1 (no scaling) for floating-point and binary images. Note that his option has no effect for floating-point and binary images.
 
+Modify generic header entries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+-  **-clear_property key** remove the specified key from the image header altogether.
+
+-  **-set_property key value** set the value of the specified key in the image header.
+
+-  **-append_property key value** append the given value to the specified key in the image header (this adds the value specified as a new line in the header value).
+
 Stride options
 ^^^^^^^^^^^^^^
 

docs/reference/commands/mrview.rst

@@ -114,6 +114,10 @@ Tractography tool options
 
 -  **-tractography.load tracks** Load the specified tracks file into the tractography tool.
 
+-  **-tractography.thickness value** Line thickness of tractography display, [-1.0, 1.0], default is 0.0.
+
+-  **-tractography.opacity value** Opacity of tractography display, [0.0, 1.0], default is 1.0.
+
 ODF tool options
 ^^^^^^^^^^^^^^^^
 

docs/reference/commands/tckconvert.rst

@@ -20,6 +20,12 @@ Convert between different track file formats.
 
 The program currently supports MRtrix .tck files (input/output), ascii text files (input/output), and VTK polydata files (output only).
 
+Note that ascii files will be stored with one streamline per numbered file. To support this, the command will use the multi-file numbering syntax, where square brackets denote the position of the numbering for the files, for example:
+
+$ tckconvert input.tck output-[].txt
+
+will produce files named output-0000.txt, output-0001.txt, output-0002.txt, ...
+
 Options
 -------
 

docs/reference/commands/tcksift2.rst

@@ -77,7 +77,7 @@ Options for controlling the SIFT2 optimisation algorithm
 
 -  **-max_coeff_step step** maximum change to a streamline's weighting coefficient in a single iteration (default: 1)
 
--  **-min_cf_decrease frac** minimum decrease in the cost function (as a fraction of the initial value) that must occur each iteration for the algorithm to continue (default: 2.5e-05)
+-  **-min_cf_decrease frac** minimum decrease in the cost function (as a fraction of the initial value) that must occur each iteration for the algorithm to continue (default: 2.5e-005)
 
 Standard options
 ^^^^^^^^^^^^^^^^

docs/reference/commands_list.rst

@@ -165,10 +165,10 @@ List of MRtrix3 commands
 
    commands/tcksample
 
-   commands/tcksift2
-
    commands/tcksift
 
+   commands/tcksift2
+
    commands/tckstats
 
    commands/tensor2metric