machinevision-toolbox-python 1.0.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

machinevisiontoolbox/BagOfWords.py

@@ -1,13 +1,27 @@
-#!/usr/bin/env python3
+"""
+Visual Bag of Words model for image classification and retrieval.
+"""
 
 from collections import Counter
-from machinevisiontoolbox.ImagePointFeatures import BaseFeature2D
+from typing import Any
+
+import cv2
 import numpy as np
-import cv2 as cv
+
+from machinevisiontoolbox.ImagePointFeatures import BaseFeature2D
+from machinevisiontoolbox import Image
+
 
 # TODO: remove top N% and bottom M% of words by frequency
 class BagOfWords:
-    def __init__(self, images, k=2_000, nstopwords=0, attempts=1, seed=None):
+    def __init__(
+        self,
+        images,
+        k: int = 2_000,
+        nstopwords: int = 0,
+        attempts: int = 1,
+        seed: int | None = None,
+    ) -> None:
         r"""
         Bag of words class
 
@@ -54,7 +68,7 @@ class BagOfWords:
 
         :seealso: :meth:`recall` :meth:`~machinevisiontoolbox.ImagePointFeatures.BaseFeature2D`
             :meth:`~machinevisiontoolbox.ImagePointFeatures.SIFT`
-            `cv2.kmeans <https://docs.opencv.org/master/d5/d38/group__core__cluster.html#ga9a34dc06c6ec9460e90860f15bcd2f88>`_
+            `cv2.kmeans <https://docs.opencv.org/4.x/d5/d38/group__core__cluster.html#ga9a34dc06c6ec9460e90860f15bcd2f88>`_
         """
 
         if images is None:
@@ -80,18 +94,18 @@ class BagOfWords:
         # do the clustering
         # NO IDEA WHAT EPSILON ACTUALLY MEANS, NORM OF THE SHIFT IN CENTROIDS?
         # NO IDEA HOW TO TELL WHAT CRITERIA IT TERMINATES ON
-        criteria = (cv.TERM_CRITERIA_EPS + cv.TERM_CRITERIA_MAX_ITER, 10, 1.0)
+        criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 10, 1.0)
 
         if seed is not None:
-            cv.setRNGSeed(seed)
+            cv2.setRNGSeed(seed)
 
-        ret, labels, centroids = cv.kmeans(
+        ret, labels, centroids = cv2.kmeans(
             data=features._descriptor,
             K=k,
             bestLabels=None,
             criteria=criteria,
             attempts=attempts,
-            flags=cv.KMEANS_RANDOM_CENTERS,
+            flags=cv2.KMEANS_RANDOM_CENTERS,
         )
 
         self._k = k
@@ -122,8 +136,8 @@ class BagOfWords:
 
         N = self.nimages
 
-        # total number of occurences of word i
-        # multiple occurences in the one image count only as one
+        # total number of occurrences of word i
+        # multiple occurrences in the one image count only as one
         ni = (W > 0).sum(axis=1)
         idf = np.log(N / ni)
 
@@ -145,7 +159,7 @@ class BagOfWords:
         self._word_freq_vectors = np.column_stack(M)
         self._idf = idf
 
-    def wwfv(self, i=None):
+    def wwfv(self, i: int | None = None) -> np.ndarray:
         """
         Weighted word frequency vector for image
 
@@ -171,7 +185,7 @@ class BagOfWords:
             return self._word_freq_vectors
 
     @property
-    def nimages(self):
+    def nimages(self) -> int:
         """
         Number of images associated in the bag
 
@@ -181,7 +195,7 @@ class BagOfWords:
         return self._nimages
 
     @property
-    def images(self):
+    def images(self) -> Any:
         """
         Images associated with this bag
 
@@ -193,7 +207,7 @@ class BagOfWords:
         return self._images
 
     @property
-    def k(self):
+    def k(self) -> int:
         """
         Number of words in the visual vocabulary
 
@@ -205,7 +219,7 @@ class BagOfWords:
         return self._k
 
     @property
-    def words(self):
+    def words(self) -> np.ndarray:
         """
         Word labels for every feature
 
@@ -221,7 +235,7 @@ class BagOfWords:
 
     # TODO better name for above
 
-    def word(self, f):
+    def word(self, f: int) -> int:
         """
         Word labels for original feature
 
@@ -233,7 +247,7 @@ class BagOfWords:
         return self._labels[f]
 
     @property
-    def nwords(self):
+    def nwords(self) -> int:
         """
         Number of usable words
 
@@ -247,7 +261,7 @@ class BagOfWords:
         return self._k - self._nstopwords
 
     @property
-    def nstopwords(self):
+    def nstopwords(self) -> int:
         """
         Number of stop words
 
@@ -259,7 +273,7 @@ class BagOfWords:
         return self._nstopwords
 
     @property
-    def firststop(self):
+    def firststop(self) -> int:
         """
         First stop word
 
@@ -269,7 +283,7 @@ class BagOfWords:
         return self.k - self._nstopwords
 
     @property
-    def centroids(self):
+    def centroids(self) -> np.ndarray:
         """
         Word feature centroids
 
@@ -289,15 +303,15 @@ class BagOfWords:
         """
         return self._centroids
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return str(self)
 
-    def __str__(self):
+    def __str__(self) -> str:
         s = f"BagOfWords: {len(self.words)} features from {self.nimages} images"
         s += f", {self.nwords} words, {self.nstopwords} stop words"
         return s
 
-    def _remove_stopwords(self, verbose=True):
+    def _remove_stopwords(self, verbose: bool = True) -> None:
         # BagOfWords.remove_stop Remove stop words
         #
         # B.remove_stop(N) removes the N most frequent words (the stop words)
@@ -346,22 +360,30 @@ class BagOfWords:
         # rearrange the cluster centroids
         self._centroids = self._centroids[map]
 
-    def similarity(self, arg):
+    def similarity(self, query) -> np.ndarray:
         """
-        Compute similarity between bag and query images
+        Compute similarity between bag of words and query
 
-        :param other: bag of words
-        :type other: BagOfWords
-        :return: confusion matrix
+        :param query: bag of words or image features
+        :type query: BagOfWords or ndarray
+        :return: similarity matrix
         :rtype: ndarray(M,N)
 
         The array has rows corresponding to the images in ``self`` and
-        columns corresponding to the images in ``other``.
+        columns corresponding to the queries in ``query``.
+
+        ``query`` can be:
+
+        - a single image, a list of images, or an Image iterator (like VideoFile,
+          ZipArchive etc.) for which the visual words are computed using the same
+          dictionary of visual words as the bag.
+        - a set of image features, in which case the similarity is computed between the
+          bag and the query features, or
 
         :seealso: :meth:`.closest`
         """
-        if isinstance(arg, np.ndarray):
-            wwfv = arg
+        if isinstance(query, np.ndarray):
+            wwfv = query
             sim = np.empty((wwfv.shape[1], self.nimages))
 
             for j, vj in enumerate(wwfv.T):
@@ -373,10 +395,8 @@ class BagOfWords:
                             np.linalg.norm(vi) * np.linalg.norm(vj)
                         )
         else:
-            images = arg
-            if not hasattr(images, "__iter__"):
-                # if not iterable like a FileCollection or VideoFile turn the image
-                # into a list of 1
+            images = query
+            if isinstance(images, Image):
                 images = [images]
 
             # similarity has bag index as column, query index as row
@@ -388,7 +408,7 @@ class BagOfWords:
                 # the elements of matches are:
                 #  queryIdx: new feature index
                 #  trainingIdx: cluster centre index
-                bfm = cv.BFMatcher(cv.NORM_L2, crossCheck=False)
+                bfm = cv2.BFMatcher(normType=cv2.NORM_L2, crossCheck=False)
                 matches = bfm.match(features._descriptor, self._centroids)
                 words = np.array([m.trainIdx for m in matches])
 
@@ -418,13 +438,13 @@ class BagOfWords:
             sim = sim[0, :]
         return sim
 
-    def retrieve(self, images):
+    def retrieve(self, images) -> tuple[int, float]:
 
         S = self.similarity(images).ravel()
         k = np.argmax(S)
         return k, S[k]
 
-    def features(self, word):
+    def features(self, word: int) -> BaseFeature2D:
         """
         Get features corresponding to word
 
@@ -439,7 +459,7 @@ class BagOfWords:
         """
         return self._features[self.words == word]
 
-    def occurrence(self, word):
+    def occurrence(self, word: int) -> int:
         """
         Number of occurrences of specified word
 
@@ -451,7 +471,7 @@ class BagOfWords:
         return np.sum(self.words == word)
 
     @staticmethod
-    def _word_freq_vector(words, maxwords):
+    def _word_freq_vector(words, maxwords: int) -> np.ndarray:
         # create columns of the W
         unique, unique_counts = np.unique(words, return_counts=True)
         # [w,f] = count_unique(words)
@@ -459,7 +479,7 @@ class BagOfWords:
         v[unique] = unique_counts
         return v
 
-    def wordfreq(self):
+    def wordfreq(self) -> tuple[np.ndarray, np.ndarray]:
         """
         Get visual word frequency
 
@@ -476,7 +496,7 @@ class BagOfWords:
         # elements of N are the number of occurrences of that word.
         return np.unique(self.words, return_counts=True)
 
-    def closest(self, S, i):
+    def closest(self, S: np.ndarray, i: int) -> tuple[np.ndarray, np.ndarray]:
         """
         Find closest image
 
@@ -494,7 +514,7 @@ class BagOfWords:
 
         return index, s[index]
 
-    def contains(self, word):
+    def contains(self, word: int) -> np.ndarray:
         """
         Images that contain specified word
 
@@ -508,7 +528,14 @@ class BagOfWords:
         return np.unique(self._image_id[self.words == word])
 
     def exemplars(
-        self, word, images=None, maxperimage=2, columns=10, max=None, width=50, **kwargs
+        self,
+        word: int,
+        images=None,
+        maxperimage: int = 2,
+        columns: int = 10,
+        max: int | None = None,
+        width: int = 50,
+        **kwargs,
     ):
         """
         Composite image containing exemplars of specified word
@@ -554,79 +581,5 @@ class BagOfWords:
 
 
 if __name__ == "__main__":
-
-    import numpy as np
-    import matplotlib.pyplot as plt
-    from machinevisiontoolbox import *
-    import cv2 as cv
-
-    cv.setRNGSeed(0)
-
-    images = ImageCollection("campus/*.png", mono=True)
-
-    features = []
-    for image in images:
-        features += image.SIFT()
-    # sort them in descending order by strength
-    features.sort(by="scale", inplace=True)
-
-    features[:10].table()
-
-    ex = []
-    for i in range(400):
-        ex.append(features[i].support(images))
-
-    Image.Tile(ex, columns=20).disp(plain=True)
-
-    feature = features[108]
-    print(feature)
-
-    bag = BagOfWords(features, 2_000)
-
-    w = bag.word(108)
-    print(w)
-    print(bag.occurrence(w))
-    print(bag.contains(w))
-
-    bag.exemplars(w, images)
-
-    bag = BagOfWords(images, 2_000)
-    print(bag)
-
-    w, f = bag.wordfreq()
-    print(len(w))
-
-    bag = BagOfWords(images, 2_000, nstopwords=50)
-    print(bag)
-
-    print(bag.wwfv(0).shape)
-    print(bag.wwfv().shape)
-
-    print(bag.similarity(bag.wwfv(3)))
-    print(bag.similarity(images[:5]))
-
-    sim_8 = bag.similarity(images[8]).ravel()
-    print(sim_8)
-    k = np.argsort(-sim_8)
-    print(np.c_[sim_8[k], k])
-
-    ss = []
-    for i in range(4):
-        ss.append(images[k[i]])
-    Image.Tile(ss, columns=2).disp()
-
-    holdout = ImageCollection("campus/holdout/*.png", mono=True)
-
-    sim = bag.similarity(holdout)
-
-    sim_2 = bag.similarity(holdout[2]).ravel()
-    print(sim_2)
-    k = np.argsort(-sim_2)
-    print(np.c_[sim_2[k], k])
-
-    ss = [holdout[2]]
-    for i in range(3):
-        ss.append(images[k[i]])
-    Image.Tile(ss, columns=2).disp()
-
-    Image(sim).disp(block=True)
+    # No dedicated test file for this module.
+    pass