Dies ist gift-guide.info, hergestellt von Makeinfo Version 4.0 aus
/tmp/sgmltmp.gift-guide1495.info.2.

   \input texinfo


File: gift-guide.info,  Node: Top,  Next: Introduction,  Up: (dir)

GIFT user's guide
*****************

     Wolfgang Müller
     0.1.2, 18th of August 2000

   The GIFT is a content based image retrieval system.

* Menu:

* Introduction::
* MRML - Why we publish GIFT this way::
* Installation::
* Prepare and run the server::
* Getting started with the Charmer interface::
* How to analyze GIFT::
* ToDo List::
* Contact details::


File: gift-guide.info,  Node: Introduction,  Next: MRML - Why we publish GIFT this way,  Prev: Top,  Up: Top

Introduction
************

   Caveat: THIS PROGRAM NEEDS MORE PREREQUISITES THAN OTHER GNU
PACKAGES (see below). At present, it installs neither info files nor
man pages. However, otherwise the install procedure tries to be GNU
conformant.

   GIFT is a content based image retrieval system (CBIRS). It gives the
user the possibility to index and search images without having to
annotate them first. Indexing is done using image properties such as
color and texture.

   The query is one or multiple image `examples'.

   Content based image retrieval (CBIRS) is presently an area of vivid
research interest, yielding many different systems.

   Our system is different from other systems with respect to the
indexing method. We use very many very simple features which are
translated into some kind of "pseudo text" for each image. On this
representation we use inverted files as indexing technique. In our
opinion this representation has two great advantages:
   * The representation is very flexible, in that it allows good
     incorporation of relevance feedback.

   * The representation is very flexible, in that it will allow
     completely integrated trea§tment of text (ASCII, HTML etc.) and
     images.

   both at a reasonable speed, which we hope to increase further. The
current implementation still leaves room for optimization.

   This document will be the user's guide to the GIFT content based
image retrieval system. It is aimed at the user of such a system.  Its
companion document will be a programmer's manual elaborating details of
interfacing etc. and a document describing the communication protocol,
MRML, which we use for the communication between the user interface and
the image retrieval system.


File: gift-guide.info,  Node: MRML - Why we publish GIFT this way,  Next: Installation,  Prev: Introduction,  Up: Top

MRML - Why we publish GIFT this way
***********************************

   One big problem of CBIRS research is the non-existence of a common
benchmark, measuring the quality of retrieval results. In our project
we have both worked on reasonable measures for benchmarks, and on
software for performing this.  A precondition for a common benchmark is
a common interface (in the programming sense of the word), permitting
the connection of the benchmarking program to the benchmarked program.
MRML is an XML based language providing such an interface.

   The other great effect of such an interface language is the
possibility to create GUIs for CBIRS which can be used by all MRML
compliant servers.  Charmer provided by our partners at EPFL (contact
details in the Author field) is a very beautiful interface which will
equally become free software.

   We (EPFLausanne and CUI, Geneva) provide this software with the goal
of promoting the use of MRML. Wide-spread use of MRML could both help
scientists (less work and easier exchange) and normal users (easy
combination of software packages from different sources. Think, for
example, of a GIMP plug-in which would help the user organize his
images).

   In fact, the idea of having interested real-world users test a system
like ours is very attractive, as data about real users are hard to get.
We hope to motivate users to share anonymized, preprocessed log files
in order to help us improve our systems.


File: gift-guide.info,  Node: Installation,  Next: Prepare and run the server,  Prev: MRML - Why we publish GIFT this way,  Up: Top

Installation
************

   Caveat: THIS PROGRAM NEEDS MORE PREREQUISITES THAN OTHER GNU
PACKAGES. However, otherwise the install procedure is GNU conformant.

   Please tell us about any bugs in the installation procedure.

   The distribution so far has been tested on a GNU/Linux distribution
by SuSE, and on a SUN Ultra Sparc 10 running Solaris.  Both machines
had memory size 64MB and more than that.

   Get installed: you have received the package GIFT-0.1.4.tgz. Now:
   * Before doing anything make sure you have installed
        *  a recent g++ (egcs 1.1 or later)

        * Image Magick (the feature extraction uses it to convert image
          formats to PPM files.)

        * Perl younger than 5.003 (you get that at www.cpan.org)

        * The Perl modules
             * XML::Parser (you also get that at www.cpan.org)

             * XML::Writer

             * HTML::Parser (if not already provided by your GNU/Linux
               distribution)

             * libnet (if not already provided by your GNU/Linux
               distribution)

             * libwww (if not already provided by your GNU/Linux
               distribution)

     The reason for this is, that the current makefiles `test' for
     these programs, but they do not draw any consequences.

   * Unpack it by doing
          tar -xvf GIFT-0.1.4.tar

   * Follow the install instructions in the file
          INSTALL

   * If you have installed KDOC, change into the directory Doc, and do
          make system-doc
     .  You can now look at the system documentation by typing
          lynx Doc/autoDoc/HTML/hier.html
     .

   * Unpack now the charmer archive:
          tar -xvf
          Charmer-0.2.tar

   * Run the configuration script
          cd Charmer-0.2;perl write-applet-frame.pl


File: gift-guide.info,  Node: Prepare and run the server,  Next: Getting started with the Charmer interface,  Prev: Installation,  Up: Top

Prepare and run the server
**************************

   We assume that you have successfully installed GIFT. Now you want to
start the server, I suppose. But first you have to give to GIFT an
image collection.

* Menu:

* Where to put configuration data::


File: gift-guide.info,  Node: Where to put configuration data,  Up: Prepare and run the server

Where to put configuration data
===============================

   By default, the indexing data of the collections, as well as the
configuration files reside in your home directory.

   To change this default, set the environment variable
GIFT[lowbar]HOME the to absolute path of the directory where you want
your gift-indexing-data etc. to reside and put the line:

     export GIFT_HOME=/absolute/path/to/my_gift_home

   into your .bashrc

   Now you are ready to index a collection.

   The vanilla way of indexing a collection is by typing
     gift-add-collection.pl /absolute/name/of/a/directory/tree/containing/images/
   .  This script will then create the appropriate configuration files
and index directories in your home directory (or in $GIFT[lowbar]HOME).
Please note that it should be possible to index all images within your
home directory tree by typing

     gift-add-collection.pl ~
   .

   The script, as it is now takes 20-30 seconds per image to create the
base indexing data for inverted file creation. The inverted file
creation itself will take about 5 minutes to about an hour, depending
on the size of the collection. The biggest collections we have indexed
so far are 13000 images. This took our fast server two days. 500 images
get indexed on my portable AMD-K6-2-based computer in less than 3 hours.

   If you have to index a large collection or if you are indexing your
collection on a portable computer, indexing a collection in one run
becomes inacceptable. If you stop the
     gift-add-collection.pl
    during feature generation and indexing, you can resume by simply
restarting the program. On restart, it will check each file if it was
correctly generated and resume operation at the first file which was
not correctly generated.

   When the indexing is done, you can start the GIFT server:
     gift
   .  At the time of writing, gift will output tons of debugging output
on the screen. Most of the time it also will tell you why it dies, if it
dies. In the cases known to me, reasons for dying are usually
inappropriate config file locations, as well as the untrapped
possibilty to nuke the server using faulty XML.

   It will start up, and it will listen on the socket 12789 for
connecting clients.

   While 12789 is the port number by default, you can override this
default port number by giving it as the first parameter. In addition to
that you can override GIFT[lowbar]HOME by giving it as parameter to the
GIFT, for example:
     gift 12888 /usr/local/share/shared-gift-collections/


File: gift-guide.info,  Node: Getting started with the Charmer interface,  Next: How to analyze GIFT,  Prev: Prepare and run the server,  Up: Top

Getting started with the Charmer interface
******************************************

   * The installation is not yet GNU-ish: Simply do:
          cd Charmer-0.2;perl write-applet-frame.pl

   * Start the Charmer interface by typing
          cd Charmer-0.2;appletviewer Charmer.html

     Note that you `have' to cd into the directory where Charmer
     resides. Otherwise you would have to play with CLASSPATHs.

   * Click on the button which symbolizes a handshake.

   * Fill in the request: In the first line you give the host and the
     port, separated by a colon. In the second line you give a
     username. This serves for opening a session under your name. We
     plan to add persistent user management to gift, to make it
     possible for the user to choose between different sessions.

   * As a reaction to pressing OK in the request, the interface
     changes: It now gives you a choice between different algorithms
     and collections. In this case all the algorithms are weighting
     functions for ranked queries on inverted files. However, in
     principle, you can put anything there.

   * Click the dice symbol. You will get a random selection from the
     collection you chose.

   * You now have the possibility to click on one or multiple of these
     images (they will get a green frame when clicked), and send a
     query for them by clicking on the `binoculars' button.


File: gift-guide.info,  Node: How to analyze GIFT,  Next: ToDo List,  Prev: Getting started with the Charmer interface,  Up: Top

How to analyze GIFT
*******************

   In any case, if you are interested in adding anything to the GIFT,
we would be happy to hear from you. Please mail the maintainer,
Wolfgang M[uuml  ]ller: Wolfgang.Mueller@cui.unige.ch . He will be happy
to help.

   We use KDOC as a system documentation tool. This means we put
JAVADoc like comments into the headers.  If you want to find out, what
the different classes are doing we suggest you to run KDOC on
libInvertedFile/include/*.h and just browse. Comments in the *.cc files
are usually shorter and only geared towards implementation. Later we
plan to include a script which synchronizes comments between the
headers and the prototypes in the *.cc files.

   For the developer there are several alternatives:
  1.  use as much code as possible Then inherit something from
     CAccessor (access to a given indexation method and database) and/or
     CQuery (using this method to actually process queries).  It would
     be useful then to understand how CSessionManager works.  If you
     have suggestions to change what we have, please notify us and help
     us release. We are currently improving the factory design for
     accessors. This should make enhancing GIFT much easier.

  2. Intermediate: use the parsing code, but not much more. The
     knowledge about MRML is in the ...handler functions in
     CSessionManager and CCommunicationHandler/Server. This might serve
     as an inspiration.

  3. As little code as possible: Simply take the DTD. If you make a
     server, try, if
          gift-mrml-client.pl
      works with your system. Try to make it work seamlessly with an
     unmodified version of the charmer interface.

   Always: patches are welcome. If you are missing MRML functionality,
we would be also very interested in providing this functionality or
helping you in providing it yourself. Please contact the maintainer of
GIFT/Charmer as named in the AUTHORS file.

   We are currently putting together some documentation which will
include a "gift extension howto". This is going hand in hand with some
redesign of the session manager, in order to make cooperation easier.


File: gift-guide.info,  Node: ToDo List,  Next: Contact details,  Prev: How to analyze GIFT,  Up: Top

ToDo List
*********

   As you see, the version number of GIFT is quite low. It implies, that
we see many areas which need more work.

* Menu:

* Code and documentation quality::
* Known shortcomings::
* Features to be added soon::
* Interesting things to be added::
* MRML::
* Research::
* Call for participation::


File: gift-guide.info,  Node: Code and documentation quality,  Next: Known shortcomings,  Up: ToDo List

Code and documentation quality
==============================

   * proper generation and installation of .info and .texinfo files

   * Write decent Makefile.am

   * improve CAccessor factory design for easy integration of foreign
     packages

   * Class graph of GIFT

   * HOWTOs for adding new query engines to GIFT

   *   * More documentation in the headers

   * Port MRML tech report from LaTeX to SGML to have it in high
     quality on line for development

   * Write script to synchronize prototype comments used in the cc file
     with the declaration in the include file.

   * Decent parameter parsing for all tools


File: gift-guide.info,  Node: Known shortcomings,  Next: Features to be added soon,  Prev: Code and documentation quality,  Up: ToDo List

Known shortcomings
==================

   * Exceptions: GIFT has been designed to throw exceptions in case of
     errors. Unfortunately this feature is still too buggy in 2.8.1 to
     be used. So, in many cases, GIFT aborts where it should not.  Some
     of the aborts were deliberately left in to make some other errors
     more visible for us during development.

   * Socket programming: get rid of silly workarounds: we sleep before
     closing down our socket. Works, but quite embarrassing.

   * Make server multithreaded (not easy, since it is not stateless)


File: gift-guide.info,  Node: Features to be added soon,  Next: Interesting things to be added,  Prev: Known shortcomings,  Up: ToDo List

Features to be added soon
=========================

   * Adding images during runtime

   * Persistent administration of sessions, including interaction
     history. Here we will have to choose a database to link GIFT to
     (probably the GPLed version of MySQL or PostgreSQL). Otherwise, we
     waste simply too much time on issues which are not really image
     processing.

   * Integrate Christoph Giess's CORBA code


File: gift-guide.info,  Node: Interesting things to be added,  Next: MRML,  Prev: Features to be added soon,  Up: ToDo List

Interesting things to be added
==============================

   * More flexible interfaces for both GIFT and Charmer, allowing them
     better to grow together with MRML. (Partly fixed, there is a new
     interface for CQuery and CAccessor which is quite flexible. We now
     need something like that for Charmer, too).

   * APIs for XML parsing

   * Feature: granting rights to users

   * Making an MRML interface a plug-in to the GIMP


File: gift-guide.info,  Node: MRML,  Next: Research,  Prev: Interesting things to be added,  Up: ToDo List

MRML
====

   We would like to add (at least) the following features to MRML
   * Add image to collection during query

   * Query by annotation is soon to be integrated

   * Queries and transmission of segments

   * A format for transmitting relevance information for benchmarks

   * ...


File: gift-guide.info,  Node: Research,  Next: Call for participation,  Prev: MRML,  Up: ToDo List

Research
========

   * search for better feature sets. The current feature set is still
     the very first version.

   * add fast flexible browsing support


File: gift-guide.info,  Node: Call for participation,  Prev: Research,  Up: ToDo List

Call for participation
======================

   It is obvious that a group of three people cannot attack all this.
However, we are hoping for help both from users and scientists. While
users probably will be most interested in treating as many file types
as possible, scientists may profit from enhancing the capabilities of
MRML as well as a persistent session management, which would permit
learning about each user and thus improve query performance.


File: gift-guide.info,  Node: Contact details,  Prev: ToDo List,  Up: Top

Contact details
***************

* Menu:

* GIFT::


File: gift-guide.info,  Node: GIFT,  Up: Contact details

GIFT
====

   GIFT has been developed at

   Centre Universitaire d'Informatique

   Vision Group

   24, rue du General Dufour

   1211 Geneva 4

   by (in the "order of appearance" in the group) Dr. David McG.
Squire, Wolfgang Mueller, Henning Mueller, Dr. Stephane
Marchand-Maillet, supervised by Prof. Dr. Thierry Pun

   See the AUTHORS file for information on who did what



Tag Table:
Node: Top123
Node: Introduction560
Node: MRML - Why we publish GIFT this way2402
Node: Installation3985
Node: Prepare and run the server5916
Node: Where to put configuration data6317
Node: Getting started with the Charmer interface8952
Node: How to analyze GIFT10514
Node: ToDo List12808
Node: Code and documentation quality13230
Node: Known shortcomings13973
Node: Features to be added soon14687
Node: Interesting things to be added15255
Node: MRML15828
Node: Research16231
Node: Call for participation16493
Node: Contact details17039
Node: GIFT17168

End Tag Table
