r538: no message

[ctsim.git] / doc / ctsim-gui.tex

diff --git a/doc/ctsim-gui.tex b/doc/ctsim-gui.tex
index 8d675de29f81518b0ad58ac0b034f220553023bd..e76f4457169c4fa1642e8dd033378ae175f6bb24 100644 (file)
--- a/doc/ctsim-gui.tex
+++ b/doc/ctsim-gui.tex
@@ -1,36 +1,30 @@
 \chapter{The Graphical User Interface}\label{ctsim}\index{ctsim}%
 \chapter{The Graphical User Interface}\label{ctsim}\index{ctsim}%

-\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
-\setfooter{\thepage}{}{}{}{}{\thepage}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{\ctsimheadtitle}{}{{\it CHAPTER \thechapter}}%
+\ctsimfooter%

 
 

-\section{Overview}
+
+\section{Overview}\index{Graphical shell}

 \ctsim\ is the graphical shell for the CTSim project. It utilizes
 using the \urlref{wxWindows}{http://www.wxwindows.org} library for
 cross-platform compatibility. The graphical shell is compatible
 with Microsoft Windows, \urlref{GTK}{http://www.gtk.org}, and
 \urlref{Motif}{http://www.openmotif.org} graphical environments.
 \ctsim\ is the graphical shell for the CTSim project. It utilizes
 using the \urlref{wxWindows}{http://www.wxwindows.org} library for
 cross-platform compatibility. The graphical shell is compatible
 with Microsoft Windows, \urlref{GTK}{http://www.gtk.org}, and
 \urlref{Motif}{http://www.openmotif.org} graphical environments.

-This graphical includes all of the functionality of the
-command-line interface \helprefn{\ctsimtext}{ctsimtext} as well as
-great image processing and visualization features.
-
-\ctsim\ can open projection files, image files, phantom files, and
-plotfiles.

 
 

-\usage \texttt{ctsim [files to open...]
+\usage \texttt{ctsim [files to open...]}

 
 You can invoke \ctsim\ by itself on the command line, or include
 
 You can invoke \ctsim\ by itself on the command line, or include

-any number of files that you want \ctsim\ to automatically open.
+on the command-line any number of files that you want \ctsim\ to
+automatically open. \ctsim\ can open projection files, image
+files, phantom files, and plot files.

 
 

-\section{File Types Support}

 
 

-Phantom and plot files are stored as ASCII text. In contrast,
-image and projection files are stored in binary format. \ctsim\
-incorporates logic so that binary files are cross-platform
-compatible between both little and big endian architectures.
+\section{File Types}\index{File types}

 
 \subsection{Phantom}
 Besides loading phantom files from the disk, the Herman and
 Shepp-Logan phantoms are built-in to \ctsim. Phantom files can be
 
 \subsection{Phantom}
 Besides loading phantom files from the disk, the Herman and
 Shepp-Logan phantoms are built-in to \ctsim. Phantom files can be

-read and stored on the disk. However, a text editor is required to
+read and stored on the disk. Phantom files are stored in a simple
+ASCII format. A text editor is required to

 create and edit these files.
 
 \subsection{Image}
 create and edit these files.
 
 \subsection{Image}


@@ -41,35 +35,173 @@ processed by Fourier transforms. As you might expect,
 complex-valued images are twice the size of real-valued images
 since both a real and imaginary component need to be store.
 
 complex-valued images are twice the size of real-valued images
 since both a real and imaginary component need to be store.
 

+Images files can also store any number of text labels. \ctsim\ uses
+these labels for storing history information regarding
+the creation and modifications of images.
+
+When complex-valued images are viewed on the screen, only the real
+component is displayed.
+

 \subsection{Projection}
 \subsection{Projection}

-Projection files are created from Phantom files during the projection process.
-Numerous options are available for creation of the these files.
+Projection files are created from Phantom files during the
+projection process. Numerous options are available for the
+creation of the these files. The files are stored in a binary
+format with cross-platform compatibility on little and big endian
+architectures.

 
 \subsection{Plot}
 Plot files are created by \ctsim\ during analysis of image files.
 They can be read and stored on the disk. They are stored as ASCII
 files for easy cross-platform support.
 
 
 \subsection{Plot}
 Plot files are created by \ctsim\ during analysis of image files.
 They can be read and stored on the disk. They are stored as ASCII
 files for easy cross-platform support.
 

+\section{Global Menu Commands}
+These commands are present on the menus of all windows.
+
+\subsection{File - Create Phantom}\index{Create phantom dialog}
+This command brings up a dialog box showing the phantoms that are preprogrammed
+into \ctsim. After selecting one of these phantoms, the new window with that
+phantom will be generated. The preprogrammed phantoms are:
+
+\begin{twocollist}
+\twocolitem{\textbf{Herman}}{The Herman head phantom\cite{HERMAN80}}
+\twocolitem{\textbf{Shepp-Logan}}{The head phantom of Shepp \& Logan\cite{SHEPP74}}
+\twocolitem{\textbf{Unit pulse}}{A phantom that has a value of \texttt{1} for the
+center of the phantom and \texttt{0} everywhere else.}
+\end{twocollist}
+
+\subsection{File - Create Filter}\index{Create filter dialog}
+This command brings up a dialog box showing the pre-programmed filters
+of \ctsim. This command will create a 2-dimensional image of the selected filter.
+The center of the filter is at the center of the image.
+
+These filters can be created in their natural frequency domain or in their spatial domain.
+\begin{twocollist}
+\twocolitem{\textbf{Filter}}{Selects the filter to generate.}
+\twocolitem{\textbf{Domain}}{Selects either the \texttt{Frequency} or \texttt{Spatial} domains. The filters have the
+frequency domain as their natural domain.}
+\twocolitem{\textbf{X Size}}{Number of columns in the output image.}
+\twocolitem{\textbf{Y Size}}{Number of rows in the output image.}
+\twocolitem{\textbf{Hamming Parameter}}{Sets the parameter for the Hamming filter.}
+\twocolitem{\textbf{Bandwidth}}{Sets the bandwidth of the filter.}
+\twocolitem{\textbf{Axis (input) Scale}}{Sets the scale for the filter input. By default, the input to the filter is
+the distance in pixels from the center of the image. By changing this value, one can set a scale the input to the filter.}
+\twocolitem{\textbf{Filter (output) Scale)}}{Multiplies the output of the filter by this amount. By default, the filter has a maximum
+value of \texttt{1}.}
+\end{twocollist}
+
+\subsection{File - Preferences}\index{Preferences}
+This command displays a dialog box that allows users to control
+the behavior of \ctsim. These options are saved across \ctsim\ sessions.
+Under Microsoft Windows environments, they are stored in the registry.
+On UNIX and Linux environments, they are stored in the users home
+directory with the filename of \texttt{.ctsim}.
+
+\begin{twocollist}
+\twocolitem{\textbf{Advanced options}}{By default, this is turned off in new installations.
+These advanced options are required for normal simulations. When \texttt{Advanced
+Options} is set, \ctsim\ will display more options during scanning of programs and
+the reconstruction of projections.}
+
+\twocolitem{\textbf{Ask before deleting new documents}}{By default, this is turned on in
+new installations. With this option set, \ctsim\ will ask before closing
+documents that have been modified or never saved on disk. By turning off
+this option, \ctsim\ will never ask if you want to save a file -- you'll
+be responsible for saving any files that you create.}
+
+\end{twocollist}
+
+\subsection{File - Open}
+This command opens a file section dialog box. Of special consideration
+is the \texttt{File Type} combo box on the bottom of the dialog. You need
+to select that to the type of file that you wish to open.
+
+\subsection{File - Save}
+This command saves the contents of the active window. If the window hasn't
+been named, a dialog box will open asking for the file name to use.
+
+\subsection{File - Close}
+As one would expect, this closes the active window.
+
+\subsection{File - Save As}
+Allows the saving of the contents of a window to any filename.
+
+\subsection{Help - Contents}
+This command displays the online help.
+
+\subsection{Help - About}
+This command shows the version number of \ctsim.
+
+

 \section{Phantom Menus}
 
 \section{Phantom Menus}
 

-\subsection{Rasterize Dialog}
+\subsection{Properties}
+Displays the properties of a phantom which includes:
+
+\begin{itemize}\itemsep=0pt
+\item Overall dimensions of a phantom
+\item A list of all component phantom elements
+\end{itemize}
+
+\subsection{Rasterize Dialog}\index{Rasterize}

 This creates an image file from a phantom. Technically, it
 converts the phantom from a vector (infinite resolution) object
 into a 2-dimension array of floating-point pixels. The parameters
 to set are:
 
 \begin{twocollist}
 This creates an image file from a phantom. Technically, it
 converts the phantom from a vector (infinite resolution) object
 into a 2-dimension array of floating-point pixels. The parameters
 to set are:
 
 \begin{twocollist}

-%\twocolitemruled{\textbf{Parameter}}{\textbf{Options}}
-\twocolitem{\texttt{X size}}{Number of columns in image file}
-\twocolitem{\texttt{Y size}}{Number of rows in image file}
-\twocolitem{\texttt{Samples per pixel}}{Numbers of samples taken
+\twocolitemruled{\textbf{Parameter}}{\textbf{Options}}
+\twocolitem{\textbf{X size}}{Number of columns in image file}
+\twocolitem{\textbf{Y size}}{Number of rows in image file}
+\twocolitem{\textbf{Samples per pixel}}{Numbers of samples taken

 per pixel in both the x and y directions. For example, if the
 \texttt{Samples per pixel} is set to \texttt{3}, then for every
 per pixel in both the x and y directions. For example, if the
 \texttt{Samples per pixel} is set to \texttt{3}, then for every

-pixel in the image file 9 samples (3 x 3) are averaged.}
+pixel in the image file 9 samples ($3\times3$) are averaged.}

 \end{twocollist}
 
 \end{twocollist}
 

-\subsection{Projection Dialog}
-This creates a projection file from a phantom.
+\subsection{Projection Dialog}\index{Projection collection}
+This creates a projection file from a phantom. The options
+available when collecting projections are:
+
+\begin{twocollist}
+\twocolitem{\textbf{Geometry}}{Selects the scanner geometry.
+  \begin{itemize}\itemsep=0pt
+    \item \texttt{Parallel}
+    \item \texttt{Equiangular}
+    \item \texttt{Equilinear}
+  \end{itemize}}
+\twocolitem{\textbf{Number of detectors}}{Sets the number of
+detectors in the detector array.}
+
+\twocolitem{\textbf{Number of views}}{Sets the number of views
+collected}
+
+\twocolitem{\textbf{Samples per detector}}{Sets the number of
+samples collected for each detector}
+
+\twocolitem{\textbf{View Ratio}}{Sets the field of view as a ratio
+of the diameter of the phantom.  For normal scanning, use a value of
+\texttt{1.0}.}
+
+\twocolitem{\textbf{Scan Ratio}}{Sets the length of scanning as a
+ratio of the view diameter. For normal scanning, use a value of \texttt{1.0}.}
+
+\twocolitem{\textbf{Focal length ratio}}{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, use a value of \texttt{1.0}. For other
+geometries, this should be at least \texttt{2.0} to avoid artifacts.}
+\end{twocollist}
+
+\subsection{Advanced Options}
+\begin{twocollist}
+\twocolitem{\textbf{Rotation Angle}}{Sets the rotation amount 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}. Using any other rotation angle will lead to artifacts.}
+\end{twocollist}
+
+

 
 \section{Image Menus}
 \subsection{File - Properties}
 
 \section{Image Menus}
 \subsection{File - Properties}


@@ -80,47 +212,241 @@ Properties of image files include
   \item Image file labels
 \end{itemize}
 
   \item Image file labels
 \end{itemize}
 

-\subsection{View}
+\subsection{File - Export}\index{Image export}
+This command allows for exporting image files to a standard
+graphics file format. This is helpful when you want to take an
+image and import it into another application. The current
+\helprefn{intensity scale}{intensityscale} is used when exporting
+the file. The support file formats are:
+
+\begin{twocollist}
+\twocolitem{\textbf{PNG}}{Portable Network Graphics format. This uses 8-bits or
+256 shades of gray.}
+\twocolitem{\textbf{PNG-16}}{This is a 16-bit version of PNG which allows for
+65536 shades of gray.}
+\twocolitem{\textbf{PGM}}{Portable Graymap format. This is a common format used on
+UNIX systems.}
+\twocolitem{\textbf{PGM}}{ASCII version of PGM.}
+\end{twocollist}
+
+
+\subsection{View}\label{intensityscale}

 These options are for change the intensity scale for viewing the image.
 They do not change the image data.
 These options are for change the intensity scale for viewing the image.
 They do not change the image data.

+\subsubsection{Set}
+This command brings up a dialog box that allows you to set the lower
+and upper intensities to display.
+
+\subsubsection{Auto}
+This command brings up a dialog box that allows \ctsim\ to automatically
+make an intensity scale. The options that \ctsim\ needs to make this
+automatic scale are:
+
+\begin{twocollist}
+\twocolitem{\textbf{Center}}{This sets the center of the intensity scale. Currently,
+\ctsim\ allows you to use either the mean, mode, or median of the image
+as the center of the intensity scale.}
+
+\twocolitem{\textbf{Width}}{This sets the half-width of the intensity scale. The width
+is specified as a ratio of the standard deviation.}
+\end{twocollist}
+
+As an example, if \texttt{median} is selected as the center and
+\texttt{0.5} is selected as the width, the the minimum intensity will
+be \texttt{median - 0.5 x standard deviation} and the maximum will be
+\texttt{median + 0.5 x standard deviation}.
+
+\subsubsection{Full}
+This resets the intensity scale to the full scale of the image.

 
 \subsection{Image}
 These commands create a new image based upon the current image,
 and for some commands, also a comparison image.
 
 
 \subsection{Image}
 These commands create a new image based upon the current image,
 and for some commands, also a comparison image.
 

-\subsection{Filter}
-These commands filter image.
+\subsubsection{Add, Subtract, Multiply, Divide}
+These are simple arithmetic operations. \ctsim\ will display a dialog
+box showing all of the currently opened image files that are the
+same size of the active image. After selecting a compatible image,
+\ctsim\ will perform the arithmetic operation on the two images and
+make a new result image.
+
+\subsubsection{Image Size}
+This command will generate a new window with the current image scaled to
+any size. Currently, \texttt{bilinear} interpolation provides the best
+image quality.
+
+\subsubsection{3-D Conversion}
+Generates a 3-dimensional view of the current phantom. This view can be
+rotated in three dimensions. The left and right arrow control the z-axis
+rotation, the up and down arrows control the x-axis rotation. The y-axis
+rotation is controlled by the \texttt{T} and \texttt{Y} keys. Other options
+include:

 
 

-\subsection{Anaylze}
+\begin{itemize}
+\item Surface plot
+\item Smooth shading
+\item Lighting on or off
+\item Color scale
+\end{itemize}
+
+\subsection{Filter}\index{Image filter}
+These commands filter and modify the image.
+
+\subsubsection{Arithmetic}
+These are simple arithmetic functions that should be self explanatory.
+
+\subsubsection{Frequency Based}
+This commands allow the Fourier and inverse Fourier transformations of
+images. By default, the transformations will automatically convert
+images from Fourier to natural order as expected. For example, \texttt{2-D FFT}
+will transform the points into natural order after the Fourier transform.
+Similarly the inverse, \texttt{2-D IFFT}, will reorder the points from
+natural order to Fourier order before applying the inverse Fourier transformation.
+
+As you would expect, images that undergo frequency filtering will be complex-valued
+images. Normally, only the real component is shown by \ctsim. However, \ctsim\ does
+have options for converting a complex-valued image into a real-valued image via
+the \texttt{Magnitude} and \texttt{Phase} filtering commands.
+
+\subsection{Analyze}

 These commands are used for analyzing an image.
 
 These commands are used for analyzing an image.
 

+\subsubsection{Plotting}
+The commands plot rows and columns of images. There are also commands
+that perform FFT and IFFT transformations prior to plotting.
+
+\subsubsection{Image Comparison}
+This command performs statistical comparisons between two images. An option
+also exists for generating a difference image from the two input images.
+
+There are also commands for plotting rows and columns from two images on
+a single plot. This is quite helpful when comparing a phantom to a reconstruction.
+

 \section{Projection Menus}
 \section{Projection Menus}

-\subsection{Process - Convert Polar Dialog}\label{convertpolardialog}
-The parameters are \texttt{xsize}, \texttt{ysize}, and \texttt{interpolation}.
-The \texttt{xsize} and \texttt{ysize} parameters set the size of the
-resulting image file. The \texttt{interpolation} parameter selects the
-interpolation method. Currently, the \texttt{bilinear} option provides
-the highest quality interpolation.
+
+\subsection{File - Properties}
+The displayed properties include:
+
+\begin{itemize}
+\item Number of detectors in the projections
+\item Number of views
+\item The variables used when generating the projections from the phantom
+\end{itemize}
+
+\subsection{Process - Convert Polar Dialog}\label{convertpolardialog}\index{Polar conversion}
+Creates an image file with the polar conversion of the projection data. The options to set are:
+
+\begin{twocollist}
+\twocolitem{\textbf{xsize}}{Number of columns in output image.}
+\twocolitem{\textbf{ysize}}{Number of rows in output image.}
+\twocolitem{\textbf{interpolation}}{Selects the interpolation method.
+Currently, the \texttt{bilinear} option provides the highest
+quality interpolation.}
+\end{twocollist}

 
 \subsection{Process - Convert FFT Polar Dialog}
 
 \subsection{Process - Convert FFT Polar Dialog}

-The parameters for this option are the same as
-\helprefn{convertpolardialog}{Convert Polar Dialog}. For this
-command, though, the projections are Fourier transformed prior to
-conversion to polar image.
+The parameters for this option are the same as \helprefn{Convert
+Polar Dialog}{convertpolardialog}. For this command, though, the
+projections are Fourier transformed prior to conversion to polar
+image.

 
 

-\subsection{Reconstruct - Filtered Backprojection Dialog}
+\subsection{Reconstruct - Filtered Backprojection Dialog}\index{Reconstruction dialog}

 This dialog sets the parameters for reconstructing an image from projections
 This dialog sets the parameters for reconstructing an image from projections

-using the Filtered Backprojection technique. The parameters are identical
-to those for the \helprefn{pjrec}{pjrec} program.
+using the Filtered Backprojection technique.
+
+
+\begin{twocollist}
+\twocolitemruled{\textbf{Parameter}}{\textbf{Options}}
+\twocolitem{\textbf{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 \texttt{abs\_bandlimit}
+\item \texttt{abs\_cosine}
+\item \texttt{abs\_hamming}
+\end{itemize}
+} \twocolitem{\textbf{Hamming parameter}}{Sets the alpha level for
+Hamming   window. At setting of 0.54, this equals the Hanning
+window.}
+
+\twocolitem{\textbf{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 \texttt{convolution}
+\item \texttt{fourier}
+\item \texttt{fourier-table}
+\item \texttt{fftw}
+\item \texttt{rfftw}
+\end{itemize}
+}
+
+\twocolitem{\textbf{Interpolation}}{Interpolation technique.
+\texttt{cubic} is optimal when many projections are taken and the
+data is smooth. Otherwise, \texttt{linear} gives better results.
+Linear is also much faster than cubic interpolation.
+
+\begin{itemize}\itemsep=0pt
+\item nearest
+\item linear
+\item cubic
+\end{itemize}
+}
+\end{twocollist}
+
+\subsection{Advanced Options}
+
+These options are only visible if \emph{Advanced Options} has been
+selected in the \texttt{File/Preferences} dialog. These parameters
+default to optimal settings and don't need to be adjusted except
+by expert users.
+
+\begin{twocollist}
+\twocolitem{\textbf{Backprojection}}{Selects the backprojection
+technique. A setting of \texttt{idiff} is optimal.
+\begin{itemize}\itemsep=0pt
+\item \texttt{trig} - Uses trigometric functions at each image point
+\item \texttt{table} - Uses precalculated trigometric tables
+\item \texttt{diff} - Uses difference method to step along image
+\item \texttt{idiff} - Uses integer difference method
+\end{itemize}
+}
+
+\twocolitem{\textbf{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 \texttt{direct}
+\item \texttt{inverse-fourier}
+\end{itemize}
+}
+
+\twocolitem{\textbf{Zeropad}}{Zeropad factor when using
+frequency-based filtering. A setting of \texttt{1} is optimal.}
+
+\end{twocollist}

 
 \section{Plot Menus}
 \subsection{File - Properties}
 
 \section{Plot Menus}
 \subsection{File - Properties}

-
-\subsection{File - Save}
-Plot files can be saved. They are saved in an ASCII text format.
+The displayed properties include the number of curves in the plot
+and the number of points per curve. Additionally, the EZPlot
+commands used to format the plot are displayed.

 
 \subsection{View Menu}
 
 \subsection{View Menu}

-These commands set the scaling for the y-axis.
+These commands set the scaling for the y-axis. They are analogous
+to the options used for setting the intensity scale for images.
+

 \subsubsection{Set}
 \subsubsection{Set}

+This command sets the upper and lower limits for the y-axis.
+

 \subsubsection{Auto}
 \subsubsection{Auto}

+This command automatically sets the upper and lower limits for the
+y-axis. Please refer to the \texttt{View - Auto} documentation for
+image files for the details.
+

 \subsubsection{Full}
 \subsubsection{Full}

+The command resets the upper and lower limits of the y-axis to the
+minimum and maximum values of the curves.