Metadata-Version: 2.4
Name: tpips
Version: 0.1.1
Summary: TPIPS: text-conditioned perceptual image similarity (inference)
Project-URL: Homepage, https://github.com/PeterWang512/TPIPS
License-Expression: LicenseRef-Adobe-Research-License
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: huggingface-hub>=0.26
Requires-Dist: peft>=0.19
Requires-Dist: pillow>=10
Requires-Dist: qwen-vl-utils
Requires-Dist: torch>=2.7
Requires-Dist: torchvision>=0.22
Requires-Dist: transformers>=5.0
Description-Content-Type: text/markdown

# TPIPS

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

## Install

```bash
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

```python
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](https://github.com/PeterWang512/TPIPS/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](https://github.com/PeterWang512/TPIPS) for evaluation,
training, data download, and release-maintenance documentation.
