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