Extensions Image, Audio et Vidéo Administration et programmation

Utilisation d'un objet de requête

Vous pouvez utiliser un objet de requête pour identifier les caractéristiques, leurs valeurs et leur poids pour votre requête. Vous créez l'objet de requête et lui ajoutez des caractéristiques. Ensuite, vous spécifiez une source de données pour chacune de celles-ci. La source de données fournit la valeur correspondant à la caractéristique et peut être, par exemple, une image contenue dans un fichier. Si la couleur moyenne est la caractéristique importante, la couleur moyenne de l'image est associée à l'objet de requête. En cas de spécification de nombreuses caractéristiques dans une requête, vous pouvez également affecter un poids à une ou plusieurs d'entre elles.

L'extension Image fournit trois API (QbQuerySearch, QbQueryStringSearch et QbQueryNameSearch) et deux fonctions UDF (QbScoreFromName et QbScoreTBFromName) permettant d'utiliser un objet de requête. Lorsque vous lancez une requête, vous devez utiliser l'API ou la fonction utilisateur appropriée, et spécifier l'objet de requête en tant que paramètre d'entrée. (Pour plus de détails, reportez-vous à la section Lancement de requêtes par contenu d'images.)

Création d'un objet de requête

Utilisez l'API QbQueryCreate pour créer un objet de requête.

Suite à cela, l'extension Image renvoie un descripteur correspondant à cet objet. Ce descripteur est d'un type de données propres à QBIC,QbQueryHandle, qui est défini dans le fichier (en-tête) d'inclusion pour QBIC, dmbqbapi.h.

Lorsque vous utilisez cette API, vous devez spécifier le descripteur de l'objet de recherche. Vous devez également indiquer ce descripteur dans les API effectuant d'autres opérations sur l'objet de requête, telles que l'ajout d'une caractéristique.

Par exemple, l'appel d'API suivant crée un objet de requête :

QbQueryHandle  qHandle;
 
rc=QbQueryCreate(
              &qHandle);                         /* descripteur de l'objet */
                                                 /* de requête */

Ajout d'une caractéristique à un objet de requête

Vous identifiez la caractéristique de l'image que l'extension Image doit rechercher en l'ajoutant à un objet de requête.

Utilisez l'API QbQueryAddFeature pour ajouter une caractéristique à un objet de requête.

Lorsque vous utilisez cette API, indiquez le descripteur de l'objet de requête ainsi que le nom de la caractéristique. Vous ne pouvez spécifier qu'une seule caractéristique dans l'API. Vous devez émettre un appel API distinct pour chaque caractéristique à ajouter à un objet de requête.

Dans l'exemple ci-dessous, l'API QbQueryAddFeature est utilisée pour ajouter la caractéristique couleur moyenne à un objet de requête :

char  featureName[qbiMaxFeatureName];
QbQueryHandle  qHandle;
 
rc=QbQueryAddFeature(
                qHandle,                    /* descripteur de l'objet de requête */
                "QbColorFeatureClass");           /* nom de la caractéristique */

Indication de la source de données pour une caractéristique contenue dans un objet de requête

Utilisez l'API QbQuerySetFeatureData afin d'indiquer la source de données pour

une caractéristique contenue dans un objet de requête. La source de données peut être :

En outre, vous pouvez indiquer explicitement des données pour la caractéristique couleur moyenne ou couleur d'histogramme. Par exemple, vous pouvez indiquer les valeurs de rouge, vert et bleu d'une couleur moyenne.

Lorsque vous utilisez cette API :

Utilisation de structures de source de données

Trois structures sont utilisées pour fournir des informations de source de données pour un objet de requête. Il s'agit de :

QbImageSource : La structure QbImageSource identifie le type de source pour une caractéristique contenue dans un objet de requête. Cette structure est définie dans le fichier (en-tête) d'inclusion pour QBIC, dmbqbapi.h, comme suit :

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

La zone type de la structure QbImageSource indique le type de la source. Vous pouvez définir la valeur de cette zone comme suit :
Valeur Signification
qbiSource_ImageHandle La source se trouve dans une colonne de table utilisateur.
qbiSource_ClientFile La source se trouve dans un fichier du poste client.
qbiSource_Buffer La source se trouve dans la mémoire tampon du poste client.
qbiSource_ServerFile La source se trouve dans un fichier de serveur.
qbiSource_AverageColor La source est une spécification de couleur moyenne.
qbiSource_HistogramColor La source est une spécification de couleur d'histogramme.

Ces paramètres ne sont valables que pour la caractéristique correspondante. Par exemple, qbiSource_AverageColor n'est valable que pour la caractéristique couleur moyenne.

Si vous attribuez la valeur qbiSource_ServerFile à la zone de type, utilisez clientFile comme nom et type du fichier sur le serveur.

En fonction du type de source, l'extension Image analyse également d'autres informations, comme l'indique le tableau suivant.

Tableau 9. Informations analysées par l'extension Image dans QbImageSource
Source Informations analysées par l'extension Image Zone
table utilisateur descripteur d'image zone du descripteur d'image de QbImageSource
fichier
nom du fichier


format du fichier

zone clientFile de QbImageSource
mémoire tampon nom du fichier QbImageBuffer (pour plus de détails sur l'utilisation de cette structure, reportez-vous à la section QbImageBuffer ci-après)
spécification de la couleur moyenne valeurs des couleurs rouge, vert et bleu QbColor (pour plus de détails sur l'utilisation de cette structure, reportez-vous à la section QBColor ci-après)
spécification de la couleur d'histogramme valeurs et pourcentages de couleur QbHistogramColor (pour plus de détails sur l'utilisation de cette structure, reportez-vous à la section QbHistogramColor ci-après)

QbImageBuffer : Utilisez la structure QbImageBuffer pour indiquer le format, la longueur et le contenu d'une image lorsque la source de données se trouve dans une mémoire tampon. Cette structure est définie dans le fichier (en-tête) d'inclusion pour QBIC, dmbqbapi.h, comme suit :

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

QbColor : Utilisez la structure QbColor pour indiquer les valeurs de rouge, de vert et de bleu d'une couleur moyenne lorsque la source de données est une spécification de couleur moyenne. Cette structure est définie dans le fichier (en-tête) d'inclusion pour QBIC, dmbqbapi.h, comme suit :

typedef struct{
          SQLUSMALLINT    red;          /*0 mini - 65535 (maxi) */
          SQLUSMALLINT    green;        /*0 mini - 65535 (maxi) */
          SQLUSMALLINT    blue;         /*0 mini - 65535 (maxi) */
} QbColor;

Définissez les valeurs de la structure QbColor afin d'indiquer le pourcentage de pixels de rouge, vert et bleu à intégrer dans le calcul de la valeur de la couleur moyenne. Vous pouvez indiquer une valeur comprise entre 0 et 65535. La valeur 0 indique que l'entrée doit être ignorée.

QbHistogramColor : Utilisez la structure QbHistogramColor pour indiquer chaque composant couleur d'une spécification de couleur d'histogramme. La spécification complète d'une couleur d'histogramme se trouve dans un tableau de structures QbHistogramColor. Chaque structure contient une valeur de couleur et un pourcentage. La valeur de couleur est constituée de valeurs de pixels de rouge, vert et bleu. Le pourcentage est celui de la couleur souhaité dans l'image cible.

Cette structure est définie dans le fichier (en-tête) d'inclusion pour QBIC, dmbqbapi.h, comme suit :

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

Définissez les valeurs de la structure QbColor afin d'indiquer le pourcentage de pixels de rouge, vert et bleu constituant la couleur. Vous pouvez indiquer une valeur comprise entre 0 et 65535. Indiquez le pourcentage souhaité de la couleur spécifiée dans l'image cible. Vous pouvez indiquer une valeur comprise entre 1 et 100. La somme des pourcentages pour les composants couleur d'une couleur d'histogramme ne peut dépasser 100.

Exemples 

Dans l'exemple ci-après, l'API indique la source de données pour la caractéristique couleur d'histogramme dans un objet de requête. La source de données est un fichier résidant sur le poste client.

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,                 /* descripteur de l'objet de requête */
                "QbColorHistogramFeatureClass",  /* nom de la caractéristique */
                &imgSource);                /* source de données de la */
                                            /* caractéristique */

Dans l'exemple suivant, la source de données est une spécification de couleur moyenne pour le rouge :

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,                    /* descripteur de l'objet de requête */
                featureName,;                    /* nom de la caractéristique */
                &imgSource);                /* source de données de la */
                                            /* caractéristique */

Configuration du poids d'une caractéristique contenue dans un objet de requête

En cas d'ajout de plusieurs caractéristiques à un objet de requête, vous pouvez configurer le poids à affecter à une ou plusieurs d'entre elles dans la requête. Utilisez l'API QbQuerySetFeatureWeight pour spécifier le poids d'une caractéristique. Celui-ci indique l'importance accordée par l'extension Image à la caractéristique concernée lors du calcul de scores de similarité et du renvoi des résultats d'une requête par contenu d'image. L'importance de la caractéristique au sein de l'objet de requête est proportionnelle au poids qui lui est associé.

Vous pouvez affecter un poids à une ou plusieurs caractéristiques dans un objet de requête, bien que vous ne puissiez spécifier que le poids d'une seule caractéristique lorsque vous lancez l'API QbQuerySetFeatureWeight. Si vous n'affectez pas de poids à une caractéristique dans un objet de requête, l'extension Image attribue la valeur par défaut correspondante. Il est inutile d'affecter un poids à une caractéristique si l'objet de requête n'en contient qu'une seule. (Dans ce cas, tout le poids de la requête porte sur cette caractéristique.)

Lorsque vous utilisez cette API :

Dans l'exemple ci-dessous, l'objet de requête contient au minimum une autre caractéristique, outre celle de couleur moyenne. L'API QbQuerySetFeatureWeight est utilisée pour préciser le poids de la caractéristique de couleur moyenne dans l'objet de requête :

char  featureName[qbiMaxFeatureName];
double               weight;
QbQueryObjectHandle  qoHandle;
 
strcpy(featureName,"QbColorFeatureClass");
weight=5.00;
 
rc=QbQuerySetFeatureWeight(
                qoHandle,                /* descripteur de l'objet */
                                          /* de requête */
                featureName,;            /* nom de la caractéristique */
                &weight);                /* poids de la caractéristique */

Sauvegarde et réutilisation d'une chaîne de requête

Les objets de requête sont transitoires sauf si vous les sauvegardez. Ils n'existent que pendant une seule connexion à une base de données. Vous pouvez sauvegarder la chaîne de requête pour la réutiliser ultérieurement dans le programme, ou après abandon de la connexion à la base de données via des appels de programmes.

L'extension Image fournit l'API QbQueryGetString qui renvoie la chaîne de requête d'un objet de requête. Vous pouvez ainsi utiliser cette chaîne comme données d'entrée dans l'API QbQueryStringSearch ou dans les fonctions UDF QbScoreFromStr et QbScoreTBFromStr dans d'autres requêtes d'images par contenu (reportez-vous à la section Lancement de requêtes par contenu d'images).

La chaîne de requête est créée lorsque la requête est générée à l'aide de :

Une fois la requête générée, vous pouvez appeler l'API QbQueryGetString pour obtenir la chaîne. Vous pouvez utiliser cette chaîne de requête dans les appels émis au sein de ce programme ou la sauvegarder dans un fichier afin de l'utiliser dans des appels ultérieurs lancés vers l'application et dans d'autres connexions à la base de données. Après utilisation de la chaîne renvoyée par QbQueryGetString, vous devez libérer explicitement l'espace utilisé.

Dans l'exemple suivant, l'API QbQueryGetString est utilisée pour extraire la chaîne de requête à partir d'un objet de requête :

  SQLRETURN rc;
char* qryString;
QbQueryHandle  qHandle;
 
.....           /* Création et utilisation de la chaîne de requête */
 
rc = QbQueryGetString(qHandle, &qryString);
if ( rc == 0) {
   ...         /* Utilisation de la chaîne de requête en entrée */
   free((void *)qryString);
   qryString=(char *)0;
}
 
Restriction:Lorsque vous utilisez un fichier client pour indiquer la source de données d'une caractéristique, la chaîne de requête ne reflète pas les données de cette dernière.

Extraction d'informations relatives à un objet de requête

Vous pouvez déterminer les caractéristiques qui ont été ajoutées à un objet de requête (le cas échéant), ainsi que le poids actuellement affecté à une caractéristique.
Utilisez cette API pour extraire
QbQueryGetFeatureCount le nombre de caractéristiques figurant dans un objet de requête
QbQueryListFeatures les noms des caractéristiques figurant dans un objet de requête

Lorsque vous utilisez l'API QbQueryGetFeatureCount, indiquez le descripteur de l'objet de requête. Vous devez également pointer sur un compteur. L'extension Image renvoie dans ce dernier le décompte des caractéristiques.

Dans l'exemple ci-dessous, l'API QbQueryGetFeatureCount est utilisée pour déterminer le nombre de caractéristiques contenues dans un objet de requête :

 SQLINTEGER     count;
QbQueryHandle  qHandle;
 
rc=QbQueryGetFeatureCount(
                qHandle,              /* descripteur de l'objet de requête */
                &count);              /* nombre de caractéristiques */

Lorsque vous émettez l'appel d'API QbQueryListFeatures, vous devez affecter une mémoire tampon dans laquelle sera placé le nom de caractéristique renvoyé. Vous devez également indiquer le descripteur du catalogue et la taille de la mémoire tampon pour les noms de caractéristiques renvoyés.

Dans l'exemple suivant, l'API QbQueryListFeatures est utilisée pour extraire le nom de chaque caractéristique contenue dans un objet de requête:

SQLINTEGER     retCount,bufSize;
char*          featureName;
QbQueryHandle  qHandle;
 
bufSize=qbiMaxFeatureName;
featureName=(char*)malloc(bufSize);
 
rc=QbQueryListFeatures(
                qHandle,                /* descripteur de l'objet de requête */
                bufSize                  /* taille de la mémoire tampon */
                &retCount,               /* nombre de caractéristiques */
                featureName);            /* mémoire tampon pour les noms */
                                         /* de caractéristiques */

Suppression d'une caractéristique dans un objet de requête

Pour supprimer une caractéristique dans un objet de requête, utilisez l'API QbQueryRemoveFeature.

Lorsque vous utilisez cette API, indiquez le descripteur de l'objet de requête et le nom de la caractéristique.

Dans l'exemple suivant, l'API QbQueryRemoveFeature est utilisée pour supprimer la caractéristique couleur d'histogramme d'un objet de requête :

char  featureName[qbiMaxFeatureName];
QbQueryHandle  qHandle;
 
strcpy(featureName,"QbColorHistogramFeatureClass");
 
rc=QbQueryRemoveFeature(
                qHandle,              /* descripteur de l'objet de requête */
                featureName);        /* nom de la caractéristique */

Suppression d'un objet de requête

Supprimez un objet de requête ne portant pas de nom à l'aide d'une API QbQueryDelete.

L'extension Image supprime la requête de la base de données à laquelle vous êtes connecté.

Lorsque vous utilisez l'API QbQueryDelete, indiquez le descripteur de l'objet de requête.

Dans l'exemple suivant, l'API QbQueryDelete est utilisée pour supprimer un objet de requête :

QbQueryHandle  qHandle;
 
rc=QbQueryDelete(
              qHandle);                          /* descripteur de l'objet */
                                                 /* de requête */

Si vous avez utilisé une requête nommée, supprimez l'objet de requête à l'aide de l'API QbQueryNameDelete.


[ Début de page | Page précédente | Page suivante | Table des matières | Index ]