X-Git-Url: http://git.kpe.io/?p=ctsim.git;a=blobdiff_plain;f=doc%2Fctsim-textui.tex;h=f926e0211976d02959dbb055512230b8cb85861d;hp=9ee549b722bf0c2c987650b1cc0429d3a960a741;hb=64de9c0b821ceae63e8979815039ff97ba3a5edd;hpb=cc68f60c280df39d8cd14dfde3c1f5b736ede026

diff --git a/doc/ctsim-textui.tex b/doc/ctsim-textui.tex
index 9ee549b..f926e02 100644
--- a/doc/ctsim-textui.tex
+++ b/doc/ctsim-textui.tex
@@ -1,210 +1,319 @@
-\chapter{ctsimtext}\label{ctsimtext}\index{ctsimtext}%
-\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
-\setfooter{\thepage}{}{}{}{}{\thepage}%
+\chapter{The Command Line Interface}\label{ctsimtext}\index{ctsimtext}\index{Command line interface}
+\setheader{{\it CHAPTER \thechapter}}{}{}{\ctsimheadtitle}{}{{\it CHAPTER \thechapter}}%
+\ctsimfooter%
+
+\ctsimtext\ is the master shell for all of the command-line tools. The
+command-line tools can perform most of the functions of the graphical
+shell. These command-line tools are especially appropriate for use on
+systems without graphical capability or for batch processing, shell scripting,
+and parallel processing.
+
+\section{Starting ctsimtext}
+\ctsimtext\ can be invoked via three different
+methods.
+\begin{enumerate}\itemsep=3pt
+\item \ctsimtext\ can executed without any parameters. In that case,
+\ctsimtext\ offers a command-line to enter the function-names and
+their parameters. The output of the command is displayed. Further
+commands may be given to \ctsimtext. The shell is exited by the
+\texttt{quit} command. \ctsimtext\ uses the
+\urlref{readline}{http://www.gnu.org} library on UNIX and Linux platforms
+to provide command history processing.
+
+\item \ctsimtext\ can also be called to
+execute a single command. This is especially useful for batch
+files containing multiple \ctsimtext\ commands. This is invoked by
+calling\\ \texttt{ctsimtext function-name parameters...}.
+
+\item Using operating systems that support soft or hard linking of
+files (such as UNIX and Linux), the executable file \ctsimtext\ can
+be linked to the function names. This is automatically done by
+the installation program and the \texttt{rpm} manager. Thus, to use \ctsimtext\ with the
+function name \texttt{pjrec}, the below command can be executed:\\
+\hspace*{1.5cm}\texttt{pjrec parameters...} \\
+as a shortcut to the equivalent command \\
+\hspace*{1.5cm}\texttt{ctsimtext pjrec parameters...}
+
+\end{enumerate}
+
+\section{Parallel Processing}\label{ctsimtextlam}\index{Parallel processing}\index{MPI}\index{LAM}
+\ctsimtext\ can distribute it's processing over a cluster. Specifically,
+\ctsimtext\ supports the \urlref{LAM}{http://www.mpi.nd.edu/lam} version of
+the MPI environment. On platforms with LAM installed, a parallel version of
+\ctsimtext\ is created. The name of this program is \texttt{ctsimtext-lam}.
+The functions that take advantage of the parallel processing are:
 
-\ctsimtext\ is a master shell for all of the command-line utilities. 
+\begin{itemize}\itemsep=0pt
+\item \texttt{phm2if}
+\item \texttt{phm2pj}
+\item \texttt{pjrec}
+\end{itemize}
+
+This parallel processing version has been tested with excellent results on
+a 16-CPU \urlref{Beowulf}{http://www.beowulf.org} cluster.
+
+
+\section{if1}\label{if1}\index{if1}%
+Performs math functions on a single image. The commands works with
+both real and complex-valued images.
 
 \usage
-\ctsimtext\ can be executed without any parameters. In that case, \ctsimtext\ 
-offers a command-line to enter the function-names and their parameters. The output of the command is displayed. Further commands may be given to \ctsimtext. The shell is exited by the {\tt quit} command.
+\texttt{if1 input-filename output-filename [options...]}
 
-\ctsimtext\ can also be called to execute a single command. This is especially useful for batch files containing multiple \ctsimtext\ commands. This is invoked by calling \par
-{\tt ctsimtext function-name parameters...}.
+\textbf{Options}
 
-The available functions are:
+\begin{twocollist}
+  \twocolitem{\doublehyphen{invert}}{Negate pixel values.}
+  \twocolitem{\doublehyphen{log}}{Take natural logrithm of pixel values.}
+  \twocolitem{\doublehyphen{exp}}{Take natural exponent of pixel values.}
+  \twocolitem{\doublehyphen{sqr}}{Take square of pixel values.}
+  \twocolitem{\doublehyphen{sqrt}}{Take square root of pixel values.}
+\end{twocollist}
 
-\section{if1}\label{if1}\index{ctsimtext,if1}%
-Perfoms math functions on a single image.
+\section{if2}\label{if2}\index{if2}%
+Performs math functions on a two images. The command works with both
+real and complex-valued images.
 
 \usage
-\begin{itemize}\itemsep=0pt
-  \item --invert
-  \item --log
-  \item --exp
-  \item --sqr
-  \item --sqrt
-\end{itemize}
+\texttt{if2 input-filename1 input-filename2 output-filename [options...]}
 
-\section{if2}\label{if2}\index{ctsimtext,if2}%
-Perfoms math functions on a two images.
+\textbf{Options}
 
-\usage
-\begin{itemize}\itemsep=0pt
-  \item --add
-  \item --sub
-  \item --mul
-  \item --comp
-  \item --column-plot
-  \item --row-plot
-\end{itemize}
+\begin{twocollist}
+  \twocolitem{\doublehyphen{add}}{Add the two images.}
+  \twocolitem{\doublehyphen{sub}}{Subtract the two images.}
+  \twocolitem{\doublehyphen{multiply}}{Multiply the two images.}
+  \twocolitem{\doublehyphen{divide}}{Divide the two images.}
+  \twocolitem{\doublehyphen{comp}}{Statistically compare the two images. The standard
+  \helpref{three distance measurements}{conceptimagecompare} are reported.}
+  \twocolitem{\doublehyphen{column-plot n}}{Plot the values of a particular column. The plot file is saved to disk.}
+  \twocolitem{\doublehyphen{row-plot n}}{Plot the values of a particular row. The plot file is saved to disk.}
+\end{twocollist}
 
-\section{ifexport}\label{ifexport}\index{ctsimtext,ifexport}%
-Export an imagefile to a standard graphics file.
+\section{ifexport}\label{ifexport}\index{ifexport}%
+Export an image file to a standard graphics file.
 
 \usage
-\begin{itemize}\itemsep=0pt
-  \item --format
+\texttt{ifexport input-filename output-filename [options...]}
+
+\textbf{Options}
+
+\begin{twocollist}
+  \twocolitem{\doublehyphen{format}}{
   \begin{itemize}\itemsep=0pt
-    \item --pgm
-    \item --pgmasc
-    \item --png
-    \item --png16
-  \end{itemize}
-  \item --center
+    \item \texttt{png} - Portable network graphics format. This is the default output format.
+    \item \texttt{png16} - 16-bit PNG format.
+    \item \texttt{pgm} - Portable graymap format, binary format.
+    \item \texttt{pgmasc} - ASCII PGM format.
+  \end{itemize}}
+  \twocolitem{\doublehyphen{center}}{Set center of intensity window.
   \begin{itemize}\itemsep=0pt
-    \item median
-    \item mode
-    \item mean
-  \end{itemize}
-  \item --auto
+    \item \texttt{median}
+    \item \texttt{mode}
+    \item \texttt{mean}
+  \end{itemize}}
+  \twocolitem{\doublehyphen{auto}}{Set half-width of intensity window as a multiple of the standard deviation.
   \begin{itemize}\itemsep=0pt
-     \item --full
-     \item --std0.1
-     \item --std0.5
-     \item --std1
-     \item --std2
-     \item --std3
-  \end{itemize}
-  \item --scale
-  \item --min
-  \item --max
-\end{itemize}
+     \item \texttt{full}
+     \item \texttt{std0.1}
+     \item \texttt{std0.5}
+     \item \texttt{std1}
+     \item \texttt{std2}
+     \item \texttt{std3}
+  \end{itemize}}
+  \twocolitem{\doublehyphen{scale}}{Set size of output image. A value of
+  \texttt{1} is default and creates an output image the same size as the input image. A value of \texttt{2} will double the
+  size of the output image.}
+  \twocolitem{\doublehyphen{min}}{Set the minimum intensity value.}
+  \twocolitem{\doublehyphen{max}}{Set the maximum intensity value.}
+\end{twocollist}
 
-\section{ifinfo}\label{ifinfo}\index{ctsimtext,ifinfo}%
+\section{ifinfo}\label{ifinfo}\index{ifinfo}%
 
-Displays information about an imagefile.
+Displays information about an image file. By default, history labels and image statistics are displayed.
 
 \usage
-\begin{itemize}\itemsep=0pt
-  \item --labels
-  \item --no-labels
-  \item --stats
-  \item --no-stats
-  \item --help
-\end{itemize}
+\texttt{ifinfo input-filename [options...]}
 
-\section{phm2pj}\label{phm2pj}\index{ctsimtext,phm2pj}%
+\textbf{Options}
+
+\begin{twocollist}
+  \twocolitem{\doublehyphen{no-labels}}{Suppress history labels.}
+  \twocolitem{\doublehyphen{no-stats}}{Suppress image statistics.}
+\end{twocollist}
+
+\section{phm2pj}\label{phm2pj}\index{phm2pj}%
 Simulates collection of X-rays data (projections) around a phantom object.
 
 \usage
-phm2pj projection-file-name number-of-detectors number-of-views [options...]
-\begin{itemize}\itemsep=0pt
-  \item --phantom
-  Select a standard phantom 
-  \begin{itemize}\itemsep=0pt
-    \item herman
-    \item herman-b
-    \item shepp-logan
-    \item shepp-logan-b
-  \end{itemize}
+\texttt{phm2pj projection-filename number-detectors number-views [options...]}
+
+\textbf{Options}
 
-  \item --phmfile
-  Load a phantom definition definition
+\begin{twocollist}
+\twocolitem{\doublehyphen{phantom}}{Select a standard phantom.
+\begin{itemize}\itemsep=0pt
+\item \texttt{herman}
+\item \texttt{shepp-logan}
+\item \texttt{unit-pulse}
+\end{itemize}
+}
+\twocolitem{\doublehyphen{phmfile}}{Reads a user-created phantom file.}
 
-  \item --geometry
+\twocolitem{\doublehyphen{geometry}}{Sets the scanner geometry. Valid values are:
   \begin{itemize}\itemsep=0pt
-    \item parallel
-    \item equiangular
-    \item equilinear
+    \item \texttt{parallel}
+    \item \texttt{equiangular}
+    \item \texttt{equilinear}
   \end{itemize}
+}
 
-  \item --nray
-    Number of samples per each detector
+\twocolitem{\doublehyphen{nray}}{ Number of samples per each detector}
 
-  \item --rotangle
-    Sets the rotation amount as a multiple of pi. For parallel geometries use
-a rotation angle of 1 and for equilinear and equiangular geometries use a rotation angle of 2.
+\twocolitem{\doublehyphen{rotangle}}{The rotation angle as a fraction of a circle.
+For parallel geometries use a rotation angle of \texttt{0.5} and for equilinear and equiangular
+geometries use a rotation angle of \texttt{1}. The default is to use to
+appropriate rotation angle based on the geometry.}
 
-  \item --field-of-view
-    Sets the field of view as a ratio of the diameter of the phantom. For parallel geometries, using a value of 1.0 is fine. For other geometies, this should be at least 1.3 to avoid artifacts.
+\twocolitem{\doublehyphen{view-ratio}}{Sets the field of view as a ratio of the diameter of the phantom.
+    For normal scanning, the default value of \texttt{1.0} is optimal.}
 
-  \item --focal-length
-    Sets the distance of the radiation source and detectors from the center of the object as a ratio of the radius of the object. For parallel geometries, a value of 1.0 is fine. For other geometries, this should be at least 2.0 to avoid artifacts.
-\end{itemize}
+\twocolitem{\doublehyphen{scan-ratio}}{Sets the length of scanning as a ratio of the view diameter.
+    For normal scanning, the default value of \texttt{1.0} is optimal.}
 
-The Herman phantom is taken with permission from Gabor Hermans 1980 book\cite{HERMAN80}. The Shepp-Logan phantom was published in 1974\cite{SHEPP74}.
+\twocolitem{\doublehyphen{focal-length}}{Sets the distance between the radiation source
+ and the center of the object as a ratio of the radius of the object.
+   For parallel geometries, a value of \texttt{1.0} is optimal. For other
+    geometries, this should be at least \texttt{2.0} to avoid artifacts. The default value is \texttt{2}.}
+\end{twocollist}
 
-\section{phm2if}\label{phm2if}\index{ctsimtext,phm2if}%
-Converts a geometric phantom object into an imagefile. The size of the
-imagefile in pixels must be specified as well as the number of samples
-to average per pixel.
+
+\section{phm2if}\label{phm2if}\index{phm2if}%
+Generates a raster image file based on a phantom.
 
 \usage
-\begin{itemize}\itemsep=0pt
-  \item --nsamples
-\end{itemize}
+\texttt{phm2if phantom-filename image-filename x-image-size y-image-size [options...]}
+
+\textbf{Options}
 
-\section{pj2if}\label{pj2if}\index{ctsimtext,pj2if}%
-Convert a projection file into an imagefile.
+\begin{twocollist}
+  \twocolitem{\doublehyphen{nsamples}}{Number of samples in x and y directions per pixel}
+  \twocolitem{\doublehyphen{view-ratio}}{Sets the view ratio. For normal scanning,
+  the default value of \texttt{1.0} is optimal.}
+\end{twocollist}
+
+\section{pj2if}\label{pj2if}\index{pj2if}%
+Convert a projection file into an image file where each row of the
+image file contains the projection data from a single view.
 
 \usage
-\begin{itemize}\itemsep=0pt
-\item --help    Print brief online help
-\end{itemize}
+\texttt{pj2if projection-filename image-filename [options...]}
+
+\textbf{Options}
+
+\begin{twocollist}
+\twocolitem{\doublehyphen{dump}}{Print all projection data to the console.}
+\end{twocollist}
 
-\section{pjinfo}\label{pjinfo}\index{ctsimtext,pjinfo}%
+\section{pjinfo}\label{pjinfo}\index{pjinfo}%
 Displays information about a projection file.
 
 \usage
-\begin{itemize}\itemsep=0pt
-  \item --binaryheader
-  \item --binaryview
-  \item --startview
-  \item --endview
-  \item --dump
-\end{itemize}
+\texttt{pjinfo projection-filename [options...]}
+
+\textbf{Options}
 
-\section{pjrec}\label{pjrec}\index{ctsimtext,pjrec}%
+\begin{twocollist}
+  \twocolitem{\doublehyphen{binaryheader}}{Dump the binary header to the standard output.
+  This option is only used when manually creating a composite projection file from
+  several different projection files.}
+  \twocolitem{\doublehyphen{binaryview}}{Dump binary view data to the standard output.
+  This option is only used when manually creating a composite projection file from
+  several different projection files.}
+  \twocolitem{\doublehyphen{startview}}{Sets starting view to display. Default is \texttt{0}.}
+  \twocolitem{\doublehyphen{endview}}{Sets ending view to display. Default is the last view.}
+  \twocolitem{\doublehyphen{dump}}{Print all projection data to the console.}
+\end{twocollist}
+
+\section{pjrec}\label{pjrec}\index{pjrec}%
 Reconstructs the interior of an object from a projection file.
 
 \usage
+\texttt{pjrec projection-filename image-filename image-cols image-rows [options...]}
+
+\textbf{Options}
+
 \begin{twocollist}
-\twocolitemruled{{\bf Parameter}}{{\bf Options}}
-\twocolitem{{\bf --filter}}
-{Selects which filter to apply to each projection. To properly reconstruct an image, this filter should be multiplied 
-by the absolute value of distance from zero frequency.
+\twocolitemruled{\textbf{Parameter}}{\textbf{Options}}
+\twocolitem{\doublehyphen{filter}}{Selects which filter to apply to
+each projection. To properly reconstruct an image, this filter should
+consist of the the absolute value of distance from zero
+frequency optionally multiplied by a smoothing filter. The optimal
+filters to use are:
 \begin{itemize}\itemsep=0pt
-\item abs\_bandlimit
-\item abs\_cosine
-\item abs\_hamming
+\item \texttt{abs\_bandlimit}
+\item \texttt{abs\_cosine}
+\item \texttt{abs\_hamming}
+\item \texttt{abs\_hanning}
 \end{itemize}
-}
-\twocolitem{{\bf --filter-parameter}}{Sets the alpha level for Hamming
-  window. At setting of 0.54, this equals the Hanning window.}
-
-\twocolitem{{\bf --filter-method}}{Selects the filtering method. For large numbers of detectors, {\tt rfftw} is optimal. For smaller numbers of detectors, {\tt convolution} might be a bit faster. 
+} \twocolitem{\doublehyphen{filter-parameter}}{Sets the alpha level
+for Hamming window.  This parameter adjusts the smoothing of the Hamming
+filter and can range from \texttt{0} to \texttt{1}.
+At a setting of \texttt{1}, the Hamming filter is the same as the bandlimit filter.
+At a setting of \texttt{0.54}, the Hamming filter is the same as the Hanning
+window.}
+
+\twocolitem{\doublehyphen{filter-method}}{Selects the filtering
+method. For large numbers of detectors, \texttt{rfftw} is optimal.
+For smaller numbers of detectors, \texttt{convolution} might be a
+bit faster.
 \begin{itemize}\itemsep=0pt
-\item convolution
-\item fourier
-\item fourier\_table
-\item fftw
-\item rfftw
+\item \texttt{convolution}
+\item \texttt{fourier} - Uses simple Fourier transform.
+\item \texttt{fourier-table} - Optimizes Fourier transform by precalculating trigometric functions.
+\item \texttt{fftw} - Uses complex-valued Fourier transform with the \emph{fftw} library.
+\item \texttt{rfftw} - Uses optimized real/half-complex Fourier transform.
 \end{itemize}
 }
+\end{twocollist}
 
-\twocolitem{{\bf --filter-generation}}{Selects the filter generation. With convolution, {\tt direct} is the proper method to select. With any of the frequency methods, {\tt inverse-fourier} is the best method.
+\begin{twocollist}
+\twocolitem{\doublehyphen{filter-generation}}{Selects the filter
+generation. With convolution, \texttt{direct} is the proper method
+to select. With any of the frequency methods,
+\texttt{inverse-fourier} is the best method.
 \begin{itemize}\itemsep=0pt
-\item direct
-\item inverse-fourier
+\item \texttt{direct}
+\item \texttt{inverse-fourier}
 \end{itemize}
 }
-\twocolitem{{\bf --interpolation}}{Interpolation technique. {\tt linear} is optimal.
+
+\twocolitem{\doublehyphen{interpolation}}{Interpolation technique during backprojection.
+\texttt{cubic} has optimal quality when the
+data is smooth. Smooth data is obtained by taking many projections and/or
+using a smoothing filter. In the absence of smooth data, \texttt{linear} gives better results and
+is many times faster than cubic interpolation.
+
 \begin{itemize}\itemsep=0pt
-\item nearest
-\item linear
+\item \texttt{nearest} - No interpolation, selects nearest point.
+\item \texttt{linear} - Uses fast straight line interpolation.
+\item \texttt{cubic} - Uses cubic interpolating polynomial.
 \end{itemize}
-}    
-  \twocolitem{{\bf -backprojection}}{Selects the backprojection technique. A setting of {\tt idiff3} is optimal.
+}
+
+\twocolitem{\doublehyphen{backprojection}}{Selects the
+backprojection technique. A setting of \texttt{idiff} is optimal.
 \begin{itemize}\itemsep=0pt
-\item trig
-\item table
-\item diff
-\item diff2
-\item idiff2
-\item idiff3
+\item \texttt{trig} - Use trigometric functions at each image point.
+\item \texttt{table} - Use precalculated trigometric tables.
+\item \texttt{diff} - Use difference method to iterate within image.
+\item \texttt{idiff} - Use integer iteration technique.
 \end{itemize}
 }
-\twocolitem{{\bf --zeropad}}{ Zeropad factor. A setting of {\tt 1} is optimal.}
 
-\twocolitem{{\bf --preinterpolate}}{Selects preinterpolation interpolation technique and sets the preinterpolation factor. Currently, this is experimental and does not work well.}
+\twocolitem{\doublehyphen{zeropad}}{Zeropad factor. A setting of
+\texttt{1} is optimal whereas a zeropad of \texttt{0} performs no zero padding.
+Settings greater than \texttt{1} perform additional zero padding, but without
+any significant output difference.}
+
 \end{twocollist}