RootSIFT

RootSIFT is SIFT with Hellinger-kernel normalization. It is the default feature extractor for both VLADEmbedder and FisherVectorEmbedder.

After computing standard SIFT descriptors, each descriptor is:

  1. L1-normalized (divided by the sum of its elements, plus a small epsilon), then

  2. element-wise square-rooted.

Comparing these transformed vectors with the Euclidean/dot-product operations the embedders use is equivalent to comparing the original descriptors under the Hellinger kernel.

Notes

  • output_dim is 128, same as SIFT.

  • No keypoints yields an empty (0, 128) array.

References

  • R. Arandjelović and A. Zisserman. “Three things everyone should know to improve object retrieval”. In: 2012 IEEE Conference on Computer Vision and Pattern Recognition. 2012, pp. 2911-2918. doi: 10.1109/CVPR.2012.6248018.

API reference

class pyvisim.features.RootSIFT(upsampling=2, n_octaves=8, n_scales=3, sigma_min=1.6, sigma_in=0.5, c_dog=0.013333333333333334, c_edge=10, n_bins=36, lambda_ori=1.5, c_max=0.8, lambda_descr=6, n_hist=4, n_ori=8)[source]

Bases: SIFT

Scale-Invariant Feature Transform with Hellinger kernel (RootSIFT) normalizer.

References:

[1] Arandjelovic, R., & Zisserman, A. (2012). Three things everyone should know to improve object retrieval.

__call__(image, /, *, dims='HWC', value_range=(0.0, 255.0))[source]

Extracts features from an image.

Parameters:

  • image (_Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) – Input image as MatLike (NumPy array, torch tensor or array-like). It is normalized to a canonical uint8 (H, W, C) image before extraction.

  • dims (str) – Axis-label string, one character per array axis in order: "H" = height (rows), "W" = width (columns), "C" = channels. For example, "HWC" is height × width × channels (NumPy/OpenCV layout); "CHW" is channels × height × width (PyTorch layout). See pyvisim.typing.

  • value_range (tuple[float, float]) – The (low, high) range the input values live in; converted into the canonical [0, 255] range.

Returns:

Feature descriptors (NumPy array).

Return type:

ndarray[tuple[int, …], dtype[float32]]

detect(image)

Detect the keypoints.

Parameters

image2D array

Input image.

detect_and_extract(image)

Detect the keypoints and extract their descriptors.

Parameters

image2D array

Input image.

extract(image)

Extract the descriptors for all keypoints in the image.

Parameters

image2D array

Input image.

extract_batch(images, /, *, dims='HWC', value_range=(0.0, 255.0))

Extracts features from a batch of images.

Returns one (N_i, D) feature array per image, in input order, since the number of descriptors an image yields varies from image to image. This default implementation extracts one image at a time; extractors that can do the whole batch in one go (e.g. a single forward pass through a neural network) override it.

Parameters:

  • images (Sequence[_Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]]) – Batch of images, each a MatLike (NumPy array, torch tensor or array-like) normalized to a canonical uint8 (H, W, C) image before extraction.

  • dims (str) – Axis-label string, one character per array axis in order: "H" = height (rows), "W" = width (columns), "C" = channels. It applies to every image of the batch. See pyvisim.typing.

  • value_range (tuple[float, float]) – The (low, high) range the input values live in; converted into the canonical [0, 255] range.

Returns:

One (N_i, D) feature array per input image.

Return type:

list[ndarray[tuple[int, …], dtype[float32]]]

classmethod from_dict(state, **kwargs)

Rebuilds an object from a state dictionary (see to_dict() to see the expected format).

Parameters:

  • state (dict[str, Any]) – A JSON-safe description of the object.

  • kwargs (Any) – Objects the state cannot describe, forwarded by load_from_disk(). Implementations that accept none raise an error if kwargs is not empty.

Returns:

A ready-to-use instance.

Return type:

FeatureExtractorBase

classmethod load_from_disk(path, **kwargs)

Loads an object previously saved with save_to_disk().

Not every part of an object survives serialization: an arbitrary callable such as a torchvision transform has no portable description, so it is left out of the file. Pass such an object back here as a keyword argument.

Parameters:

  • path (str | Path) – Path to the file to load.

  • kwargs (Any) – Objects the file cannot hold, forwarded to from_dict().

Returns:

A ready-to-use instance.

Raises:

  • FileNotFoundError – If path does not exist.

  • ValueError – If the file is not a valid file of this kind or was saved by a different class.

  • TypeError – If the class does not take one of kwargs.

Return type:

_SerializableT

save_to_disk(path)

Saves the serialized state of this object to a file.

Parameters:

path (str | Path) – Target file path. Overwritten if it exists.

Returns:

The path of the written file.

Raises:

OSError – If the destination directory does not exist.

Return type:

Path

to_dict()

Serializes this object into a JSON-safe state dictionary.

The mapping holds the output of _state() plus the format version under "format_version" and the class name under "__class__". Arrays may be embedded as __ndarray__ nodes, which the serialization layer stores as binary tensors.

Returns:

A JSON-safe description suitable for from_dict().

Return type:

dict[str, Any]

property deltas

The sampling distances of all octaves

property output_dim: int

The dimensionality (D) of each feature vector, i.e., shape[1] of the output.

Parameters: