Inheritance diagram for ColorBoWMatcher:

Collaboration diagram for ColorBoWMatcher:

Public Member Functions
def	__init__ (self, CfgBoW\|str\|None theConfig=None, int\|None n_words=None, DistanceMetric\|None metric=None, float\|None tau=None, **kmeans_kwargs)

def	compare (self, piece_A, piece_B, float\|None tauMatch=None)
	Compare two pieces and, for a match, return their rigid alignment. More...

Histogram	extractFeature (self, piece)
	Encode a puzzle piece's foreground colors as a BoW histogram. More...

"ColorBoWMatcher"	fit (self, list[RGBMatrix] groups, list[str]\|None labels=None)
	Build the color vocabulary and encode all groups as BoW histograms. More...

"ColorBoWMatcher"	fitFromImageSegmented (self, Irgb, Iseg, hasLabs=False)
	Given an image and a segmentation, generate BoW fit. More...

np.ndarray	histogram_image (self, int group_idx, int width=600, int height=200)

"ColorBoWMatcher"	loader (cls, CfgBoW\|str\|None theConfig=None)
	Build a matcher from a configuration, filename prefix, or defaults. More...

np.ndarray	quantizeImage (self, np.ndarray Irgb, np.ndarray\|None Iseg=None)
	Quantize an RGB image using the learned vocabulary centroids. More...

list[dict]	query (self, RGBMatrix query_group, int\|None top_k=None)

list[dict]	query_histogram (self, Histogram query_hist, int\|None top_k=None)

None	save (self, str fileName)
	Save ColorBoWMatcher state and model to an HDF5 file. More...

None	saveTo (self, h5py.File\|h5py.Group fPtr)
	Save ColorBoWMatcher attributes and configuration to an HDF5 group or file pointer. More...

None	saveToYAML (self, str fileName)
	Save current configuration parameters to a YAML file. More...

float	score (self, piece_A, piece_B)
	Compute BoW color similarity between two puzzle pieces. More...

np.ndarray	vocabulary_as_image (self, int swatch_size=60)

Public Member Functions inherited from MatchSimilar
def	__init__ (self, theParams=CfgSimilar())

def	compare (self, piece_A, piece_B)

Public Member Functions inherited from Matcher
tuple[float, np.ndarray]	estimateAffineMatch (self, piece_A, piece_B)
	Estimate the rigid affine transform that aligns piece A to piece B. More...

"Matcher"	fit (self, groups, list[str]\|None labels=None)
	Given raw data regarding expected element instances, identify model to differentiate them if possible for this matcher type. More...

def	solveMatchedPuzzle (self, puzzle, sol)

Static Public Member Functions
"ColorBoWMatcher"	load (str fileName)
	Load and instantiate a ColorBoWMatcher instance from an HDF5 file. More...

"ColorBoWMatcher"	loadFrom (h5py.File\|h5py.Group fPtr)
	Static factory method to instantiate ColorBoWMatcher from an HDF5 file or group pointer. More...

"ColorBoWMatcher"	loadFromYAML (str fileName)
	Instantiate ColorBoWMatcher from a YAML configuration file. More...

Static Public Member Functions inherited from Matcher
tuple[np.ndarray, np.ndarray]	pcaFrame (piece)
	Estimate a signed PCA frame from a puzzle piece's foreground pixels. More...

Public Attributes
	centroids_
	(n_words, 3) float32 array of discovered color centroids. More...

	group_labels_
	Human-readable labels for each database group. More...

	histograms_
	List of encoded BoW histograms, one per database group. More...

	metric

	n_words

Public Attributes inherited from Matcher
	params

Static Public Attributes
np.ndarray	quantize_image = quantizeImage

Detailed Description

@brief End-to-end Bag-of-Words color matcher.

@details
Encapsulates the full BoW pipeline: vocabulary discovery via K-Means++,
histogram encoding for a database of groups, and ranked retrieval of the
closest matches to a query group.

Typical usage:
@code
matcher = ColorBoWMatcher()
matcher.fit(groups)               # build vocabulary + encode database
results = matcher.query(q_group)  # rank database groups by similarity
@endcode

Constructor & Destructor Documentation

◆ init()

def __init__	(		self,
		CfgBoW \| str \| None	theConfig = `None`,
		int \| None	n_words = `None`,
		DistanceMetric \| None	metric = `None`,
		float \| None	tau = `None`,
		**	kmeans_kwargs
	)

@brief Initialise the matcher with configuration node or parameter settings.

@param[in] theConfig        Configuration instance (CfgBoW), YAML filepath, or None.
@param[in] n_words          Optional override for number of K-Means cluster centroids.
@param[in] metric           Optional override for histogram distance metric.
@param[in] tau              Optional override for similarity threshold.
@param[in] **kmeans_kwargs  Optional extra K-Means parameter overrides (max_iter, epsilon, attempts, random_seed).

Member Function Documentation

◆ compare()

def compare	(		self,
			piece_A,
			piece_B,
		float \| None	tauMatch = `None`
	)

Compare two pieces and, for a match, return their rigid alignment.

Returns: (is_match, rotation_degrees, affine). The rotation and affine transform map piece_A onto piece_B. A failed match returns (False, 0.0, None).

◆ extractFeature()

Histogram extractFeature	(	self,
		piece
	)

Encode a puzzle piece's foreground colors as a BoW histogram.

Parameters

[in] piece Template puzzle piece containing foreground color samples in piece.y.appear.

Returns: An L1-normalized histogram over the fitted color vocabulary.

Exceptions

TypeError	if `piece` is not a Template.
RuntimeError	if no vocabulary has been fitted or loaded.
ValueError	if the piece has no valid RGB appearance samples.

Reimplemented from Matcher.

◆ fit()

"ColorBoWMatcher" fit	(		self,
		list[RGBMatrix]	groups,
		list[str] \| None	labels = `None`
	)

Build the color vocabulary and encode all groups as BoW histograms.

Calls build_vocabulary() on the pooled pixel data from all groups to discover centroids, then calls encode_all() to convert each group into a normalized frequency histogram. Must be called before query().

Parameters

groups	List of (3, N) RGB matrices forming the database.
labels	Optional list of human-readable names, one per group. Auto-generated as "group_0", "group_1", ... if None.

Returns: Self, to allow method chaining (e.g., matcher.fit(groups).query(q)).

Exceptions

ValueError if len(labels) != len(groups).

◆ fitFromImageSegmented()

"ColorBoWMatcher" fitFromImageSegmented	(	self,
		Irgb,
		Iseg,
		hasLabs = `False`
	)

Given an image and a segmentation, generate BoW fit.

Permits fitting based on two images, one with all objects of interest in it as a color image. The next as a segmentation isolating the objects. If should be considered binary in nature, then no labels assumed. If it has labels (each unique value is the label), then snag from Iseg as labels.

Parameters

[in]	Irgb	Source color image.
[in]	Iseg	Binary segmentation of image, or label segmentation.
[in]	hasLabs	Iseg has labels and is interpreted as binary. Default: False.

Reimplemented from Matcher.

◆ histogram_image()

np.ndarray histogram_image	(		self,
		int	group_idx,
		int	width = `600`,
		int	height = `200`
	)

@brief Render a color-coded bar chart of a group's BoW histogram.

@details
Each bar corresponds to one vocabulary word (centroid) and its height is
proportional to the word's frequency in the group.  The fill color of each
bar matches the RGB value of its corresponding centroid, making it easy to
see which colors dominate a group.  The image is returned in BGR format
for direct use with OpenCV.

@param group_idx  Zero-based index of the database group to visualize.
@param width      Width of the output image in pixels. Default 600.
@param height     Height of the output image in pixels. Default 200.

@return (height, width, 3) uint8 BGR bar-chart image.

@throws RuntimeError if fit() has not been called.

◆ load()

"ColorBoWMatcher" load ( str fileName )

static

Load and instantiate a ColorBoWMatcher instance from an HDF5 file.

Parameters

[in] fileName Source HDF5 file path.

Returns: Instantiated ColorBoWMatcher object populated from file.

◆ loader()

"ColorBoWMatcher" loader	(		cls,
		CfgBoW \| str \| None	theConfig = `None`
	)

Build a matcher from a configuration, filename prefix, or defaults.

Parameters

[in] theConfig A CfgBoW instance, a filename prefix (for .h5 or .yaml), or None.

Returns: A ColorBoWMatcher. When both files exist for a string prefix, the persisted HDF5 model is preferred over the YAML configuration.

◆ loadFrom()

"ColorBoWMatcher" loadFrom ( h5py.File | h5py.Group fPtr )

static

Static factory method to instantiate ColorBoWMatcher from an HDF5 file or group pointer.

Parameters

[in] fPtr Opened HDF5 file or group pointer.

Returns: Instantiated ColorBoWMatcher object.

◆ loadFromYAML()

"ColorBoWMatcher" loadFromYAML ( str fileName )

static

Instantiate ColorBoWMatcher from a YAML configuration file.

Parameters

[in] fileName Path to the YAML configuration file.

Returns: ColorBoWMatcher instance initialized with configuration settings from file.

◆ quantizeImage()

np.ndarray quantizeImage	(		self,
		np.ndarray	Irgb,
		np.ndarray \| None	Iseg = `None`
	)

Quantize an RGB image using the learned vocabulary centroids.

Replaces each pixel (or each foreground pixel where Iseg > 0) with the RGB color of its nearest centroid in self.centroids_. Background pixels (where Iseg == 0) are preserved as-is if Iseg is provided.

Parameters

[in]	Irgb	Source RGB color image array.
[in]	Iseg	Optional binary or labeled segmentation mask. Default None.

Returns: Quantized RGB image array of shape matching Irgb with dtype uint8.

Exceptions

RuntimeError if fit() has not been called (self.centroids_ is None).

◆ query()

list[dict] query	(		self,
		RGBMatrix	query_group,
		int \| None	top_k = `None`
	)

@brief Rank all database groups by color similarity to a query group.

@details
Encodes @p query_group into a BoW histogram using the fitted vocabulary,
then computes the configured distance metric against every database
histogram.  Results are returned sorted by ascending distance
(rank 1 = most similar).

@param query_group  (3, N) RGB matrix of the query sample.
@param top_k        If set, return only the top-k closest matches.
                    Returns all database groups if None (default).

@return List of dicts sorted by ascending distance, e.g.:
        [{"rank": 1, "label": "group_2", "distance": 0.031}, ...]

@throws RuntimeError if fit() has not been called.

◆ query_histogram()

list[dict] query_histogram	(		self,
		Histogram	query_hist,
		int \| None	top_k = `None`
	)

@brief Rank database groups by similarity to a pre-computed query histogram.

@details
Identical to query() but accepts an already-encoded histogram directly,
avoiding redundant encoding when the caller has pre-computed it.

@param query_hist  (n_words,) float32 histogram to match against the database.
@param top_k       If set, return only the top-k closest matches.
                   Returns all database groups if None (default).

@return List of dicts sorted by ascending distance:
        [{"rank": 1, "label": "group_2", "distance": 0.031}, ...]

@throws RuntimeError if fit() has not been called.

◆ save()

None save	(		self,
		str	fileName
	)

Save ColorBoWMatcher state and model to an HDF5 file.

Parameters

[in] fileName Target HDF5 file path or filename.

◆ saveTo()

None saveTo	(		self,
		h5py.File \| h5py.Group	fPtr
	)

Save ColorBoWMatcher attributes and configuration to an HDF5 group or file pointer.

Parameters

[in] fPtr Opened HDF5 file or group pointer.

◆ saveToYAML()

None saveToYAML	(		self,
		str	fileName
	)

Save current configuration parameters to a YAML file.

Parameters

[in] fileName Target path for the YAML configuration file.

◆ score()

float score	(	self,
		piece_A,
		piece_B
	)

Compute BoW color similarity between two puzzle pieces.

The configured histogram metric is evaluated as a distance, then normalized to a similarity in [0, 1] so this MatchSimilar-derived matcher retains its higher-is-better score convention.

Parameters

[in]	piece_A	First Template puzzle piece.
[in]	piece_B	Second Template puzzle piece.

Returns: Histogram similarity, where 1.0 denotes identical BoW features.

Reimplemented from Matcher.

◆ vocabulary_as_image()

np.ndarray vocabulary_as_image	(		self,
		int	swatch_size = `60`
	)

@brief Render the discovered color vocabulary as a row of solid-color swatches.

@details
Produces a BGR image of shape (swatch_size, n_words * swatch_size, 3) where
each square block is filled with the RGB color of one centroid.  Useful for
visually inspecting the quality and spread of the discovered vocabulary.

@param swatch_size  Pixel width and height of each color swatch. Default 60.

@return (swatch_size, n_words * swatch_size, 3) uint8 BGR image.

@throws RuntimeError if fit() has not been called.

Member Data Documentation

◆ centroids_

centroids_

(n_words, 3) float32 array of discovered color centroids.

None before fit().

◆ group_labels_

group_labels_

Human-readable labels for each database group.

◆ histograms_

histograms_

List of encoded BoW histograms, one per database group.

◆ metric

metric

◆ n_words

n_words

◆ quantize_image

np.ndarray quantize_image = quantizeImage

static

The documentation for this class was generated from the following file:

/home/mary/python/puzzle_solver/puzzle/pieces/BoW.py

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ compare()

◆ extractFeature()

◆ fit()

◆ fitFromImageSegmented()

◆ histogram_image()

◆ load()

◆ loader()

◆ loadFrom()

◆ loadFromYAML()

◆ quantizeImage()

◆ query()

◆ query_histogram()

◆ save()

◆ saveTo()

◆ saveToYAML()

◆ score()

◆ vocabulary_as_image()

Member Data Documentation

◆ centroids_

◆ group_labels_

◆ histograms_

◆ metric

◆ n_words

◆ quantize_image

◆ init()