1 \chapter{The Command Line Interface}\label{ctsimtext}\index{ctsimtext}
2 \setheader{{\it CHAPTER \thechapter}}{}{}{\ctsimheadtitle}{}{{\it CHAPTER \thechapter}}%
5 \section{Overview}\index{Command line interface}
6 \ctsimtext\ is a master shell for all of the command-line tools. The
7 command-line tools can perform most of the functions of the graphical
8 shell. These command-line utilities are especially appropriate for use on
9 systems without graphical capability or for batch processing, shell scripting,
10 and parallel processing.
12 \usage \ctsimtext\ can be invoked via three different
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.
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...}.
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 rather to the equivalent command \\
35 \hspace*{1.5cm}\texttt{ctsimtext pjrec parameters...}
39 \section{Parallel Processing}\index{Parallel processing}
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:
46 \begin{itemize}\itemsep=0pt
52 This parallel processing version has been tested with excellent results on
53 a 16-CPU \urlref{Beowulf}{http://www.beowulf.org} cluster.
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.
61 \texttt{if1 input-filename output-filename [options...]}
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.}
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.
78 \texttt{if2 input-filename1 input-filename2 output-filename [options...]}
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.}
90 \twocolitem{\doublehyphen{row-plot n}}{Plot the values of a particular row.}
93 \section{ifexport}\label{ifexport}\index{ifexport}%
94 Export an image file to a standard graphics file.
97 \texttt{ifexport input-filename output-filename [options...]}
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.
109 \twocolitem{\doublehyphen{center}}{Set center of intensity window.
110 \begin{itemize}\itemsep=0pt
111 \item \texttt{median}
115 \twocolitem{\doublehyphen{auto}}{Set half-width of intensity window as a multiple of the standard deviation.
116 \begin{itemize}\itemsep=0pt
118 \item \texttt{std0.1}
119 \item \texttt{std0.5}
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.}
131 \section{ifinfo}\label{ifinfo}\index{ifinfo}%
133 Displays information about an image file. By default, history labels and image statistics are displayed.
136 \texttt{ifinfo input-filename [options...]}
141 \twocolitem{\doublehyphen{no-labels}}{Suppress history labels.}
142 \twocolitem{\doublehyphen{no-stats}}{Suppress image statistics.}
145 \section{phm2pj}\label{phm2pj}\index{phm2pj}%
146 Simulates collection of X-rays data (projections) around a phantom object.
149 \texttt{phm2pj projection-filename number-detectors number-views [options...]}
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}
161 \twocolitem{\doublehyphen{phmfile}}{Reads a user-created phantom file.}
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}
171 \twocolitem{\doublehyphen{nray}}{ Number of samples per each detector}
173 \twocolitem{\doublehyphen{rotangle}}{The rotation angle as a multiple of \latexonly{$\pi$.}
175 For parallel geometries use a rotation angle of \texttt{1} and for equilinear and equiangular
176 geometries use a rotation angle of \texttt{2}. The default is to use to
177 appropriate rotation angle based on the geometry.}
179 \twocolitem{\doublehyphen{view-ratio}}{Sets the field of view as a ratio of the diameter of the phantom.
180 For normal scanning, the default value of \texttt{1.0} is optimal.}
182 \twocolitem{\doublehyphen{scan-ratio}}{Sets the length of scanning as a ratio of the view diameter.
183 For normal scanning, the default value of \texttt{1.0} is optimal.}
185 \twocolitem{\doublehyphen{focal-length}}{Sets the distance between the radiation source
186 and the center of the object as a ratio of the radius of the object.
187 For parallel geometries, a value of \texttt{1.0} is optimal. For other
188 geometries, this should be at least \texttt{2.0} to avoid artifacts. The default value is \texttt{2}.}
192 \section{phm2if}\label{phm2if}\index{phm2if}%
193 Generates a raster image file based on a phantom.
196 \texttt{phm2if phantom-filename image-filename x-image-size y-image-size [options...]}
201 \twocolitem{\doublehyphen{nsamples}}{Number of samples in x and y directions per pixel}
202 \twocolitem{\doublehyphen{view-ratio}}{Sets the view ratio. For normal scanning,
203 the default value of \texttt{1.0} is optimal.}
206 \section{pj2if}\label{pj2if}\index{pj2if}%
207 Convert a projection file into an imagefile.
210 \texttt{pj2if projection-filename image-filename x-size y-size [options...]}
215 \twocolitem{\doublehyphen{dump}}{Print all projection data to the console.}
218 \section{pjinfo}\label{pjinfo}\index{pjinfo}%
219 Displays information about a projection file.
222 \texttt{pjinfo projection-filename [options...]}
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.}
238 \section{pjrec}\label{pjrec}\index{pjrec}%
239 Reconstructs the interior of an object from a projection file.
242 \texttt{pjrec projection-filename image-filename image-cols image-rows [options...]}
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 be consist of the the absolute value of distance from zero
251 frequency optionally multiplied by a smoothing filter.
252 \begin{itemize}\itemsep=0pt
253 \item \texttt{abs\_bandlimit}
254 \item \texttt{abs\_cosine}
255 \item \texttt{abs\_hamming}
256 \item \texttt{abs\_hanning}
258 } \twocolitem{\doublehyphen{filter-parameter}}{Sets the alpha level
259 for Hamming window. This parameter adjusts the smoothing of the Hamming
260 filter and can range from \texttt{0} to \texttt{1}.
261 At a setting of \texttt{1}, the Hamming filter is the same as the bandlimit filter.
262 At a setting of \texttt{0.54}, the Hamming filter is the same as the Hanning
265 \twocolitem{\doublehyphen{filter-method}}{Selects the filtering
266 method. For large numbers of detectors, \texttt{rfftw} is optimal.
267 For smaller numbers of detectors, \texttt{convolution} might be a
269 \begin{itemize}\itemsep=0pt
270 \item \texttt{convolution}
271 \item \texttt{fourier} - Uses simple Fourier transform.
272 \item \texttt{fourier-table} - Optimizes Fourier transform by precalculating trigometric functions.
273 \item \texttt{fftw} - Uses complex-valued Fourier transform with the \emph{fftw} library.
274 \item \texttt{rfftw} - Uses optimized real/half-complex Fourier transform.
280 \twocolitem{\doublehyphen{filter-generation}}{Selects the filter
281 generation. With convolution, \texttt{direct} is the proper method
282 to select. With any of the frequency methods,
283 \texttt{inverse-fourier} is the best method.
284 \begin{itemize}\itemsep=0pt
285 \item \texttt{direct}
286 \item \texttt{inverse-fourier}
290 \twocolitem{\doublehyphen{interpolation}}{Interpolation technique during backprojection.
291 \texttt{cubic} has optimal quality when the
292 data is smooth. Smooth data is obtained by taking many projections and/or
293 using a smoothing filter. In the absence of smooth data, \texttt{linear} gives better results and
294 is many times faster than cubic interpolation.
296 \begin{itemize}\itemsep=0pt
297 \item \texttt{nearest}
298 \item \texttt{linear}
303 \twocolitem{\doublehyphen{backprojection}}{Selects the
304 backprojection technique. A setting of \texttt{idiff} is optimal.
305 \begin{itemize}\itemsep=0pt
306 \item \texttt{trig} - Use trigometric functions at each image point.
307 \item \texttt{table} - Use precalculated trigometric tables.
308 \item \texttt{diff} - Use difference method to iterate within image.
309 \item \texttt{idiff} - Use integer iteration technique.
313 \twocolitem{\doublehyphen{zeropad}}{Zeropad factor. A setting of
314 \texttt{1} is optimal whereas a zeropad of \texttt{0} performs no zero padding.
315 Settings greater than \texttt{1} perform additional zero padding, but without
316 any significant output difference.}