イメージ、オーディオ、およびビデオ・エクステンダー 管理およびプログラミングの手引き

照会オブジェクトの使い方

照会のためにフィーチャー、フィーチャーの値および重みを指定するために照会オブジェクトを使用することができます。

照会オブジェクトを作成し、それにフィーチャーを追加します。 次に、各フィーチャーごとにデータ・ソースを指定します。 データ・ソースで、各フィーチャーの値を提供します。 たとえば、データ・ソースはファイル内の画像である場合があります。 平均色が該当するフィーチャーである場合、画像の平均色が照会オブジェクトに関連付けられます。 1 つの照会オブジェクトに複数のフィーチャーを追加する場合、1 つまたは複数のフィーチャーに重みを割り当てることができます。

イメージ・エクステンダーでは、照会オブジェクトを使用する 3 つの API (QbQuerySearch、QbQueryStringSearch、および QbQueryNameSearch) および 2 つの UDF (QbScoreFromName および QbScoreTBFromName) が用意されています。 照会を出す場合、適切な API または UDF を使用し、入力パラメーターとして照会オブジェクトを指定してください。 (詳細については、イメージ内容による照会の実行を参照してください。)

照会オブジェクトの作成

照会オブジェクトを作成するには、QbQueryCreate API を使用します。

応答として、イメージ・エクステンダーは、その照会オブジェクトのハンドルを戻します。 このハンドルは、QBIC 用のインクルード (ヘッダー) ファイル dmbqbapi.h に定義されている QBIC 固有のデータ・タイプ QbQueryHandle を持ちます。

この API を使用するときは、照会オブジェクト・ハンドルをポイント指定する必要があります。 このハンドルは、照会オブジェクトに関して行う他の操作の API (フィーチャーの追加など) にも指定する必要があります。

たとえば、次の API 呼び出しは、照会オブジェクトを作成します。

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

フィーチャーを照会オブジェクトに追加する

画像のフィーチャーをイメージ・エクステンダーに照会させる場合は、それらのフィーチャーを照会オブジェクトに追加しておきます。

フィーチャーを照会オブジェクトに追加するには、QbQueryAddFeature API を使用します。

この API を使用するときは、照会オブジェクト・ハンドルを指定します。 さらに、フィーチャー名を指定する必要があります。 この API にはフィーチャーを 1 つしか指定できません。 照会オブジェクトに追加するフィーチャーごとに別個の 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 を使用してください。

ソースのタイプによっては、イメージ・エクステンダーは指定された他の情報も検査します。 これを次の表 に示します。

表 9. QbImageSource でイメージ・エクステンダーが調べる項目
ソース イメージ・エクステンダーが調べる項目 指定する場所
ユーザー表 画像ハンドル QbImageSource の画像ハンドル・フィールド
ファイル
ファイルの名前ファイルの形式

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 構造体を使用します。

1 つのヒストグラム色に対する指定は、QbHistogramColor 構造体の配列で行います。 各構造体には、1 つの色とパーセントを指定します。 色値は、赤、緑、青のピクセル値からなります。 パーセントでは、ターゲット・イメージにおけるその色の割合を指定します。

この構造体は、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 */

照会オブジェクトにフィーチャーの重みを設定する

照会オブジェクトに複数のフィーチャーを追加した場合、照会で 1 つまたは複数のフィーチャーに与える重みを指定することができます。 フィーチャーの重みを指定するには、QbQuerySetFeatureWeight API を使用します。 フィーチャーの重みは、イメージ・エクステンダーが類似性得点を計算し、イメージ内容による照会の結果を戻すときに、フィーチャーに置く強調を示します。 フィーチャーに指定する重みが大きければ大きいほど、照会オブジェクトに組み込まれたそのフィーチャーに対する強調が大きくなります。

照会オブジェクトに組み込まれた 1 つまたは複数のフィーチャーの重みを指定できますが、QbQuerySetFeatureWeight API を出すたびに、1 つのフィーチャーの重みしか指定できません。 照会オブジェクトでフィーチャーに重みを割り当てない場合、イメージ・エクステンダーはそのフィーチャーの省略時の重みを使用します。 フィーチャーが 1 つの照会ストリングに指定された唯一のフィーチャーである場合、重みの割り当ては無意味です。 フィーチャーが 1 つの照会オブジェクトの指定された唯一のフィーチャーである場合、重みの割り当ては無意味です。 (そのフィーチャーは照会オブジェクト内で常にすべての重みを持ちます。)

この API を使用するときは、次のようにします。

次の例では、照会オブジェクトに平均色フィーチャーと少なくとも 1 つの他のフィーチャーが含まれています。 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 */

照会ストリングの保管と再利用

照会オブジェクトは、保管しない限り一時的なものです。 照会オブジェクトは、1 度のデータベース接続の間だけ存在します。 照会によって取得した照会ストリングを保管して、プログラム内で再び使用することができます。 また、現行のデータベース接続を除去した後や、別のプログラムを呼び出している間にも使用することもできます。

イメージ・エクステンダーには、照会オブジェクトから照会ストリングを戻す QbQueryGetString API があります。 それで、その照会ストリングを QbQueryStringSearch API への入力として、またはイメージ内容による他の照会で QbScoreFromStr および QbScoreTBFromStr UDF への入力として使用することができます (イメージ内容による照会の実行を参照)。

照会ストリングは、以下の API を使用して照会を作成するときに作成されます。

照会を作成した後、QbQueryGetString を呼び出して、そのストリングを入手することができます。 この照会ストリングを、そのプログラム中の呼び出しで使用したり、ファイルに保管しておいて、アプリケーションのその後の呼び出しや他のデータベース接続で使用したりすることができます。 QbQueryGetString によって戻された照会ストリングの使用を終えたならば、スペースを明示的に解放する必要があります。

次の例では、QbQueryGetString を使って、照会オブジェクトから照会ストリングを取り出します。

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;
}
制約事項:クライアント・ファイルを使用してフィーチャーのデータ・ソースを指定する場合、照会ストリングはそのフィーチャー・データを反映しません。

照会オブジェクトに関する情報を取り出す

どのようなフィーチャー (もしあれば) が照会オブジェクトに追加されているかを知ることができます。 さらに、フィーチャーの現在の重みも知ることができます。
API 取り出す情報
QbQueryGetFeatureCount 照会オブジェクトに組み込まれているフィーチャーの数
QbQueryListFeatures 照会オブジェクトに組み込まれているフィーチャーの名前

QbQueryGetFeatureCount API を出す場合には、照会オブジェクト・ハンドルを指定します。 さらに、カウンターをポイント指定する必要があります。 イメージ・エクステンダーはフィーチャー数をこのカウンターに戻します。

次の例では、QbQueryGetFeatureCount API を使って、照会オブジェクトに組み込まれているフィーチャー数を判別します。

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

QbQueryListFeatures API 呼び出しを出す場合には、戻されるフィーチャー名が入るバッファーを割り振る必要があります。 さらに、カタログ・ハンドルと、戻されるフィーチャー名のバッファー・サイズを指定する必要があります。

次の例では、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 を使用する場合には、照会オブジェクト・ハンドルとフィーチャーの名前を指定します。

次の例では、QbQueryRemoveFeature API を使って、ヒストグラム色というフィーチャーを照会オブジェクトから除去します。

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

照会オブジェクトを削除する

名前の付いていない照会オブジェクトを削除するには、QbQueryDelete API を使用します。

イメージ・エクステンダーは、現在接続されているデータベースからその照会を削除します。

QbQueryDelete API を使用する場合には、照会オブジェクト・ハンドルを指定します。

次の例では、QbQueryDelete API を使って照会オブジェクトを削除します。

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

名前付きの照会を使用していた場合には、QbQueryNameDelete API を使って照会オブジェクトを削除してください。


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]