IBM Books

Image, Audio, and Video Extenders Administration and Programming

Using a query object

You can use a query object to identify the features, feature values, and feature weights for your query. You create the query object and add features to it. Then you specify a data source for each feature. The data source provides a value for the feature. For example, a data source might be an image in a file. If average color is the pertinent feature, the average color of the image is associated with the query object. If you add multiple features to a query object, you can assign a weight to one or more of the features.

The Image Extender provides three APIs (QbQuerySearch, QbQueryStringSearch, and QbQueryNameSearch) and two UDFs (QbScoreFromName and QbScoreTBFromName) that use a query object. When you issue a query, you use the appropriate API or UDF and specify the query object as an input parameter. (See Issuing queries by image content for details.)

Creating a query object

Use the QbQueryCreate API to create a query object.

In response, the Image Extender returns a handle for the query object. The handle has a QBIC-specific data type of QbQueryHandle that is defined in the include (header) file for QBIC, dmbqbapi.h.

When you use the API, you need to point to the query object handle. You also need to specify the handle in APIs that perform other operations on the query object, such as adding a feature.

For example, the following API call creates a query object:

QbQueryHandle  qHandle;
 
rc=QbQueryCreate(
              &qHandle);                          /* query object handle */

Adding a feature to a query object

You identify the image features that you want the Image Extender to query by adding the features to a query object.

Use the QbQueryAddFeature API to add a feature to a query object.

When you use the API, specify the query object handle. You also name the feature. You can specify only one feature in the API. You must issue a separate API call for each feature that you want to add to a query object.

In the following example, the QbQueryAddFeature API is used to add the average color feature to a query object:

char  featureName[qbiMaxFeatureName];
QbQueryHandle  qHandle;
 
rc=QbQueryAddFeature(
                qHandle,                          /* query object handle */
                "QbColorFeatureClass");           /* feature name */

Specifying the data source for a feature in a query object

Use the QbQuerySetFeatureData API to specify the data source for

a feature in a query object. The data source can be:

In addition, you can explicitly specify data for the average color or histogram color feature. For example, you can specify the red, green, and blue values of an average color.

When you use the API:

Using data source structures

Various structures are used to provide data source information for a query object. The structures are:

QbImageSource: The QbImageSource structure identifies the type of source for a feature in a query object. The structure is defined in the include (header) file for QBIC, dmbqbapi.h, as follows:

typedef struct{
          SQLINTEGER    type;
          union {
                char              imageHandle[MMDB_BASE_HANDLE_LEN+1];
                QbImageFile       clientFile;
                QbImageBuffer     buffer;
                QbSampleSource    reserved;
                QbColor           averageColor;
                QbHistogramColor  histogramColor[qbiHistogramCount];
          };
} QbImageSource;

The type field in the QbImageSource structure indicates the type of source. You can set the value in the field as follows:
Value Meaning
qbiSource_ImageHandle Source is in a user table column
qbiSource_ClientFile Source is in client workstation file
qbiSource_Buffer Source is in client workstation buffer
qbiSource_ServerFile Source is in server file
qbiSource_AverageColor Source is an average color specification
qbiSource_HistogramColor Source is a histogram color specification

These settings are valid only for the appropriate feature. For example, qbiSource_AverageColor is valid only for the average color feature.

If you set the type field to qbiSource_ServerFile, use clientFile for the name and type of the file on the server.

Depending on the type of source, the Image Extender also examines other information that you specify. This is shown in the following table.

Table 9. What the Image Extender examines in QbImageSource
Source What the Image Extender examines Where specified
a user table image handle image handle field of QbImageSource
file
name of file
format of file

clientFile field of QbImageSource
buffer name of file QbImageBuffer (see QbImageBuffer below for details about using this structure)
average color specification red, green, and blue color values QbColor structure (see QBColor below for details about using this structure)
histogram color specification color values and percentages QbHistogramColor structure (see QbHistogramColor below for details about using this structure)

QbImageBuffer: Use the QbImageBuffer structure to specify the format, length, and content of an image when the data source is in a buffer. The structure is defined in the include (header) file for QBIC, dmbqbapi.h, as follows:

typedef struct{
          char          format[qbiImageFormatLength+1];
          SQLINTEGER    length;
          char*         image;
} QbImageBuffer;

QbColor: Use the QbColor structure to specify the red, green, and blue values of an average color when the data source is an average color specification. The structure is defined in the include (header) file for QBIC, dmbqbapi.h, as follows:

typedef struct{
          SQLUSMALLINT    red;          /*0 off - 65535 (fully on) */
          SQLUSMALLINT    green;        /*0 off - 65535 (fully on) */
          SQLUSMALLINT    blue;         /*0 off - 65535 (fully on) */
} QbColor;

Set the values in QbColor to indicate the amount of red, green, and blue pixels to be factored in the average value calculation. The values can range from 0 to 65535. A value of 0 means ignore the entry.

QbHistogramColor: Use the QbHistogramColor structure to specify each color component of a histogram color specification. The full specification for a histogram color is contained in an array of QbHistogramColor structures. Each structure contains a color value and a percentage. The color value is comprised of red, green, and blue pixel values. The percentage specifies the percentage of that color that is required in the target image.

The structure is defined in the include (header) file for QBIC, dmbqbapi.h, as follows:

typedef struct{
          QbColor         color;
          SQLUSMALLINT    percentage;   /*0 - 100 */
} QbHistogramColor;

Set the values in QbColor to indicate the amount of red, green, and blue pixels for the color. The values can range from 0 to 65535. Set the percentage to indicate the percentage of the specified color that is required in the target image. The value can range from 1 to 100. The sum of the percentages for the color components in a histogram color must be 100 or less.

Examples

The API in the following example specifies the data source for the histogram color feature in a query object. The data source is a file in the client workstation.

char           featureName[qbiMaxFeatureName];
QbQueryHandle  qHandle;
QbImageSource  imgSource;
 
imgSource.type=qbiSource_ClientFile;
strcpy(imgSource.clientFile.fileName,"/tmp/image.gif");
strcpy(imgSource.clientFile.format,"GIF");
 
rc=QbQuerySetFeatureData(
                qHandle,                               /* query object handle */
                "QbColorHistogramFeatureClass",        /* feature name */
                &imgSource);                           /* feature data source */

In the following example, the data source is an average color specification of red:

char                 featureName[qbiMaxFeatureName];
QbColor              avgColor;
QbImageSource        imgSource;
 
imgSource.type=qbSource_AverageColor;
avgColor.red=255;
avgColor.green=0;
avgColor.blue=0;
strcpy(featureName,"QbColorFeatureClass");
 
rc=QbQuerySetFeatureData(
                qHandle,                              /* query object handle */
                featureName,                          /* feature name */
                &imgSource);                          /* feature data source */

Setting the weight of a feature in a query object

If you have added more than one feature to a query object, you can specify the weight that one or more features are to be given in a query. Use the QbQuerySetFeatureWeight API to specify the weight of a feature. The weight of a feature indicates the emphasis that the Image Extender places on the feature when it computes similarity scores and returns results for a query by image content. The higher the weight you specify for a feature, the greater the emphasis on that feature in the query object.

You can specify a weight for one or more features in a query object, although you can specify a weight for only one feature each time you issue the QbQuerySetFeatureWeight API. If you do not assign a weight to a feature in a query object, the Image Extender will use the default weight for the feature. Assigning a weight to a feature has no meaning if that feature is the only feature in a query object. (That feature will always have full weight in the query object.)

When you use the API:

In the following example, a query object contains the average color feature and at least one other feature. The QbQuerySetFeatureWeight API is used to specify a weight for the average color feature in the query object:

char                 featureName[qbiMaxFeatureName];
double               weight;
QbQueryObjectHandle  qoHandle;
 
strcpy(featureName,"QbColorFeatureClass");
weight=5.00;
 
rc=QbQuerySetFeatureWeight(
                qoHandle,                            /* query object handle */
                featureName,                         /* feature name */
                &weight);                            /* feature weight */

Saving and reusing a query string

Query objects are transient unless you save them. They exist only during a single database connection. You can save the query string from a query to use again in the program, or even after the current database connection is dropped and across program invocations.

The Image Extender provides the QbQueryGetString API that returns the query string from a query object. You can then use that query string as input to the QbQueryStringSearch API or to the QbScoreFromStr and QbScoreTBFromStr UDFs in other queries by image content (see Issuing queries by image content).

The query string is built when you build the query using:

After you build the query, you can call QbQueryGetString to get the string. You can use this query string in calls within that program or save it to a file for use in subsequent invocations of your application and in other database connections. After you are finished using the query string returned by QbQueryGetString, you must explicitly free the space.

In the following example, the QbQueryGetString is used to retrieve the query string from a query object:

SQLRETURN rc;
char* qryString;
QbQueryHandle  qHandle;
 
.....           /* Here you create and use the query */
 
rc = QbQueryGetString(qHandle, &qryString);
if ( rc == 0) {
   ...         /* Use the query string as input here  */
   free((void *)qryString);
   qryString=(char *)0;
}
 
Restriction::When you use a client file to specify the data source for a feature, the query string does not reflect the feature data.

Retrieving information about a query object

You can determine what features (if any) have been added to a query object. You can also determine the current weight of a feature.
Use this API To retrieve
QbQueryGetFeatureCount The number of features in a query object
QbQueryListFeatures The names of the features in a query object

When you issue the QbQueryGetFeatureCount API, specify the query object handle. You also need to point to a counter. The Image Extender returns the feature count in the counter.

In the following example, the QbQueryGetFeatureCount API is used to determine the number of features in a query object:

SQLINTEGER     count;
QbQueryHandle  qHandle;
 
rc=QbQueryGetFeatureCount(
                qHandle,                             /* query object handle */
                &count);                             /* feature count */

When you issue the QbQueryListFeatures API call, you need to allocate a buffer to hold the returned feature name. You also need to specify the catalog handle, and the size of the buffer for the returned feature name.

In the following example, the QbQueryListFeatures API is used to retrieve the name of each feature in a query object:

SQLINTEGER     retCount,bufSize;
char*          featureName;
QbQueryHandle  qHandle;
 
bufSize=qbiMaxFeatureName;
featureName=(char*)malloc(bufSize);
 
rc=QbQueryListFeatures(
                qHandle,                            /* query object handle */
                bufSize                             /* size of buffer */
                &retCount,                          /* feature count */
                featureName);                       /* buffer for feature names */

Removing a feature from a query object

Remove a feature from a query object with the QbQueryRemoveFeature API.

When you use the API, specify the query object handle and name the feature.

In the following example, the QbQueryRemoveFeature API is used to remove the histogram color feature from a query object:

char           featureName[qbiMaxFeatureName];
QbQueryHandle  qHandle;
 
strcpy(featureName,"QbColorHistogramFeatureClass");
 
rc=QbQueryRemoveFeature(
                qHandle,                             /* query object handle */
                featureName);                        /* feature name */

Deleting a query object

Delete an unnamed query object with the QbQueryDelete API.

The Image Extender deletes the query from the currently connected database.

When you use the QbQueryDelete API, specify the query object handle.

In the following example, the QbQueryDelete API is used to delete a query object:

QbQueryHandle  qHandle;
 
rc=QbQueryDelete(
            qHandle);                            /* query object handle */

If you have used a named query, delete the query object with the QbQueryNameDelete API.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]