1 \chapter{The Command Line Interface}\label{ctsimtext}\index{ctsimtext}\index{Command line interface}
2 \setheader{{\it CHAPTER \thechapter}}{}{}{\ctsimheadtitle}{}{{\it CHAPTER \thechapter}}%
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.
11 \section{Starting ctsimtext}
12 \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 to the equivalent command \\
35 \hspace*{1.5cm}\texttt{ctsimtext pjrec parameters...}
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:
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. 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.}
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 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.}
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 a raster image file based on a phantom.
195 \texttt{phm2if phantom-filename image-filename x-image-size y-image-size [options...]}
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.}
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.
210 \texttt{pj2if projection-filename image-filename [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 consist of the the absolute value of distance from zero
251 frequency optionally multiplied by a smoothing filter. The optimal
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}
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
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
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.
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}
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.
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.
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.
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.}