==============
The Gamera GUI
==============

Starting the GUI
----------------

There is a ``gamera_gui`` script installed somewhere on your system
(platform-specific, see `Building and Installing Gamera`__).  Run it
to start the Gamera GUI. 

.. __: install.html

.. note:: It is possible to run Gamera image processing without the
   GUI, saving the memory and runtime overhead.

Console window
--------------

  .. image:: images/console.png

The main Gamera console window is divided into three parts: the Python
console, the icon display and the information pane.

Python console
``````````````

On the right is a standard Python console.  You can type code
here and it is run interactively.  Most operations that you perform
using the mouse in the GUI will generate code that is entered in the
interpreter here.  This code and be copied-and-pasted into your
favorite programmer's editor to build Gamera image processing scripts.

The Python console features auto-completion.  For example, load an
image and store it in the variable name ``image``.  Type ``image.`` in
the console, and a window will appear showing all of the (many)
members and methods of the image.

  .. image:: images/autocompletion.png

Icon display
````````````

On the left, all active image objects (displayed as icons.  When you load images,
they are displayed here.

The icon indicates the pixel type of the image.  See `Image types`__
for more information on the different image types in Gamera.  

A magnifying glass appears over the icon if the image is a subimage of
another image.  It acts as a warning that any changes made to this
image will affect another.

.. __: image_types.html

The icons are as follows:

  +------------------+---------------------+-----------------------+
  | Image            | SubImage            | Description           |  
  +==================+=====================+=======================+
  | |RGBImage|       | |RGBSubImage|       | RGB (24-bit color)    |
  +------------------+---------------------+-----------------------+
  | |GREYSCALEImage| | |GREYSCALESubImage| | GreyScale (8-bit)     |  
  +------------------+---------------------+-----------------------+
  | |GREY16Image|    | |GREY16SubImage|    | Grey16 (16-bit)       |
  +------------------+---------------------+-----------------------+
  | |FLOATImage|     | |FLOATSubImage|     | Floating-point image  |
  +------------------+---------------------+-----------------------+
  | |ONEBITImage|    | |ONEBITSubImage|    | One-bit (binary)      |
  +------------------+---------------------+-----------------------+

.. |RGBImage| image:: images/icon_image_rgb.png
.. |GREYSCALEImage| image:: images/icon_image_grey.png
.. |GREY16Image| image:: images/icon_image_grey16.png
.. |FLOATImage| image:: images/icon_image_float.png
.. |ONEBITImage| image:: images/icon_image_binary.png
.. |RGBSubImage| image:: images/icon_subimage_rgb.png
.. |GREYSCALESubImage| image:: images/icon_subimage_grey.png
.. |GREY16SubImage| image:: images/icon_subimage_grey16.png
.. |FLOATSubImage| image:: images/icon_subimage_float.png
.. |ONEBITSubImage| image:: images/icon_subimage_binary.png

There are other things that can appear in the icon display as well:

  +------------------+------------------------------------------+
  | |ImageList|      | A list of images                         |
  +------------------+------------------------------------------+
  | |Cc|             | A connected component                    |
  +------------------+------------------------------------------+
  | |Classifier|     | A classifier object                      |
  +------------------+------------------------------------------+
  | |NonClassifier|  | A non-interactive classifier object      |
  +------------------+------------------------------------------+

.. |ImageList| image:: images/icon_image_list.png
.. |Cc| image:: images/icon_cc.png
.. |Classifier| image:: images/icon_classify.png
.. |NonClassifier| image:: images/icon_noninter_classify.png

Context menu
''''''''''''

Right-clicking on any of these icons brings up a context menu to
perform operations on an image.

  .. image:: images/right_click_menu.png

At the top of the menu, the pixel type is displayed.

The next two items are for creating new references and copies of the
image.  You will be prompted for a variable name for the result.

The **Info** submenu displays basic information about the image.

The rest of the context menu contains plugin methods, sorted by category.  The
plugin methods are documented here__.
Many of the plugin methods require arguments.  In that case, a dialog
will be displayed.  This dialog includes a brief description of the
method, if available.  For example the dialog for ``erode_dilate`` is:

  .. image:: images/erode_dilate_dialog.png

After entering the arguments for a plugin function, code is generated
to perform the operation and automatically run in the console:

.. code:: Python

   >>>image.erode_dilate(5, 0, 1)

.. __: plugins.html

Information pane
````````````````

The information pane includes three modes, selectable via the tabs.
(These tabs will appear at the top of the information pane on Windows
and Mac OSX).  This functionality is adapted from the PyCrust_ project
and should be familiar to users of that tool.

.. _PyCrust: http://sourceforge.net/projects/pycrust/

Documentation
'''''''''''''

The documentation pane displays the docstring of the object that was
last typed in the console window.  

For an example, type "Image(" in the console, and the docstring for
the Image constructor will be displayed.

Namespace
'''''''''

This is a "namespace browser" which displays the objects in the
namespace of the console in a tree like view. 

For an example, type ``x = 5`` in the console, and then find the
variable ``x`` in the locals part of the namespace tree.

History
'''''''

History contains a command history that can be copied-and-pasted into
an editor to develop scripts.

Console menu
````````````

File menu
'''''''''

**Open...**
  Open an image.

**Exit**
  Exit Gamera.

Classify menu
'''''''''''''

**Interactive Classifier**
  Create a new `Interactive Classifier window`_.

Toolkits
''''''''

See `Writing toolkits`__ for more information.

.. __: writing_toolkits.html

Image display
-------------

Double-clicking on the image icon will display the image in its own
window.  Alternatively, you can use the ``display`` method:

.. code:: Python

   >>>image.display()

.. image:: images/display.png

Rectangular regions of the image can be selected by clicking and
dragging a bounding box on the image itself.  The selection can be modified by dragging the
drag boxes in the corners of the selection.

Right-clicking on the image brings up the same `context menu`_ as in the `icon display`_.

The image display toolbar has the following buttons:

  +-----------------+--------------------------------------------------------------+
  | |Refresh|       | Force a refresh of the display, in case any change has       |
  |                 | occurred to the image.                                       |
  +-----------------+--------------------------------------------------------------+
  | |ZoomIn|        | Zoom in.                                                     |
  +-----------------+--------------------------------------------------------------+
  | |ZoomNorm|      | Actual size.                                                 |
  +-----------------+--------------------------------------------------------------+
  | |ZoomIn|        | Zoom out.                                                    |
  +-----------------+--------------------------------------------------------------+
  | |ZoomHighlight| | Zoom so that the highlighted region is fit to the window     |
  |                 | as closely as possible.                                      |
  +-----------------+--------------------------------------------------------------+
  | Zoom quality    | low quality						   |
  |                 |    no interpolation                                          |
  |                 | medium quality                                               |
  |                 |    linear interpolation                                      |
  |                 | high quality                                                 |
  |                 |    spline interpolation                                      |
  +-----------------+--------------------------------------------------------------+
  | |NewReference|  | Create a new subimage from the currently selected area (or   |
  |                 | the entire image if there is no selection.)                  |
  +-----------------+--------------------------------------------------------------+
  | |NewCopy|       | Create a new copy of the currently selected area of the image|
  |                 | (or the entire image if there is no selection.)		   |
  +-----------------+--------------------------------------------------------------+
  | |Save|          | Saves the image to a file.                                   |
  +-----------------+--------------------------------------------------------------+
  | |Print|         | Prints the image.                                            |
  +-----------------+--------------------------------------------------------------+

.. |Refresh| image:: images/icon_refresh.png
.. |ZoomIn| image:: images/icon_zoom_in.png
.. |ZoomNorm| image:: images/icon_zoom_norm.png
.. |ZoomOut| image:: images/icon_zoom_out.png
.. |ZoomHighlight| image:: images/icon_zoom_view.png
.. |NewReference| image:: images/icon_make_view.png
.. |NewCopy| image:: images/icon_image_copy.png
.. |Save| image:: images/icon_save.png
.. |Print| image:: images/icon_printer.png

.. note:: 
  On Linux and OS-X, the Print command works by printing to a
  PostScript file and then sends the result to ``lpr``.  Because of
  this, it cannot properly detect the resolution of the printer.
  Therefore, a reasonable default of 720dpi is used.  Future versions
  of wxPython may handle this better.

Multiple image display
----------------------

Double-clicking on a list of images in the icon display brings up the
**multi-image display** window.  Alternatively, you can use the
``display_multi`` function:

.. code:: Python

  >>>display_multi(list_of_images)

Images are displayed in a grid.  By default, the images are sorted so
the grid takes up a minimum amount of total space.

  .. image:: images/multi_display.png

Images can be selected by clicking on a cell in the grid.  Individual cells
can be added to the selection by **Ctrl** clicking.  Ranges of cells
can be selected by **Shift** clicking.

The `context menu`_ can be used to perform operations on multiple
images.  Right-clicking on a selected image brings up the context menu.

The multi-display toolbar has the following items:

  +-----------------+--------------------------------------------------------------+
  | |Refresh|       | Force a refresh of the display, in case any change has       |
  |                 | occurred to the image.                                       |
  +-----------------+--------------------------------------------------------------+
  | |ZoomIn|        | Zoom in.                                                     |
  +-----------------+--------------------------------------------------------------+
  | |ZoomNorm|      | Actual size.                                                 |
  +-----------------+--------------------------------------------------------------+
  | |ZoomIn|        | Zoom out.                                                    |
  +-----------------+--------------------------------------------------------------+
  | |Label|         | Displays a value within each cell. The value is determined by|
  |                 | the expression in the drop-down text box to the left of      |
  |                 | the label button.                                            |
  |                 | Within the context of the expression, `x` represents the     |
  |                 | image within each cell, and the expression is evaluated to   |
  |                 | determine the result to display.                             |
  +-----------------+--------------------------------------------------------------+
  | |SortA| |SortD| | Sorts the images in the grid based on a given property.  The |
  |                 | property is determined by the expression in the drop-down    |
  |                 | text box to the left of the sort buttons.                    |
  +-----------------+--------------------------------------------------------------+
  | |Select|        | Selects the image in the grid based on a given criteria.     |
  |                 | The criteria is determined by the expression in the drop-down|
  |                 | text box to the left of the select button.                   |  
  |                 | Within the context of the expression, `x` represents the     |
  |                 | image within each cell.  When the expression evaluates to    |
  |                 | ``True``, the image will be selected.                        |
  +-----------------+--------------------------------------------------------------+
  | |SelectAll|     | Selects all images.                                          |
  +-----------------+--------------------------------------------------------------+

.. |Label| image:: images/icon_show_name.png
.. |SortA| image:: images/icon_sort_asc.png
.. |SortD| image:: images/icon_sort_dec.png
.. |Select| image:: images/icon_select.png
.. |SelectAll| image:: images/icon_select_all.png

Interactive classifier window
-----------------------------

The interactive classifier window is the most involved part of the
Gamera GUI.  It is where you can train the Gamera classifier to
recognize different symbol types.

  .. image:: images/classifier_window.png

A tutorial introduction to training image data is given in the
`training tutorial`__.

.. __: training_tutorial.html

Concepts
````````

Before the parts of the classifier window are discussed, some general
concepts should be understood.

Glyph collections
'''''''''''''''''

In the classifier window, there are two sets of glyphs (connected
components) involved: one in the classifier and one for the current page:

Classifier glyphs
  The set of glyphs used by the classifier to make guesses about
  unknown glyphs.  The classifier glyphs work "behind the scenes".

Page glyphs
  The set of glyphs on the current page.

When glyphs on the page are classified by the user, they
are copied into the classifier.  When glyphs are deleted or renamed in
either collection, they are updated in both places.

The number of glyphs on the page and in the classifier are displayed in
the status bar at the bottom of the window.


Coloring
''''''''

When connected components are displayed in the classifier, they are
colored according to how they were classified:

  +----------+--------------+-----------------------------------------------------+
  | Color    | Constant     | Description                                         |
  +==========+==============+=====================================================+
  | |UColor| | UNCLASSIFIED | The connected component is completely unclassified. |
  | (white)  |              |                                                     |
  +----------+--------------+-----------------------------------------------------+
  | |AColor| | AUTOMATIC    | The connected component was classified by the       | 
  | (red)    |              | automatic classifier using training data.           |
  +----------+--------------+-----------------------------------------------------+
  | |HColor| | HEURISTIC    | The connected component was classified by some      |
  | (yellow) |              | heuristic (non-exemplar-based) process.             |
  +----------+--------------+-----------------------------------------------------+
  | |MColor| | MANUAL       | The connected component was classified by a human.  |
  | (green)  |              |                                                     |
  +----------+--------------+-----------------------------------------------------+

.. |UColor| image:: images/unclassified_color.png
.. |AColor| image:: images/autoclassified_color.png
.. |HColor| image:: images/heuristicclassified_color.png
.. |MColor| image:: images/manualclassified_color.png

Class names
'''''''''''

"Class names" name a particular class of symbols.  Class names are made
up of period-delimited parts so that they can be grouped into
categories.  Names can be invented on the fly.

For instance, if you were training for a subset of the characters in the
English language, you might have the following class names::

  lower.a
  lower.b
  lower.c

  upper.a
  upper.b
  upper.c

  punctuation.comma

These period-delimited parts are used to create a tree-like structure
in the classifier window that might look something like:

  .. image:: images/symbol_table_example.png

Special class names
...................

Special class names begin with an underscore (``_``).

``_group``
  Glyphs trained with names beginning with ``_group.`` are first
  grouped together and then trained as a single unit.  For instance,
  you may wish to train lowercase i's (which are made up of two
  connected components) as a single logical unit.  Select both parts
  (by dragging a bounding box around them in the original image
  display) and then train as ``_group.lower.i``.

``_split``
  Glyphs trained with names beginning with ``_split.`` are run
  through a given splitting algorithm.  For instance, glyphs that
  need to be broken into upper and lower halves for further
  classification of those parts would be trained as
  ``_split.splity``.  When the automatic classifier encounters glyphs
  that most closely match those trained as ``_split``, it will perform
  the splitting algorithm and then continue to recursively classify its parts.

  The splitting algorithms are documented `here`__.

.. __: plugins.html#segmentation

  New splitting algorithms can be created by `writing plugin`__ methods
  in the category ``Segmentation``.  

.. __: writing_plugins.html

Parts of the classifier window
``````````````````````````````

The interactive classifier window is divided into three parts: The
symbol table, the connected component display, and the original image
display.

Symbol table
''''''''''''

The symbol table is a hierarchical tree of symbol names that are
currently in use.  It is preloaded with `special class names`_.

Symbols can be trained by typing the class name in the text box at
the top or double-clicking on a class name in the tree.  The text box
features auto-completion (similar to the Unix shell), so you can type
a partial name and then press the <Tab> key to attempt to complete it.

Connected component display
'''''''''''''''''''''''''''

The connected component display is made up of two collapsible
displays.  To expand or collapse the panes, use the *+* and *X*
buttons in the panes' title bars.  By default, only the page glyphs
pane is displayed.

.. note:: Training will run much slower with the classifier glyphs
          displayed.  It is recommended that you leave it closed
          unless you are interested in what is there.

The connected components panes behave identically to the `multiple
image display`_, with additional functionality.

When connected components are selected in the page glyphs pane, 
they are highlighted in the original image display below.

The background of connected components are colored based on their
classification state.  (See `coloring`_).

There are some additional toolbar buttons:

  +-----------------+--------------------------------------------------------------+
  | |Delete|        | Deletes the selected connected components.  They will be     |
  |                 | displayed with a red-hatching pattern to indicate they are   |
  |                 | deleted.  Re-sorting the connected component display will    |
  |                 | remove them completely.  Deleted glyphs are never saved to   |
  |                 | disk.                                                        |
  +-----------------+--------------------------------------------------------------+
  | |NextU| |NextA| | Auto-move toggles.					   |
  |                 | Whenever a glyph is classified, the 'cursor' will            |
  | |NextH| |NextM| | automatically move to the next glyph that matches any of the |
  |                 | selected types: UNCLASSIFIED, AUTOMATIC, HEURISTIC or MANUAL.|
  +-----------------+--------------------------------------------------------------+

.. |Delete| image:: images/icon_delete.png
.. |NextU| image:: images/icon_next_unclass.png
.. |NextA| image:: images/icon_next_autoclass.png
.. |NextH| image:: images/icon_next_heurclass.png
.. |NextM| image:: images/icon_next_manclass.png


Original image display
''''''''''''''''''''''

The original image display, for the most part, behaves identically to
the standard `image display`_.

Clicking on a connected component will select it in the connected
component display.  Dragging a bounding box around a
collection of connected components will select multiple connected
components.  Additional connected components can be added to the
selection by Shift-clicking.

There are some additional toolbar buttons:

  +-----------------+--------------------------------------------------------------+
  | |Mark|          | (Toggle) Display an animated rectangle around the            |
  |                 | currently selected connected component.                      |
  +-----------------+--------------------------------------------------------------+

.. |Mark| image:: images/icon_mark_highlights.png

Classifier menu
```````````````

File menu
'''''''''

.. note:: 
   If you give any of the XML files a ``.gz`` extension, they
   will be transparently converted to/from Gzip-compressed files.
   This saving and loading is actually faster!

**Open all...**
  Opens a special directory of files containing an original image, and
  contents of the editor and the classifier.  This directory should be one
  created by **Save all...**

**Save all...**
  Saves all of the data necessary to restore the classifier's state
  into a special directory.  This includes the original image and the
  contents of the editor and the classifier.  This special directory can be
  reloaded using **Open all...**.

The following options are used to save and load connected components in the
`Gamera XML format`__.

.. __: xml_format.html

**Save by criteria...**
  For *expert* users.  Provides a dialog box to save different
  sets of glyphs to a single XML file.

  .. image:: images/save_by_criteria.png

**Classifier glyphs**
  This menu allows one to Open, Merge,
  Save, Save As or Clear the glyphs in the classifier.  (See `glyph
  collections`_).

**Page glyphs**
  This menu allows one to Open, Merge, Save, Save
  As the glyphs on the current page display.  (See `glyph
  collections`_).

**Save selected glyphs as...**
  Saves the selected glyphs to a new file.

**Symbol names**
  Import or export a set of symbol names.  Symbol names can be
  imported from a full Gamera XML file containing images, or a symbol
  name-only Gamera XML file.

Image menu
''''''''''

**Open and segment image...**
  Loads an image from disk and then performs a given segmentation
  algorithm on it to create connected components.  The segmentation
  algorithm can be selected from the drop-down list.  (If you're not
  sure which one to use, try ``cc_analysis``.)  The connected
  components are loaded into the page glyphs pane and the
  original image is loaded into the original image display.

**Select and segment image...**
  Select an already-loaded image from the console, and perform a given
  segmentation algorithm on it to create connected components.  The
  segmentation algorithm can be selected from the drop-down list.  (If
  you're not sure which one to use, try ``cc_analysis``.)  The
  connected components are loaded into the page glyphs pane
  and the original image is loaded into the original image display.

**Select image...**
  Select an already-loaded image from the console and use it as the
  original image.  This image does not have to correspond to the
  contents of the page glyphs pane.

**Save glyphs into separate files**
  Saves each of the connected components into a separate image file in
  a given directory using one of the following sets of connected
  components:

    - Classifier glyphs...)
    - Page glyphs...
    - Selected glyphs...

  See `glyph collections`_.

Classifier menu
'''''''''''''''

**Guess all** / **Guess selected**
  Classifies the glyphs using the automatic classifier.  Glyphs that
  were classified manually are not reclassified (they must be
  unclassified first).
  
**Group and guess all** / **Group and guess selected**
  Classifies the glyphs using the automatic classifier, while
  attempting to group nearby connected components to form glyphs that
  are more similar to glyphs in the classifier.  This process
  can take considerably longer than one-by-one classification.

  The parameters are described in greater detail in the classifier documentation__.

.. __: classify.html#group-list-automatic

**Confirm all** / **Confirm selected**
  Treats all automatically classified glyphs as if they were manually
  classified and adds them to the classifier.  Use this
  function only when you are sure all glyphs are correctly classified.

**Display contents**
  Displays the glyphs in the classifier in a new window.  As of this
  writing this display is read-only and not "live" (i.e. it will not
  change when the contents of the classifier change).  This
  shortcoming should be remedied in a future version of Gamera.

**Change set of features**
  Change which features of the connected components are used for
  classification.  The features themselves are documented here__.

.. __: plugins.html#features

  .. image:: images/feature_selection.png

**Classifier settings**
  Allows the settings specific to a particular classifier type to be
  changed, saved or loaded.

**Create noninteractive copy**
  When training is completed (or partially completed) this function
  will create a noninteractive copy, which is likely more optimized
  than the interactive version (depending on the classifier type).

**Create edited classifier**
  This option will show a dialog to create a new classifier with a modified 
  training-set based on the current classifer. This modified classifier is 
  produced by one of several kNN-editing algorithms which the user can chose
  from. Depending on the chosen algorithm a set of parameters is displayed which
  can be changed by the user to tune the algorithm's results. Additionally the 
  documentation for this algorithm and its parameters is displayed.
  
  .. image:: images/knn_editing.png
  
  After confirming this dialog, the user is prompted to select a name for the 
  new classifier. The classifier will then be added to the icon display in the 
  console under this name.
  
  The produced classifier is usually improved either in terms of speed or 
  classification accuracy, depending on the chosen algorithms and its 
  parameters. For details about the algorithms, their parameters and how to 
  include your own editing algorithms see the `classifier documentation`__.

.. __: classify.html#improving-knn-classifiers-using-editing

Rules menu
''''''''''

Unstable.

TODO: Write me.
