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 utilities. The
7 command-line utilities 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, batch processing, shell scripting,
10 and parallel processing with a Beowulf-type computer cluster.
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 than the equivalent command \\
35 \hspace*{1.5cm}\texttt{ctsimtext pjrec parameters...}
39 \section{Parallel Processing}\index{Parallel processing}
40 \ctsimtext\ can be used to spread 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 -\,-format }\emph{graphic-format} \texttt{ [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 pi.
174 For parallel geometries use a rotation angle of \texttt{1} and for equilinear and equiangular
175 geometries use a rotation angle of \texttt{2}. The default is to use to
176 appropriate rotation angle based on the geometry.}
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.}
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.}
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}.}
191 \section{phm2if}\label{phm2if}\index{phm2if}%
192 Generates rasterized image file based on a phantom.
195 \texttt{phm2if phantom-filename image-filename [options...]}
200 \twocolitem{\doublehyphen{nsamples}}{Number of samples in x \& y directions per pixel}
201 \twocolitem{\doublehyphen{view-ratio}}{Sets the view ration. For normal scanning,
202 the default value of \texttt{1.0} is optimal.}
205 \section{pj2if}\label{pj2if}\index{pj2if}%
206 Convert a projection file into an imagefile.
209 \texttt{pj2if projection-filename image-filename x-size y-size [options...]}
214 \twocolitem{\doublehyphen{dump}}{Print all projection data to the console.}
217 \section{pjinfo}\label{pjinfo}\index{pjinfo}%
218 Displays information about a projection file.
221 \texttt{pjinfo projection-filename [options...]}
226 \twocolitem{\doublehyphen{binaryheader}}{Dump the binary header to the standard output.
227 This option is only used when manually creating a composite projection file from
228 several different projection files.}
229 \twocolitem{\doublehyphen{binaryview}}{Dump binary view data to the standard output.
230 This option is only used when manually creating a composite projection file from
231 several different projection files.}
232 \twocolitem{\doublehyphen{startview}}{Sets starting view to display. Default is \texttt{0}.}
233 \twocolitem{\doublehyphen{endview}}{Sets ending view to display. Default is the last view.}
234 \twocolitem{\doublehyphen{dump}}{Print all projection data to the console.}
237 \section{pjrec}\label{pjrec}\index{pjrec}%
238 Reconstructs the interior of an object from a projection file.
241 \texttt{pjrec projection-filename image-filename image-cols image-rows [options...]}
246 \twocolitemruled{\textbf{Parameter}}{\textbf{Options}}
247 \twocolitem{\doublehyphen{filter}}{Selects which filter to apply to
248 each projection. To properly reconstruct an image, this filter should
249 be consist of the the absolute value of distance from zero
250 frequency optionally multiplied by a smoothing filter.
251 \begin{itemize}\itemsep=0pt
252 \item \texttt{abs\_bandlimit}
253 \item \texttt{abs\_cosine}
254 \item \texttt{abs\_hamming}
255 \item \texttt{abs\_hanning}
257 } \twocolitem{\doublehyphen{filter-parameter}}{Sets the alpha level
258 for Hamming window. This parameter adjusts the smoothing of the Hamming
259 filter and can range from \texttt{0} to \texttt{1}.
260 At a setting of \texttt{1}, the Hamming filter is the same as the bandlimit filter.
261 At a setting of \texttt{0.54}, the Hamming filter is the same as the Hanning
264 \twocolitem{\doublehyphen{filter-method}}{Selects the filtering
265 method. For large numbers of detectors, \texttt{rfftw} is optimal.
266 For smaller numbers of detectors, \texttt{convolution} might be a
268 \begin{itemize}\itemsep=0pt
269 \item \texttt{convolution}
270 \item \texttt{fourier} - Uses simple Fourier transform.
271 \item \texttt{fourier-table} - Optimizes Fourier transform by precalculating trigometric functions.
272 \item \texttt{fftw} - Uses complex-valued Fourier transform with the \emph{fftw} library.
273 \item \texttt{rfftw} - Uses optimized real/half-complex Fourier transform.
279 \twocolitem{\doublehyphen{filter-generation}}{Selects the filter
280 generation. With convolution, \texttt{direct} is the proper method
281 to select. With any of the frequency methods,
282 \texttt{inverse-fourier} is the best method.
283 \begin{itemize}\itemsep=0pt
284 \item \texttt{direct}
285 \item \texttt{inverse-fourier}
289 \twocolitem{\doublehyphen{interpolation}}{Interpolation technique.
290 \texttt{cubic} is optimal when the
291 data is smooth. Smooth data is obtained by taking many projections and/or
292 using a smoothing filter. In the absence of smooth data, \texttt{linear} gives better results and
293 is many times faster than cubic interpolation.
295 \begin{itemize}\itemsep=0pt
296 \item \texttt{nearest}
297 \item \texttt{linear}
302 \twocolitem{\doublehyphen{backprojection}}{Selects the
303 backprojection technique. A setting of \texttt{idiff} is optimal.
304 \begin{itemize}\itemsep=0pt
305 \item \texttt{trig} - Use trigometric functions at each image point.
306 \item \texttt{table} - Use precalculated trigometric tables.
307 \item \texttt{diff} - Use difference method to iterate within image.
308 \item \texttt{idiff} - Use integer iteration technique.
312 \twocolitem{\doublehyphen{zeropad}}{Zeropad factor. A setting of
313 \texttt{1} is optimal whereas a zeropad of \texttt{0} performs no zero padding.
314 Settings greater than \texttt{1} perform additional zero padding, but without
315 any significant output difference.}