Developer's Manual

PicSearch -- Interactive Picture Searcher

http://
Last modified .

Contents

1. Introduction
2. Environment and setting up the system
3. Files
4. Maintenance of PicSearch

1. Introduction

This document explains how to install PicSearch application and how to maintain and develop the system. This document covers the version 1.0 of the system. PicSearch is designed to work in environments such as Linux, UNIX and MS Windows 95.

PicSearch is freely available under the GNU General Public License.

2. Environment and setting up the system

2.1. Operating systems

So far we have been able to run the system using Linux, Digital UNIX, Windows95 and Windows NT. In the following, we specifically point out which actions apply only to Linux and other Unix systems and which apply only to Windows.

2.2. Software components

To run PicSearch you need a set of external software components not part of PicSearch itself. In Windows to develop the system you will also need a decent C++ compiler and the source files of PicSearch. In Unix systems the PicSearch system has to be compiled in any case.

To run PicSearch your system must have the Tcl/Tk package, versions 7.5 and 4.1 respectively. There should be no reason why any more recent versions would not work, but we can not guarantee it.
In Unix systems after you have compiled Tcl/Tk libraries, you will probably need to edit the makefiles of PicSearch so that the directories of library and include files are correct. In Windows, you need not compile (or even have) the Tcl/Tk source files, but to link PicSearch two extra files are required: tcl75.lib and tk41.lib (plus, of course, the DLLs). These are provided (for Microsoft Visual C++) within PicSearch package.

Since Unix systems do not have built-in threads, we have used (POSIX standard) pthread-package. This needs to be installed and compiled like Tcl/Tk. Edit the main Makefile of PicSearch to include the library in linking, check also that the Makefile in subdirectory 'common' has proper path to find the include file 'pthread.h'. If you run into difficulties in compiling our files 'common/src/pthread.hxx' and 'common/src/pthread.cxx', try to hack those files yourself (the pthread- package does not seem to be as standard as it claims). In Windows none of the this is required.

In Unix systems one more external component is needed: xgrabsc. Since Tcl/Tk does not provide a proper way to implement a drawing window, we use a screen grabber to snatch the image from the screen. Xgrabsc is not linked with PicSearch and needs only be separately compiled into executable and put into the main directory of PicSearch. Once again, in Windows this is not needed since the screen grabber is implemented as part of PicSearch (and is thus much faster).

2.3. Compiling the system

In Unix systems we have used GNU's C++ compiler (gcc) and in Windows Microsoft's Visual C++ (version 2.0 or higher). Below is a step-by-step list of how to set up PicSearch. We refer to the directory where the executable file of PicSearch is to be located as the main directory of PicSearch or just by $PICSEARCHDIR

In Unix systems:

  1. Create a directory for PicSearch. This directory is to be the main directory of the system.
    1. mkdir <dirname>
    2. cd <dirname>
  2. Set environment variable:
    setenv PICSEARCHDIR <pathname> (the actual command depends on the shell you are using).
  3. Download PicSearch, e.g. from http://www.cs.helsinki.fi/~klemstro/picsearch.html
  4. Unpack PicSearch package:
    1. gunzip pics10.tar.gz
    2. tar -xf pics10.tar
  5. Update your Tcl/Tk to at least versions 7.5 and 4.1:
    1. Download the package for example from: http://www.NeoSoft.com/tcl
    2. Unpack the package
    3. Compile
    4. Test with some small test programs included with the package
  6. Set up the pthread-package
    1. Download the package for example from: http://www.mit.edu:8001/people/proven/pthreads.html
    2. Unpack the package
    3. Compile
  7. Compile xgrabsc:
    1. Change directory from main directory of PicSearch:
      cd $PICSEARCHDIR/source/xgrabsc
    2. Compile: make
  8. Compile PicSearch:
    1. Update makefiles: pathnames of
      • XWindows library
      • Tcl/Tk library
      • pthread library
    2. cd $PICSEARCHDIR/source
    3. make
  9. Test the system:
    1. cd $PICSEARCHDIR
    2. picsearch
  10. You are now free to modify the code. See 4. Maintenance of PicSearch for more instructions.

For Windows we provide no makefile. Please build a makefile of your own by following the instructions below. We have used no Microsoft-specific code in our implementation so the code should compile e.g. under Borland C++.

  1. Create a directory for PicSearch. This directory is to be the main directory of the system.
    1. mkdir <dirname>
    2. cd <dirname>
  2. Download PicSearch, e.g. from http://...
  3. Unpack PicSearch package: install.exe
  4. Test the system by running 'run.bat' in the main directory of PicSearch.
  5. Create your own makefile and note the following:
  6. You may keep the dynamic link libraries tcl75.dll and tk41.dll in the main directory of PicSearch or copy them elsewhere as long as they are found along the system path.
  7. You are now free to modify the code. See 4. Maintenance of PicSearch for more instructions.

3. Files

Below is a list and short description of all the files that are part of PicSearch.

For more information on the technical issues of PicSearch, refer to technical specification and documentation of the C++ classes.

4. Maintenance of PicSearch

4.1 Database management

The simple database implementation now used in PicSearch saves all its data into the directory 'DataBase'. We urge you to regularly make backup copies of all the database files (*.db, *.idx) in the directory.
Since the database implementation is not as robust one would like, if PicSearch crashes, the database may be left into incoherent state. If that happens, restore the files from your backup or just delete all the files in the directory. NOTE: connecting to database is guarded by file $PICSEARCHDIR/DBLOCK.LCK; this file is left undeleted if PicSearch did not shutdown properly. In that case you may delete the file manually (but don't use this to start up more than one copy of the system since our database implementation can not handle multiple connection to the database).

4.2 Programming new algorithms and image formats

Once you have successfully installed and compiled PicSearch, you are free to modify the system as you please. Before starting to program, spend some time browsing through the documentation of the C++ classes we have provided. Also you need to understand basics of the common class library (PicLib) that we have used throughout the system: see PicLib basics.

If you only want to program some algorithms of your own, all you need is to save copies of the following files under new names

and fill in the code as instructed by the templates. Remember to update makefiles source/alg/Makefile and source/Makefile. For search algorithms you also need to update the function 'algorithmParams' in script file source/gui/src/subwins.tk to create a window for parameters of your algorithm (if none, you may skip this). Equivalently for segmentation algorithms the function is 'segmentParams' and for image processing algorithms 'imageProcess' in source/gui/src/editor.tk.

You may program PicSearch without much knowledge about the inner workings of the system or PicLib. However, since we have used extensively the classes provided by PicLib, many of the parameters of the functions use classes of PicLib. That's why we suggest that you use some of your time getting to know the most important classes. Take a look at the documentation of PicLib, especially the PicLib basics. Furthermore, browse through the main code of PicSearch to get a hang of how to use the classes provided. And if your C++ needs a brush-up, now is the time. Make sure you understand how inheritance and virtual functions work.

4.3 Further development of the system

If you want to make functional changes to PicSearch, you'll have to spend much more time getting used to the programming environment. Read carefully through the technical specification and check out our code until you approximately know how different parts of the system interact and function.

When making bigger funcional changes, try to keep the APIs unchanged if possible. That way you'll be able to narrow down the problem areas you may be creating. For example, if you decide to re-implement the database engine, keep the functions of class PicDbConnection as they are, so there should be little need to touch any code within PicCore and certainly not within PicAlg or PicGui.

It may be a good idea to contact the development team of PicSearch before starting to make any major changes. We will be able to give a rough estimate on what needs to be changed and how much effort it will take. If the job is small, we might even do it ourselves :-). Our contact information you will find below (up-to-date on May 1997).

4.4 Reporting errors

The development team of PicSearch can be reached by e-mail using the addresses given below. If outdated, try locating us using some search engine on the Web. Each of the developers mentioned here has his own field of expertise as indicated. Since this system was an outcome of a course project, you will probably benefit most by contacting our client for the project, who should be developing this system further.

You are free to develop the software any way you want under General Public License. If you detect any bugs in the original code, please send the following information about the case: