doc/ctsim-textui.tex

   1 \chapter{The Command Line Interface}\label{ctsimtext}\index{ctsimtext}\index{Command line interface}
   2 \setheader{{\it CHAPTER \thechapter}}{}{}{\ctsimheadtitle}{}{{\it CHAPTER \thechapter}}%
   3 \ctsimfooter%
   4
   5 \ctsimtext\ is the master shell for all of the command-line tools. The
   6 command-line tools can perform most of the functions of the graphical
   7 shell. These command-line tools are especially appropriate for use on
   8 systems without graphical capability or for batch processing, shell scripting,
   9 and parallel processing.
  10
  11 \section{Starting ctsimtext}
  12 \ctsimtext\ can be invoked via three different
  13 methods.
  14 \begin{enumerate}\itemsep=3pt
  15 \item \ctsimtext\ can executed without any parameters. In that case,
  16 \ctsimtext\ offers a command-line to enter the function-names and
  17 their parameters. The output of the command is displayed. Further
  18 commands may be given to \ctsimtext. The shell is exited by the
  19 \texttt{quit} command. \ctsimtext\ uses the
  20 \urlref{readline}{http://www.gnu.org} library on UNIX and Linux platforms
  21 to provide command history processing.
  22
  23 \item \ctsimtext\ can also be called to
  24 execute a single command. This is especially useful for batch
  25 files containing multiple \ctsimtext\ commands. This is invoked by
  26 calling\\ \texttt{ctsimtext function-name parameters...}.
  27
  28 \item Using operating systems that support soft or hard linking of
  29 files (such as UNIX and Linux), the executable file \ctsimtext\ can
  30 be linked to the function names. This is automatically done by
  31 the installation program and the \texttt{rpm} manager. Thus, to use \ctsimtext\ with the
  32 function name \texttt{pjrec}, the below command can be executed:\\
  33 \hspace*{1.5cm}\texttt{pjrec parameters...} \\
  34 as a shortcut to the equivalent command \\
  35 \hspace*{1.5cm}\texttt{ctsimtext pjrec parameters...}
  36
  37 \end{enumerate}
  38
  39 \section{Parallel Processing}\label{ctsimtextlam}\index{Parallel processing}\index{MPI}\index{LAM}
  40 \ctsimtext\ can distribute it's processing over a cluster. Specifically,
  41 \ctsimtext\ supports the \urlref{LAM}{http://www.mpi.nd.edu/lam} version of
  42 the MPI environment. On platforms with LAM installed, a parallel version of
  43 \ctsimtext\ is created. The name of this program is \texttt{ctsimtext-lam}.
  44 The functions that take advantage of the parallel processing are:
  45
  46 \begin{itemize}\itemsep=0pt
  47 \item \texttt{phm2if}
  48 \item \texttt{phm2pj}
  49 \item \texttt{pjrec}
  50 \end{itemize}
  51
  52 This parallel processing version has been tested with excellent results on
  53 a 16-CPU \urlref{Beowulf}{http://www.beowulf.org} cluster.
  54
  55
  56 \section{if1}\label{if1}\index{if1}%
  57 Performs math functions on a single image. The commands works with
  58 both real and complex-valued images.
  59
  60 \usage
  61 \texttt{if1 input-filename output-filename [options...]}
  62
  63 \textbf{Options}
  64
  65 \begin{twocollist}
  66   \twocolitem{\doublehyphen{invert}}{Negate pixel values.}
  67   \twocolitem{\doublehyphen{log}}{Take natural logrithm of pixel values.}
  68   \twocolitem{\doublehyphen{exp}}{Take natural exponent of pixel values.}
  69   \twocolitem{\doublehyphen{sqr}}{Take square of pixel values.}
  70   \twocolitem{\doublehyphen{sqrt}}{Take square root of pixel values.}
  71 \end{twocollist}
  72
  73 \section{if2}\label{if2}\index{if2}%
  74 Performs math functions on a two images. The command works with both
  75 real and complex-valued images.
  76
  77 \usage
  78 \texttt{if2 input-filename1 input-filename2 output-filename [options...]}
  79
  80 \textbf{Options}
  81
  82 \begin{twocollist}
  83   \twocolitem{\doublehyphen{add}}{Add the two images.}
  84   \twocolitem{\doublehyphen{sub}}{Subtract the two images.}
  85   \twocolitem{\doublehyphen{multiply}}{Multiply the two images.}
  86   \twocolitem{\doublehyphen{divide}}{Divide the two images.}
  87   \twocolitem{\doublehyphen{comp}}{Statistically compare the two images. The standard
  88   \helpref{three distance measurements}{conceptimagecompare} are reported.}
  89   \twocolitem{\doublehyphen{column-plot n}}{Plot the values of a particular column. The plot file is saved to disk.}
  90   \twocolitem{\doublehyphen{row-plot n}}{Plot the values of a particular row. The plot file is saved to disk.}
  91 \end{twocollist}
  92
  93 \section{ifexport}\label{ifexport}\index{ifexport}%
  94 Export an image file to a standard graphics file.
  95
  96 \usage
  97 \texttt{ifexport input-filename output-filename [options...]}
  98
  99 \textbf{Options}
 100
 101 \begin{twocollist}
 102   \twocolitem{\doublehyphen{format}}{
 103   \begin{itemize}\itemsep=0pt
 104     \item \texttt{png} - Portable network graphics format. This is the default output format.
 105     \item \texttt{png16} - 16-bit PNG format.
 106     \item \texttt{pgm} - Portable graymap format, binary format.
 107     \item \texttt{pgmasc} - ASCII PGM format.
 108   \end{itemize}}
 109   \twocolitem{\doublehyphen{center}}{Set center of intensity window.
 110   \begin{itemize}\itemsep=0pt
 111     \item \texttt{median}
 112     \item \texttt{mode}
 113     \item \texttt{mean}
 114   \end{itemize}}
 115   \twocolitem{\doublehyphen{auto}}{Set half-width of intensity window as a multiple of the standard deviation.
 116   \begin{itemize}\itemsep=0pt
 117      \item \texttt{full}
 118      \item \texttt{std0.1}
 119      \item \texttt{std0.5}
 120      \item \texttt{std1}
 121      \item \texttt{std2}
 122      \item \texttt{std3}
 123   \end{itemize}}
 124   \twocolitem{\doublehyphen{scale}}{Set size of output image. A value of
 125   \texttt{1} is default and creates an output image the same size as the input image. A value of \texttt{2} will double the
 126   size of the output image.}
 127   \twocolitem{\doublehyphen{min}}{Set the minimum intensity value.}
 128   \twocolitem{\doublehyphen{max}}{Set the maximum intensity value.}
 129 \end{twocollist}
 130
 131 \section{ifinfo}\label{ifinfo}\index{ifinfo}%
 132
 133 Displays information about an image file. By default, history labels and image statistics are displayed.
 134
 135 \usage
 136 \texttt{ifinfo input-filename [options...]}
 137
 138 \textbf{Options}
 139
 140 \begin{twocollist}
 141   \twocolitem{\doublehyphen{no-labels}}{Suppress history labels.}
 142   \twocolitem{\doublehyphen{no-stats}}{Suppress image statistics.}
 143 \end{twocollist}
 144
 145 \section{phm2pj}\label{phm2pj}\index{phm2pj}%
 146 Simulates collection of X-rays data (projections) around a phantom object.
 147
 148 \usage
 149 \texttt{phm2pj projection-filename number-detectors number-views [options...]}
 150
 151 \textbf{Options}
 152
 153 \begin{twocollist}
 154 \twocolitem{\doublehyphen{phantom}}{Select a standard phantom.
 155 \begin{itemize}\itemsep=0pt
 156 \item \texttt{herman}
 157 \item \texttt{shepp-logan}
 158 \item \texttt{unit-pulse}
 159 \end{itemize}
 160 }
 161 \twocolitem{\doublehyphen{phmfile}}{Reads a user-created phantom file.}
 162
 163 \twocolitem{\doublehyphen{geometry}}{Sets the scanner geometry. Valid values are:
 164   \begin{itemize}\itemsep=0pt
 165     \item \texttt{parallel}
 166     \item \texttt{equiangular}
 167     \item \texttt{equilinear}
 168   \end{itemize}
 169 }
 170
 171 \twocolitem{\doublehyphen{nray}}{ Number of samples per each detector}
 172
 173 \twocolitem{\doublehyphen{rotangle}}{The rotation angle as a fraction of a circle.
 174 For parallel geometries use a rotation angle of \texttt{0.5} and for equilinear and equiangular
 175 geometries use a rotation angle of \texttt{1}. The default is to use to
 176 appropriate rotation angle based on the geometry.}
 177
 178 \twocolitem{\doublehyphen{view-ratio}}{Sets the field of view as a ratio of the diameter of the phantom.
 179     For normal scanning, the default value of \texttt{1.0} is optimal.}
 180
 181 \twocolitem{\doublehyphen{scan-ratio}}{Sets the length of scanning as a ratio of the view diameter.
 182     For normal scanning, the default value of \texttt{1.0} is optimal.}
 183
 184 \twocolitem{\doublehyphen{focal-length}}{Sets the distance between the radiation source
 185  and the center of the object as a ratio of the radius of the object.
 186    For parallel geometries, a value of \texttt{1.0} is optimal. For other
 187     geometries, this should be at least \texttt{2.0} to avoid artifacts. The default value is \texttt{2}.}
 188 \end{twocollist}
 189
 190
 191 \section{phm2if}\label{phm2if}\index{phm2if}%
 192 Generates a raster image file based on a phantom.
 193
 194 \usage
 195 \texttt{phm2if phantom-filename image-filename x-image-size y-image-size [options...]}
 196
 197 \textbf{Options}
 198
 199 \begin{twocollist}
 200   \twocolitem{\doublehyphen{nsamples}}{Number of samples in x and y directions per pixel}
 201   \twocolitem{\doublehyphen{view-ratio}}{Sets the view ratio. For normal scanning,
 202   the default value of \texttt{1.0} is optimal.}
 203 \end{twocollist}
 204
 205 \section{pj2if}\label{pj2if}\index{pj2if}%
 206 Convert a projection file into an image file where each row of the
 207 image file contains the projection data from a single view.
 208
 209 \usage
 210 \texttt{pj2if projection-filename image-filename [options...]}
 211
 212 \textbf{Options}
 213
 214 \begin{twocollist}
 215 \twocolitem{\doublehyphen{dump}}{Print all projection data to the console.}
 216 \end{twocollist}
 217
 218 \section{pjinfo}\label{pjinfo}\index{pjinfo}%
 219 Displays information about a projection file.
 220
 221 \usage
 222 \texttt{pjinfo projection-filename [options...]}
 223
 224 \textbf{Options}
 225
 226 \begin{twocollist}
 227   \twocolitem{\doublehyphen{binaryheader}}{Dump the binary header to the standard output.
 228   This option is only used when manually creating a composite projection file from
 229   several different projection files.}
 230   \twocolitem{\doublehyphen{binaryview}}{Dump binary view data to the standard output.
 231   This option is only used when manually creating a composite projection file from
 232   several different projection files.}
 233   \twocolitem{\doublehyphen{startview}}{Sets starting view to display. Default is \texttt{0}.}
 234   \twocolitem{\doublehyphen{endview}}{Sets ending view to display. Default is the last view.}
 235   \twocolitem{\doublehyphen{dump}}{Print all projection data to the console.}
 236 \end{twocollist}
 237
 238 \section{pjrec}\label{pjrec}\index{pjrec}%
 239 Reconstructs the interior of an object from a projection file.
 240
 241 \usage
 242 \texttt{pjrec projection-filename image-filename image-cols image-rows [options...]}
 243
 244 \textbf{Options}
 245
 246 \begin{twocollist}
 247 \twocolitemruled{\textbf{Parameter}}{\textbf{Options}}
 248 \twocolitem{\doublehyphen{filter}}{Selects which filter to apply to
 249 each projection. To properly reconstruct an image, this filter should
 250 consist of the the absolute value of distance from zero
 251 frequency optionally multiplied by a smoothing filter. The optimal
 252 filters to use are:
 253 \begin{itemize}\itemsep=0pt
 254 \item \texttt{abs\_bandlimit}
 255 \item \texttt{abs\_cosine}
 256 \item \texttt{abs\_hamming}
 257 \item \texttt{abs\_hanning}
 258 \end{itemize}
 259 } \twocolitem{\doublehyphen{filter-parameter}}{Sets the alpha level
 260 for Hamming window.  This parameter adjusts the smoothing of the Hamming
 261 filter and can range from \texttt{0} to \texttt{1}.
 262 At a setting of \texttt{1}, the Hamming filter is the same as the bandlimit filter.
 263 At a setting of \texttt{0.54}, the Hamming filter is the same as the Hanning
 264 window.}
 265
 266 \twocolitem{\doublehyphen{filter-method}}{Selects the filtering
 267 method. For large numbers of detectors, \texttt{rfftw} is optimal.
 268 For smaller numbers of detectors, \texttt{convolution} might be a
 269 bit faster.
 270 \begin{itemize}\itemsep=0pt
 271 \item \texttt{convolution}
 272 \item \texttt{fourier} - Uses simple Fourier transform.
 273 \item \texttt{fourier-table} - Optimizes Fourier transform by precalculating trigometric functions.
 274 \item \texttt{fftw} - Uses complex-valued Fourier transform with the \emph{fftw} library.
 275 \item \texttt{rfftw} - Uses optimized real/half-complex Fourier transform.
 276 \end{itemize}
 277 }
 278 \end{twocollist}
 279
 280 \begin{twocollist}
 281 \twocolitem{\doublehyphen{filter-generation}}{Selects the filter
 282 generation. With convolution, \texttt{direct} is the proper method
 283 to select. With any of the frequency methods,
 284 \texttt{inverse-fourier} is the best method.
 285 \begin{itemize}\itemsep=0pt
 286 \item \texttt{direct}
 287 \item \texttt{inverse-fourier}
 288 \end{itemize}
 289 }
 290
 291 \twocolitem{\doublehyphen{interpolation}}{Interpolation technique during backprojection.
 292 \texttt{cubic} has optimal quality when the
 293 data is smooth. Smooth data is obtained by taking many projections and/or
 294 using a smoothing filter. In the absence of smooth data, \texttt{linear} gives better results and
 295 is many times faster than cubic interpolation.
 296
 297 \begin{itemize}\itemsep=0pt
 298 \item \texttt{nearest} - No interpolation, selects nearest point.
 299 \item \texttt{linear} - Uses fast straight line interpolation.
 300 \item \texttt{cubic} - Uses cubic interpolating polynomial.
 301 \end{itemize}
 302 }
 303
 304 \twocolitem{\doublehyphen{backprojection}}{Selects the
 305 backprojection technique. A setting of \texttt{idiff} is optimal.
 306 \begin{itemize}\itemsep=0pt
 307 \item \texttt{trig} - Use trigometric functions at each image point.
 308 \item \texttt{table} - Use precalculated trigometric tables.
 309 \item \texttt{diff} - Use difference method to iterate within image.
 310 \item \texttt{idiff} - Use integer iteration technique.
 311 \end{itemize}
 312 }
 313
 314 \twocolitem{\doublehyphen{zeropad}}{Zeropad factor. A setting of
 315 \texttt{1} is optimal whereas a zeropad of \texttt{0} performs no zero padding.
 316 Settings greater than \texttt{1} perform additional zero padding, but without
 317 any significant output difference.}
 318
 319 \end{twocollist}