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:
Sometimes feature tables in the same catalog can become inconsistent (for example, one feature table might have more keys than another). This inconsistency can occur if the program was stopped in the middle of feature computation, or if a feature computation failed and exited prematurely. In this case, use the incrementRecord enumerated type to process the last few images to bring the tables to a consistent state.
The following methods are described in this chapter:
You can see coding examples in Appendix C, "Sample Code" on page 185. Other programs are located in the qbic/QbicApi
directory.
This is the constructor for the class.
QbCatalogClass( const QbConnectClass &connect )
connect-A reference to the QbConnectClass instance
This is the destructor for the class.
virtual ~QbCatalogClass( void )
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.
virtual int AddFeatureClass( const char *featureClassName )
featureClassName-A pointer to a string that holds the feature class name
An integer value: 0 indicates success; nonzero indicates failure
This method adds an object to the catalog. This method has overloaded functions:
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)
An integer value: 0 indicates success; -1 indicates a fatal error; 1 indicates a non-fatal error
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.
virtual int AddSample( const char *keyArg, const char *samplerList, const QbGenericDataClass &data, const QbParameterClass *parms, const UpdateType update = insertRecord )
An integer value: 0 indicates success; -1 indicates failure
This method closes the catalog.
virtual int CloseCatalog( void )
An integer value: 0 indicates success; nonzero indicates failure
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.
virtual int CreateCatalog( const char * catalogNameArg )
catalogNameArg-A pointer to a string that holds the catalog name
An integer value: 0 indicates success; -1 indicates failure
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.
vitrual int CreateSampler( const char *samplerName, const char *featureclassName)
An integer value: 0 indicates success; -1 indicates failure
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.
virtual int DefineSubPart( const char *parentKey, const char *subpartKey, const QbGenericDataClass &subpart )
An integer value: 0 indicates success; nonzero indicates failure
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.
virtual int DeleteFeatureClass( const char * featureClassName )
featureClassName-A pointer to a string that holds the feature class name
An integer value: 0 indicates success; nonzero indicates failure
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.
virtual int DeleteRecord( const char *keyArg, const char *featureListBuffer = NULL ) virtual int DeleteRecord( const char *keyArg, const QbFeatureClass **features, int numOfFeatures)
An integer value: 0 indicates success; -1 indicates a fatal error; 1 indicates a non-fatal error
This method deletes the named key from the list of samplers.
virtual int DeleteSample( const char *key, const char *samplerList )
An integer value: 0 indicates success; -1 indicates failure
This method deletes only the sub-part of a record, leaving the parent record unaffected.
virtual int DeleteSubPartRecord( const char * subKeyArg )
subKeyArg-A pointer to a string that holds the name of the subkey
An integer value: 0 indicates success; -1 indicates a fatal error; 1 indicates a non-fatal error
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.
virtual unsigned long DeltaSinceDistTableBuild( const char *featureClassname )
featureClassname-A pointer to the feature class name
An unsigned long integer value representing the number of changed records
This method returns the number of records that have changed since the index table was last built.
virtual unsigned long DeltaSinceIndexBuild( const char *featureClassname )
featureClassname-A pointer to the feature class name
An unsigned long integer value representing the number of changed records
This method drops (deletes) the catalog from persistent storage. Dropping the catalog removes all feature data tables and feature index tables from the database.
virtual int DropCatalog( const char * catalogNameArg )
catalogNameArg-A pointer to a string that holds the catalog name
An integer value: 0 indicates success; nonzero indicates failure
This method drops a sampler table from the database.
virtual int DropSampler( const char *samplerName )
samplerName-A pointer to the sampler table name
An integer value: 0 indicates success; -1 indicates failure
This method returns the name of the database class. In the default implementation, the name is QbDbmDatabaseClass.
virtual const char * GetDatabaseClassName( void )
A pointer to a string that holds the name of the database class name
This method gets the feature data of the given key from the catalog and uses that data to initialize the input feature class.
virtual int GetFeature( const char *keyArg, QbFeatureClass &feature )
An integer value: 0 indicates success; -1 indicates failure
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.
int GetFeatureDistTableName( const char *featureName, QbStringClass &tableName )
An integer value: 0 indicates success; -1 indicates failure
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.
int GetFeatureIndexTableName( const char *featureName, QbStringClass &tableName )
An integer value: 0 indicates success; -1 indicates failure
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.
int GetFeatureSamplerTableName( const char *featureName, QbStringClass &tableName )
An integer value: 0 indicates success; -1 indicates failure
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.
int GetFeatureTableName( const char *featureName, QbStringClass &tableName )
An integer value: 0 indicates success; -1 indicates failure
This method retrieves the global feature information for the given feature class name.
virtual int GetGlobalFeatureInfo( const char *featureName, QbDatumClass &datum )
An integer value: 0 indicates success; nonzero indicates failure
This method retrieves the parent key for a given subpart key.
virtual int GetParentKey( const char *subpartKey, QbDatumClass &parentKey )
An integer value: 0 indicates success; -1 indicates failure
This method retrieves the feature data and feature class for a given key from persistent storage.
virtual int GetRecord( const char *keyArg, const char *featureClassname, QbDatumClass &fdata )
An integer value: 0 indicates success; -1 indicates failure
This method retrieves the feature data of the named key and named sampler, and store the data in a datum object.
virtual int GetSampleRecord( const char *key, const char *samplerName, QbDatumClass &datum )
An integer value: 0 indicates success; -1 indicates failure
This method retrieves the feature data for the named key and the named sampler, and initializes the given feature object with the feature data.
virtual int GetSamplerFeature( const char *key, const char *samplerName, QbFeatureClass &feature )
An integer value: 0 indicates success; -1 indicates failure
This method retrieves the subpart definition (the mask) for the subpartKey.
virtual int GetSubPartDefinition( const char *subpartKey, QbGenericDataClass &subpartData )
An integer value: 0 indicates success; -1 indicates failure
This method retrieves all subpart keys for the given parent key.
virtual int GetSubPartKeys( const char *parentKey, unsigned int &numberOfKeys, QbDatumClass &subpartKeys )
An integer value: 0 indicates success; -1 indicates failure
This method returns the catalog interface type.
virtual const QbInterfaceType Itype( void )
CatalogInterfaceType of QbInterfaceType defined in the QbBaseClass. See page 49.
This method retrieves all available feature class names for which QBIC can compute feature data.
virtual int ListFeatureClasses( QbDatumClass &featureList )
featureList-A reference to a QbDatumClass object whose byte string holds the feature class names, which are separated with spaces
An integer value: 0 indicates success; -1 indicates failure
This method retrieves the current sample names and their associated feature class names.
virtual int ListSampler( QbDatumClass &samplerList )
samplerList-A reference to a QbDatumClass object to hold the sampler list
An integer value: 0 indicates success; -1 indicates failure
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.
virtual unsigned long NumberOfIndexRecords( const char *featureClassname )
featureClassname-A pointer to a string that holds the feature class name
An unsigned long integer value representing the number of image keys
This method returns the number of image keys the named feature class has computed.
virtual unsigned long NumberOfRecords( const char *featureClassname )
featureClassname-A pointer to the feature class name
An unsigned long integer value representing the number of image keys
This method returns the number of samples in a given sampler set.
virtual unsigned long NumberOfSamples( const char *samplerName )
samplerName-A pointer to a string that holds the sampler name
An unsigned long integer that represents the number of samples in the set
This method checks if the database object has been created, and assigns the catalogName with the input catalogNameArg.
virtual int OpenCatalog( const char * catalogNameArg )
catalogNameArg-A pointer to a string that holds the catalog name
An integer value: 0 indicates success; nonzero indicates failure
This method returns True if the parent key is in the catalog. Otherwise, it returns False.
virtual Boolean ParentKnown( const char *pKeyArg )
pKeyArg-A pointer to a string that holds the parent key
A Boolean value: True if the parent key is in the catalog; False otherwise
This method updates the global information in the feature table with the information stored in a QbDatumClass object.
virtual int PutGlobalFeatureInfo( const char *featureName, QbDatumClass &datum )
An integer value: 0 indicates success; nonzero indicates failure
This method returns the name of the class.
virtual const char * Type( void )
A pointer to the string QbCatalogClass