v0.10.2

Upgrade Notes

• ExternalSearchIndex is removed, and with it the support for indexes of libraries other than FAISS. Pass the FAISS index itself as search_index to InMemoryImageEmbeddingStore and to its load_from_disk.

• A store on a FAISS index is named after the index type, such as faiss.IndexHNSWFlat, and takes its space from the index metric. index_params and FAISS metrics other than METRIC_L2 and METRIC_INNER_PRODUCT raise ValueError.

• A store on a FAISS inner-product index now scores by 1 - inner_product like the built-in "ip" space, so lower is more similar. 1 - candidate.score gives the inner product back.

New Features

• KReciprocalReranker accepts a store on a FAISS index.

• Added to_single_image helper in pyvisim.utils.image_utils, which converts one image into the canonical uint8 array described by dims and value_range. An example is shown below.

  import numpy as np
  
  from pyvisim.utils.image_utils import to_single_image
  
  rng = np.random.default_rng(0)
  
  # A uint8 image in the NumPy layout (height, width, channels), values in [0, 255]
  image_hwc = rng.integers(0, 256, size=(64, 80, 3), dtype=np.uint8)
  
  # The same pixels as a float image in the PyTorch layout
  # (channels, height, width), values in [0, 1]
  image_chw = image_hwc.transpose(2, 0, 1) / 255.0
  
  # dims and value_range describe each input, and both come back as a
  # uint8 array of shape (64, 80, 3) with values in [0, 255]
  canonical_hwc = to_single_image(image_hwc, dims="HWC")
  canonical_chw = to_single_image(image_chw, dims="CHW", value_range=(0.0, 1.0))
  
  print(canonical_chw.shape, canonical_chw.dtype)  # (64, 80, 3) uint8
  print(np.array_equal(canonical_hwc, canonical_chw))  # True
  

• Added set_pca_from_sklearn to VLADEmbedder and FisherVectorEmbedder. It replaces the embedder’s PCA with one created from a sklearn.decomposition.PCA estimator, fitted or not.

Enhancement Notes

• The new tutorial Custom Feature Extractor with RootSIFT under the classical methods implements RootSIFT on top of the SIFT of OpenCV, which is the recommended way to use RootSIFT since it is much faster than the built-in RootSIFT.

• The new tutorial Introduction to VLAD and Fisher Vectors under the classical methods trains both embedders on RootSIFT features, once with learn and once from fitted scikit-learn estimators, which have more training options.

Bug Fixes

• A store saved on an ExternalSearchIndex named "hnsw" was loaded onto a newly built HNSW graph without a warning. Index names now come from the index type, so they cannot collide with a built-in index.

• A store saved on a FAISS index and loaded without it falls back to a brute-force scan in the metric of that index, and no longer in "cosine".

• VLADEmbedder and FisherVectorEmbedder now raise RuntimeError for a fitted PCA whose dimensions do not match the feature extractor or the clustering model, like their other dimension checks.

• learn(dim_reduction_factor=...) now emits a FutureWarning when it replaces a PCA the embedder already has.