 /////////////////////////////////////////////////////////////////////////////
(((((			    Toftool                                      )))))
///////////////////////////////////////////////////////////////////////////// 
	    A tool for local use and maintenance of the Psql photo
	    database used by the Tof Web Based Photo Album
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\


******************************************************************************
* 			    Warning                                          *
*                                                                            *
*	Some actions of this script may have drastic effects                 *
*       on Tof's database.  So handle with care!!!                           *
*                                                                            *
******************************************************************************


Introduction
============

Toftool provides an interface to the database, used by the 'Tof  Web
Based Photo Album' See http://tof.bearteam.org/ for further information.

Tof is designed to serve multiple users by using a web interface.
Toftool is restricted to local use.  A username variable is provided for
compatibility with Tof.

Special features of Toftool are:

    - Full keywords and multi-level topics indexing of pictures with
      allowed multiple topics per picture.
    - A GUI with powerful facilities for maintenance of the database:
      . multiple pictures can be associated to multiple keywords and
        topics or rated simultaneously.
      . multiple pictures can be added to or removed from a roll
        simultaneously.
    - Extended queries based upon combinations of ratings, keywords and
      topics, easy available on the GUI.
    - Interactive zoom, rotate, shift facilities available in
      presentations. 
    - The pictures in a single topic can be arranged in a particular order
      that can be arranged easily by 'drag' and 'drop' operations on
      thumbnails and is stored in the database.
       

For managing of thumbnail collections (drag, drop etc.) and special
effects (zoom, rotate etc.) in presentations, the the GQview image browser
are used.  See for further information: http://gqview.sourceforge.net/


Installation
============
1.  The program is written in perl, using the Perl/TK widgets.
    It has been tested for 
		perl-5.6.1
    with
		perl-Tk-800.022-3cl.i386
    and
		Tk-JPEG-2.014

2.  The Tof database and the GQview image browser and the file  kdc2jpeg
    which is part of the kdc2tiff package should be installed first. 
    For these programs the following versions were used

		tof-1.4.1
		gqview-1.1.4-1
		kdc2tiff-0.32

3.  Next a few settings in the configuration file 

		toftool.cfg

    should be edited. See the comments in that file for further details.
    Some settings can be overruled by command line switches (see below).

4.  We use an extra table in the psql database. This table can be created with
    the supplied file 

		extra.sql

    with using the command

		psql dbname < extra.sql 

    where 'dbname' is the name of the Psql database, used by Tof.

5.  Since Toftool allows empty topics in the topics hierarchy.
    These topics are invisible in the default setting of Tof.
    To make them visible:
    
    A. In Tof versions up to 1.1.4:
    ------------------------------- 
	In the file

		    slooze_render.php 

	of the Tof package in 

		    function showTopics( $topics ) {

	Change the  line 

		    if ($count>0) {
	
	into
		    if (true) {


    B. In newer versions
    --------------------
    Set in the file slooze_local.php the variable:

	$show_empty_topics = true;


6.  Edit the configuration file toftool.cfg
    (see comments in the file) and remove ~/.toftool.cfg if you want to
    the new settings in toftool.cfg to be installed.

6.  Finally a

	    make install

    will put  

	    toftool.cfg in ~/.toftool.cfg

    unless ~/.toftool.cfg already exists, and

	    toftool in ~/bin/toftool


Usage
=====
The program has two main modes of application,
    
	    1. View Mode
	    2. Admin Mode

The view mode is to show pictures matching selected rates, rollnames,
keywords and/or topics as thumbnails or in a slide show.  The admin mode
provides many features for maintaining the picture sources and the Tof's
psql database.

After starting the program with the command

	    toftool [ -d databasename -u username ]

the main window appears in the view mode.

Main window
-----------
The top frame of the main window contains two buttons:
    - left a button to switch between the two modes;
    - right an exit button, to leave the program gracefully. 

The center of the main window consists of a frame with a slider and three
lists:
    - a slider for setting ratings
    - a list of rolls
    - a list of keywords
    - a hierarchical list of topics

These slider and lists can be used used to select pictures for viewing (view
mode) or indexing (admin mode)  with, 
    - matching certain  rolls and/or  keywords and/or topics and
    - if desired, a minimal rating.

View Mode
---------
In the view mode the 'Any' or 'All' buttons are enabled. By using these
buttons queries for multiple rolls, keywords and topics can be specified.
The default setting is 'Any' so if for instance multiple keywords are
selected, pictures are shown that match any of these keywords. With the
'Clear' buttons any selection can be cleared. The combination of rolls,
keywords, topics and rates is a logical 'AND', i.e. pictures are selected
matching the selected rolls AND the selected keywords AND the selected
topics AND the selected minimum rating. In general complex queries are
seldom needed and just single topics or a few keywords are selected. Lists
with no selected items are disregarded.

The bottom frame of the main window contains in the view mode two
buttons: 'Thumbnails' and 'Slideshow'. These are used to show the
matching pictures.

After pressing the 'Thumbnails' button two windows of the GQview program
are opened, one with a collection of small thumbnails and a second one
which is empty, initially.  By double clicking on any of the images,
the picture appears in the second window. Several  zoom, rotate, adjust
etc. features as described in the GQview documentation are available by
mouse actions and keyboard shortcuts.

If the 'Slideshow' button is pressed, the selected pictures appear
successively in full screen format. Slide show options, such as the
delay before image change,  can be set in the GQview configuration file
~/.gqview/gqviewrc (most easily changed by GQview's option dialogs).
Again, GQview's mouse operations and keyboard keyboard shortcuts are
available, in particular:

    left-mouse-click (on image) 	next image
    middle-mouse-click (on image) 	previous image
    PageDown				next image
    PageUp 				previous image
    Home   				first image 
    End    				last image 
    Arrows 				pan image
    Shift+Arrows			pan image faster
    Space  				next image
    Backspace,B				previous image
    +,=     				zoom in
    -      				zoom out
    ]      				rotate image clockwise
    [      				rotate image counterclockwise
    shift-M				mirror image (horizontal)
    shift-F				flip image (vertical)
    V      				toggle full-screen mode
    S      				toggle slide-show mode
    P      				toggle pause of slideshow
    Q  					quit

Admin Mode
----------
After selecting  the admin mode, the bottom frame of the main window
changes and below the rolls, keywords and topics lists new entry fields
and buttons appear. In this mode the three lists treated separately. The
available actions, which are slightly different for the three cases,
are discussed below.

Rolls
-----
This part is mainly used to maintain the collection of pictures stored
in Tof's database.

In Toftool a source directory 'srcdir' with original sources pictures,
and an 'imagedir' with images and thumbnails as used by Tof, both with
subdirectories known as 'rolls' are distinguished.  The list 'Rolls'
in toftool's admin window corresponds with names of the subdirectories.

New subdirectories in the source directory can be created with the
rolls-entry box 'New'.  With the 'Delete' button selected rolls can be
removed. This means that the pictures in these rolls are removed from
the database.  The files in the source directories remain unaffected
by this action, but empty source directories are removed.

For storing all pictures of selected rolls, just push the 'Import' button.

For selecting a subset of pictures from the sources, use the 'Update'
button.  Then two windows of the GQview program appear. One is
initially empty, the other contains thumbnails of the pictures in the
source directory.  By drag and drop actions pictures can be put in the
first window.  Note that 'left-mouse-click' and 'middle-mouse-drag' are
the mouse actions, needed for this operation. After saving and exiting
GQview, Toftool performs (if needed) the actions required to create
images and thumbnails and updating of some database tables.

The Admin window
----------------
Most of the special features of Toftool mentioned in the introduction can
be performed in the Admin window. This window appears after selecting
one or more  roll(s) and  clicking the 'Admin' button.  It contains a
table with thumbnails of pictures in the selected roll(s) and on top a
set of checkboxes: 'numbers', 'roll', 'keywords', 'topics' and 'ratings'
which  allow the display of further info in the table. Just check some
of the boxes and push the 'Rewrite' button below the table.

Left and right of the table the lists of keywords and topics are
reproduced.  To add keywords or topics to selected pictures in the table,
select some pictures by clicking on the thumbnails and keywords
and/or topics as desired. By pushing the 'Add keywords' or 'Add topics'
buttons below, the changes in the database takes place.

By clicking with the right button on a thumbnail an enlarged picture is
shown in a pop up window.

(Re)setting the rating of selected pictures is achieved by selecting
pictures in the table, activating one of the radiobuttons below the
table and pushing the 'Rate' button.

Removing pictures from the current roll(s) is possible by selecting
pictures in the table and pushing the 'Remove' button. After completing
the changes the window can be closed with the 'Close' button.

Keywords
--------
New keywords can be created with the keywords-entry box 'New', below
the keywords list. Just enter a keyword and push the 'Add' button.

With the 'Cut' button, keywords can be removed.  After this action
the removed keyword appears in the 'Buffer' field at the bottom of the
window. This means that the data associated with the removed keyword
are stores temporarily, and the removal can be restored by pushing the
'Restore' button. The pictures associated with the removed keyword can
also be merged with the pictures belonging to an existing keyword. This
is done by selecting the new keyword and pushing the 'Merge'
button. Filling of the buffer without removal of the original keyword
can be achieved with the 'Copy' button. After that a merge with other
keywords is possible.  These actions may be useful in cases of synonym
keywords.

Associating a keyword with selected pictures is also possible by
selecting a keyword and pushing the 'Update' button below the keywords
list.  Then two GQview  are opened. One with thumbnails of pictures,
matching the selected keywords and a second one a directory listing
of all rolls. Selecting one of these rolls results in a thumbnail
directory of the roll. From there, by cut and paste actions as described
above new pictures in the set associated with the given keyword can be
added. Similarly, pictures can be removed from that set by removing them
from the GQview-window. After saving and closing the GQview program,
all changes in Tof's database will be performed.

With the 'Admin' button an Admin window for a selection of (all) pictures
matching a selected keyword(s) can be opened. This enables the removal or
(re)setting of keywords, topics and rates of selected pictures in the
current set keyword(s).


Topics
------
For topics the procedure is the similar to keywords. Note that while
adding a new topics, a 'parent topic' in the existing topics tree
should be selected first. There is no 'Merge' but a 'Cut' and 'Paste'
option to remove whole subtrees from the topics-tree and paste them to
a different location.  The database will be updated accordingly.

A special feature of Toftool is the possibility of storing a particular
order of pictures for any given topic. To that end, use 'Update' button
for the selected topic.  and rearrange by drag and drop operations the
thumbnails in the GQview window that pops up.  After saving and quitting
GQview the new order will be stored in the database. This order will be
used for single topics view and slideshows. 


R.J.J. Jongschaap October 9 2002
