v0.9.5

Upgrade Notes

  • Binary files for the docs are now added through a pull request against the assets branch instead of a force-push. Contributors who used the old recipe follow the updated “Adding binary files to the docs” section of CONTRIBUTING.md.

  • The file format of a serializable class is now declared on the class itself under one set of names, and the module-level constants that held it are gone. _FILE_SUFFIX became __file_format__, _METADATA_KEY became __metadata_key__, _CLASS_KEY became __class_key__, _STATE_KEYS became __state_keys__, and every per-module format version (_CLUSTERING_EMBEDDER_FILE_FORMAT_VERSION, _NEURAL_EMBEDDER_FORMAT_VERSION, _PIPELINE_FORMAT_VERSION, _CLIP_EMBEDDER_FORMAT_VERSION, _STORE_FORMAT_VERSION) became __format_version__ on the class that writes it. Their compatibility table is __compatibility_mapping__. Subclasses outside the library that set any of the old names have to rename them: the old names are no longer read, and SerializerMixin now raises a TypeError at class-definition time when a class that implements to_dict and from_dict leaves one of the required attributes undeclared.

  • pyvisim.serialization.EMBEDDER_METADATA_KEY and pyvisim._base_classes.EMBEDDER_FILE_SUFFIX were removed. Read them from the embedder class instead, for example VLADEmbedder.__metadata_key__ and VLADEmbedder.__file_format__.

  • Subclasses outside the library that implement _embed now receive one batch as a list of canonical uint8 (H, W[, C]) images, without dims and value_range, since ImageEmbedderBase.embed normalizes and batches the input. Drop the two parameters and the batching loop from your _embed.

  • SerializerMixin.to_dict is no longer abstract. It adds the format version and the class name to the mapping returned by the new abstract _state method. Subclasses outside the library rename their to_dict to _state and drop the format_version and class-name entries from it, and __state_keys__ no longer lists the class key. Loading a file whose state lacks the format version or the class name raises a ValueError.

  • pyvisim.serialization.embedder_to_dict and pyvisim.serialization.embedder_from_dict are removed. Code importing them calls embedder.to_dict() instead, and SerializableImageEmbedder.from_dict(state) to rebuild an embedder of any class from its state.

New Features

  • The KMeans, DiagCovarGaussianMixture and PCA models of the classic embedders can be saved on their own with save_to_disk and loaded back with load_from_disk, as .safetensors files.

Enhancement Notes

  • The Benchmarks workflow pushes its barplots to docs/benchmark-barplots for review instead of publishing them directly. The new Squash assets workflow keeps assets at a single commit after each merge.

  • Every embedder rejects an empty input with the same ValueError (“Expected at least one image, got none.”) instead of a NumPy concatenation error or an embedder-specific message.

  • Every load_from_disk reports an unreadable file the same way, as “File … is not a valid <suffix> file” followed by the reason. The image store used to raise the bare reason, while the embedders dropped it.

  • The clustering models of VLADEmbedder and FisherVectorEmbedder record a format_version in their part of the .embedder file. Files written before still load.