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.)
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 */
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 */
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:
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.
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 */
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 */
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. |
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 */
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 */
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.