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:
To start the web-based QBIC demo:
qbic
directory.
qbicdemo
.
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:
The QBIC database implementation is derived from the Berkeley dbm system. Therefore:
All of these programs expect command line input. If input is not provided, or if the input is incorrect, the program prints a summary of the command line syntax on the screen so you can read the required input and proper syntax.
You can set environment variables for these programs, as described in "Setting QBIC Environment Variables" on page 28.
Source code for these programs is in the qbic/QbicApi
subdirectory.
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.
QbMkDbs expects a set of command line inputs:
QBIC uses the input image names as the key to feature data. If you decide that the key should not contain path information, set the QbicImagePath environment variable to point to the image directory, or start QbMkDbs in the directory where images are stored because QBIC always searches the current directory for a given input file name.
If you want to include path information as part of the key, set the QbicImagePath environment variable to point to the parent directory name appended with the key name that corresponds to the path for the input image, or start QbMkDbs in that directory. For example, if you have images in /qbic/images/ibm33/flower01.jpg
, and you want the key to be ibm33/flower01.jpg
, then you should set the environment variable as QbicImagePath=qbic/images
or go to qbic/images
to start QbMkDbs.
The database name and catalog name can be passed to QbMkDbs using -d and -c options. If a database name is not passed on the command line, QBIC will use the database name provided by the environment variable QbicDatabaseName. If QbicDatabaseName is not set, QBIC will default to QbicData. If the catalog name is not passed on the command line, QBIC will default to test.
QBIC feature names can be passed to QbMkDbs using a set of -f options. Each option describes a feature that QBIC must have implemented in order to extract data from the input image.
There are two basic operations that this program performs. First, it adds feature tables to the catalog. Second, it adds records to each of the feature tables (and modifies global information) for each image name specified. Though these two operations can be combined in one step, we recommend separating these two functions.
For example, assume the following case:
image/ibm33
there are images named flower01.jpg flower02.jpg
, and so on.
text/ibm33
the corresponding keyword information is in flower01.jpg.txt
, flower02.jpg.txt
, and so on.
/qbic/QbicData
and a catalog named ibm33
need to be created.
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 QbTextFeatureClassThe result is that a directory named
/qbic/QbicData
is created, together with a set of dbm files:
/qbic/QbicData/FeatIdx.ibm33
/qbic/QbicData/ColorHiF.ibm33
/qbic/QbicData/TextureF.ibm33
/qbic/QbicData/TextFeaF.ibm33
To add images to the catalog for these features, use the following command:
QbMkDbs -c ibm33 -d /qbic/QbicData flower01.jpg flower02.jpg ... QbMkDbs -c ibm33 -d /qbic/QbicData -l imageListwhere 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:
This program also supports deleting records and deleting the entire catalog. The command line syntax supports SubParts. Contact IBM for information about SubParts. (See "Licensing Information" on page xiii for contact information.)
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.
QbQBE expects a set of command line inputs:
Database query -d and -c options are needed to provide the program with database and catalog names. A set of -f options indicate which QBIC feature(s) to use in the query.
If more than one -f option is specified, QbQBE will perform a multi-feature or multi-pass query, depending on the input feature parameters.
If you do not supply input, environment variable settings are used.
For example, assume the following case:
/qbic/QbicData
and a catalog named ibm33
were created.
flower01.jpg flower02.jpg
, and so on.
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 5To find the default number of images (20) that are similar to
QbQBE -c ibm33 -d /qbic/QbicData -f QbColorHistogramFeatureClass:W=.7 -f QbTextureFeatureClass:W=.3 -i flower02.jpgflower02.jpg
in theibm33
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:
To find the default number of images (20) that are similar to
QbQBE -c ibm33 -d /qbic/QbicData -f QbColorHistogramFeatureClass:W=0.5:O=0 -f QbDrawFeatureClass:W=0.5:O=1 -i flower02.jpgflower02.jpg
in theibm33
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:
To dump the feature data for
QbQBE -c ibm33 -d /qbic/QbicData -F QbColorHistogramFeatureClass -i flower02.jpgflower02.jpg
using the QbColorHistogramFeatureClass feature, use the following command:
To list all features that were extracted from
QbQBE -c ibm33 -d /qbic/QbicData -libm33
catalog, use the following command:
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
QbQBE -c ibm33 -d /qbic/QbicData -ribm33
catalog in the/qbic/QbicData
QBIC database, use the following command:
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.
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.
To create thumbnails with an input image name and output thumbnail name:
QbMkThmb imageName thumbnailNameThis 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.
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] 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.
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.jpgYou 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
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:
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:
ibm33.tcl
to bar.tcl
.
- 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)
.
qbictcl qbic-make bar.tclYou 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 asibm33.tcl
or yourbar.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) 12If 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.
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.
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
):
See qbicmain-common-demo.tcl
for more examples. If you were planning to use MyFeaturesClass with other QBIC applications, you should move the code to the common script.