<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY app "AMIDE">
<!ENTITY date "Feb 2013">
<!ENTITY appversion "1.0.5">
<!ENTITY manrevision "0.3.1">
<!ENTITY legal          SYSTEM "legal.xml">
]>

<article id="index" lang="en">
  <articleinfo>
    <title>The <application>&app;</application> User's Manual V&manrevision;</title>
    
    <abstract role="description">
      <para> AMIDE stands for Amide's a Medical Image Data Examiner.
	This program is a tool for viewing and analyzing volumetric
	medical imaging data sets, and has been designed from the
	ground up with support for multi-modality imaging.
      </para>
    </abstract>

    <copyright><year>2000-2017</year> <holder>Andy Loening</holder></copyright>
    <!--- translators should put additional copyright entries -->

    <authorgroup>
      <author role="maintainer"> <!-- not everybody needs maintainer -->
	<firstname>Andy</firstname> <surname>Loening</surname>
	<affiliation>
	  <!-- <orgname> </orgname> -->
	  <address>
	    <email>loening at alum dot mit dot edu</email>
	  </address>
	</affiliation>
      </author>

      <othercredit role="translator">
        <firstname>Pablo</firstname>
        <surname>Sau</surname>
        <affiliation>
          <orgname>CDMEDICS PACS WEB (http://cdmedicpacsweb.sourceforge.net)</orgname>
          <address> 
            <email>pablosau at users dot sourceforge dot net</email> 
          </address>
        </affiliation>
        <contrib>Spanish translation</contrib>
      </othercredit>
    </authorgroup>

    <releaseinfo>
      This is release &manrevision; of the &app; User's Manual.
    </releaseinfo>

    <revhistory>
      <revision>
	<revnumber>AMIDE Manual V0.3</revnumber>
	<date>2003-06-09</date>
	<revdescription>
	  <para role="author">Andy Loening</para>
	</revdescription>
      </revision>
    </revhistory>
    
    <xi:include href="legal.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

  </articleinfo>

  <indexterm>
    <primary>&app;</primary>
  </indexterm>




<!-- ###################################### -->
<sect1 id="introduction">
  <title>Introduction</title>

<sect2><title>Licensing</title>

  <para>AMIDE is released under the terms of the <ulink type="http"
  url="http://www.gnu.org/copyleft/gpl.html">GNU General Public
  Library (GPL).</ulink></para>

  <para>The text of the license is fairly verbose.  A quick summary
  follows:
  </para>

  <orderedlist>
   <listitem>
    <para>
     You are free to run the program, for any purpose.  Please note
     that, although the GPL makes no restrictions on use of the
     program, your government probably does.  For instance, in the
     United States, AMIDE is not FDA approved and cannot be used
     clinically.
    </para>
   </listitem>
   <listitem>
    <para>
     You are free to study the source code of the program, and adapt
     it to your needs.
    </para>
   </listitem>
   <listitem>
    <para>
     You are free to redistribute the program.
    </para>
   </listitem>
   <listitem>
    <para>
     You are free to release modified versions of the program, as long
     as you also redistribute the source code to the modified program,
     and you label your modified version of the program appropriately.
    </para>
   </listitem>
  </orderedlist> 




</sect2>

<sect2><title>Availability of Source Code</title>

  <para> The source code for AMIDE is readily available from the
  <ulink type="http" url="http://amide.sourceforge.net">AMIDE web
  site</ulink>.
  </para>

</sect2>


<sect2><title>Supported Platforms</title>

  <para> In addition to source code, binary versions of AMIDE along
  with installation instructions can be found for several systems on
  the <ulink type="http" url="http://amide.sourceforge.net">AMIDE web
  site</ulink>.  The currently supported systems are Linux/i386,
  Microsoft Windows, and Macintosh OS X (achieved through the use of
  the <ulink type="http"
  url="http://fink.sourceforge.net">fink</ulink> add-on packages).
  </para>

</sect2>

  
<sect2><title>Contact Information</title>

    <para> Questions and bug reports can be addressed to the AMIDE
    users list <email> amide-users@lists.sourceforge.net</email>.
    Information on joining the list and/or viewing archived messages
    can be found <ulink type="http"
    url="http://sourceforge.net/mail/?group_id=9464">here</ulink>.
    </para> 

</sect2>
</sect1>

<!-- ###################################### -->
<sect1 id="basics">
  <title>AMIDE Basics</title>

  <para> As the use of AMIDE is bound to be completely intuitive only
    to the one who wrote the program (i.e. me), this section provides
    a brief overview of operating within the program.  It assumes you
    already have a data set loaded in.  For instructions on getting a
    data set into AMIDE, see <xref linkend="importing_data_sets" />
  </para>
  




  <sect2><title>A Quick Theory of Operations</title>

   <sect3><title>AMIDE Objects</title>

    <para>AMIDE can work with and display a large number of objects
    simultaneous (limited only be available memory).  The object types
    current implemented in AMIDE are as follows:

    <variablelist>
 
      <varlistentry><term>Data Set</term>
      <listitem>
       <para>A data set object
       contains the raw information from a medical imaging study,
       along with the corresponding parameters needed for interpreting
       that information (thresholds, colormaps, etc.).
       </para>
      </listitem>
      </varlistentry>

      <varlistentry><term>ROI</term>
      <listitem>
       <para>A region of interest
       object defines a volume of space over which statistics can be
       calculated.  All ROI's in AMIDE are volumetric.  Currently,
       AMIDE implements ellipsoid, cylinderical, rectangular, and
       isocontour based ROI geometries.
       </para>
      </listitem>
      </varlistentry>

      <varlistentry><term>Fiducial Mark</term>
      <listitem>
       <para>A very simple
       object, fiducial marks encode only the location of a reference
       point in space, and are used for rigid body alignment.
       </para>
      </listitem>
      </varlistentry>

      <varlistentry><term>Study</term>
      <listitem>
       <para>Each AMIDE session has
       a single study object, which is used for grouping together a
       number of related data sets, ROI's, and fiducial marks.
       </para>
      </listitem>
      </varlistentry>

     </variablelist>


    </para>
   </sect3>

   <sect3><title>Object Tree</title> 


   <figure id="studytree-fig">
    <title>Study Tree</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/study_tree.png" format="PNG"/>
      </imageobject>
      <textobject>
       <phrase>An example of a study's tree structure within AMIDE.
       The two data sets (FDG PET and microCT) and 1 ROI (bladder) are
       children of the study object (m2862).  The remaining ROI's are
       children of the data sets.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>



    <para> In order to facilitate working with a large number of
     objects simultaneously, AMIDE conceptually groups all objects
     into a tree hierarchy, with the study object as the root of the
     tree (see <xref linkend="studytree-fig" />).  Data set objects
     will generally be primary branches off of the study object, while
     ROI's can be branches off of the study object or off of
     individual data sets.  Why is this important?  Because the
     structure of the tree determines how movements are mapped within
     the program.  If a data set is moved relative to the rest of the
     study, the ROI's that are branches from that data set object will
     be correspondingly moved, so that they will maintain the correct
     orientation and position with respect to the data set that is
     their parent.</para>
   </sect3>

   <sect3><title>Real World Units</title>

    <para>An important thing to realize when working with AMIDE is
    that the program will try to abstract away the underlying digital
    format of the data as much as possible.  When you listen to
    digital audio, the CD player automatically converts the series of
    0's and 1's encoded on the compact disc into an analog format so
    that you don't have to worry about the underlying digital format.
    Similarly, AMIDE presents the digital data to you in analog form.
    When ever possible, units are given in terms of real world units
    (e.g. mm's, seconds), and most operations are not constrained by
    the discrete nature of the underlying data.  For example, data in
    AMIDE is viewed in terms of "slices", not fixed image planes.
    These slices can be taken from the data set at arbitary angles,
    and can be of any thickness (they are not constrained to be
    integer multiples of the underlying voxel size).  You may be used
    to looking at medical images in terms of voxels and integers, but
    remember that the object or subject scanned is an item in the real
    world, and AMIDE tries to recreate this "analog signal" for you.
    </para>

    <para> The only place the abstraction starts to break down is when
    dealing with dynamic data sets.  Einstein understood time to be a
    "special" dimension, and AMIDE agrees.  The reason for this, is
    that trying to represent dynamic data as anything but separate
    frames of data becomes overly complex from a computational
    standpoint, primarily because dynamic data is generally not
    equally spaced.  While moving 1 voxel in the x, y, or z directions
    will always move you a constant unit of measurement (say 0.4 mm)
    in the appropriate direction, moving 1 voxel in the t direction
    may move you 30 seconds or 30 minutes in time, depending on what
    frame you're looking at.  Because of this, AMIDE deals with
    dynamic data in terms of frames, although it should always tell
    you the time that those frames correspond to. </para>

   </sect3>


  </sect2>









  <sect2><title>Components of the Display</title>

   <figure id="mainwindow-fig">
    <title>AMIDE Main Window</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/amide_main_window.png" format="PNG"/>
      </imageobject>
      <textobject>
       <phrase>A diagram pointing out the salient features of the main window</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>


   <sect3><title>Context Sensitive Help</title>

      <para> Located in the lower left corner of the window, the
      context sensitive help window shows what different mouse buttons
      and key strokes can accomplish given the current cursor
      position. Note that mouse buttons are labelled in UNIX fashion.
      Buttons 1, 2, and 3 correspond to the left, middle, and right
      mouse buttons, respectively.  Under Macintosh OS X, the middle
      and right buttons are emulated by pressing the option key or the
      open apple key, respectively, while pressing the mouse
      button.</para>

   </sect3>



   <sect3><title>Tree View of Study Data</title>

    <para> Located on the left side of the window is a tree listing of
    all the objects in the study.  The tree structure shows how
    movements will be propogated to other objects in the study.  For
    instance, if a data set is rotated, all of its children will be
    correspondingly rotated. </para>

    <para> Objects in the tree can be selected for display by left
    clicking on the name of the object.  Middle clicking on a data set
    will make that data set the "active" data set.  The "active" data
    set is designated by being highlights, and when a function is
    chosen that can logically apply to only one data set
    (e.g. filtering), the active data set is the one chosen. </para>

    <para> Object modification dialog boxes can be brought up by right
    clicking on the corresponding object.  ROI's can be added by right
    clicking on the blank area of the tree, or shift-right clicking on
    one of the objects.  These functions are further described in
    <xref linkend="data_sets" /> and <xref linkend="rois" />.</para>
   </sect3>
    

   <sect3><title>Orthogonal Views</title>
    
    <para> Most of the main window display consists of the orthogonal
    views used for visually displaying the data sets being studied.
    Data is usually presented as three orthogonal slices taken from
    the data sets, but the user can choose to display fewer of these
    views if desired by using the view selector (described below in
    <xref linkend="view_selector" />).  The three views shown are the
    transverse, coronal, and sagittal planes.  Note that the views may
    be incorrectly labeled for you.  This could be because the data in
    the file you imported was not in the order that AMIDE expected it
    to be in.  It could also be because you want to use the
    transverse/coronal/sagittal terminology differently then the
    program does (e.g. a coronal section of a rat brain is not the
    same as a coronal section of a rat). </para>


    <para> Below the views are sliders for adjusting where in the data
    set the slices are being taken from.  The location can also be
    changed by directly clicking on any of the canvases.  The
    appropriate mouse clicks are as follows</para>


   <variablelist> 

    <varlistentry><term>Left Mouse Button</term>
     <listitem>
      <para>Changes the location in the data set that the slices are
      taken from, without changing the thickness of the slices.</para>
    </listitem>
    </varlistentry>

    <varlistentry><term>Middle Mouse Button</term>
    <listitem>
     <para>Change the
     location in the data set that the slices are taken from, along
     with setting the thickness of the slices to the minimum
     reasonable. </para>
    </listitem>
    </varlistentry>

    <varlistentry><term>Right Mouse Button</term>
    <listitem>
     <para>Clicking an
     dragging with this button changes the thickness of the slices
     without changing the location.  The thickness of the viewed
     slices can also be altered by adjusting the slice thickness
     setting spin button (see <xref linkend="slice_thickness_setting"
     />).</para>
    </listitem>
    </varlistentry>

  
    <varlistentry><term>Other</term>
    <listitem>
     <para>Additional functionality of the mouse buttons for
     manipulating data sets and ROI's is explained in <xref
     linkend="data_sets" /> and <xref linkend="rois" /></para>
    </listitem>
    </varlistentry>

   </variablelist>

   </sect3>

   
   <sect3 id="view_selector"><title>View Selector</title>
    
    <para>Which of the three orthogonal views are shown can be
    selected by using these toggle buttons.  By default, all three
    views are shown. </para>

   </sect3>


   <sect3><title>Linked Viewing</title>
    
    <para>In addition to the three orthogonal views, AMIDE can display
    mutiple sets of these orthogonal views, all looking at the same
    point ("linked") in three dimension space.  This is most often
    used for looking at fusion images of two data sets, with one set
    of views used for the first data set, the next set of views used
    for the second data set, and the third set of views used for the
    fusion of the two data sets.  </para>

   </sect3>


   <sect3 id="threshold_dialog"><title>Thresholding Tool</title>
    
    <para> This button on the toolbar will pop-up a thresholding and
    colormap selection dialog for the currently active data set.  In
    the dialog, the maximum and minimum thresholding levels can be
    changed by either directly typing in the values (in absolute or
    percentage units), or by using sliders on the color bar.  The
    color scale can be changed using the corresponding drop-down menu.
    A log normalized histogram is shown to give an idea of the
    distribution of the data set's value.  Finally, the thresholding
    type can be changed.  The thresholding type determines how the
    maximum and minimum threshold values are applied to the data set,
    and are:
    </para>

	<variablelist> 

		<varlistentry><term>Per Slice</term>
		<listitem><para>The max and min threshold values will
		be applied in proportion to the max and min values in
		the current slice of data</para></listitem>
		</varlistentry>

		<varlistentry><term>Per Frame</term>
		<listitem><para>The max and min threshold values will
		be applied in proportion to the max and min values in
		the current frame of the data set</para></listitem>
		</varlistentry>

		<varlistentry><term>Interpolate Between Frames</term>
		<listitem><para>This threshold mode only makes sense
		for dynamic studies.  In this mode, two sets of max
		and min threshold values are specified, along with
		which frame of data each of these sets corresponds to.
		For data frames before and including the first
		reference frame, the first set of threshold values are
		used.  For data frames after and including the second
		reference frame, the second set of threshold values
		are used.  For data frames between the two reference
		frames, the max and min threshold values are derived
		by interpolating (as a function of time) between the
		two sets of thresholding values.</para></listitem>
		</varlistentry>

		<varlistentry><term>Global</term>
		<listitem><para>The max and min threshold values will
		be applied in proportion to the max and min values in
		the entire data set</para></listitem>
		</varlistentry>

	</variablelist>

    <para> If the data set's modality is set to CT, buttons will be
    shown for applying bone and soft tissue windows as the thresholds.
    </para>

   </sect3>



   <sect3><title>Zoom Selector</title>
    
    <para>This specifies how much to enlarge the views.  AMIDE tries
    to make an educated guess about how large the display of the data
    should be, by using the smallest voxel dimension from the data set
    with the largest voxels to correspond to a displayed pixel.  Zoom
    can be used in addition to that guesswork.</para>

   </sect3>



   <sect3 id="slice_thickness_setting"><title>Slice Thickness Setting</title>
    
    <para> Thickness specifies how deep the slices displayed on the
    views are.  The minimum slice thickness is determined by the
    smallest voxel dimension of any of the data sets in the study.
    </para>

   </sect3>



   <sect3 id="frame-dialog"><title>Frame Selector</title>
    
    <para>This button pops up a dialog for picking which frames of
    data to show from a dynamic data set. A frame (i.e. time period)
    to display can be selected by clicking on a list element.
    Multiple frames can be selected by holding down the shift key and
    selecting additional frames.  Note, that for each data set
    selected for view, at least one frame from that data set will be
    displayed.  If the choosen time period does not encompass a frame
    from that data set, the closest appropriate frame will be
    choosen.</para>

   </sect3>


   <sect3 id="gate-dialog"><title>Gate Selector</title>
    
    <para>This button pops up a dialog for picking which gates of data
    to show from a gated data set. A gate to display can be selected
    by clicking on a list element.  Multiple gates can be selected by
    holding down the shift key and selecting additional frames.  Note
    that by using the entries, a span of gates can be choosen that
    loops around (e.g. gates 8, 0, and 1).</para>

   </sect3>


   <sect3><title>Target Selector</title>
    
    <para>The target cross hairs are generally only displayed when one
     of the mouse buttons is depressed.  With this toggle button, you
     can tell the program that you want the target cross hairs left on
     the views.</para>

   </sect3>


   <sect3 id="interpolation"><title>Interpolation</title>
    
    <para>Interpolation refers to the method whereby AMIDE extracts
     data from the original medical imaging data set in order for it
     to be viewed on the screen.  The interpolation selection button
     lets the user specify what type of interpolation to use when
     generating slices from the active data set.  Nearest neighbor is
     faster, while tri-linear interpolation produces better looking
     (smoother) images with the penalty of being ~8x slower.
    </para>
   </sect3>

   <sect3 id="slab_rendering"><title>Rendering</title>

    <para>Three rendering methods are available, MPR (multiplanar
    reformation), MIP (maximum intensity projection), and MINIP
    (minimum intensity projection). These rendering algorithms are
    utilized to combine data in the depth direction of the slice
    and/or over multiple frames of data. As such, the effects are most
    noticeable when the view thickness of the slices is increased
    and/or several frames of data are being combined. For MPR, each
    displayed pixel corresponds to the weighted average of the
    underlying data. For MIP and MINIP, each displayed pixel
    corresponds to the maximum or minimum value of the underlying data,
    respectively.
    </para>

   </sect3>


   <sect3><title>Fusion/Overlay Selector</title>
    
    <para>By default, AMIDE displays multiple data sets as fused
    images.  With the fused/overlay selector, you can tell AMIDE that
    you want the active data set to simply be overlayed on the other
    data sets, rather than fused.</para>

   </sect3>

  <sect3 id="preferences-dialog"><title>Preferences Dialog Box</title>
    <para>
      Underneath the edit menu is the preferences menu item.  This
      will pop-up a dialog box that allows you to change preferences
      as to how things in AMIDE are displayed.  The preferences will
      be saved in a configuration file for use by future AMIDE
      sessions (note: saved preferences are not currently supported on MS
      Windows).
    </para>

    <variablelist>

    <varlistentry><term>ROI/View Preferences</term> 
     <listitem><para>
      Here are several preferences for changing how ROI's are the view
      canvas are drawn, more thoroughly described in <xref
      linkend="study-dialog" />.  Note that these preferences are only
      used when a new study is created.  To change these preferences
      for an existing study, you need to use the study modification
     </para></listitem>
    </varlistentry>

    <varlistentry><term>Threshold Windows</term> 
     <listitem><para> 
      The window preferences are more throughly described in <xref
      linkend="data-set-dialog" />.  Note that these preferences are
      only used for new data sets. To change the window levels for an
      existing data set, use the data set modification dialog.
     </para></listitem>
    </varlistentry>

    <varlistentry><term>Default Colortable Preferences</term>
      <listitem> <para>
        The program uses the specified color tables by default on a
        newly imported data set.
      </para></listitem>
    </varlistentry>
    
    <varlistentry><term>Misc. Preferences</term>
      <listitem> 

       <para> The "Send Warning Messages to Console" option does
       exactly that.  This is useful if enough warning messages are
       popping up that they're becoming annoying. </para>

       <para> With the "Don't Prompt for 'Save Changes' on Exit"
       option, you can tell the program to not prompt you to save
       changes done on the study when exiting an AMIDE session.
       </para>

       <para> The "Which Default Directory" controls which directory
       the file chooser dialog (used for save/import/open operations)
       will use as it's default location. "None" will cause the file
       chooser to show a list of recent locations as
       default. "Specified Directory" will cause the file chooser to
       utilize the directory specified as the default
       directory. "Working Directory" will utilize the directory from
       which the AMIDE program was executed as the default directory -
       this is most useful if you're often envoking AMIDE from the
       command line.
       </para>

     </listitem>
    </varlistentry>

    </variablelist>

  </sect3>


</sect2>

</sect1>

<!-- ###################################### -->
<sect1 id="file_handling">
  <title>Importing Data and Saving Studies</title>


<sect2 id="importing_data_sets"><title>Importation of Data Sets</title>

 <para> AMIDE uses its own format (described below: <xref
  linkend="xif-files" />) for saving data between session.  To get new
  data into AMIDE, it needs to be imported (located under the file
  menu).  You can either let AMIDE try to guess the file format (which
  works for most data types) or tell AMIDE explicitly which format the
  file to be imported is suppose to be in.  Importing of all data
  types except for raw data is done using Erik Nolf's <ulink
  type="http" url="http://xmedcon.sourceforge.net">(X)medcon</ulink>
  medical imaging conversion library.</para>

  <sect3><title>Raw Data Files</title>

    <para> AMIDE will generally attempt to load any file ending in
    ".dat" or ".raw" as a raw data file.  The user will be prompted
    for the dimensions of the study, the offset of the data in the
    file, and the data format of the data in the file.  Both big
    endian, little endian, and PDP endian files can be loaded (endian
    refers to the order in which bytes are arranged in memory).</para>

    <para> The following data formats are supported: 8 bit signed or
    unsigned integer, 16 bit signed or unsigned integer, 32 bit signed
    or unsigned integer, 32 bit IEEE floating point, 64 bit IEEE
    floating point, and ASCII data. </para>

  </sect3>

  <sect3><title>ECAT Files</title>

   <para> Static and dynamic ECAT 6.4 and 7.2 files are supported
    through (X)MedCon.  AMIDE will generally try to load any file
    ending in ".img" as ECAT 6.4, and any file ending in ".v" as ECAT
    7.  Please note that ECAT 6.4 files are very difficult to
    autodetect, so if the file does not end in .img, you will probably
    have to tell AMIDE explicitly to import the file as ECAT
    6.4.</para>

  <para> Although not compiled in by default, AMIDE can be configured
    to use the z_matrix_7/libecat library for handling ECAT files
    instead of (X)MedCon. </para>

 </sect3>


 <sect3><title>DICOM Files</title>
  
  <para> DICOM 3.0 is supported through (X)MedCon, which actually uses
    a slightly modified version of Tony Voet's VT-DICOM library.  The
    level of support for DICOM 3.0 is entirely determined by
    (X)MedCon/VT-DICOM.
  </para>

  <para> DICOM data is often distributed as a series of single slice
   data files.  To read these into AMIDE as a single data set, you
   will need to stack these slices into a single, volumetric file.
   Notes on how to do this can be found at <ulink type="http"
   url="http://xmedcon.sourceforge.net/faq/stack.html">the (X)medcon
   website</ulink>.</para>
  
 </sect3>


 <sect3><title>Concorde microPET files</title>
  
  <para> Concorde format files are generated by the Concorde company's
  series of microPET scanners.  It's a two file format (a data file
  and a header file), with the header in easily read ASCII format.
  Please note that you will need to tell AMIDE to open the header file
  (.img.hdr), not the raw data file (.img).</para>

 </sect3>

 <sect3><title>Acr/Nema 2.0, Analyze (SPM), InterFile3.3, Gif87a/89a</title>

  <para> A variety of additional file formats are supported through
    (X)MedCon, including: Acr/Nema 2.0, Analyze (SPM), InterFile3.3,
    and Gif87a/89a.  For more information, please see the (X)MedCon
    documentation, or the corresponding <ulink type="http"
    url="http://xmedcon.sourceforge.net"> webpage
    (http://xmedcon.sf.net) </ulink>. </para>
  
  
 </sect3>
  

</sect2>


<sect2 id="xif-files"><title>XIF Files</title>

 <para> AMIDE saves studies in an extensible XML based format called
  XIF (Xml Image Format).  This format can be stored as either a
  single file (flat file format XIF) or as a XIF directory.  The flat
  file format is the default, and simplifies file moving and handling.</para>

  <para> The directory format on the other hand allows easy access to the raw
  study data external to the AMIDE program, and will be of interest to
  developers.  The directory format can be utilized via the "Save as
  XIF Directory" and "Open XIF Directory" menu items under the File
  menu. </para>

 <para> In any case, these files or directories will
  characteristically end with ".xif", and are treated identically
  within the AMIDE program.</para>

 <sect3><title>Opening Studies</title>
  
  <para> From the main window, select "File->Open", and a file
    selection widget will open up.  Select an XIF filename in the
    right column, and then hit the "OK" button (or double click on the
    filename). </para>

 </sect3>

 <sect3><title>Saving Studies</title>

  <para> To save a study, from the study window select "File->Save As"
    and a file selection dialog will appear.  Look at the "selection:"
    line near the bottom of the window, if this is the desired XIF
    filename, hit "OK" and the file will be saved.  If this is not the
    desired XIF filename, select or enter in the correct XIF study,
    and hit the "OK" button. </para>

  <para> Note that the original data set files are no longer needed by
    AMIDE, as all the information AMIDE needs is saved inside the .XIF
    file.  You should however still archive the original data files,
    as AMIDE only reads in and stores the information from the header
    that it needs (which is generally not all the information enclosed
    within the header).
  </para>

 </sect3>


 <sect3><title>XIF Directory Format</title>

  <para> Although admittedly annoying from a data transfer standpoint,
    using a directory structure for saving study information has the
    decisive advantage of making the saved information easily
    accessible using standard command-line utilities and text-based
    tools. </para>

  <para> Each XIF directory contains a file called "study_*.xml" which
    contains the basic study parameters.  Additional files can also be
    found in the XIF directory, such as ROI_*.xml files which contain
    ROI's, and data-set_*.xml files and their corresponding
    data-set_*_raw-data files, which contain the image data set
    parameters and the raw data respectively.  The raw data file
    format is arbitrary (double/float/int, 64/32/16/8 bit, little or
    big endian, per plane/per frame/single scale factor), and is
    determined by the format of the originally imported data. </para>
 </sect3>

 <sect3><title>XIF Flat File Format</title>

  <para> The flat file format is basically a concatenation of the
  information enclosed within the directory format.  It is not meant
  to be editable or developer friendly.  Instead, it allows easy
  management of studies for casual users.  If you wish to access the
  information in a XIF flat file external to AMIDE, you'll be much
  better off resaving the data as in XIF directory format.</para>

  <para> The format is as follows: The first 64 bytes of the file
  contain a magic string for format identification.  The next 16 bytes
  contain 2 64bit unsigned little endian integers, the first one being
  the location of the study xml data within the file, and the second
  integer being the size of this xml data.  Within the study xml data,
  is encased the information as to where in the file the children's
  xml data is.  And within the children's xml data, is enclosed the
  location information of the raw data and subchildren.
  </para>

 </sect3>

</sect2>



<sect2><title>Exporting a View to JPEG/PNG</title>

  <para> To export one of the views (transverse/coronal/sagittal) to
    an external image file, select "File->Export View->[view]" from
    the menu.  The saved data format by default is jpeg. If the saved
    filename ends in ".png", the saved data format will be PNG.

  </para>

</sect2>
</sect1>





<!-- ###################################### -->
<sect1 id="data_sets">
  <title>Manipulating Medical Data Sets </title>

<para> After being loaded in, medical images can be manipulated in a
  variety of ways with AMIDE.  An important point to remember is that
  AMIDE deals with all data sets as 3 or 4 dimensional data sets.
  While 2D slices extracted from the the data set are displayed on the
  computer screen, at no time does AMIDE handle images as anything
  less than 3 dimensional data.</para>




<sect2><title>Manipulating Data Sets on Screen</title>

  <sect3><title>Displaying Data Sets</title>

  <para> When initially loaded into the program, a data set is not
    displayed on the canvases.  Rather, the name of the data set is
    contained in the study list, and the user needs to select the data
    set in the study list so that it is displayed on the
    canvases. </para>
  
  <para> Displaying multiple data sets is as simple as importing more
    than one data set, and then selecting the data sets that you wish
    to view from the study list. </para>

  <para> The time period over which the slices are drawn is determined
    by the time dialog, described in more detail in <xref
    linkend="frame-dialog" /> </para>

  </sect3>

  <sect3><title>Pertinent Mouse Actions</title>

   <para> The following mouse actions can be used when the mouse is
   hovering over a data set on any of the orthogonal views</para>

   <variablelist>

     <varlistentry><term>Shift-Left Mouse Button</term> 
     <listitem><para> This combination allows shifting of the active
       data set in space (usually used for aligning two data sets).
       While holding the shift key, left click (and release) on the
       canvas, and you'll grab the active data set. You can now shift
       the active data around on the canvas.  At this point, to enact
       the shift, click the right button (button 3).  Any other mouse
       button will cancel the shift action.  </para></listitem>
     </varlistentry>

     <varlistentry><term>Shift-Right Mouse Button</term> 
     <listitem><para> This combination allows rotating of the active
	data set in space (usually used for aligning two data sets).
	While holding the shift key, middle click (and release) on the
	canvas, and you'll grab the active data set. You can now
	rotate the active data around on the canvas.  At this point,
	to enact the rotation, click the right button (button 3).  Any
	other mouse button will cancel the rotation.</para></listitem>
     </varlistentry>

     <varlistentry><term>Ctrl-Right Mouse Button</term>
     <listitem><para> This combination will place an alignment point
        at the current cursor location.  A dialog will popup for entry
        of the alignment point's name.</para></listitem>
     </varlistentry>

   </variablelist>


  </sect3>
  

</sect2>

<sect2 id="manual_alignment"><title>Manually Aligning Data Sets</title>

  <para> What follows is a quick guide to manually aligning data sets
  in AMIDE</para>

  <procedure>
    <step>
      <para>
	First rotate each of the data sets so that they are level with
	respect to the transverse, coronal, and sagittal views.  This is
        easily done using the shift-2 mouse combination, but 
        can also be done from the data set modification dialog.
      </para>
    </step>
    <step>
      <para>
	Choose one of the data sets to be the active data set.  The other
        data set will be the "fixed" data set.  
      </para>
    </step>
    <step>
      <para>
	Shift the active data set so that the two data sets line up appropriately.
        This is easily done using the shift-1 mouse combination, but can also be
        done from the data set modification dialog.
      </para>
    </step>
    <step>
      <para>
        If fine tuning adjustments are needed, these are best done from the
        data set modification dialog.
      </para>
    </step>
  </procedure>          
  
</sect2>


<sect2 id="data-set-dialog"><title>Data Set Modification Dialog</title>

    <para> To modify parameters of a data set, right click on the name
      of the data set in the study tree to pop-up the data set
      modification dialog box.  Parameters that can be modified are
      divided into the following pages. </para>

   <variablelist>    

    <varlistentry><term>Basic Info</term>
      <listitem><para>

	On this page are options to alter the data set name, type of
	modality, subject name, subject id, subject date of birth
	(DOB), conversion factor, and the interpolation type to use
	for this data set (described at <xref linkend="interpolation"
	/>).  The conversion factor is a parameter that is multiplied
	to the data set before it is used for viewing or quantitation.
	Since the data set is in ECAT/MAP/abitrary scale units, the
	conversion factor can be used in order to analyze the data set
	in another type of reference unit (e.g. Percent Injected Dose
	[%ID]).  There is also a built in calculator, where parameters
	such as subject weight and injected dose can be entered, and
	the conversion factor will be generated.  Note that 1 cc is
	assumed to equal 1 g when generating the %ID/g and SUV.

      </para></listitem>
    </varlistentry>
    
    <varlistentry><term>Center</term>
      <listitem><para>
	The data set can be shifted by respecifing the center of the
	data set with respect to the origin.  The x, y, and z
	dimensions are in millimeters.
	</para></listitem>
    </varlistentry>

    <varlistentry><term>Voxel Size</term>
      <listitem><para>
        The size of the data set's voxels (again, in millimeters) can
	be altered on this page.  The "keep aspect ratio" button
	specifies that when altering the size of any voxel component
	(x, y, or z), the relative sizes between the components should
	be kept the same.
	</para></listitem>
    </varlistentry>

    <varlistentry><term>Rotate</term>
      <listitem><para>
	The data set can be rotated around its center in this page.
        There is one dial for each of the three slice planes.  The
        transverse dial will spin the data set in the transverse plane
        (i.e. rotate on the z-axis).  The coronal dial will spin the
        data set in the coronal plane (i.e. rotate on the y-axis).
        And the sagittal dial will spin the data set in the sagittal
        plane (i.e. rotate on the x-axis).  The "reset to default"
        button allows the data set to be rotated back to the default
        orientation.  On the bottom of this page is a matrix showing
        the coordinate frame of the data set with respect to the base
        coordinate frame.
	</para></listitem>
    </varlistentry>
    
    <varlistentry><term>Colormap/Threshold</term>
      <listitem><para>
	This page is analogous to the thresholding tool dialog
	(described at <xref linkend="threshold_dialog" />) above).  
      </para></listitem>
    </varlistentry>

   <varlistentry><term>Time</term>
      <listitem><para>
	From this page, the timing information of the data set can be
	altered.  Scan start time can be used for altering the start
	time of the scan with respect to other data sets.  Corrections
	in the duration of each data frame can also be made on this
	page. </para></listitem>
    </varlistentry>

   <varlistentry><term>Windowing Preferences</term>
    <listitem><para>
      The max and min threshold levels used for the bone and soft
      tissue CT window buttons can be explicitly set here.  The
      "Insert Current Thresholds" button will reset the max and min
      values with the data set's currently used threshold levels.  
     </para></listitem>
    </varlistentry>
    
    <varlistentry><term>Immutables</term>
      <listitem><para>
	This panel lists information about the data set that cannot be
	altered.  The underlying internal data format of the data set
	and the data set dimensions in voxels are displayed on this
	page.
	</para></listitem>
    </varlistentry>

    </variablelist>
</sect2>
</sect1>




 
<!-- ###################################### -->
<sect1 id="rois">
  <title>Using Regions of Interest (ROI's)</title>

 <para> ROI stands for Region of Interest.  An ROI designated a volume
  in space over which statistics should be calculated.
 </para>


<sect2><title>ROI Types</title>

  <para>
    The following ROI types are currently supported in AMIDE:
  </para>
  
  <sect3><title>Geometric ROI's</title>

   <variablelist> 

    <varlistentry><term>Ellipsoid</term>
    <listitem><para> An ellipsoid is similar to a sphere, but with a
      diameter specified for each direction [x,y,z].  In the case of
      x=y=z, the ellipsoid is a sphere.</para></listitem>
    </varlistentry>
  
    <varlistentry><term>Elliptic Cylinder</term>
    <listitem><para>An elliptic cylinder is similar to a regular
      cylinder, except it has an ellipse as its base instead of a
      circle.</para></listitem>
    </varlistentry>

    <varlistentry><term>Box</term>
    <listitem><para>Exactly what it says, a 3D box.</para></listitem>
    </varlistentry>

   </variablelist>

  </sect3>
  
  <sect3><title>Isocontour ROI's</title>

    <para> Isocontour ROI's are regions selected from the data set
      such that the edge values of the ROI are always the same value.
      There are two types, 2D and 3D isocontours.  Additionally, both
      these ROI types can be defined so that they encompass all
      neighboring values either above a certain minimum value, below a
      certain maximum value, or between a minimum and maximum value.
      After drawing of these ROI's, they can be modified by using
      manual drawing or erasing operations. </para>
    
   <variablelist> 

    <varlistentry><term>2D Isocontour</term>
    <listitem><para>A 2D isocontour is derived by considering a value
	on one of the displayed 2D slices.  The depth of a 2D
	isocontour is specified initially by the depth of the viewed
	slices.</para></listitem>
    </varlistentry>
  
    <varlistentry><term>3D Isocontour</term>
    <listitem><para>A 3D isocontour is derived by considering a value
	on the current frame of the active data set.</para></listitem>
    </varlistentry>
  
   </variablelist>

 </sect3>
  
  <sect3><title>Freehand ROI's</title>

    <para> Freehand ROI's are regions of interest that are drawn
    manually.  </para>
    
   <variablelist> 

    <varlistentry><term>2D Freehand</term>

    <listitem><para>A 2D Freehand ROI is similar to a 3D Freehand,
         except that it is constrained to be only one voxel thick.  By
         default, the depth is the current slice thickness, although
         this can be changed by the user.</para></listitem>
    </varlistentry>
  
    <varlistentry><term>3D Freehand</term>
    <listitem><para>An ROI that can be drawn freely in all 3 dimensions..</para></listitem>
    </varlistentry>
  
   </variablelist>

 </sect3>
  
</sect2>


<sect2><title>Drawing ROI's</title>

  <para>
    To draw an ROI, you first need to create a new ROI.  You can add a
    new ROI to either the study, or a particular data set.  To add an
    ROI to the study, you can either select the ROI desired under the
    "Edit->add ROI:" menu item, or right click on the blank area of
    the study tree.  To add an ROI to a data set, shift-right click on
    the data set that you'd like to add the ROI to.  In both cases, a
    dialog box will pop-up for you to enter in the new ROI's name.
  </para>

  <para>
    When first added, the new (undrawn) ROI will be selected in the
    study tree.  When an undrawn ROI is selected in the study tree,
    the program will use the next mouse input on any of the displayed
    views to begin the process of drawing this ROI.
  </para>

  <para>
    For ellipsoid, elliptic cylinder, and box ROI's, a click with the
    left button will begin an edge-to-edge drawing, while a click with
    the middle button will begin a center-out drawing.  The x and y
    dimensions of the ROI are determined by this process. The z
    dimension (thickness) of the ROI can be specified by the pop-up
    dialog that will appear on the completion of the mouse movement.
  </para>

  <para>
    For isocontour's, the value of the data set at the clicked upon
    location will be used to derive the isocontour.
  </para>

  <para>
   For freehand's, the point on the screen that is clicked upon will
   be included in the ROI.
  </para>    

</sect2>

<sect2><title>Manipulating ROI's</title>

  <para>
    After an ROI is drawn, it can be further manipulated to adjust its
    size, placement, and orientation.  You can directly manipulate the
    ROI by clicking on it in any of the viewing windows.  Mouse button
    1 is used to shift ROIs.  Mouse button 2 is used for zooming
    ellipsoid, elliptic cylinder and box ROI, and is used for entering
    drawing mode for isocontour and freehand ROI's.  Mouse button 3 is
    used to rotate ellipsoid, elliptic cylinder, and box ROIs, and for
    redefining the isocontour value for isocontour ROI's.  </para>

  <para> For isocontour and freehand ROI's, drawing mode can be
     entered by using thie middle mouse button (button 2).  Once
     entered, points can be added or removed from the ROI by using the
     left (button 1) or right (button 3) mouse buttons, respectively.
     Holding down the shift key while using these buttons increases
     the size of the action.  The middle button (button 2) allows the
     user to leave drawing mode.
  </para>

  <para>
    You can also edit the ROI size/placement/orientation/name etc. by
    clicking on mouse button 3 while over the ROI's name in the study
    item list.  This brings up the ROI modification dialog (described
    at <xref linkend="roi-dialog" />).
  </para>
    
</sect2>



<sect2 id="roi_statistics"><title>Calculating Statistics</title>

  <para>

    Statistics on an ROI can be calculated via the "Tools->calulate
    ROI statistics" menu item.  Choosing this will pop-up a dialog
    that lets you choose which ROI's (selected or all) and which data
    sets (selected or all) you'd like to calculate statistics over.
    You will also have three options as to how you what the values to
    be calculated.
  </para>

  <orderedlist>
   <listitem>
    <para> Calculate over all voxels. </para>
   </listitem>

   <listitem>
    <para> Calculate over highest x percent of voxels.  For example,
    if you choose this and pick 25% as the number, your ROI will be
    calculated from the 25% of the voxels in the ROI that have the
    highest values.
    </para>
   </listitem>

   <listitem>
    <para> Calculate for voxels >= % of Max.  This method is based on
    Lee, Madsen, Bushnel, and Menda, Nuc Med Comm 2000, 21:685-690.
    As an example, if you choose this and pick 50% as the number, the
    highest valued voxel in the ROI will be found, and then the ROI
    statistics will be calculated for all voxels that are greater or
    equal to 50% of the highest valued voxel.
    </para>
   </listitem>

   <listitem>
    <para> Calculate for voxel >= Value. This algorithm only does
    calculations for voxels in the ROI that have a value greater than
    the value specified.
    </para>
   </listitem>

  </orderedlist>

  <para> There's also a check box to enable "more accurate
  quantitation".  The default algorithm (corresponding to unchecked)
  makes some approximations in deciding which voxel are in our out of
  the ROI.  If this check boxed is checked, the ROI results will be
  more accurate, but will take much longer to compute.
  </para>

  <para>
   After hitting execute, the program will crank for a while, and then
   show the calculated values in a new dialog window.  Hitting "Save
   as" button allows saving these values as a tab separated values
   (TSV) file.  This file should be easily imported into most
   spreadsheet applications (Excel's a little stupid, you may have to
   explicitly tell it you're importing a TSV file).  Pressing the
   "Copy" button copies the information into the operating systems
   clipboard, allowing pasting of the results into other programs.
   The "Save Raw Values" button allows you to export the underlying
   raw data values for the ROI's in case you wish to do your own
   statistical analysis.
  </para>

  



 <sect3><title>Gotcha's to ROI calculations </title>
  
  <sect4><title>Variance and Standard Deviation Fallacies</title>
    
    <para>
      Currently, AMIDE generates variance and standard deviation values
      that may occasionally be of interest to imaging physicists.  It
      is very important to remember, that these numbers represent the
      noise in the data set, NOT the noise in your experiment.
    </para>

    <para> The variance of an experiment can only truly be measured by
      taking multiple samples (i.e. performing multiple scans) and
      calculating the variance between these different samples.
    </para>

  </sect4>

  <sect4 id="roi-volume-calculation"><title>Changing Calculated Volume</title> 

   <para><emphasis>Short story:</emphasis> The calculated volume shown
    by the ROI statistics dialog is correct.  Use this value as the
    volume of the ROI, not the value you might calculate by hand based
    on the ROI's dimensions.
   </para>

   <para><emphasis>Long story:</emphasis> AMIDE calculates ROI's by
    translating the ROI's dimensions into the data set's coordinate
    space.  It then computes statistics for all the data set voxels
    that are in the ROI.  For voxels that lie on the edge of the ROI,
    AMIDE will subdivide the voxel into a finite number of subvoxels,
    and calculate over the subvoxels.  This approach yields correct
    statistics, but it is important to realize that the computed ROI
    is a discrete representation of the specified analytical ROI.  So
    while the true volume of an ellipse is pi*r1*r2*r3, the computed
    volume of the ellipse in AMIDE will depend on the number of voxels
    and subvoxels that were determined to lie within the ellipse,
    which in turn can depend on the orientation of the ROI with
    respect to the data set in question.  Since the computed volume
    given by AMIDE represents the volume in the data set that was used
    for the ROI calculation, you will want to use that value (not the
    real ellipse value).
    </para>
  </sect4>

  <sect4><title>Why isn't a "total" statistic calculated for the ROI?</title>

   <para> AMIDE doesn't present the "total" value in the ROI, as it
   doesn't necessarily know what the units of the underlying data are.
   If you're using PET or SPECT data, your voxel values are most
   likely proportional to activity/volume/time.  To calculate the
   total in your ROI, you should multiple the mean value of the ROI
   times the ROI volume and the frame duration.  If you're using CT
   data, your values are probably proportional to density, so to
   calculate the total you would multiple the mean ROI value by the
   ROI volume. </para>

  </sect4>

 </sect3>

 <sect3 id="roi-terms"><title>Explanations of ROI Statistical Values</title>

  <variablelist>
  
   <varlistentry><term>Median</term>
   <listitem><para>This is the median value of all the voxels that are
   enclosed (partially or totally) within the ROI.  For an even number
   of voxels, the median is defined as the average of the center 2
   values.</para></listitem>
   </varlistentry>

   <varlistentry><term>Mean</term>
   <listitem><para>The mean value of the voxels in the ROI.  Voxels
   that are partially enclosed within the ROI are appropriately
   weighted.</para></listitem>
   </varlistentry>

   <varlistentry><term>Variance</term>
   <listitem><para>The variance of the voxels in the ROI.  This is
   a weighted variance calculation so that voxels that are
   partially enclosed within the ROI are correctly
   handled.</para></listitem>
   </varlistentry>

   <varlistentry><term>Standard Deviation</term>
   <listitem><para>The square root of the variance.</para></listitem>
   </varlistentry>

   <varlistentry><term>Standard Error</term>
   <listitem><para>The square root of the variance, divided by the
   square root of the total number of voxels in (totally or partially)
   the ROI.</para></listitem>
   </varlistentry>

   <varlistentry><term>Minimum/Maximum</term> 
   <listitem><para>The minimum and maximum values for all voxels
   enclosed totally or partially within the ROI.</para></listitem>
   </varlistentry>

   <varlistentry><term>Size</term>
   <listitem><para>The volume of an ROI (mm^3).  Details as to its
   calculation are above in: <xref linkend="roi-volume-calculation"
   />.</para></listitem>
   </varlistentry>

   <varlistentry><term>Fractional Voxels</term>
   <listitem><para>The is the sum of the voxel weights, and gives an
   indication of how large the ROI is in voxel
   space.</para></listitem>
   </varlistentry>

   <varlistentry><term>Voxels</term>
   <listitem><para>This is the total number of voxels used in
   calculating the ROI, both partial and total.  In contrast to the
   "Fraction Voxels" measure, the "Voxels" measure gives a better
   indication of the statistical validity of the mean, variance, etc.
   </para></listitem>
   </varlistentry>

  </variablelist>
 </sect3>

</sect2>



<sect2 id="roi-dialog"><title>ROI Modification Dialog</title>

 <para>
   To directly modify parameters of an ROI, right click on the name of
   the ROI in the study tree to pop-up the modification dialog.
   Parameters that can be modified are divided into the following
   pages.
 </para>

 <variablelist>
  <varlistentry><term>Basic Info</term>
   <listitem><para>
     The name and type of ROI can be altered on this page.
   </para></listitem>
  </varlistentry>
    
  <varlistentry><term>Center</term>
   <listitem><para>
    The center of the ROI can be shifted with respect to the origin on
    this page.  The x, y, and z parameters are in millimeters.
   </para></listitem>
  </varlistentry>
    
  <varlistentry><term>Dimensions</term>
   <listitem><para>
	The size of the ROI can be altered from this page.  The x',
	y', and z' dimensions are in millimeters and are orientated
	with respect to the orientation of the ROI.
   </para></listitem>
  </varlistentry>
    
  <varlistentry><term>Rotate</term>
   <listitem><para>
	The ROI can be rotated around its center in this page.  There
	is one dial for each of the three slice planes.  The
	transverse dial will spin the ROI in the transverse plane
	(i.e. rotate on the z-axis).  The coronal dial will spin the
	ROI in the coronal plane (i.e. rotate on the y-axis).  And the
	sagittal dial will spin the ROI in the sagittal plane
	(i.e. rotate on the x-axis).  The "reset to default" button
	allows the ROI to be rotated back to the default orientation.
	On the bottom of this page is a matrix showing the coordinate
	frame of the ROI with respect to the base coordinate frame.
    </para></listitem>
  </varlistentry>
  </variablelist>
</sect2>
</sect1>





<!-- ###################################### -->
<sect1 id="study">
  <title>The Study</title>

 <para> The "Study object" in AMIDE is used for grouping a set of
 related data sets and ROI's.  Note that the use of the word "Study"
 here diverges from the traditional nuclear medicine use of the word,
 in which study generally connotates a single scan (or occasionally
 multiple but highly coupled scans) done on a single patient.  A study
 in AMIDE is often used to group an entire experiment (several
 patients, several animals, whatever) into a single file.  The study
 object itself is used mostly for storing parameters that effect all
 other objects stored in the study.</para>

<sect2 id="study-dialog"><title>Study Modification Dialog</title>

    <para> Similarly to the data set and ROI modification dialogs, the
      study modification dialog can be used to alter parameters
      relevant to the entire study.  Right click on the name of the
      study in the study tree to pop-up the study modification dialog
      box.  Parameters that can be modified are divided into the
      following pages. </para>

   <variablelist>    

    <varlistentry><term>Basic Info</term>
      <listitem><para>
	On this page are options to alter the name and creation date of the study.
      </para></listitem>
    </varlistentry>
    
    <varlistentry><term>View Center</term>
      <listitem><para>
        From this page, the point that the study is currently viewing 
        can be explicitly changed.  The x, y, and z
	dimensions are in millimeters.
	</para></listitem>
    </varlistentry>

    <varlistentry><term>Rotate</term>
      <listitem><para>
	The entire study (including all objects within it) can be
        rotated around the view center in this page.  There is one
        dial for each of the three slice planes.  The transverse dial
        will spin the study in the transverse plane (i.e. rotate on
        the z-axis).  The coronal dial will spin the study in the
        coronal plane (i.e. rotate on the y-axis).  And the sagittal
        dial will spin the study in the sagittal plane (i.e. rotate
        on the x-axis).  The "reset to default" button allows the study
        to be rotated back to the default orientation.  On the
        bottom of this page is a matrix showing the coordinate frame
        of the study with respect to the base coordinate frame.
        </para></listitem>
    </varlistentry>

    <varlistentry><term>ROI/View Preferences</term>
     <listitem><para>
	The width of the line used to draw geometric ROIs can be
	altered here (1-5 pixels).  This parameter is not relevant for
	isocontour ROI's.  For isocontour ROI's, you can choose to have
        them draw as filled in or hollow.
     </para><para>
	Canvas layout allows you to switch the three views
	(transverse, coronal, and sagittal) between a linear style
	layout more commonly seen in PET software, and an orthogonal
	style layout more commonly seen in MRI software.  "Maintain
	view size constant" allows you to pick if you want the size of
	the view to remain constant or not.  If not checked, the size
	of the views shown will depend only on the data sets selected.
	If the checkbox is checked, the size of the views will depend
	on all the data sets in the study.  Finally, "target empty
	area" is for setting the size of the empty area in the middle
	of the target (the crosshairs on the views when changing the
	view location).
     </para></listitem>
    </varlistentry>
    
    <varlistentry><term>Immutables</term>
      <listitem><para>
	This panel lists information about the study that cannot be
	altered.  "Voxel dim" is the preferred voxel dimension, this
	is what the canvas will use as the "basic" voxel dimension,
	from which the zoom factor is relative too.
	</para></listitem>
    </varlistentry>

    </variablelist>

 </sect2>
</sect1>





<!-- ###################################### -->
<sect1 id="series">
  <title>Viewing Series of Slices</title>
<para>
   Instead of looking at three orthogonal slices through the data set,
   a series of slices (all of the same orientation) can also be
   examined.  Select: "View->Series", and a dialog box will come up
   allowing you to pick which objects you'd like to display on the
   series viewer, along with if you'd like to display the slices over
   space, time, or gates.  The thickness of the slices are determined
   at the time the series window is brought up.  A slider appears on
   the top of the window which allows moving through the data set.
   Note that since slices are cached in memory after being displayed,
   already displayed slices do not need to be regenerated from the
   data set and reviewing these slices is significantly faster.
</para>
</sect1>






<!-- ###################################### -->
<sect1 id="rendering">
  <title>Rendering Data</title>

<para> Rendering in AMIDE is accomplished using the <ulink type="http"
  url="http://graphics.stanford.edu/software/volpack/"> Volpack volume
  rendering library</ulink>.  This software library is both portable,
  and provides for true volume rendering (as opposed to the surface
  rendering used by many other libraries and hardware
  accelerators).</para>

<para> To start a rendering window, select the "View->Rendering" menu
  item.  A small dialog window will pop-up allowing you to select
  which objects you'd like rendered, along with some additional
  options.  The first "Set values greater than max threshold to zero"
  allows you to strip high level voxels out of the rendering process.
  In general you won't want this, but it might be useful if you have
  high valued areas in your data set that obscures what you'd like to
  see.  The second option "Accelerate Rendering" tells VolPack to use
  a faster method for doing the volume rendering.  You will in general
  want to use this option, as it causes a significance performance
  enhancement (around 10 fold).  It does, however, require around 3
  fold as much rendering as the non-accelerated option, so if you're
  running out of memory, you'll want to try to rendering without the
  acceleration. The third option "Initial opacity functions only
  density dependent" sets things such that the initial gradient
  opacity function does not contribute to the rendering.  This is
  useful for data sets (e.g. PET) where one is more interested in
  having an accurate view of the data, rather than a view where
  gradients in the data set are highlighted.</para>

<para> After hitting "Execute" the program will reslice the data sets
  and ROI's into a data structure that the volpack library can handle,
  and then perform some initial renderin gcalculations.  For data
  sets, the <link linkend="interpolation">interpolation type</link>
  specified for the data set will be used. This whole process will
  take some time, so be patient.  Please also note that, when
  converting the data set, the data is scaled between the current
  minimum and maximum threshold, with all data above the current
  maximum threshold set to the maximum threshold value (or zero, if
  specified), and all data below the current minimum threshold set to
  the minimum threshold value.  This scaling can be relative to the
  data set's "Global" maximum and minimum, to the "Per Frame" maximum
  and minimum, or can be from maximum and minimum values "Interpolated
  Between Frames".  "Per slice" scaling does not make sense in the
  context of volume rendering, and is interpreted as "Global"
  scaling. </para>

<para> When all this is completed, the rendering window should pop-up.
  Its use is described below. </para>



<sect2><title>Rendering Window</title>

  <sect3><title>Main Rendering Canvas</title>
    <para>
      The result of the rendering process is presented on the canvas
      in the center of the window.  This canvas can accept user input
      to change the orientation of the rendering.  Button 1 allows
      rotating on the x and y axis, and button 2 allows rotating on
      the z axis.
    </para>
  </sect3>


  <sect3><title>Spin Sliders</title>
    <para>
      You should notice two slider type widgets, one on top of the
      rendered image, and one on the right side.  These are both
      appropriately labeled with the axis around which the rendering
      will be spun if they are changed.  Additionally you should
      notice a dial widget (labeled 'z').  The dial is for rotating on
      the z axis (which comes out of the plane of the display).  Note
      that the effect of rotations are cumulative.
    </para>
  </sect3>

  <sect3><title>Reset Axis</title>
    <para>
      This button will reset the rendering's orientation back to the
      default orientation.
    </para>
  </sect3>


  <sect3><title>Toolbar</title>

    <sect4 id="transfer-function-dialog"><title>Transfer Function Button</title>

    <para> This will pop-up a dialog with a panel for each object
    being rendered.  The available options are described below:
    </para>

    <variablelist>

    <varlistentry><term>Return Type</term>
      <listitem><para>This setting determines whether the rendering returns an
      image which looks more analogous to an x-ray (the "opacity"
      setting), or returns an image which looks more like a surface
      (the "grayscale" setting).  The "grayscale" setting does this by
      specifying a light source, material properties, and using depth
      cueing. </para></listitem>
    </varlistentry>

    <varlistentry><term>Color Table</term>
      <listitem><para>
	The color table of each rendered object can be changed here.
      </para></listitem>
    </varlistentry>

    
    <varlistentry><term>Classification Functions</term>
      <listitem>
      <para>
	This is the most confusing part of rendering, so hang on here.
	The classification functions are used to map between the value
	in each voxel and how much that voxel should be represented in
	the final rendered image.  On the x axis is the possible
	values of the different voxels.  On the y-axis is the opacity
	that will be given a voxel based on its value.
      </para>
      <para>
	Both classification functions have several buttons on the
	right side of their graphs.  The top button allows the
	classification function to be drawn as a spline.  The second
	button allows the classification function to be drawn as a
	series of straight lines.  Finally, the last button resets
	the classification function to a straight line.
      </para>
      <para>
	There are two classification functions:
      </para>

          <itemizedlist>

	  <listitem><para><emphasis>Density Dependent:</emphasis> This
	    function tells you how opaque each voxel will be based on
	    its current value.  In a sense, this is analogous to an
	    x-ray, where the amount of the x-rays that are absorbed in
	    a structure is related to the density of that structure.
	    of the display.</para></listitem>

	  <listitem><para><emphasis>Gradient Dependent:</emphasis>
	    Instead of relating the density of a voxel to its opacity,
	    this function relates the gradient of a voxel (how much
	    the value changes between this voxel and its neighbors)
	    to its opacity.  This has the effect of giving added
	    weight to surfaces.</para></listitem>

       </itemizedlist>
     </listitem>

     </varlistentry>
    </variablelist>
   </sect4>

    
   <sect4><title>Monoscopic/Stereoscopic Buttons</title>
    <para> You can choose between generating a single rendered image
      (monoscopic), or a stereoscopic image pair.  A stereoscopic
      image pair is a pair of images that have been generated at
      slightly different angles.  When viewed correctly, these two
      images can be interpreted by the viewer's eyes as a single image
      containing depth information.
     </para>
   </sect4>

   <sect4><title>Zoom</title>
    <para> Determines the size at which the resultant rendered image
     will be displayed.  Note that changing the zoom will not affect
     the speed of the rendering, and increasing the zoom past 1 will
     not increase the resolution of the rendered image. </para>
   </sect4>

  </sect3>




  <sect3><title>Rendering Menus</title>
    <sect4><title>File->Export Rendering</title>
      <para>
	This menu item allows you to export the rendered image to
	an external image file.  The saved data format is 
        jpeg. </para>
    </sect4>

    <sect4><title>File->Create Movie</title>
      <para>
	This causes the movie generation dialog box to pop up.  This
	dialog box is further described below: <xref
	linkend="rendering-movie-dialog" />.
      </para>
    </sect4>
  
    <sect4><title>Edit->Rendering Parameters</title>
      <para>
	This causes the rendering parameters dialog box to pop up.
	This dialog box is described below: <xref
	linkend="rendering-dialog" />.
      </para>
    </sect4>
  </sect3>
  
</sect2>

<sect2 id="rendering-dialog"><title>Rendering Parameters Dialog</title>

  <sect3><title>Speed versus Quality</title>
   <para> With this drop-down menu, the user can choose between
   rendering speed and rendering quality.  To increase speed, voxels
   with values either close to zero or close to unity can be counted
   as completely translucent or completely opaque, respectively.  The
   highest quality doesn't use this approximation at all, the lowest
   quality setting uses this approximation big-time. </para>
  </sect3>


  <sect3><title>Stereosopic parameters</title>

   <para>These parameters are used for controlling the results when
   the "stereoscopic" option has been chosen. </para>
      
   <sect4><title>Stereo Angle</title>
    <para> This is the angle offset (in degrees) between a pair of
    rendered images.  Increasing this number will generally give a
    greater sensation of depth in the image pair.  A Reasonable value
    for this parameter is between 2 and 5 degrees.  Note that this
    parameter will be saved between different sessions of the
    program (not currently done on MS Windows).</para>
   </sect4>
      
   <sect4><title>Eye Width (mm) </title>
    <para> Ideally, this should be (roughly) the distance between the
    two rendered images, and corresponds to the distance between the
    user's eyes.  It is impossible for a person to resolve a
    stereoscopic pair if the images are farther apart then the
    person's eyes, since human eyes cannot move independently.  While
    this parameter is specified in millimeters, the actually distance
    between the pair of images that gets displayed on the monitor
    depends on the setup of the computer.  If the monitor information
    reported by the operating system is not correct (usually the
    case), the "eye width" parameter will not be in true millimeters.
    Note that this parameter will be saved between different sessions
    of the program (not currently done on MS windows).</para>
  </sect4>

 </sect3>

 <sect3><title>Depth Cueing</title>

  <para> These parameters are only used if the "grayscale" output type
  has been chosen.</para>
      
  <sect4><title>Enable/Disable Depth Cueing</title>
   <para> Specify whether or not we want depth cueing.  Depth cueing
   puts in a "fog" that causes more distant voxels to appear less
   bright.</para>
  </sect4>
      
  <sect4><title>Front Factor</title>
   <para> This is the transparency of the fog at the front of the data
   set.  If this number is greater than 1.0, voxels toward the front
   of the data set will be brightened.  If this parameter is less than
   1.0, voxels toward the front of the data set will be darker,
   respectively.</para>
  </sect4>

  <sect4><title>Density</title>

   <para> This is how thick the "fog" is.  The thicker the fog, the
   darker distant objects seem. </para>
  </sect4>
 </sect3>
</sect2>
    

<sect2 id="rendering-movie-dialog"><title>Rendering Movie Dialog</title>

 <sect3><title>Frames</title>
      <para>
	How many frames should be in the MPEG1 movie.  The MPEG1
	movies generated will be set to run at 30 frames/second, so
	the default of 300 frames will give a ten second movie.
      </para>

 </sect3>

 <sect3><title>Rotations on [x,y,z] </title> 
      <para> 
	This setting determines how many times the data set will be
	rotated around the given axis over the course of the movie.
	The rotation for each frame is done in x->y->z order (rotate
	on x first, then y, then z).
      </para>
 </sect3>

 <sect3><title>Dynamic Movie: No/Over Time/Over Frames Smoothed/Over Gates</title>

   <para> This option allows a rendered movie to be made over a time
   period, which is useful for dynamic data sets. 
   </para>

    <para> Note that every time a frame boundary in the data set is
    passed over, the rendering process must slice and load in a new
    frame of data.  This makes creating a rendered movie over time
    significantly slower than a movie with just rotations.
    </para>

   <para> Picking "over time" will allow entry of a start and end time
   for which the data from the data sets should be drawn.  With the
   "over time" option, each second is given equal waiting in terms of
   how many images from that time period are generated for the output
   movie.</para> 

   <para>Picking "over frames" allows entry of a start and end frame
   (note that this really only makes sense with a single data set).
   The advantage of "over frames", is that each frame is weighted
   equally in terms of how many images are generated for the output
   movie, so for data sets were the dynamics of interest correspond
   closely to the dynamics of the data set framing sequence, "over
   frames" may give a more appealing result.
   </para>

   <para> The "over frames smoothed" option is almost the same as
   "over frames", except that data will be interpolated between
   frames.  This makes for a smoother movie (no jumps) but takes much
   longer as nearly every movie frame has to be reloaded.
   </para>

 </sect3>

</sect2>

</sect1>




<!-- ###################################### -->
<sect1 id="tools">
  <title>Additional Tools</title>

<sect2><title>Alignment Wizard</title>

  <para>In addition to manually aligning data sets (described at <xref
  linkend="manual_alignment" />), data sets can also be aligned using
  the alignment wizard utilizing either mutual information or
  fiducial markers.</para>


  <sect3 id="mutual_information"><title>Alignment with Mutal Information</title>
  <para> A rigid body alignment can be performed utilizing mutual
  information between two data sets. This algorithm works by
  taking orthogonal slices from one data set (transverse, coronal, and
  sagittal) and computing a transform to best allow matching of these
  slices to the second data set. This algorithm works best when the
  two data sets have already been roughly aligned. Note that the
  orthogonal slices utilized for the matching are derived utilizing
  the current viewing parameters (current viewing location, slice
  width, interpolation method, etc).
  </para>
  </sect3>

  <sect3 id="procrustes"><title>Alignment with Fiducial Markers</title>

  <para>A rigid body alignment can be performed utilizing fiducial
  markers. The process is basically:</para>
  
  <procedure>
    <step>
      <para>
       Draw at least three pairs of fiducial makers between the two
       data sets that you wish to align.  Drawing fiducial markers is
       described below as <xref linkend="fiducial-marker" />.
      </para>
    </step>
    <step>
      <para>
       Run the alignment wizard (under tools->alignment wizard).  For
       the alignment wizard to recognize two fiducial markers as a
       pair, they must have exactly the same name.  So if you have a
       marker labeled "1" under the first data set, you will need
       another marker, also labeled "1", under the second data set.
      </para>
    </step>
  </procedure>          
  </sect3>
  

  <sect3 id="fiducial-marker"><title>Drawing Fiducial Markers</title>
   <para>
    Fiducial markers can be added to any of the data sets in the study
    in a variety of ways.  For the currently active data set, hitting
    the "Edit->Add fiducial mark" menu item will drop a fiducial maker
    at the currently viewed location.  Fiducial marks can be added for
    the active data set directly from the views by pressing ctrl-right
    mouse button, which will drop a fiducial marker at the point that
    the mouse is currently at.  Finally, fiducial markers can be added
    to non-active data sets by pressing ctrl-right mouse button while
    hovering over a data set's name in the study list.</para>

   <para>After being created, the fiducial marker can be moved by
    clicking on the marker point shown in any of the views.
   </para>
 </sect3>

 <sect3 id="fiducial-marker-dialog"><title>Fiducial Marker Modification Dialog Box</title>
  <para>
      To modify parameters of a fiducial mark, right click the point
      in the study list to pop-up the Fiducial Marker Modification
      Dialog.  From this dialog, the name and location of the fiducial
      marker can be altered.
  </para>
    
 </sect3>

</sect2>


<sect2><title>Crop Wizard</title> 

  <para>Coming soon.  Note that only what is strictly inside the
   cursor lines is saved.  What's underneath and outside the cursor
   lines is cropped away. </para>
</sect2>


<sect2><title>Factor Analysis Wizard</title>
   <para>The factor analysis wizard is currently being developed.  It
   probably won't work for you, and is only included in AMIDE for
   those who might be interested in working on it (rather than with
   it).</para>
</sect2>


<sect2><title>Filter Wizard</title>
   <para>Nothing written yet...</para>
</sect2>


<sect2><title>Fly Through Wizard</title>
   <para>Nothing written yet...</para>
   <para> Note, will generally get much better results for fly through
   if using trilinear interpolation.</para>
</sect2>


<sect2 id="profile-dialog"><title>Profile Tool</title>
 <para>A complete description of this tool has not yet been written.</para>

 <para> The left and right limits of the gaussian fit can be altered
 by clicking on the profile with the left and right mouse buttons,
 respectively.  The x value used for initializing the gaussian fit can
 be picked by clicking on the profile with the middle mouse button.
 </para>

 <para> Note that the line profile is extracted from the currently
   viewed image, not the underlying raw data itself. This means things
   like the current interpolation and FOV will effect the line profile
   that's generated, and as such may effect the FWHM that's fitted.
 </para>

</sect2>


<sect2><title>ROI Statistics</title>
   <para>A description of the ROI statistics tool can be found at:
   <xref linkend="roi_statistics" />.</para>
</sect2>

</sect1>

</article>