查詢物件可用來識別您查詢的特性、特性值及特性比重。 建立查詢物件並將特性加入其中。 然後指定每一個特性的資料來源。 資料來源提供特性的值。 例如,資料來源可以是檔案中的影像。 如果平均色是相關特性,則影像的平均色與查詢物件有關。 如果將多個特性加入查詢物件,則您可以指定比重給一或多個特性。
Image Extender 提供三個 API (QbQuerySearch、QbQueryStringSearch 及QbQueryNameSearch) 以及兩個 UDF (QbScoreFromName 和QbScoreTBFromName),皆共用一個查 詢物件。當發出某個查詢時,請使用適當的 API 或 UDF, 並指定查詢物件作為輸入參數。(詳細資訊,請參閱按影像內容發出查詢。)
在回應時,Image Extender 會傳回查詢物件的 handle。 handle 具有 QBIC 特定資料類型 QbQueryHandle, 其定義在 QBIC 併入 (標頭) 檔 dmbqbapi.h 中。
在使用 API 時,您需要指出查詢物件 handle。 您也需要在查詢物件上執行其它作業 (如新增特性) 的 API 中指定 handle。
例如,下列 API 呼叫可建立查詢物件:
QbQueryHandle qHandle; rc=QbQueryCreate( &qHandle); /* query object handle */
藉由將特性加入查詢物件,可識別您要 Image Extender 查詢的影像特性。
使用 QbQueryAddFeature API 來將特性加入查詢物件。
在使用 API 時,請指定查詢物件 handle。 您也要將特性命名。您只能在 API 中指定一個特性。 您必須對每一個要加入查詢物件的特性發出個別的 API 呼叫。
在下列範例中,QbQueryAddFeature API 用來加入平均色特性到查詢物件:
char featureName[qbiMaxFeatureName]; QbQueryHandle qHandle; rc=QbQueryAddFeature( qHandle, /* query object handle */ "QbColorFeatureClass"); /* feature name */
使用 QbQuerySetFeatureData API 來指定查詢物件中特性的資料來源。
資料來源檔可以是:
此外,您可以明確地指定平均色或直方圖特性的資料。 例如,您可以指定平均色的紅色、綠色及藍色值。
當使用 API 時:
使用各種結構來提供查詢物件的資料來源資訊。 這些結構如下:
QbImageSource: QbImageSource 結構可識別查詢物件中特性的來源類型。
此結構定義在 QBIC 併入 (標頭) 檔 dmbqbapi.h 中,如下所示:
typedef struct{ SQLINTEGER type; union { char imageHandle[MMDB_BASE_HANDLE_LEN+1]; QbImageFile clientFile; QbImageBuffer buffer; QbSampleSource reserved; QbColor averageColor; QbHistogramColor histogramColor[qbiHistogramCount]; }; } QbImageSource;
QbImageSource 結構中的類型欄位指示來源類型。
您可以設定欄位中的值,如下所示:
值 | 意義 |
---|---|
qbiSource_ImageHandle | 來源位於使用者表格直欄中 |
qbiSource_ClientFile | 來源位於從屬站工作站檔案中 |
qbiSource_Buffer | 來源位於從屬站工作站緩衝區中 |
qbiSource_ServerFile | 來源位於伺服器檔案 |
qbiSource_AverageColor | 來源為平均色規格 |
qbiSource_HistogramColor | 來源為直方圖色規格 |
這些設定僅對適當特性有效。例如,qbiSource_AverageColor 僅對平均色特性有效。
若類型欄位設為 qbiSource_ServerFile,對伺服器上檔案的名稱及類型,請使用 clientFile。
根據來源類型,Image Extender 也會檢查您指定的其它資訊。
它會顯示於下列表格。
表 9. Image Extender 在 QbImageSource 中檢查什麼
來源 | Image Extender 檢查什麼 | 在何處指定 |
---|---|---|
使用者表格 | 影像 handle | QbImageSource 的影像 handle 欄位 |
檔案 |
檔名 檔案格式 | QbImageSource 的 clientFile 欄位 |
緩衝區 | 檔名 | QbImageBuffer (關於使用此結構的詳細資訊,請參閱下 列的 QbImageBuffer) |
平均色規格 | 紅色、綠色和藍色值 | QbColor 結構 (有關使用此結構的細節,請參閱下面的 QBColor) |
直方圖色規格 | 顏色值和百分比 | QbHistogramColor 結構 (有關使用此結構的細節,請參閱下面的 QbHistogramColor) |
QbImageBuffer:當資料來源位於緩衝區中時,使用 QbImageBuffer 結構來指定影像格式、 長度和內容。
此結構定義在 QBIC 併入 (標頭) 檔 dmbqbapi.h 中,如下所示:
typedef struct{ char format[qbiImageFormatLength+1]; SQLINTEGER length; char* image; } QbImageBuffer;
QbColor: 當資料來源是平均色規格時,可使用 QbColor 結構來指定平均色的紅色、 綠色及藍色值。
此結構定義在 QBIC 併入 (標頭) 檔 dmbqbapi.h 中,如下所示:
typedef struct{ SQLUSMALLINT red; /*0 off - 65535 (fully on) */ SQLUSMALLINT green; /*0 off - 65535 (fully on) */ SQLUSMALLINT blue; /*0 off - 65535 (fully on) */ } QbColor;
設定 QbColor 中的值,指示平均值計算中要分解為因素的紅色、 綠色及藍色圖點數量。 這些值的範圍從 0 到 65535。 0 值表示忽略項目。
QbHistogramColor:使用 QbHistogramColor 結構,指定直方圖色規格的每一個顏色元件。
直方圖陣列的完整規格包含在 QbHistogramColor 結構的陣列中。 每一個結構含有一個顏色值和一個百分比。 此顏色值由紅色、綠色和藍色圖點值構成。 此百分比指定目標影像中所需顏色所佔的百分比。
此結構定義在 QBIC 併入 (標頭) 檔 dmbqbapi.h 中,如下所示:
typedef struct{ QbColor color; SQLUSMALLINT percentage; /*0 - 100 */ } QbHistogramColor;
設定 QbColor 中的值,指示顏色的紅色、綠色和藍色圖點數量。 這些值的範圍從 0 到 65535。設定百分比,以指示目標影像中所需的指定顏色所佔的的百分比。此值範圍從 1 到 100。直方圖色中顏色元件的百分比總和必須不大於 100。
下列範例中的 API 指定查詢物件中直方圖色特性的資料來源。 資料來源檔是從屬站工作站中的檔案。
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 */
在下列範例中,資料來源是紅色的平均色規格:
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 */
如果您已將一個以上特性加入查詢物件,可以指定查詢中所提供一個以上特性的比重。使用 QbQuerySetFeatureWeight API 來指定特性的比重。 特性的比重指出 Image Extender 在計算相似性點數及傳回影像內容的查詢結果時, 對特性的強調。對特性指定了越高的比重,表示越強調查詢物件中的該特性。
雖然,每次您發出 QbQuerySetFeatureWeight API 時, 只能對一個特性指定比重,但您可以對查詢物件中一或多個特性指定比重。 如果您沒有指定比重給查詢物件中的特性,則 Image Extender 將使用此特性的預設比重。 如果特性是查詢物件中唯一的特性,則不需要指定比重給該特性。(在查詢物件中,此特性將一直保有完整的比重。)
當使用 API 時:
在下列範例中,一個查詢物件含有平均色特性及至少一個其它特性。 您可使用 QbQuerySetFeatureWeight API 來指定查詢物件中平均色特性的比重:
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 */
除非您儲存查詢物件,否則它們只是暫時性狀態。 這些查詢物件只存在於單一資料庫連接期間。 您可以儲存來自查詢的查詢字串,再次用於程式, 或即使現行資料庫連接捨棄後的程式呼叫中使用。
Image Extender 提供 QbQueryGetString API,可傳回來自查詢物件的查詢字串。 然後,該查詢字串可以輸入 QbQueryStringSearch API 或 QbScoreFromStr,及按影像內容的其它字串 QbScoreTBFromStr UDF。 (請參閱按影像內容發出查詢)。
當您使用下列指令來建置字串時,可建置查詢字串︰
建立查詢後,您可以呼叫 QbQueryGetString 來取得字串。 在該程式內呼叫中可以使用此查詢字串, 或將它儲存至其他檔案,以使用於應用程式後續的呼叫及其它資料庫連接。 使用 QbQueryGetString 所傳回的查詢字串後, 您必須明確地釋放空間。
在下列範例中,QbQueryGetString 用來擷取查詢物件的查詢字串︰
SQLRETURN rc; char* qryString; QbQueryHandle qHandle; ..... /* 這裡建立並使用查詢 */ rc = QbQueryGetString(qHandle, &qryString); if ( rc == 0) { ... /* 這裡查詢字串作為輸入 */ free((void *)qryString); qryString=(char *)0; }
限制︰: | 當您使用從屬站檔案指定資料來源給某特性時, 查詢字串不會反映特性資料。 |
您可以判斷已加入查詢物件的特性 (若有的話)。 您亦可判斷特性的現行比重。
使用此 API | 擷取 |
---|---|
QbQueryGetFeatureCount | 查詢物件中的特性數目 |
QbQueryListFeatures | 查詢物件中的特性名稱 |
當您發出 QbQueryGetFeatureCount API 時, 請指定查詢物件 handle。 您也需要指向計數器。Image Extender 會傳回計數器中的特性計數。
在下列範例中,QbQueryGetFeatureCount API 用來判斷查詢物件中特性數目:
SQLINTEGER count; QbQueryHandle qHandle; rc=QbQueryGetFeatureCount( qHandle, /* query object handle */ &count); /* feature count */
當您發出 QbQueryListFeatures API 呼叫時, 您必須配置緩衝區來保留傳回的特性名稱。 您也需要為傳回的特性名稱指定型錄 handle 和緩衝區大小。
在下列範例中,QbQueryListFeatures API 用來擷取查詢物件中每一個特性的名稱:
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 */
使用 QbQueryRemoveFeature API,移除查詢物件中的特性。
當您使用 API 時, 請指定查詢物件 handle 及為特性命名。
在下列範例中,QbQueryRemoveFeature API 用來移除查詢物件中直方圖色特性:
char featureName[qbiMaxFeatureName]; QbQueryHandle qHandle; strcpy(featureName,"QbColorHistogramFeatureClass"); rc=QbQueryRemoveFeature( qHandle, /* query object handle */ featureName); /* feature name */
使用 QbQueryDelete API 刪除未命名的查詢物件。
Image Extender 會從目前連接的資料庫中刪除查詢。
當您使用 QbQueryDelete API 時,請指定查詢物件 handle。
在下列範例中,QbQueryDelete API 用來刪除查詢物件:
QbQueryHandle qHandle; rc=QbQueryDelete( qHandle); /* query object handle */
如果您使用指名的查詢,請使用 QbQueryNameDelete API 來刪除查詢物件。