Features

A feature extractor maps one image to a (N, D) array of local descriptors. Embedders consume these descriptors and aggregate them into a fixed-size vector:

image -> feature extractor -> local descriptors -> embedder -> embedding

The extractors implemented in pyvisim are split into handcrafted features and deep learning based features.

Reconstructing feature extractors

Every extractor describes itself as a JSON-safe configuration, and from_dict() rebuilds the extractor a description names.

from pyvisim.base import FeatureExtractorBase
from pyvisim.features import RootSIFT

extractor = RootSIFT(n_hist=2, n_ori=4)

# Serialize extractor
serialized = extractor.to_dict()

# Reload extractor
reloaded = FeatureExtractorBase.from_dict(serialized)

An extractor can also be saved to a .safetensors file and loaded with the load_from_disk method of its class.

from pyvisim.features import RootSIFT

path = RootSIFT(n_hist=2, n_ori=4).save_to_disk("root_sift.safetensors")
reloaded = RootSIFT.load_from_disk(path)

Table of Contents

• Handcrafted features
• Deep learning based features

Serialization

Every extractor except Lambda can be written to and read from a JSON-safe dictionary or a .safetensors file with the methods below.

FeatureExtractorBase.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]

classmethod FeatureExtractorBase.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

FeatureExtractorBase.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

classmethod FeatureExtractorBase.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