X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fctsim-gui.tex;h=d54bfeb0cd652473fb168b9f786b49a35b1c2955;hb=e5c753200f28fdf5542a48051ad79c7c7dfbb299;hp=420e56d5220a60acadba111912d1b731772316e6;hpb=b85ea88dcc2bac54f035ea0976b04b7814c029a9;p=ctsim.git diff --git a/doc/ctsim-gui.tex b/doc/ctsim-gui.tex index 420e56d..d54bfeb 100644 --- a/doc/ctsim-gui.tex +++ b/doc/ctsim-gui.tex @@ -1,109 +1,419 @@ -\chapter{ctsim - 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}% +\ctsimfooter% + \section{Overview} -\ctsim\ is the graphical shell for the CTSim project. It is -written using the wxLibrary for cross-platform compatibility with GTK, -Motif, and Microsoft Windows. It includes all of the functionality of -the command-line tool \ctsimtext\ as well as image processing and visualization features. +\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. + +\usage \texttt{ctsim [files to open...]} + +You can invoke \ctsim\ by itself on the command line, or include +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. -\ctsim\ can open projection files, image files, phantom definition files, and plotfiles. -\usage -ctsim [OPTIONS] [files to open...] +\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{Files Supported} \subsection{Phantom} -Phantom files are supported. 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 create and edit these files. - +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 +create and edit these files. + \subsection{Image} -Image files are 2-dimensional files stored a 4-byte floating point values. -They are stored in little-endian format and \ctsim\ incorporates routines -to read and write files correctly on both big and little endian architextures. +Image files are 2-dimensional files that store 4-byte floating +point values. Images files can be either real or complex valued. +Typically, all images are real except for images that have been +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. -Images files can be either real or complex valued. Typically, all images -are real except for images that have been processed by Fourier transforms. +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} -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. +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 for all of the windows of +\ctsim. + +\subsection{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{description}\itemsep=0pt +\item[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. + +\item[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{description} + +\subsection{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{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{Save As...} +Allows the saving of the contents of a window to any filename. + +\subsection{Help} +This command displays the online help. + +\subsection{About} +This command shows the version number of \ctsim. + \section{Phantom Menus} +\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} -This creates an image file from a phantom. Technically, it converts -the phantom from a vector (infinite resolution) object into defined resolution -image. The parameters to set are: +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: -x-size Number of columns in image file -y-size Number of rows in image file -samples Numbers of samples taken per pixel in the x and y directions. - For example, if the nsamples is set to \texttt{3}, then for every - pixel in the image file, 9 samples (3 x 3) are averaged. +\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 +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.} +\end{twocollist} \subsection{Projection Dialog} -This creates a projection file from a phantom. +This creates a projection file from a phantom. The options +available when collecting projections are: + +\begin{twocollist} +\twocolitem{\texttt{Geometry}}{ + \begin{itemize}\itemsep=0pt + \item Parallel + \item Equiangular + \item Equilinear + \end{itemize}} +\twocolitem{\texttt{Number of detectors}}{Sets the number of +detectors in the detector array.} + +\twocolitem{\texttt{Number of views}}{Sets the number of views +collected} + +\twocolitem{\texttt{Samples per detector}}{Sets the number of +samples collected for each detector} + +\twocolitem{\texttt{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{\texttt{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{\texttt{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} Properties of image files include -%\begin{itemize}\itemsep=0 -%\item Whether the image is real or complex valued -%\item Numeric statistics -%\item Image file labels -%\end{itemize} +\begin{itemize}\itemsep=0pt + \item Whether the image is real or complex valued + \item Numeric statistics + \item Image file labels +\end{itemize} + +\subsection{File - 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{description}\itemsep=0pt +\item[PNG]Portable Network Graphics format. This uses 8-bits or +256 shades of gray. + +\item[PNG-16]This is a 16-bit version of PNG which allows for +65536 shades of gray. +\item[PGM]Portable Graymap format. This is a common format used on +UNIX systems. +\item[PGM]ASCII version of PGM. +\end{description} -\subsection{View} + +\subsection{View}\label{intensityscale} 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{description}\itemsep=0pt +\item[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. + +\item[Width] This sets the half-width of the intensity scale. The width +is specified as a ratio of the standard deviation. +\end{description} + +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. +\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: + +\begin{itemize} +\item Surface plot +\item Smooth shading +\item Lighting on or off +\item Color scale +\end{itemize} + \subsection{Filter} -These commands filter image. +These commands filter and modify the image. -\subsection{Anaylze} +\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. +\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} + +\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} The parameters are \texttt{xsize}, \texttt{ysize}, and \texttt{interpolation}. -The \texttt{xsize} and \texttt{ysize} parameters set the size of the +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{Process - Convert FFT Polar Dialog} -The paramters 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} 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 abs\_bandlimit +\item abs\_cosine +\item 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 convolution +\item fourier +\item fourier\_table +\item fftw +\item 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 trig +\item table +\item diff +\item idiff +\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 direct +\item 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} - -\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} -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} +This command sets the upper and lower limits for the y-axis. + \subsubsection{Auto} -\subsubsection{Full} +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} +The command resets the upper and lower limits of the y-axis to the +minimum and maximum values of the curves.