Metadata-Version: 2.4
Name: vsflip
Version: 1.1.0
Summary: A VapourSynth wrapper for the FLIP perceptual metric
Author-email: PingWer <r74michele@gmail.com>
License: MIT License
        
        Copyright (c) 2025 PingWer
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: flip_evaluator
Requires-Dist: vapoursynth
Dynamic: license-file

# vsflip

**vsflip** is a Python wrapper for **VapourSynth** that enables perceptual video comparison using the [FLIP metric](https://github.com/NVlabs/flip). It computes frame-by-frame error maps that quantify visual differences between a reference and a test video.

This wrapper integrates the `flip` Python library and works entirely within VapourSynth pipelines.

## 📦 Features

- Frame-by-frame FLIP comparison between two `VideoNode`.
- Outputs GrayscaleS error maps where darker pixels indicate better perceptual similarity.
- Supports both `LDR` and `HDR` evaluation modes.
- Optionally exports error maps as images (`.png`).

## 🛠 Requirements

- Python ≥ 3.13
- [VapourSynth](https://www.vapoursynth.com/) R71 or newer
- [NumPy](https://numpy.org/)
- [Matplotlib](https://matplotlib.org/)
- [flip](https://github.com/NVlabs/flip)

## 🚀 Installation

You can install `vsflip` via pip:

```bash
pip install vsflip
```

## ✏️ Basic Usage
```python
from vsflip import vsflip_frame, vsflip_video

# Compare the first frame of two clips
result = vsflip_frame(ref_clip, test_clip)

# Compare all frames (must be aligned and same length)
result = vsflip_video(ref_clip, test_clip)
```
- Both functions return a VideoNode (GRAYS format).

- Refer to the Python docstrings for detailed parameter descriptions and options.

## Parameter Presets
To help understand the various screen resolution, distance, etc., I have created a set of presets called `FlipParams`. Check the docstring and the function itself for more info.

## License
This project is licensed under the **MIT License**. See the [LICENSE](./LICENSE) file for details.

### Third-party Dependencies
This project uses the [FLIP metric](https://github.com/NVlabs/flip) python wrapper by NVIDIA, which is licensed under the BSD 3-Clause License.

The flip library's source code or binaries are **not bundled** with this project.
It is installed separately as a required runtime dependency.

## TODO List
- Hoping that Nvidia hasn't dropped the project, I want to create the Python  wrapper and the Vaporsynth implementation for the CUDA version as well. 
  I actually tried, but I miserably failed... Any help is appreciated.

## 📬 Contact
For questions, bugs, or feature requests, feel free to open an issue or pull request.
