tpips 0.1.1

TPIPS: text-conditioned perceptual image similarity (inference)

TPIPS

Text-Conditioned Perceptual Image Similarity for comparing two images along a specified factor, such as lighting warmth, color palette, or camera angle.

Install

pip install tpips

TPIPS requires Python 3.10+ and downloads the selected model checkpoint from Hugging Face on its first use. A CUDA GPU is recommended. FlashAttention is optional: TPIPS selects a compatible backend automatically and falls back to PyTorch SDPA when FlashAttention is unavailable.

Quick start

import tpips
from PIL import Image

model = tpips.load_model("embedding", device="cuda")
a = Image.open("a.jpg").convert("RGB")
b = Image.open("b.jpg").convert("RGB")

similarity = model.similarity(a, b, factor="lighting")  # higher is more similar
distance = model.distance(a, b, factor="lighting")      # lower is more similar

# Raw, prompt-conditioned image vector; pass normalized=True for an L2-normalized vector.
vector = model.embed(a, factor="lighting")

Pass model_path= to load_model() to load a compatible local checkpoint directory or Hugging Face repository instead of the released default.

Models and API

Model type	similarity()	distance()	embed()
embedding	Cosine similarity	1 - similarity	Per-image, text-conditioned embedding
early_fusion	Cosine similarity	1 - similarity	Not supported
activation_dist	Not supported	Activation distance	Not supported

License

TPIPS is provided under the Adobe Research License, for noncommercial research use only. Source files are Adobe confidential; ensure you have the required Adobe authorization before using, redistributing, or publishing the package or its checkpoints.

More information

See the repository README for evaluation, training, data download, and release-maintenance documentation.