\chapter{The Command Line Interface}\label{ctsimtext}\index{ctsimtext}%
-\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
-\setfooter{\thepage}{}{}{}{\manver}{\thepage}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{\ctsimheadtitle}{}{{\it CHAPTER \thechapter}}%
+\ctsimfooter%
-\ctsimtext\ is a master shell for all of the command-line utilities.
+\ctsimtext\ is a master shell for all of the command-line utilities. The
+command-line utilities can perform most of the functions of the graphical
+shell. These command-line utilities are especially appropriate for use on
+systems without graphical capability, batch files, and parallel processing
+with a Beowulf-type computer cluster.
\usage \ctsimtext\ can be invoked via three different
methods.
-\begin{itemize}\itemsep=0pt
+\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.
+\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
be linked to the function names. This is automatically done by
the installation file for Linux. Thus, to use \ctsimtext\ with the
function name \texttt{pjrec}, the below command can be executed:\\
-\texttt{pjrec parameters...}
+\texttt{pjrec parameters...} \\
+as a shortcut rather than the equivalent command \\
+\texttt{ctsimtext pjrec parameters...}
-\end{itemize}
+\end{enumerate}
+
+\section{Parallel Processing}
+\ctsimtext\ can be used to spread 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
+\texttt{phm2if}, \texttt{phm2pj}, \texttt{pjrec}.
+
+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{ctsimtext,if1}%
-Perfoms math functions on a single image.
+
+\section{if1}\label{if1}\index{if1}%
+Performs math functions on a single image. The commands 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{if1 input-filename output-filename [options...]}
-\section{if2}\label{if2}\index{ctsimtext,if2}%
-Perfoms math functions on a two images.
+\textbf{Options}
+\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{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 -\,-add
- \item -\,-sub
- \item -\,-mul
- \item -\,-comp
- \item -\,-column-plot
- \item -\,-row-plot
-\end{itemize}
+\texttt{if2 input-filename1 input-filename2 output-filename [options...]}
+
+\textbf{Options}
+\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.}
+ \twocolitem{\doublehyphen{column-plot n}}{Plot the values of a particular column.}
+ \twocolitem{\doublehyphen{row-plot n}}{Plot the values of a particular row.}
+\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 -\,-format }\emph{graphic-format} \texttt{ [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{pgm} - Portable graymap format.
+ \item \texttt{pgmasc} - ASCII PGM format.
+ \item \texttt{png} - Portable network graphics format.
+ \item \texttt{png16} - 16-bit PNG 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.}
+ \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.
\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{labels}}{Display history labels.}
+ \twocolitem{\doublehyphen{no-labels}}{Suppress history labels.}
+ \twocolitem{\doublehyphen{stats}}{Display image statistics.}
+ \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 shepp-logan
- \item unit-pulse
- \end{itemize}
+\texttt{phm2pj projection-filename number-detectors number-views [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. The default is to use to
-appropriate rotation angle based on the geometry.
+\twocolitem{\doublehyphen{rotangle}}{The rotation angle as a multiple of pi.
+For parallel geometries use a rotation angle of \texttt{1} and for equilinear and equiangular
+geometries use a rotation angle of \texttt{2}. The default is to use to
+appropriate rotation angle based on the geometry.}
- \item -\,-view-ratio
- Sets the field of view as a ratio of the diameter of the phantom.
- For normal scanning, a value of 1.0 is fine.
+\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 -\,-scan-ratio
- Sets the length of scanning as a ratio of the view diameter.
- For normal scanning, a value of 1.0 is fine.
+\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.}
- \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{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.}
+\end{twocollist}
-The Herman phantom is taken with permission from Gabor Hermans 1980 book\cite{HERMAN80}. The Shepp-Logan phantom was published in 1974\cite{SHEPP74}.
-\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}%
+Converts a geometric phantom object into an imagefile.
\usage
-\begin{itemize}\itemsep=0pt
- \item -\,-nsamples
- \item -\,-view-ratio
-\end{itemize}
+\texttt{phm2if phantom-filename image-filename [options...]}
-\section{pj2if}\label{pj2if}\index{ctsimtext,pj2if}%
+\textbf{Options}
+\begin{twocollist}
+ \twocolitem{\doublehyphen{nsamples}}{Number of samples in x \& y directions per pixel}
+ \twocolitem{\doublehyphen{view-ratio}}{Sets the view ration. 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 imagefile.
\usage
-\begin{itemize}\itemsep=0pt
-\item -\,-help Print brief online help
-\end{itemize}
+\texttt{pj2if projection-filename image-filename x-size y-size [options...]}
-\section{pjinfo}\label{pjinfo}\index{ctsimtext,pjinfo}%
+\textbf{Options}
+\begin{twocollist}
+\twocolitem{\doublehyphen{dump}}{Print all projection data to the console.}
+\end{twocollist}
+
+\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}
+\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{ctsimtext,pjrec}%
+\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{\textbf{Parameter}}{\textbf{Options}}
-\twocolitem{\textbf{-\,-filter}}{Selects which filter to apply to
+\twocolitem{\doublehyphen{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.
\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}
\end{itemize}
-} \twocolitem{\textbf{-\,-filter-parameter}}{Sets the alpha level
-for Hamming
- window. At setting of 0.54, this equals the Hanning window.}
+} \twocolitem{\doublehyphen{filter-parameter}}{Sets the alpha level
+for Hamming window. At setting of \texttt{0.54}, this equals
+the Hanning window.}
-\twocolitem{\textbf{-\,-filter-method}}{Selects the filtering
+\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{\textbf{-\,-filter-generation}}{Selects the filter
+\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{\textbf{-\,-interpolation}}{Interpolation technique.
-\texttt{linear} is optimal.
+\twocolitem{\doublehyphen{interpolation}}{Interpolation technique.
+\texttt{cubic} is optimal 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 cubic
+\item \texttt{nearest}
+\item \texttt{linear}
+\item \texttt{cubic}
\end{itemize}
}
-\twocolitem{\textbf{-\,-backprojection}}{Selects the
+\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 idiff
+\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 math.
\end{itemize}
}
-\twocolitem{\textbf{-\,-zeropad}}{Zeropad factor. A setting of
-\texttt{1} is optimal.}
+\twocolitem{\doublehyphen{zeropad}}{Zeropad factor. A setting of
+\texttt{1} is optimal whereas a zeropad of \texttt{0} performs no zeropadding.}
\end{twocollist}
projects / ctsim.git / blobdiff