QbFeatureClass is derived from the QbBaseClass and is used to represent a feature. The methods ComputeFeatures, Distance, ExecutionCostForDistanceFunction, FilterResult, and ExecutationCostForFilterFunction are the required virtual functions.
The ComputeFeature method takes two arguments, a pointer to a QbGenericDataClass object and a pointer to a QbParameterClass object that contains the query specification.
The Distance method returns the distance between the current instance of a feature class and another instance of the feature class.
The FilterResult method arguments are a connected database, an optional key sublist of this database, the number of results requested by the query, the name of the catalog, and the query parameters. This method can return a ranked or an unranked list. If the list is not ranked, the returned distances do not reflect final query ordering, and the calling method or function should use the Distance method to determine the final ordering.
The GenericDataClassname and ParameterClassname methods return the name of the QbGenericDataClass and QbParameterClass instances needed by this feature.
The GetDefaultParameters method returns a pointer to the default parameters for this feature class. This default parameter data is normally implemented as class static member data. The return type is const so that the caller cannot delete the result. To change the default parameters, make a copy of the default parameters using the assignment operator before changing the values.
The UpdateGlobalFeatureInfo method allows the implementor of a feature to keep various statistics, such as sum and sum of squares that are needed for distance computations. These statistics allow implementation of such algorithms as Mahalanobis distance. The base implementation of this method implements a simple counter to count the number of records in a database. You can use the parameter information to determine when to use global information, using the ParameterUpdateFromGlobalInfo method.
Currently, only the Texture feature uses a variance-weighted distance. In this case, the sum and sum of squares are stored as the global information for the feature. During a query, a parameter value of Vxx
(where V
stands for variance and xx
is an optional numerical weight) implements an inverse variance weighting. That is, a given feature is weighted by a coefficient given as one divided by the variance of that feature value for all data in the collection times the weight xx
. For example, V5 means (5/variance) weighting. During a query, the global information is read from the catalog and used to update the weights that will be used in the distance computation.
QBIC has no knowledge of the type of weighting or how the distance will be computed. This is left entirely up to the feature designer. |
Features must be stored in a database. This is accomplished using the methods ToByteString and FromByteString. These methods convert the contents of the class into a byte string and set the contents of the class from a byte string. The argument for both of these methods is a reference to a QbDatumClass instance.
A utility method called FeatureSize returns an unsigned long that describes the length of the feature vector needed by ToByteString.
This class contains the public enumerated variable GlobalFeatureInfoEnum:
This chapter describes the following methods:
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.
QbFeatureClass( void )
This is the destructor for the class.
virtual ~QbFeatureClass( void )
This method converts generic data to features. Given generic data and parameters, this method computes feature data based on the input that is pointed to by the QbGenericDataClass object. The QbGenericDataClass object can contain either raw data or a key to retrieve the data from a database.
virtual int ComputeFeatures( const QbGenericDataClass *data, const QbParameterClass *parms )
An integer value: 0 indicates success; nonzero indicates failure
This method computes the distance between this feature instance (typically the query feature) and another instance of the same feature using the parameters passed in the second argument, parms. The abortDistance argument can be used to speed up distance computation. If, in the middle of the distance computation, you are certain that the final distance exceeds the abortDistance, you can stop the computation and return it with the abortDistance value.
virtual fastfloat Distance( const QbFeatureClass *feature, const QbParameterClass *parms, const float abortDistance )
A fastfloat (double) value between 0 and 1; -1 indicates an error
This method provides a measure of the complexity of the distance evaluation. Such a measure can be used to choose the optimized parameter for running a query. The default implementation simply returns -1.0.
virtual float ExecutionCostForDistanceFunction( const QbFeatureClass *feature, const QbParameterClass *parms, const float abortDistance )
A float value between 0 and 1; -1 indicates an error
This method provides a measure of the complexity of the FilterResult method. The default implementation simply returns -1.0.
virtual float ExecutionCostForFilterFunction( QbDatabaseClass &database, const QbKeyDatabaseClass *list, const unsigned long queryResultsRequested, const char *catalogName, const QbParameterClass *parms )
A float value between 0 and 1; -1 indicates an error
This method returns the number of bytes of the feature vector.
virtual unsigned long FeatureSize( void )
An unsigned long integer value that represents the number of bytes in the feature vector
This method produces a restriction list, which can be either ranked or unranked. The default result is -1, which indicates that no restriction list is produced.
virtual int FilterResult( QbDatabaseClass &database, const QbKeyDatabaseClass *list, const unsigned long queryResultsRequested, const char *catalogName, const QbParameterClass *parms, QbKeyDatabaseClass &results )
An integer value; 0 indicates that a list was produced; -1 indicates no list was produced
This method decodes a byte string from the given data, and initializes an object with that decoded data.
virtual int FromByteString( const QbDatumClass &data )
data-A reference to a QbDatumClass object that holds the data to initialize the feature class object
An integer value: 0 indicates success; -1 indicates failure
This method returns the QbGenericDataClassname, the QbGenericImageDataClassname, or whatever the current feature class expects in order to compute feature data.
virtual const char * GenericDataClassname( void )
A pointer to a string that contains the QbGenericDataClass or its derived class name
This method returns the default parameters for the feature class.
virtual const QbParameterClass * GetDefaultParameters( void )
A pointer to a QbParameterClass object that contains the default parameters
This method returns the dimension of the feature vector.
virtual const unsigned long GetDimension( void )
An unsigned long integer that represent the dimension of the feature vector
This method returns whether the object is a subpart feature.
virtual Boolean IsSubPartFeature( void )
A Boolean value. True if it is a subpart; False if it is not
This method returns the name of the QbParameterClass object that this feature supports.
virtual const char * ParameterClassname( void )
A pointer to a string that contains the parameter class name
This method updates the feature's parameters using the global information for the feature. In the QbTextureFeatureClass, for example, the distance calculation requires the global statistics of the variance of the texture feature vector in the given catalog in the database. These global statistics can be stored in the global information for the catalog and can be retrieved. When you have the global information, the ParameterUpdateGlobalInfo method can update the parameter class, which can be subsequently used as the input parameter for feature distance computations.
virtual int ParameterUpdateFromGlobalInfo( QbParameterClass &parms, const QbDatumClass &globalInfo )
An integer value: 0 indicates success; -1 indicates failure
This method converts the feature data into a formatted ASCII string and assigns it to the byte string of the input string, a reference to a QbDatumClass object.
virtual int ToAsciiString( C &string )
string-A reference to a QbDatumClass object that stores the feature data
An integer value: 0 indicates success; -1 indicates failure
This method encodes feature information to a byte string which is assigned to data.
virtual int ToByteString( QbDatumClass &data )
data-A reference to a QbDatumClass object to hold the feature data
An integer value: 0 indicates success; -1 indicates failure
This method updates the global information in a QbDatumClass object based on the type (a public enumerated type defined within the class).
virtual int UpdateGlobalFeatureInfo( QbDatumClass &datum, const GlobalFeatureInfoEnum gType)
An integer value: 0 indicates success; -1 indicates failure