Welcome to pyvisim!
pyvisim is a computer vision library for computing image similarities using traditional and deep learning methods.
📚 Documentation: https://mechacritter.github.io/Python-Visual-Similarity/
Table of Contents
Status
🚀 The first stable release v1.0.0 is out!
Overview
The goal of pyvisim is to become the largest collection of image similarity metrics, varying from
traditional methods like PSNR, SSIM, Fisher Vectors, and VLAD to deep
learning methods like CLIP and Siamese Networks. Furthermore, advanced
image similarity search and reranking algorithms are provided to allow
users to refine the search results as desired. For more details, please refer to
the documentation provided.
Currently, one would need to install numerous libraries just to everything mentioned above (for example, scikit-image + opencv-python for Fisher Vectors, SSIM, open-clip for CLIP Embedder, and faiss for Approximate Nearest Neighbors Search). pyvisim
attempts to close this gap by implementing as many metrics as possible using only numpy, scipy (for conventional metrics), and optionally
torch (for deep learning metrics) as core dependencies, plus making them more user-friendly with a simple Object-Oriented code design.
Accelerated Computation
Cython kernels and C++ libraries are used for some metrics to accelerate computation significantly compared
to all reference libraries on the CPU. See, for example, benchmark results of the SSIM implementation.
Examples
Structural Similarity (see documentation here):
from pyvisim.dense.structural import SSIM
ssim = SSIM()
similarity_score = ssim.similarity_score(image1, image2)
print(f"Similarity Score: {similarity_score}")
One-Shot similarity computation using the CLIPEmbedder(see documentation here):
from pyvisim.neural_networks import ClipEmbedder
# Declare the Clip Embedder
embedder = ClipEmbedder()
# Compute the similarity score. By default, cosine similarity is used.
similarity_score = embedder.similarity_score(image1, image2)
print(f"Similarity Score: {similarity_score}")
Image retrieval (see documentation here):
from pyvisim.neural_networks import ClipEmbedder
from pyvisim.retrieval.image_store import InMemoryImageEmbeddingStore
embedder = ClipEmbedder()
image_store = InMemoryImageEmbeddingStore(
image_paths=train_image_paths,
embedder=embedder,
search_index="hnsw",
index_params={"graph_degree": 16, "build_candidates": 200},
)
image_store.build_store() # embeds the gallery and builds the index
candidates = image_store.retrieve_top_k_similar(image, k=5)[0] # one Candidate per match
for candidate in candidates:
print(candidate.path, candidate.score)
The alpha query expansion and the k-reciprocal re-rankingcan additionally be used to refine
the retrieval results, improving mean Average Precision (see the
documentation):
from pyvisim.retrieval.reranking import KReciprocalReranker
pool = image_store.retrieve_top_k_similar(image, k=100, query_expansion=True)[0]
best = KReciprocalReranker(image_store).rerank(pool, top_k=5)
For more examples, please refer to the tutorials.
Installation
To install the slim version (without deep learning features):
pip install pyvisim
Additional features include (note: these pull in heavy dependencies like torch):
# For deep learning features and the OxfordFlowerDataset
pip install "pyvisim[nn]"
All experiments in this project was made on the Oxford Flower Dataset [7], for which I have created a custom dataset class. For more details on the dataset, please refer to the documentation.
Contributing
See the contributing guidelines.
Get in Touch
Feel free to:
- Open an issue on GitHub.
- Write me an email at vunhathuy234@gmail.com.
- Connect on LinkedIn to follow my work and share your thoughts.
License
This project is licensed under the terms of the MIT license.
1 maintainer
Metadata
1 maintainer
Release files for pyvisim 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pyvisim-1.0.0.tar.gz | 705.4 kB | Details |
Built distributions (wheels)
Total release size: 41.4 MB
Release files / pyvisim-1.0.0.tar.gz
| Download URL | pyvisim-1.0.0.tar.gz |
|---|---|
| Size | 705.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
315b07ca66a8c5b8f91f2d5cc1fbede8273db537eda4acd1286f549cea151a96
|
|
BLAKE2b-256 checksum How to use checksums |
dd4f1827e8cd45fec973533c077d144113d52232e2f9bb7681a3c6c840e12d0a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp314-cp314-win_amd64.whl
| Download URL | pyvisim-1.0.0-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
4b5b9f10c207cc60c378506cc4fcfb26bf7f45e1cdee7167647fb7146b5c8792
|
|
BLAKE2b-256 checksum How to use checksums |
96fa14abe0bcd8997bc8c4fe1ef64a0a27c7bac6ec0ed33404a636e5f890423c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyvisim-1.0.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.5 MB |
| Tags | CPython 3.14 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
d89f8caaa81d9499dee678f9f22050c02fd8d401a804ab42919cbf926636cc88
|
|
BLAKE2b-256 checksum How to use checksums |
2684cda37dd1ba61cac6ac278119f98e04bf6eb524d4ac85da4840898f67f9a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | pyvisim-1.0.0-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d8bbfd7fa4e2ce8d5f0c8044f5de85aa88386d0e6b1899c8ae008f5e9c8e32b8
|
|
BLAKE2b-256 checksum How to use checksums |
60d2ec8fed3e63bed873f636ccd5d480c7fac69c6927e27e4ddcd2ff33d55acd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp313-cp313-win_amd64.whl
| Download URL | pyvisim-1.0.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
8462c81d2d9dad3ee33ae64da27dc6c83d7976680023da64d26a71296b5fa935
|
|
BLAKE2b-256 checksum How to use checksums |
1e57044106e9a81fae233bfce621c02ed14fc580cdcaae9eab6f9c9d3b4f7f21
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyvisim-1.0.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.5 MB |
| Tags | CPython 3.13 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
7b01938bf742fe22b0c891a66606171a38eefebd899a073813611c5d50f158f1
|
|
BLAKE2b-256 checksum How to use checksums |
1e65ccc5cf8740cab7d30962744a245e9c45d30dfd28bf7a3c5abcc131ade91f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | pyvisim-1.0.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b48f9b47e59737ea8fbedcc435ce688da847f4f3cf648c2a6c5dca0796d4be64
|
|
BLAKE2b-256 checksum How to use checksums |
bc525f156ff647e1957c9a1201c296b9b77764a814e9b53b1745686cfc54ffe2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp312-cp312-win_amd64.whl
| Download URL | pyvisim-1.0.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
52211f75b14353f24e3815818a8c6d08da55de049de7d3aa617ffc1e0b89240f
|
|
BLAKE2b-256 checksum How to use checksums |
9ad11189ec767129420856e9d1ff4b63822b67493edd242ed83edde3dc6548cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyvisim-1.0.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.5 MB |
| Tags | CPython 3.12 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
f0dae9ece27998db6f385a147eeaa143aa8bba627c1881926c27d24f4860c747
|
|
BLAKE2b-256 checksum How to use checksums |
202e5c5c6cc57b019b3aa363045d3490f94876003901c97a5ca763d6bf308f2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | pyvisim-1.0.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4f37234c0d22ed41f04d8c41c1f42eff82d2c8358f4581c99c6e14d8027caf1c
|
|
BLAKE2b-256 checksum How to use checksums |
eb5274dd2f9b8aa07ee15ffb6913d6b9a21901ae612c0bc40a85264ef5bb4de2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp311-cp311-win_amd64.whl
| Download URL | pyvisim-1.0.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
1ac5879cdf97039294825985bb14955a98f8da41466085aef1570a46ba7af093
|
|
BLAKE2b-256 checksum How to use checksums |
872e2e1e4ca29fe091208187a5bfff3267840d158cdeee53d9694fea7b242a50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyvisim-1.0.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.4 MB |
| Tags | CPython 3.11 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
865086877abaec09c24ac66968962779824f6cc2d642898e8784ca8a224a51a1
|
|
BLAKE2b-256 checksum How to use checksums |
d19a3f9515f43436a23b7c4a151cb151716216e02ee5eb6b483520866e2b7c75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | pyvisim-1.0.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a5199c035515e3cf5dc565ccee48d55d700f865062df47f62386fab24679a749
|
|
BLAKE2b-256 checksum How to use checksums |
2914b54a1d889b8704cb9ae5272480db7670347cacc561136e90f45ffd8eac7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp310-cp310-win_amd64.whl
| Download URL | pyvisim-1.0.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
6fa3b0a7fa5ac5de85f0fa4b89c1d141b1357bd405c7d20d320658c01562c171
|
|
BLAKE2b-256 checksum How to use checksums |
ced2ab726e0380b2783251ecf81343705256b22f546fd25fb8dcc0e5c6b83687
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pyvisim-1.0.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.10 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
0a7ffb37ba4dd0b6696a24319c6bf3a999214be2737dc1db135eb0feafa122ec
|
|
BLAKE2b-256 checksum How to use checksums |
3fd8f8cb0e0145b75e681758507b1822d90a4c837895f02887d3cc001b8f7d15
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pyvisim-1.0.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | pyvisim-1.0.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
848726ac3ce90b9769959221a262d2ad61939f9063f227fa58e7a451f2cd1b6e
|
|
BLAKE2b-256 checksum How to use checksums |
4db10c488edb7d1929715c3555a9724e3014984d5297859a852c02b9ab90e6c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency log
