This file describes the procedure for installing the QBIC api and web
server.  Documentation for the api can be found in QbicApi/docs.

This distribution includes binaries for AIX version 3.2.5 or 4.1, 
Linux (Slackware 3.0 with gcc 2.7.2) and NT 3.51.

The procedure assumes QBIC will be installed and used by userid qbic
whose home directory is /usr/local/qbic.  We recommend that you:

1. Create userid qbic ( AIX and Linux )
2. Set its home directory to /usr/local/qbic

   The installation will overwrite the .profile and .kshrc 
   files in /usr/local/qbic, so if there are things in there 
   you need to save, make a backup copy.

   If you know what you are doing, you don't have to install
   into the directory as described above, but you will need to 
   ensure that the environment variables set in the qbic .profile 
   are set explicitly. 

3. If you want the apache web server create the directory /usr/local/etc
   and make it writable by user qbic.

--------- INSTALLING THE FILES FROM THE DISTRIBUTION FILE -----

As user qbic in directory /usr/local, uncompress and untar the
distribution file. You must do the untar from userid qbic.

cd /usr/local ; gunzip -c qbwww1.tgz | tar -xvf -

(gunzip and tar utility programs for NT can be found from various
ftp sites, in particular from ftp.cygnus.com/pub/gnu-win32/win32/i386.)

This creates two trees, qbic and etc/httpd (the 1.1.1 release of the
apache http server), as subdirectories of /usr/local.  The web server
is precompiled for AIX. For linux users you can get a prebuilt version
of the web server at http://www.apache.org or rebuild it yourself from
the distributed files ( see the file INSTALL ).  You will need the
info in the files conf/{httpd,srm,access}.conf reflected into your web
server.

Files .profile and .kshrc are created in /usr/local/qbic, overwriting
any previous version of those files.  (The files won't be overwritten
if their are not owned by the userid doing the untar.)  Environment
variables used by QBIC are set in .profile, and $PATH is set to
/usr/local/qbic/bin.  Source this file before proceeding.


--------------- BUILDING THE DEMO DATABASE --------------------

To be able to query an image database, you must first create the
database.  You can use your own images or use a set of 438 images can
be downloaded with the distribution and install using the commands 
"cd /usr/local; tar -xvf IBMImgs.tar".

Alternatively 


1. Be sure the environment variables given in .profile are set. Also
   you need to set the bin and lib directories appropriate to the
   platform you are using. This can be done using the commands below.
        
   cd ; 
   mv bin.{your_platform} bin ; 
   (e.g. mv bin.aix bin
         move bin.nt bin)
   mv QbicApi/lib.{your_platform} QbicApi/lib
   (e.g. mv QbicApi/lib.aix QbicApi/lib
         move QbicApi\lib.nt QbicApi\lib)

2. Now it is time to create an image database.  The operations below
   create a 438 image database from the sample images provided. Run
   only the A or the B part of this section - not both. 
  
  A. cd /usr/local/qbic/html/images ;
     QbCreateCat.sh ibm  #This process will run for awhile.

     For NT workstation, a batch script is enclosed, execute the command
     at qbic\bin directory to create the image database:

     cd \usr\local\qbic\bin
     QbCreateCat
 
  B. If you have tcl/tk install and want to use the gui front end to
     populate the database follow the steps below.  We tested with Tcl
     v7.5a2 and Tk v4.1a2.  Earlier version may not work with our
     scripts.  Tcl/tk can be found at various ftp sites.  Make sure
     your PATH includes the wish program.

     Run the command:
  
     QbCreateCat.tcl          

     Note: If wish (the tcl/tk interpreter) is not found, update your
           PATH to with your local installation directory for wish.

     You will get an interface that has fields for scrollable lists of 
     directories and files on the left, and fields for database, catalog, 
     features, etc. on the right.  By selecting the button "List Images",
     you get a listing of the images that match the extensions given in the 
     "Image File Extentions" input field. 

     a. Enter "/usr/local/qbic/html/images/ibm" in the "Image Directory" 
     b. Under "Filename Qualifier", select "Use Short Keys".  (This means
        use relative, or not fully qualified, filenames as database
        keys.)
     c. Enter "/usr/local/qbic/QbicData" in the "Database Name" field.
     d. Enter "ibm" in the "Catalog Name" field.
     e. Select all features in the list under "Feature Class"
     f. Set "Generate Thumbnails" to yes. 
     g. Enter "/usr/local/qbic/html/thumb" in the "Directory for Thumbnails"
        field. 
     h. Press okay


-------------- SETTING UP THE HTTP SERVER ------------

The tar file includes a compiled version of the 1.1.1 release of the
apache server (available at http://www.apache.org).  Although it will
run as setup, you should configure it as outlined in
http://www.apache.org/docs/install.html.  At least change ServerAdmin
in /usr/local/etc/httpd/conf/httpd.conf (for example, to qbic).  The
server is setup to use /usr/local/qbic/html as DocumentRoot.

You need to make sure the server spawned processes can write the
directory qbic/Query.  This can be done by changing User and Group in
httpd.conf to a user/group with appropriate permissions (e.g. User
qbic, Group staff) or by changing the permissions on the Query
directory as done in the example below.

su 
chown nobody:nobody /usr/local/qbic/Query

As root, start the httpd server by using the command:

/usr/local/etc/httpd/src/httpd -f /usr/local/etc/httpd/conf/httpd.conf

For NT workstation, there are several http servers.  To set up the server,
it is important to make sure

\usr\local\qbic\html
\usr\local\qbic

are both server's document directories with the primary document directory
to be

\usr\local\qbic\html

-------------- RUNNING QUERIES AGAINST THE DEMO DATABASE ------------

After the server is running and a database is built, you can run a query.

1. Invoke a web browser, such as:
     netscape

2. Enter the URL 
     http://localhost 

   which takes you to the QBIC home page.  Follow the directions
   on the pages.  

To export this demo, edit Config/QBICWWW.api.cnf replace //localhost
in the BASE_URL stanza with the name of the machine your server runs
on.

---------------- USING YOUR OWN IMAGES  --------------------

You can use your own images by placing them in a subdirectory (could
be a symbolic link) in qbic/html/images/YourImageDirectory and
selecting that subdirectory when running QbCreateCat.sh.  Use
/usr/local/qbic/QbicData as the database name, and
/usr/local/qbic/html/thumb as the thumbnail directory. You must chose
YourImageDirectory as the catalog name ( QbCreateCat.sh does that for
you ).

For NT workstation, you should just specify your directory name
(Don't use the whole path) to run QbCreateCat.  For example, if
you put your images in qbic\html\images\myImage, do
QbCreateCat myImage
