Classes
struct	DistanceFactory

struct	Node
	Tree node. More...

Public Types
enum	LNorm { L1, L2 }
	L-norms for normalization.

enum	WeightingType { TF_IDF, TF, IDF, BINARY }
	Weighting type.

enum	ScoringType { L1_NORM, L2_NORM, CHI_SQUARE, KL, BHATTACHARYYA, DOT_PRODUCT }
	Scoring type.

Public Member Functions
	Vocabulary (int k=10, int L=5, WeightingType weighting=TF_IDF, ScoringType scoring=L1_NORM)
	Initiates an empty vocabulary. More...

	Vocabulary (const std::string &filename)
	Creates the vocabulary by loading a file. More...

bool	save (const std::string &filename, bool binary_compressed=false) const
	Saves the vocabulary into a file. More...

bool	load (const std::string &filename)
	Loads the vocabulary from a file created with save. More...

bool	load (std::istream &ifs)

virtual unsigned int	size () const
	Returns the number of nodes in the vocabulary. More...

virtual bool	empty () const
	Returns whether the vocabulary is empty (i.e. More...

void	clear ()
	Clears the vocabulary object. More...

void	transform (const std::vector< TinyMat > &features, BowVector &v) const

virtual void	transform (const TinyMat &features, BowVector &v) const
	Transforms a set of descriptores into a bow vector. More...

virtual void	transform (const std::vector< TinyMat > &features, BowVector &v, FeatureVector &fv, int levelsup=0) const
	Transform a set of descriptors into a bow vector and a feature vector. More...

virtual void	transform (const TinyMat &features, BowVector &v, FeatureVector &fv, int levelsup=0) const
	Transform a set of descriptors into a bow vector and a feature vector. More...

virtual WordId	transform (const TinyMat &feature) const
	Transforms a single feature into a word (without weight) More...

double	score (const BowVector &a, const BowVector &b) const
	Returns the score of two vectors. More...

virtual NodeId	getParentNode (WordId wid, int levelsup) const
	Returns the id of the node that is "levelsup" levels from the word given. More...

void	getWordsFromNode (NodeId nid, std::vector< WordId > &words) const
	Returns the ids of all the words that are under the given node id, by traversing any of the branches that goes down from the node. More...

int	getBranchingFactor () const
	Returns the branching factor of the tree (k) More...

int	getDepthLevels () const
	Returns the depth levels of the tree (L) More...

float	getEffectiveLevels () const
	Returns the real depth levels of the tree on average. More...

virtual TinyMat	getWord (WordId wid) const
	Returns the descriptor of a word. More...

virtual WordValue	getWordWeight (WordId wid) const
	Returns the weight of a word. More...

WeightingType	getWeightingType () const
	Returns the weighting method. More...

ScoringType	getScoringType () const
	Returns the scoring method. More...

void	setWeightingType (WeightingType type)
	Changes the weighting method. More...

void	setScoringType (ScoringType type)
	Changes the scoring method. More...

virtual int	stopWords (double minWeight)
	Stops those words whose weight is below minWeight. More...

int	getDescritorSize () const
	Returns the size of the descriptor employed. More...

int	getDescritorType () const
	Returns the type of the descriptor employed normally(8U_C1, 32F_C1)

float	distance (const TinyMat &a, const TinyMat &b) const
	Calculates the distance between two descriptors. More...

void	createScoringObject ()
	Creates an instance of the scoring object accoring to m_scoring.

virtual void	transform (const TinyMat &feature, WordId &id, WordValue &weight, NodeId *nid, int levelsup=0) const
	Returns the word id associated to a feature. More...

virtual void	transform (const TinyMat &feature, WordId &id, WordValue &weight) const
	Returns the word id associated to a feature. More...

void	HKmeansStep (NodeId parent_id, const std::vector< TinyMat > &descriptors, int current_level)
	Creates a level in the tree, under the parent, by running kmeans with a descriptor set, and recursively creates the subsequent levels too. More...

Static Public Member Functions
static std::shared_ptr< Vocabulary >	create (const std::vector< TinyMat > &training_features, int k=10, int L=5, WeightingType weighting=TF_IDF, ScoringType scoring=L1_NORM)
	Creates a vocabulary from the training features, setting the branching factor nad the depth levels of the tree, and the weighting and scoring schemes.

static void	meanValue (const std::vector< TinyMat > &descriptors, TinyMat &mean)
	Calculates the mean value of a set of descriptors. More...

static void	addWeight (BowVector &bow, WordId id, WordValue v)
	Returns the word id associated to a feature. More...

static void	addIfNotExist (BowVector &bow, WordId id, WordValue v)

static void	normalize (BowVector &bow, LNorm norm_type)

static void	addFeature (FeatureVector &fvec, NodeId id, unsigned int i_feature)

Public Attributes
int	m_k
	Branching factor.

int	m_L
	Depth levels.

WeightingType	m_weighting
	Weighting method.

ScoringType	m_scoring
	Scoring method.

std::shared_ptr< GeneralScoring >	m_scoring_object
	Object for computing scores.

std::vector< Node >	m_nodes
	Tree nodes.

TinyMat	m_nodeDescriptors

Constructor & Destructor Documentation

Vocabulary	(	int	k = `10`,
		int	L = `5`,
		WeightingType	weighting = `TF_IDF`,
		ScoringType	scoring = `L1_NORM`
	)

Initiates an empty vocabulary.

Parameters

k	branching factor
L	depth levels
weighting	weighting type
scoring	scoring type

References Vocabulary::createScoringObject().

Referenced by Vocabulary::create(), and GeneralScoring::~GeneralScoring().

Vocabulary ( const std::string & filename )

Creates the vocabulary by loading a file.

Parameters

filename

References Vocabulary::load().

Member Function Documentation

bool save	(	const std::string &	filename,
		bool	binary_compressed = `false`
	)		const

Saves the vocabulary into a file.

If filename extension contains .yml, opencv YALM format is used. Otherwise, binary format is employed

Parameters

filename

References Vocabulary::createScoringObject(), Vocabulary::getDescritorSize(), Vocabulary::getDescritorType(), Vocabulary::load(), Vocabulary::m_k, Vocabulary::m_L, Vocabulary::m_nodes, Vocabulary::m_scoring, Vocabulary::m_weighting, and Vocabulary::Node::Node().

bool load ( const std::string & filename )

Loads the vocabulary from a file created with save.

Parameters

filename.

References Vocabulary::getBranchingFactor(), Vocabulary::getDepthLevels(), Vocabulary::getScoringType(), Vocabulary::getWeightingType(), and Vocabulary::size().

Referenced by Vocabulary::save(), and Vocabulary::Vocabulary().

virtual unsigned int size ( ) const

virtual

Returns the number of nodes in the vocabulary.

Returns: number of nodes

References Vocabulary::m_nodes.

Referenced by Vocabulary::HKmeansStep(), and Vocabulary::load().

virtual bool empty ( ) const

virtual

Returns whether the vocabulary is empty (i.e.

it has not been trained)

Returns: true iff the vocabulary is empty

References Vocabulary::clear(), Vocabulary::getParentNode(), Vocabulary::getWordsFromNode(), Vocabulary::m_nodes, and Vocabulary::score().

Referenced by Vocabulary::transform().

void clear ( )

Clears the vocabulary object.

Vocabulary::clear.

References Vocabulary::m_nodes, and Vocabulary::m_scoring_object.

Referenced by Vocabulary::empty().

void transform	(	const TinyMat &	features,
		BowVector &	v
	)		const

virtual

Transforms a set of descriptores into a bow vector.

Parameters

features,one	per row
v	(out) bow vector of weighted words

References Vocabulary::addWeight(), Vocabulary::empty(), Vocabulary::m_scoring_object, and Vocabulary::m_weighting.

void transform	(	const std::vector< TinyMat > &	features,
		BowVector &	v,
		FeatureVector &	fv,
		int	levelsup = `0`
	)		const

virtual

Transform a set of descriptors into a bow vector and a feature vector.

Parameters

features
v	(out) bow vector
fv	(out) feature vector of nodes and feature indexes
levelsup	levels to go up the vocabulary tree to get the node index

References Vocabulary::addWeight(), Vocabulary::empty(), Vocabulary::m_scoring_object, and Vocabulary::m_weighting.

void transform	(	const TinyMat &	features,
		BowVector &	v,
		FeatureVector &	fv,
		int	levelsup = `0`
	)		const

virtual

Transform a set of descriptors into a bow vector and a feature vector.

Parameters

features
v	(out) bow vector
fv	(out) feature vector of nodes and feature indexes
levelsup	levels to go up the vocabulary tree to get the node index

References Vocabulary::addWeight(), Vocabulary::empty(), Vocabulary::m_scoring_object, and Vocabulary::m_weighting.

WordId transform ( const TinyMat & feature ) const

virtual

Transforms a single feature into a word (without weight)

Parameters

feature

Returns: word id

References Vocabulary::empty().

double score	(	const BowVector &	a,
		const BowVector &	b
	)		const

Returns the score of two vectors.

Parameters

a	vector
b	vector

Returns: score between vectors

Note: the vectors must be already sorted and normalized if necessary

Referenced by Vocabulary::empty(), and GeneralScoring::~GeneralScoring().

NodeId getParentNode	(	WordId	wid,
		int	levelsup
	)		const

virtual

Returns the id of the node that is "levelsup" levels from the word given.

Parameters

wid	word id
levelsup	0..L

Returns: node id. if levelsup is 0, returns the node id associated to the word id

References Vocabulary::getWordsFromNode(), and Vocabulary::m_k.

Referenced by Vocabulary::empty(), and Vocabulary::transform().

void getWordsFromNode	(	NodeId	nid,
		std::vector< WordId > &	words
	)		const

Returns the ids of all the words that are under the given node id, by traversing any of the branches that goes down from the node.

Parameters

nid	starting node id
words	ids of words

References Vocabulary::Node::isLeaf(), Vocabulary::m_k, and Vocabulary::m_nodes.

Referenced by Vocabulary::empty(), and Vocabulary::getParentNode().

int getBranchingFactor ( ) const

Returns the branching factor of the tree (k)

Returns: k

References Vocabulary::m_k.

Referenced by Vocabulary::load().

int getDepthLevels ( ) const

Returns the depth levels of the tree (L)

Returns: L

References Vocabulary::getEffectiveLevels(), Vocabulary::getWord(), Vocabulary::getWordWeight(), and Vocabulary::m_L.

Referenced by Vocabulary::load().

float getEffectiveLevels ( ) const

Returns the real depth levels of the tree on average.

Returns: average of depth levels of leaves

Referenced by Vocabulary::getDepthLevels().

TinyMat getWord ( WordId wid ) const

virtual

Returns the descriptor of a word.

Parameters

wid word id

Returns: descriptor

Referenced by Vocabulary::getDepthLevels().

WordValue getWordWeight ( WordId wid ) const

virtual

Returns the weight of a word.

Parameters

wid word id

Returns: weight

References Vocabulary::m_nodes.

Referenced by Vocabulary::getDepthLevels().

WeightingType getWeightingType ( ) const

Returns the weighting method.

Returns: weighting method

References Vocabulary::m_weighting.

Referenced by Vocabulary::load().

ScoringType getScoringType ( ) const

Returns the scoring method.

Returns: scoring method

References Vocabulary::m_scoring, Vocabulary::setScoringType(), Vocabulary::setWeightingType(), and Vocabulary::stopWords().

Referenced by Vocabulary::load().

void setWeightingType ( WeightingType type )

Changes the weighting method.

Parameters

type	new weighting type

References Vocabulary::m_weighting.

Referenced by Vocabulary::getScoringType().

void setScoringType ( ScoringType type )

Changes the scoring method.

Parameters

type	new scoring type

References Vocabulary::createScoringObject(), and Vocabulary::m_scoring.

Referenced by Vocabulary::getScoringType().

int stopWords ( double minWeight )

virtual

Stops those words whose weight is below minWeight.

Words are stopped by setting their weight to 0. There are not returned later when transforming image features into vectors. Note that when using IDF or TF_IDF, the weight is the idf part, which is equivalent to -log(f), where f is the frequency of the word (f = Ni/N, Ni: number of training images where the word is present, N: number of training images). Note that the old weight is forgotten, and subsequent calls to this function with a lower minWeight have no effect.

Returns: number of words stopped now

References Vocabulary::m_nodes.

Referenced by Vocabulary::getScoringType().

int getDescritorSize ( ) const

Returns the size of the descriptor employed.

If the Vocabulary is empty, returns -1

Referenced by Vocabulary::save().

void meanValue	(	const std::vector< TinyMat > &	descriptors,
		TinyMat &	mean
	)

static

Calculates the mean value of a set of descriptors.

Parameters

descriptors
mean	mean descriptor

Referenced by Vocabulary::getDescritorType(), and Vocabulary::HKmeansStep().

float distance	(	const TinyMat &	a,
		const TinyMat &	b
	)		const

Calculates the distance between two descriptors.

Parameters

a
b

Returns: distance

Referenced by Vocabulary::getDescritorType(), Vocabulary::HKmeansStep(), and Vocabulary::transform().

void transform	(	const TinyMat &	feature,
		WordId &	id,
		WordValue &	weight,
		NodeId *	nid,
		int	levelsup = `0`
	)		const

virtual

Returns the word id associated to a feature.

Parameters

feature
id	(out) word id
weight	(out) word weight
nid	(out) if given, id of the node "levelsup" levels up
levelsup

References Vocabulary::Node::isLeaf(), Vocabulary::m_k, Vocabulary::m_L, and Vocabulary::m_nodes.

void transform	(	const TinyMat &	feature,
		WordId &	id,
		WordValue &	weight
	)		const

virtual

Returns the word id associated to a feature.

Parameters

feature
id	(out) word id
weight	(out) word weight
nid	(out) if given, id of the node "levelsup" levels up
levelsup

References Vocabulary::distance(), Vocabulary::getParentNode(), Vocabulary::Node::isLeaf(), Vocabulary::m_k, and Vocabulary::m_nodes.

static void addWeight	(	BowVector &	bow,
		WordId	id,
		WordValue	v
	)

static

Returns the word id associated to a feature.

Parameters

feature
id	(out) word id

References Vocabulary::HKmeansStep().

Referenced by Vocabulary::transform().

void HKmeansStep	(	NodeId	parent_id,
		const std::vector< TinyMat > &	descriptors,
		int	current_level
	)

Creates a level in the tree, under the parent, by running kmeans with a descriptor set, and recursively creates the subsequent levels too.

Parameters

parent_id	id of parent node
descriptors	descriptors to run the kmeans on
current_level	current level in the tree

References Vocabulary::distance(), Vocabulary::m_k, Vocabulary::m_L, Vocabulary::m_nodes, Vocabulary::meanValue(), and Vocabulary::size().

Referenced by Vocabulary::addWeight().

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Constructor & Destructor Documentation

Member Function Documentation