ibisa - Image-Based Identification/Search for Archaeology
Copyright (C) 2008, 2009 Anthony Beurive'

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

----------------------------------------------------------------------

(Date: 2009-04-10.)


Welcome to IBISA!
*****************

This package contains IBISA's source code.  IBISA stands for
"Image-Based Identification/Search for Archaeology".  It is free
software aiming to manage collections of photos of archaeological
objects and find similarities between these objects by means of a
simple graphical user interface and specific algorithms.  The software
is a testbed for experimenting such algorithms.  It is related to a
research project initiated by Sylvain Marchand from LaBRI, university
of Bordeaux 1, France.  Here is the Web page of the project (in
French):

  http://dept-info.labri.fr/~sm/Projets/IBISA/


Requirements
************

IBISA depends on the following software components.

  * Tcl/Tk 8.5 or later, for the GUI and all the glue.

  * SQLite 3 for databases.

  * Tcl Thread extension for separating long native operations from
    the GUI.  (However, on systems where this combination was found
    unstable a non-threaded solution is used instead.)

  * libibisa and liboctava, C/C++ Tcl/Tk extensions which source code
    can be found in the 'libibisa' subdirectory.  These extensions
    have their own dependencies, the most noticeable ones being
    ImageMagick (for loading images) and GNU Octave (for numerical
    computations).


Running the Software
********************

  (This section pertains to source and binary releases of IBISA.)

At the time of writing this README, IBISA has been successfully tested
on a GNU Linux system, on a MacOS X system and on a Windows XP system.
The software can be started from the command line by invoking the
'ibisa' executable (preferred) or the 'ibisa.sh' shell script
(deprecated).  They rely on the environment to provide the required
components, although binary releases may come with precompiled
versions (libibisa and liboctava, ar least) in appropriate
subdirectories.

Public binary releases of IBISA for Windows and MacOS X are now
planned to come soon.


Octave as an Option
*******************

Libibisa has been recently split into libibisa and liboctava.  It
gives the opportunity to use Octave only as an option.  Distribution
can also be split into the main IBISA software without Octave support,
and an Octave/liboctava "plug-in".  If you have a binary release it is
possible that it came without Octave support.  If you are interested
in that support you need to get the plug-in and install it in the
directory where you installed IBISA.


The Case of Tcl/Tk 8.5
**********************

8.5 is a rather new version of Tcl/Tk and the main operating systems
rarely include it by default.  However, the source code is available
as well as binary releases which could be installed separately (e.g.,
ActiveTcl).  So it can be the way to go if your system falls in this
category.


Compiling and Installing
************************

  (This section only pertains to the source releases of IBISA.  If you
   have a binary release then you don't need to read it.)

If there is a 'configure' script then you are ready to proceed with
the generic instructions in the 'INSTALL' file.  Libibisa, liboctava
and the ibisa executable should be built in the process.

If there is no 'configure' script there should be a
'config-aux/bootstrap.sh' script which can be run to create
'configure' (and other files).  It requires a recent version of the
GNU autotools (say, autoconf >= 2.61).  Once 'configure' has been
created you can proceed with the 'INSTALL' file.

If your system doesn't already provide the SQLite 3 and/or Tcl Thread
extensions for Tcl you will also have to compile and install them.

  (Notes for MaxOS X users: IBISA doesn't currently use Tcl Thread on
   MacOS X so it is not required.  Furthermore, chances are that it
   might already be provided by the system, as well as SQLite 3.  Look
   for libtclsqlite3.dylib in '/usr/lib/sqlite3/'.  If it exists then
   you don't need another one.)

You might also need to arrange the 'pkgIndex.tcl' file in 'lib'.  This
is rather simple though.  Look at the provided sample.


Packaging a Binary Release
**************************

Instructions will soon be written here to assemble binary releases of
IBISA so to make them relatively independent of a given system.  Note
however that albeit IBISA is rather small on its own, the packages on
which it depends are quite huge, especially Octave.  Most of the time
it would be convenient that the target system already provided them.
It is not always possible, though.  Hence binary releases will tend to
be qite fat, hopefully for good reasons.

