Page 7 out of 26 total pages


Running QBIC Demo Programs


This chapter contains the information you need to run the web-based QBIC demo, run the QBIC command-line demo programs, set demo program environment variables, and add your own features classes to use with the QBIC demos, as described in the following sections:

Running the Web-Based QBIC Demo

You need Netscape Navigator version 3.01 or later to run the web-based QBIC demo.

To start the web-based QBIC demo:

  1. Go to the qbic directory.
  2. Run qbicdemo.

    On the Macintosh, you must start the demo manually:

    1. Start the qbictcl program in the qbic/bin directory.
    2. In the command shell of qbictcl type: source ../script/qbserver.tcl
    3. Start Netscape or Internet Explorer.
    4. Enter the following URL: http://MachineName:3456, where MachineName is your Macintosh's Internet domain name. If you are unsure, you can enter http://127.0.0.1:3456.

Running QBIC Command-Line Programs

QBIC furnishes a collection of programs that provide QBIC functionality via the command-line. You can implement these programs in your own applications, or you can use them as examples when designing and writing your own programs:

Building a Catalog with QbMkDbs

QbMkDbs builds a catalog. (That is, it computes features describing image content properties, and adds them to the feature tables in the catalog.) It also has functions that can add an item to a sampler, update or delete an item from a feature table or sampler, and remove an entire catalog.

Removing an entire catalog can be dangerous. This is because you can create several catalogs in the same database, resulting in several sets of files that end with the catalog name as the file extension.

Command Line Input and Environment Variables

QbMkDbs expects a set of command line inputs:

Example

For example, assume the following case:

  1. Under image/ibm33 there are images named flower01.jpg flower02.jpg, and so on.
  2. Under text/ibm33 the corresponding keyword information is in flower01.jpg.txt, flower02.jpg.txt, and so on.
  3. A QBIC database named /qbic/QbicData and a catalog named ibm33 need to be created.
  4. QBIC keys should contain the image name, without any path information.
  5. Features described by QbColorHistogramFeatureClass, QbTextureFeatureClass, and QbTextFeatureClass are needed.

    The two-step method to create the QBIC database is go to image/ibm33 and issue the following command:

QbMkDbs -c ibm -d /qbic/QbicData -f QbColorHistogramFeatureClass -f 
QbTextureFeatureClass -f QbTextFeatureClass

The result is that a directory named /qbic/QbicData is created, together with a set of dbm files:

QbMkDbs -c ibm33 -d /qbic/QbicData flower01.jpg flower02.jpg ...

or

QbMkDbs -c ibm33 -d /qbic/QbicData -l imageList

where imageList is a plain text file containing one image file name per line (with no blank lines).

QbMkDbs will report errors if it tries to add or insert a record to the catalog that already contains that record. Besides the insert mode, QbMkDbs has three modes for updating records. These are:

Querying the QBIC Catalog Using QbQBE

QbQBE is designed to query the QBIC database and get other QBIC-related information. It can be used to query the database for images similar to the query image or key. It can also provide information such as which features were extracted for a particular catalog, or which features are enabled in the current QBIC release. It can even return the actual feature data for a query object.

Command Line Input and Environment Variables

QbQBE expects a set of command line inputs:

Example

For example, assume the following case:

  1. A QBIC database named /qbic/QbicData and a catalog named ibm33 were created.
  2. Image keys are flower01.jpg flower02.jpg, and so on.
  3. QbColorHistogramFeatureClass, QbDrawFeatureClass, QbTextureFeatureClass, and QbTextFeatureClass features were extracted.

    To find the top five images that are most similar to flower02.jpg in the ibm33 catalog using the QbColorHistogramFeatureClass feature, use the following command:

QbQBE -c ibm33 -d /qbic/QbicData -f QbColorHistogramFeatureClass -i 
flower02.jpg -n 5

To find the default number of images (20) that are similar to flower02.jpg in the ibm33 catalog using the QbColorHistogramFeatureClass and QbTextureFeatureClass features, with 70 percent weight on color histogram and 30 percent weight on texture in distance evaluation (multi-feature query), use the following command:

QbQBE -c ibm33 -d /qbic/QbicData -f QbColorHistogramFeatureClass:W=.7 -f QbTextureFeatureClass:W=.3 -i flower02.jpg

To find the default number of images (20) that are similar to flower02.jpg in the ibm33 catalog using the QbColorHistogramFeatureClass feature and to reorder the top returned results based on the QbDrawFeatureClass feature, with 50-percent weight on color histogram and 50-percent weight on the draw feature as the combined distance for reordering (multi-pass query), use the following command:

QbQBE -c ibm33 -d /qbic/QbicData -f QbColorHistogramFeatureClass:W=0.5:O=0 -f QbDrawFeatureClass:W=0.5:O=1 -i flower02.jpg

To dump the feature data for flower02.jpg using the QbColorHistogramFeatureClass feature, use the following command:

QbQBE -c ibm33 -d /qbic/QbicData -F QbColorHistogramFeatureClass -i flower02.jpg

To list all features that were extracted from ibm33 catalog, use the following command:

QbQBE -c ibm33 -d /qbic/QbicData -l

To list all feature classes that the current QBIC release can extract from input images, use the following command:

QbQBE -L

To return random image keys from ibm33 catalog in the /qbic/QbicData QBIC database, use the following command:

QbQBE -c ibm33 -d /qbic/QbicData -r

The -i key option in the command line can be replaced by the -I imageName option to run a query with the image imageName stored locally on the system (that is, one not already stored in the database). In this case, QbQBE computes the feature from the input image, and then does the query using the image.

Generating Thumbnails Using QbMkThmb

QbMkThmb creates thumbnail images for displaying query results. By default, the program will generate thumbnails using QBIC's own palette (four red, eight green, and four blue colors). The thumbnails are 100-by-100 pixels in both dimensions. The aspect ratio is maintained in the thumbnail. Because most images are not perfectly square, QbMkThmb pads any extra space with black pixels.

Command line options allow you to change the default behavior, as shown in the following examples.

Examples

To create thumbnails with an input image name and output thumbnail name:

QbMkThmb imageName thumbnailName

This command reads the image file named imageName from either the current directory or the search path specified by the environment variable QbicImagePath. It then generates an output file called thumbnailName in the current directory with the dimensions 100-by-100 pixels. Depending on the extension of the thumbnailName specified, the thumbnail can be in any of the supported QBIC image formats.

To generate multiple thumbnails:

QbMkThmb -l imageList

imageList is a file containing a list of files with one image name per line and no blank lines. (This can be the same file used for QbMkDbs.)

In this example, the generated thumbnails are placed in the current directory, have the dimensions 100-by-100 pixels, and are padded, if necessary. Thumbnail names are generated from the image names by appending the default suffix .thumb0.gif.

The -o option can be used to set the output directory, and the -s option can be used to change the suffix (for example, .thumb0.jpg for JPEG images). The -t option instructs the program to generate thumbnails using 24-bit color (true color). If the output image format (for example, GIF) requires a colormap, a dynamic (not fixed) colormap is generated based on the input image colors.

Dumping Databases Using QbDumpDb

QbDumpDb dumps the contents of any Berkeley dbm file generated by the QBIC API. It dumps non-ASCII data in hexadecimal. The command syntax is:


QbDumpDb [-d databaseName] dbm_filename [-f featureName]

or

QbDumpDb -c catalogName -d databaseName -f feature1 [-f feature2 ...]

In the first syntax example, the dbm_filename should not contain any path information. If the dbm file is not in the current directory, you should provide the path information using the -d option. In the second syntax example, if you specify the -c option to indicate the catalog name and the -f option to indicate the feature name, QBIC will know what the feature table name is and will open and dump its contents for you.

If the Berkeley dbm file is a feature table, and the feature class name is also specified in the command line with an -f option, QbDumpDb can print the feature in a more readable format.

The -f option parameter should match the contents of the database, or the results will be unpredictable.

Extending tcl script with QBIC Functionality Using qbictcl

QBIC provides scripting capability by being integrated with the tcl scripting language. "qbictcl" includes the functionality of tcl's standard function calls as well as QBIC function calls. These calls are described in "QBIC-Specific tcl Function Calls" on page  169.

"qbictcl" includes the functionality provided in QbMkDbs, QbQBE, QbMkThmb, and QdDumpDb with exactly the same function name and function syntax. Therefore, you can invoke these functions exactly the same way inside a tcl shell.

For example, to create and query ibm33 catalog, you can enter the following in a qbictcl shell, which can be started by typing qbictcl in a command shell on the UNIX or NT platforms, or by clicking the qbictcl program on the Macintosh platform:


QbMkDbs -c ibm33 -d qbic/QbicData -f QbColorHistogramFeatureClass -l 
image.dat 

QbQBE -c ibm33 -d qbic/QbicData -f QbColorHistogramFeatureClass -i 
flower01.jpg

You can also use qbictcl's lower-level functions for better control during image feature extraction. For example, the following script provides functionality similar to a standard database creation:

set qb [qbic_start ibm33 /qbic/QbicData w] ;# Create a qbic descriptor qbic_add_feature $qb QbColorHistogramFeatureClass ;# Add Qbic Feature to the descriptor qbic_add_feature $qb QbDrawFeatureClass ;#Add another Qbic Feature qbic_add_image $qb flower01.jpg ;# Extract features for flower01.jpg qbic_add_image $qb flower02.jpg ;# Extract features for flower02.jpg ... qbic_end $qb ;# delete the qbic descriptor

Setting QBIC Environment Variables

QBIC uses a set of optional environment variables to define search paths, default values, and so on for the engine. The following table lists the environment variables used by each program. Detailed descriptions of each environment variable follow the table.

The provided QBIC programs support the -e EnvVar=EnvValue option for setting the internal state of environment variables via the command line. The exception is QbDumpDb, where this is not needed.

Programs
Environment Variables QbMkDbs QbQBE QbMkThmb qbictcl
QbicImagePath X X X X
QbicTextPath X X X
QbicConnectMode X X X
QbicDatabaseName X X X
TCL_LIBRARY X
QBTCL_LIB X

The following are descriptions of QBIC environment variables:

Environment variable Description
QbicImagePath List of directories, separated by semi-colons, where QBIC will search for images to load. The default is the current directory.
QbicTextPath List of directories, separated by semi-colons, where QBIC will search for a text file containing keyword information about a given image. The text file name must equal the image file name with the extension TXT. The default is the current directory.
QbicDatabaseName Initializes the name of the database to which a connection will be requested. If a name is not specified, the default name "QbicData" is used. The database name can be overridden using the -d command line option.
QbicConnectMode Specifies the mode to connect to the database using the string "r" or "w" (for "read" and "write"). This environment variable is ignored if the call to QbGetConnection in QbCreate.cpp specifies the mode explicitly, as is done in all calls in the current implementation.
TCL_LIBRARY Specifies the location where tcl or qbictcl can find init.tcl start script.
QBTCL_LIB If you want to put the common script such as qbicmain-common-demo.tcl and qbicmain-common-index.tcl in a different directory from the cgi script ibm33.tcl (which may have to be moved to your cgi-bin directory). You need to set up this environment variable.

Modifying the tcl Script

The qbic/script directory contains a set of tcl scripts that qbictcl uses for database population and query. For example, ibm33.tcl is used both as a script for database population and as a cgi script for the web demo. You can edit the script to create and demonstrate other image collections. For example, suppose you have a collection of images located in /myImage/foo and the corresponding text (keyword) files are in /myText/foo, and you want to create a new catalog called bar. To do this, you would:

  1. Copy ibm33.tcl to bar.tcl.
  2. Use a text editor to make the following changes:

    - Change set catalog ibm33 to set catalog bar

    - Change set paths(image_root) $root/html/images/$catalog to set paths(image_root) /myImage/foo

    - Change set paths(text) $root/html/text/$catalog to set paths(text) /myText/foo

    - If you want to put thumbnail images in a different directory, change the corresponding lines in set paths(thumbnail).

  3. To populate the database and generate thumbnails type:

qbictcl qbic-make bar.tcl

You can change the way the demo looks or behaves by changing the common script (qbic/script/qbicmain-common-demo.tcl) or by redefining variables and procedures in the cgi script such as ibm33.tcl or your bar.tcl.

For example, if you want the result table to display images in a 4-by-3 format, add the following code to the "user customizations" section of your template script:

set params(images_per_row) 4 set params(qbic_table_images) 12

If you want the "QBIC Information" page to look different, modify the page(info) section to suit your preferences. Any other changes are at your own risk.

Adding Your Feature Classes to the Demos

When you create your own feature classes, you must link them to QBIC's executables.

For example, if you want to add MyFeatureClass to the QBIC demo, you would need to add the following code to your copy of the script, such as ibm33.tcl, after you build the catalog.

Descriptions of each variable follow the example.

set type(MyFeatureClass) "My Feature Class"
set icon(MyFeatureClass) "letterM.gif"
set iconhelp(MyFeatureClass) "My Feature Class"
set fname(MyFeatureClass) "My+Feature+Class" 
set feature(Average+Color) "MyFeatureClass"
set pickerpage(MyFeatureClass) "unenabled"
set pickertext(MyFeatureClass) "Unenabled"

The code in the example uses the following variables (as documented in qbicmain-common-demo.tcl):




Page 7 out of 26 total pages


xzhu@almaden.ibm.com or tedl@almaden.ibm.com
Copyright © 1998, IBM Corporation. All rights reserved.