Image、Audio 及 Video Extenders 管理與程式設計

使用查詢物件

查詢物件可用來識別您查詢的特性、特性值及特性比重。 建立查詢物件並將特性加入其中。 然後指定每一個特性的資料來源。 資料來源提供特性的值。 例如,資料來源可以是檔案中的影像。 如果平均色是相關特性,則影像的平均色與查詢物件有關。 如果將多個特性加入查詢物件,則您可以指定比重給一或多個特性。

Image Extender 提供三個 API (QbQuerySearch、QbQueryStringSearch 及QbQueryNameSearch) 以及兩個 UDF (QbScoreFromName 和QbScoreTBFromName),皆共用一個查 詢物件。當發出某個查詢時,請使用適當的 API 或 UDF, 並指定查詢物件作為輸入參數。(詳細資訊,請參閱按影像內容發出查詢。)

建立查詢物件

使用 QbQueryCreate API 來建立查詢物件。

在回應時,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 來刪除查詢物件。


[ 頁面頂端 | 前一頁 | 下一頁 | 目錄 | 索引 ]