.. _relnotes_v0.10.2:

v0.10.2
=======

.. _relnotes_v0.10.2_Upgrade Notes:

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.


.. _relnotes_v0.10.2_New Features:

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.
  
  .. code:: python
  
      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.


.. _relnotes_v0.10.2_Enhancement Notes:

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.


.. _relnotes_v0.10.2_Bug Fixes:

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.