Page 10 out of 26 total pages


QbCatalogClass


QbCatalogClass is derived from the QbBaseClass and handles all catalog-related operations, such as creating and deleting feature tables; adding, removing, and updating the feature data for input images in feature tables; and so on.

This release of the QBIC API uses Berkeley dbm files as persistent storage. Therefore, feature tables correspond to a set of files in the database directory. The catalog name is used as the file extension. For each new catalog, QbCatalogClass creates a feature index file, called FeatIdx, that keeps track of which QBIC features are indexed for the catalog and other global information for each feature class.

For each feature class, QbCatalogClass creates a feature table that uses part of the feature class name as the file name. Whenever possible, QBIC catalogs use the "8.3" file naming convention. The feature table name is created by first removing the leading "Qb" characters of the feature class name, and then joining the next 7 characters of the feature class name with an uppercase F. For example, for the QbColorHistogramFeatureClass, the table name will be ColorHiF. If the catalog name is ibm, then the full feature index name and the table name would be FeatIdx.ibm and ColorHiF.ibm respectively.

This class contains the public enumerated variable UpdateType which specifies whether to insert, increment, update, or force update records in the catalog:

QbCatalogClass method

This is the constructor for the class.

Syntax

QbCatalogClass( const QbConnectClass &connect )

Parameters

Input

connect-A reference to the QbConnectClass instance

Output

None

~QbCatalogClass method

This is the destructor for the class.

Syntax

virtual ~QbCatalogClass( void )

Parameters

None

AddFeatureClass method

This method adds the feature class of the name given to the catalog. It creates a feature table for the class, and updates the feature index table (created by the CreateCatalog method) to include the added feature class.

Syntax

virtual int AddFeatureClass( const char *featureClassName ) 

Parameters

Input

featureClassName-A pointer to a string that holds the feature class name

Output

An integer value: 0 indicates success; nonzero indicates failure

AddRecord method

This method adds an object to the catalog. This method has overloaded functions:

Syntax

virtual int AddRecord( const char *keyArg, const QbGenericDataClass 
&data, const QbParameterClass *parms, const UpdateType update = 
insertRecord, const char *featureListBuffer = NULL )

virtual int AddRecord (const char *keyArg, const QbGenericDataClass 
&data, const QbFeatureClass **features, const QbParameterClass 
**parms, int numOfFeatures, const UpdateType update = insertRecord)

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates a fatal error; 1 indicates a non-fatal error

AddSample method

This method adds the image object into the given sampler table. Feature data is computed and saved in persistent storage, one for each sampler name in samplerList.

Syntax

virtual int AddSample( const char *keyArg, const char *samplerList, 
const QbGenericDataClass &data, const QbParameterClass *parms, 
const UpdateType update = insertRecord )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

CloseCatalog method

This method closes the catalog.

Syntax

virtual int CloseCatalog( void )

Parameters

Input

None

Output

An integer value: 0 indicates success; nonzero indicates failure

CreateCatalog method

This method creates the catalog in persistent storage (for example, on disk). This method creates a container in the persistent storage for global catalog information (such as feature names, global feature information, and so on).

The default implementation of this method uses Berkeley dbm as the database manager, so the CreateCatalog method creates the feature index table in the database directory with the name FeatIdx and with the catalog name as the extension. The feature index table stores global information such as feature names used for image feature extraction, number of images processed, global statistics of feature data, and so on.

Syntax

virtual int CreateCatalog( const char * catalogNameArg )

Parameters

Input

catalogNameArg-A pointer to a string that holds the catalog name

Output

An integer value: 0 indicates success; -1 indicates failure

CreateSampler method

This method creates a new sampler table in the database. A sampler table is not specific to a particular catalog. It can be used to put samples of feature data (presumably uniformly distributed) in the feature data space to allow a user to choose a particular place in the feature space to start a QBIC search.

Syntax

vitrual int CreateSampler( const char *samplerName, const char 
*featureclassName)

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

DefineSubPart method

This method defines a subpart of a query object. Defining a subpart allows feature information to be computed for only a certain portion of an image that is of interest.

This method updates the subpart index table. It adds the input subpartKey to the child list of the parentKey, and adds the subpartKey with its mask data as a key-data pair entry.

Syntax

virtual int DefineSubPart( const char *parentKey, const char 
*subpartKey, const QbGenericDataClass &subpart )

Parameters

Input

Output

An integer value: 0 indicates success; nonzero indicates failure

DeleteFeatureClass method

This method deletes a feature class object from the catalog. This deletes the feature data table from the database, and updates the feature table (created by the CreateCatalog method) to remove the deleted feature class.

Syntax

virtual int DeleteFeatureClass( const char * featureClassName ) 

Parameters

Input

featureClassName-A pointer to a string that holds the feature class name

Output

An integer value: 0 indicates success; nonzero indicates failure

DeleteRecord method

This method deletes a record from the catalog using the given key. This method has overloaded functions. The method assumes that the key is a parent key and that, therefore, deleting a parent will delete all logical children of that parent record.

Syntax

virtual int DeleteRecord( const char *keyArg, const char 
*featureListBuffer = NULL )

virtual int DeleteRecord( const char *keyArg, const QbFeatureClass 
**features, int numOfFeatures)

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates a fatal error; 1 indicates a non-fatal error

DeleteSample method

This method deletes the named key from the list of samplers.

Syntax

virtual int DeleteSample( const char *key, const char *samplerList )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

DeleteSubPartRecord method

This method deletes only the sub-part of a record, leaving the parent record unaffected.

Syntax

virtual int DeleteSubPartRecord( const char * subKeyArg  )

Parameters

Input

subKeyArg-A pointer to a string that holds the name of the subkey

Output

An integer value: 0 indicates success; -1 indicates a fatal error; 1 indicates a non-fatal error

DeltaSinceDistTableBuild method

This method returns the number of records that have changed since the distance table was built. The distance table stores precomputed key-distance pairs for each image key in the feature data table. It can greatly speed up the QBIC search if you only need to find similar images within the catalog.

Syntax

virtual unsigned long DeltaSinceDistTableBuild( const char 
*featureClassname )

Parameters

Input

featureClassname-A pointer to the feature class name

Output

An unsigned long integer value representing the number of changed records

DeltaSinceIndexBuild method

This method returns the number of records that have changed since the index table was last built.

Syntax

virtual unsigned long DeltaSinceIndexBuild( const char 
*featureClassname )

Parameters

Input

featureClassname-A pointer to the feature class name

Output

An unsigned long integer value representing the number of changed records

DropCatalog method

This method drops (deletes) the catalog from persistent storage. Dropping the catalog removes all feature data tables and feature index tables from the database.

Syntax

virtual int DropCatalog( const char * catalogNameArg )

Parameters

Input

catalogNameArg-A pointer to a string that holds the catalog name

Output

An integer value: 0 indicates success; nonzero indicates failure

DropSampler method

This method drops a sampler table from the database.

Syntax

virtual int DropSampler( const char *samplerName )

Parameters

Input

samplerName-A pointer to the sampler table name

Output

An integer value: 0 indicates success; -1 indicates failure

GetDatabaseClassName method

This method returns the name of the database class. In the default implementation, the name is QbDbmDatabaseClass.

Syntax

virtual const char * GetDatabaseClassName( void )

Parameters

Input

None

Output

A pointer to a string that holds the name of the database class name

GetFeature method

This method gets the feature data of the given key from the catalog and uses that data to initialize the input feature class.

Syntax

virtual int GetFeature( const char *keyArg, QbFeatureClass &feature )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetFeatureDistTableName method

This method uses part of the feature name and the catalog name to construct the name for the table that holds precomputed distance data for the given feature. The name is assigned to the input tableName, a reference to QbStringClass type.

Syntax

int GetFeatureDistTableName( const char *featureName,  QbStringClass 
&tableName )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetFeatureIndexTableName method

This method uses part of the feature name and the catalog name to construct the name for the table that holds feature index data. The name is assigned to tableName of QbStringClass.

Syntax

int GetFeatureIndexTableName( const char *featureName, QbStringClass 
&tableName )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetFeatureSamplerTableName method

This method uses part of the feature name and the catalog name to construct the name for the table that holds sampler feature data. The name is assigned to tableName of QbStringClass.

Syntax

int GetFeatureSamplerTableName( const char *featureName, QbStringClass 
&tableName )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetFeatureTableName method

This method uses part of the feature class name and the catalog name to construct the name for the table that holds feature data. The name is assigned to tableName of QbStringClass.

Syntax

int GetFeatureTableName( const char *featureName, QbStringClass 
&tableName )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetGlobalFeatureInfo method

This method retrieves the global feature information for the given feature class name.

Syntax

virtual int GetGlobalFeatureInfo( const char *featureName, 
QbDatumClass &datum )

Parameters

Input

Output

An integer value: 0 indicates success; nonzero indicates failure

GetParentKey method

This method retrieves the parent key for a given subpart key.

Syntax

virtual int GetParentKey( const char *subpartKey, QbDatumClass 
&parentKey )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetRecord method

This method retrieves the feature data and feature class for a given key from persistent storage.

Syntax

virtual int GetRecord( const char *keyArg, const char 
*featureClassname, QbDatumClass &fdata )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetSampleRecord method

This method retrieves the feature data of the named key and named sampler, and store the data in a datum object.

Syntax

virtual int GetSampleRecord( const char *key, const char *samplerName, 
QbDatumClass &datum )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetSamplerFeature method

This method retrieves the feature data for the named key and the named sampler, and initializes the given feature object with the feature data.

Syntax

virtual int GetSamplerFeature( const char *key, const char 
*samplerName, QbFeatureClass &feature )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetSubPartDefinition method

This method retrieves the subpart definition (the mask) for the subpartKey.

Syntax

virtual int GetSubPartDefinition( const char *subpartKey, 
QbGenericDataClass &subpartData )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

GetSubPartKeys method

This method retrieves all subpart keys for the given parent key.

Syntax

virtual int GetSubPartKeys( const char *parentKey, unsigned int 
&numberOfKeys, QbDatumClass &subpartKeys )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

Itype method

This method returns the catalog interface type.

Syntax

virtual const QbInterfaceType Itype( void )

Parameters

Input

None

Output

CatalogInterfaceType of QbInterfaceType defined in the QbBaseClass. See page 49.

ListFeatureClasses method

This method retrieves all available feature class names for which QBIC can compute feature data.

Syntax

virtual int ListFeatureClasses( QbDatumClass &featureList )

Parameters

Input

featureList-A reference to a QbDatumClass object whose byte string holds the feature class names, which are separated with spaces

Output

An integer value: 0 indicates success; -1 indicates failure

ListSampler method

This method retrieves the current sample names and their associated feature class names.

Syntax

virtual int ListSampler( QbDatumClass &samplerList )

Parameters

Input

samplerList-A reference to a QbDatumClass object to hold the sampler list

Output

An integer value: 0 indicates success; -1 indicates failure

NumberOfIndexRecords method

This method returns the number of image keys in the index table of the given feature in the catalog. The index table is used to enable fast searches.

Syntax

virtual unsigned long NumberOfIndexRecords( const char 
*featureClassname )

Parameters

Input

featureClassname-A pointer to a string that holds the feature class name

Output

An unsigned long integer value representing the number of image keys

NumberOfRecords method

This method returns the number of image keys the named feature class has computed.

Syntax

virtual unsigned long NumberOfRecords( const char *featureClassname )

Parameters

Input

featureClassname-A pointer to the feature class name

Output

An unsigned long integer value representing the number of image keys

NumberOfSamples method

This method returns the number of samples in a given sampler set.

Syntax

virtual unsigned long NumberOfSamples( const char *samplerName )

Parameters

Input

samplerName-A pointer to a string that holds the sampler name

Output

An unsigned long integer that represents the number of samples in the set

OpenCatalog method

This method checks if the database object has been created, and assigns the catalogName with the input catalogNameArg.

Syntax

virtual int OpenCatalog( const char * catalogNameArg )

Parameters

Input

catalogNameArg-A pointer to a string that holds the catalog name

Output

An integer value: 0 indicates success; nonzero indicates failure

ParentKnown method

This method returns True if the parent key is in the catalog. Otherwise, it returns False.

Syntax

virtual Boolean ParentKnown( const char *pKeyArg )

Parameters

Input

pKeyArg-A pointer to a string that holds the parent key

Output

A Boolean value: True if the parent key is in the catalog; False otherwise

PutGlobalFeatureInfo method

This method updates the global information in the feature table with the information stored in a QbDatumClass object.

Syntax

virtual int PutGlobalFeatureInfo( const char *featureName, 
QbDatumClass &datum )

Parameters

Input

Output

An integer value: 0 indicates success; nonzero indicates failure

Type method

This method returns the name of the class.

Syntax

virtual const char * Type( void )

Parameters

Input

None

Output

A pointer to the string QbCatalogClass




Page 10 out of 26 total pages


xzhu@almaden.ibm.com or tedl@almaden.ibm.com
Copyright © 1998, IBM Corporation. All rights reserved.