qvx-o/Qlipi

QLIP-I: Image Embedding Model

QLIP-I is a vision transformer-based model that generates normalized 512-dimensional embeddings for images. The model uses a patch-based approach to encode visual information into a compact representation suitable for similarity search, retrieval, and downstream tasks.

Install dependencies

pip install torch torchvision pillow numpy

Usage

Single Image Encoding

from PIL import Image
import QLIPI

# Load and encode an image
image = Image.open("path/to/image.jpg")
embedding = QLIPI.encode(image)

# The embedding is a 512-dimensional normalized tensor
print(embedding.shape)  # torch.Size([512])

Batch Encoding

import QLIPI
from PIL import Image

# Encode multiple images at once
images = [
    "image1.jpg",
    "image2.jpg",
    Image.open("image3.jpg")
]
embeddings = QLIPI.encode_batch(images)

# Returns a batch of embeddings
print(embeddings.shape)  # torch.Size([3, 512])

Computing Similarity

import torch
import QLIPI
from PIL import Image

# Encode two images
img1 = Image.open("cat.jpg")
img2 = Image.open("dog.jpg")

emb1 = QLIPI.encode(img1)
emb2 = QLIPI.encode(img2)

# Compute cosine similarity (embeddings are already normalized)
similarity = torch.dot(emb1, emb2)
print(f"Similarity: {similarity.item():.4f}")

Save and Load Embeddings

import torch
import QLIPI
from PIL import Image

# Encode and save
image = Image.open("image.jpg")
embedding = QLIPI.encode(image)
torch.save(embedding, "embedding.pt")

# Load embedding
loaded_embedding = torch.load("embedding.pt")

Model Information

import QLIPI

# Get device being used
print(QLIPI.device())  # cuda or cpu

# Get model path
print(QLIPI.model_path())  # Path to qlip-img.pt

# Get embedding dimensions
print(QLIPI.embedding_dim())  # 512

# Get number of parameters
print(QLIPI.model_parameters())  # Total trainable parameters

Input Specifications

• Format: RGB images (automatically converted from other formats)
• Preprocessing: Images are resized to 224×224 using bicubic interpolation with center cropping
• Normalization: ImageNet statistics
  • Mean: [0.485, 0.456, 0.406]
  • Std: [0.229, 0.224, 0.225]

The model automatically uses CUDA if available and falls back to CPU otherwise.

Use Cases

• Image Similarity Search: Find similar images using cosine similarity
• Image Retrieval: Build reverse image search systems
• Clustering: Group similar images together
• Classification: Use embeddings as features for downstream classifiers
• Content-Based Recommendation: Recommend visually similar content
• Duplicate Detection: Identify near-duplicate images

Limitations

• Images are resized to 224×224, which may lose detail in high-resolution images
• Model is trained for general visual understanding; domain-specific fine-tuning may improve performance on specialized datasets
• Embeddings are fixed at 512 dimensions

License

MIT Licenses