vsflip 1.0.1__py3-none-any.whl

vsflip-1.0.1.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: vsflip
+Version: 1.0.1
+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 **VapourSynt** that enables perceptual video comparison using the [FLIP metric](https://github.com/NVlabs/flip) (Fidelity Loss Image Processing). 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 in grayscale (GRAYS format)
+
+- Refer to the Python docstrings for detailed parameter descriptions and options.
+
+## 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.
+
+## 📬 Contact
+For questions, bugs, or feature requests, feel free to open an issue or pull request.

vsflip-1.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+vsflip.py,sha256=hruhkbPwgQ7bdBTuQ4UjmbkikmshlmIxvnsQLvALRDs,7839
+vsflip-1.0.1.dist-info/licenses/LICENSE,sha256=8fC0iEVo529xntZ3jNX833XuusyRcbOOu_lDOInjqDU,1064
+vsflip-1.0.1.dist-info/METADATA,sha256=5u9h1jWtLG3SBmG_XcoNmotoXx9kPWfkoJv8jWO3DzI,3529
+vsflip-1.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+vsflip-1.0.1.dist-info/top_level.txt,sha256=U4HstSPijwk8bINMXTp01dRh7lGdqAC5pr9lbYYq3sc,7
+vsflip-1.0.1.dist-info/RECORD,,

vsflip-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vsflip-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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.

vsflip-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+vsflip

vsflip.py

@@ -0,0 +1,214 @@
+try:
+    import vapoursynth as vs
+except ImportError:
+    raise ImportError('Vapoursynth R71> is required')
+
+import flip_evaluator as flip
+from matplotlib.pyplot import imsave
+import numpy as np
+from weakref import WeakValueDictionary
+
+core = vs.core
+
+FLIPDICT = {
+        "vc": [0.5, 3840, 0.6],
+        "tonemapper": "ACES"
+    }
+
+_f2c_cache = WeakValueDictionary[int, vs.VideoNode]()
+
+def frame2clip(frame: vs.VideoFrame) -> vs.VideoNode:
+    """
+    Original code from [vsjetpack](https://github.com/Jaded-Encoding-Thaumaturgy/vs-jetpack/blob/main/vstools/functions/utils.py#L369)
+
+    Convert a VideoFrame to a VideoNode.
+
+    :param frame:       Input frame.
+
+    :return:            1-frame long VideoNode of the input frame.
+    """
+
+    key = hash((frame.width, frame.height, frame.format.id))
+
+    if _f2c_cache.get(key, None) is None:
+        _f2c_cache[key] = blank_clip = vs.core.std.BlankClip(
+            None, frame.width, frame.height,
+            frame.format.id, 1, 1, 1,
+            [0] * frame.format.num_planes,
+            True
+        )
+    else:
+        blank_clip = _f2c_cache[key]
+
+    frame_cp = frame.copy()
+
+    return vs.core.std.ModifyFrame(blank_clip, blank_clip, lambda n, f: frame_cp)
+
+
+def frame_to_numpyArray(frame: vs.VideoNode) -> np.ndarray:
+    """
+    Convert a VapourSynth 1-frame long VideoNode to a NumPy array.
+    
+    :param frame: The VapourSynth 1-frame long VideoNode to convert.
+    :return: A NumPy array representation of the frame.
+    """
+    frame = frame.get_frame(0)
+
+    return  np.stack([np.asarray(frame[i]) for i in range(frame.format.num_planes)], axis=-1)
+
+
+def numpy_to_frame(np_array: np.ndarray, blank_clip1 : vs.VideoNode) -> vs.VideoFrame:
+    """
+    Convert a 2D NumPy array (float32) to VapourSynth VideoFrame in GRAYS.
+    """
+    assert np_array.ndim == 2 and np_array.dtype == np.float32, "Input must be a 2D NumPy array of type float32."
+    
+    if blank_clip1 is None:
+        height, width = np_array.shape
+        blank_clip1 = core.std.BlankClip(format=vs.GRAYS, width=width, height=height, length=1) 
+
+    frame = blank_clip1.get_frame(0).copy()
+
+    np.copyto(np.asarray(frame[0]), np_array)
+
+    return frame
+
+
+def vsflip_frame (
+        ref_clip:vs.VideoNode,
+        test_clip:vs.VideoNode,
+        range:str="LDR",
+        ref_frame: int = 0,
+        test_frame: int = 0,
+        parameters: dict = FLIPDICT,
+        save_flip_error_mask: bool = False,
+        debug: bool = False,
+        blank: vs.VideoNode = None
+)-> vs.VideoNode:
+    """
+    Compare two frames using the FLIP metric. Darker values indicate a better match.
+
+    :param ref_clip:                The reference VapourSynth VideoNode.
+    :param test_clip:               The test VapourSynth VideoNode.   
+    :param range:                   The range of the video, either "LDR" or "HDR".
+    :param ref_frame:               The frame number of the reference clip to compare. Default is 0.
+    :param test_frame:              The frame number of the test clip to compare. Default is 0.
+    :param parameters:              A dictionary of parameters for the FLIP evaluation. Default is {"vc": [0.5, 3840, 0.6], "tonemapper": "ACES"}).
+    :param save_flip_error_mask:    If True, saves the FLIP error mask as png in the script folder. Default is False.
+    :param debug:                   If True, prints debug information. Default is False.
+    :param blank:                   Only for devoloper use.
+    :return:                        A VapourSynth 1-frame long VideoNode containing the FLIP error map in GrayScaleS.
+    """
+    
+    if range not in ["LDR", "HDR"]:
+        raise ValueError("Range must be either 'LDR' or 'HDR'.")
+    
+    frame_test=test_clip[test_frame]
+    frame_ref=ref_clip[ref_frame]
+
+    if debug:
+        print("Reference Frame Properties:\n")
+        print(frame_ref)
+        print("\nTest Frame Properties:\n")
+        print(frame_test)
+
+    try:
+        if frame_ref.format.id != vs.RGBS or frame_test.format.id != vs.RGBS:
+            frame_ref= core.resize.Bicubic(frame_ref, format=vs.RGBS)
+            frame_test = core.resize.Bicubic(frame_test, format=vs.RGBS)
+
+        np_ref = frame_to_numpyArray(frame_ref)
+        np_test = frame_to_numpyArray(frame_test)
+
+        flipErrorMap, meanFLIPError, parameters = flip.evaluate(np_ref, np_test, range, applyMagma=False, parameters=parameters)
+        flipErrorMap = np.squeeze(flipErrorMap)
+
+        if debug:
+            print("Mean FLIP error: ", round(meanFLIPError, 6), "\n")
+
+            print("The following parameters were used:")
+            for key in parameters:
+                val = parameters[key]
+                if isinstance(val, float):
+                    val = round(val, 4)
+                print("\t%s: %s" % (key, str(val)))
+
+        if save_flip_error_mask:
+            imsave(f"vsflip_error_map_{ref_frame}_{test_frame}.png", flipErrorMap, cmap="gray")
+
+        if debug:
+            print("numpy array max and min values (correct value should be between 1-0):")
+            print(flipErrorMap.max(), flipErrorMap.min())
+
+        frame= numpy_to_frame(flipErrorMap, blank_clip1=blank)
+        
+        # Add meanFLIPError to frame properties
+        frame.props["meanFLIPError"] = float(meanFLIPError)
+        
+        return frame2clip(frame)
+
+    except Exception as e:
+        print(f"Error processing frame {ref_frame} and {test_frame}: {e}")
+        return blank # Return a blank frame in case of error
+
+
+def vsflip_video(
+        ref_clip: vs.VideoNode,
+        test_clip: vs.VideoNode,
+        range: str = "LDR",
+        parameters: dict = FLIPDICT,
+        debug: bool = False,
+        allignment_to_ref: int = 0
+) -> vs.VideoNode:
+    """
+    Compare two videos using the FLIP metric frame by frame. Darker values indicate a better match.
+    Both clips must have the same number of frames or at least be perfectly aligned.
+    
+    :param ref_clip:                The reference VapourSynth VideoNode.
+    :param test_clip:               The test VapourSynth VideoNode.
+    :param range:                   The range of the video, either "LDR" or "HDR".
+    :param parameters:              A dictionary of parameters for the FLIP evaluation. Default is {"vc": [0.5, 3840, 0.6], "tonemapper": "ACES"}).
+    :param debug:                   If True, prints debug information. Default is False.
+    :param allignment_to_ref:       The number of frames to align the test clip to the reference clip. Default is 0.
+                                    Ensure both clip are perfectly aligned, because using this offset could lead to error. 
+    :return:                        A VapourSynth VideoNode containing the FLIP error map for each frame in GrayScaleS.
+    """
+    
+    # just in case the user is tard
+    min_length = min(ref_clip.num_frames, test_clip.num_frames - allignment_to_ref)
+
+    blank = core.std.BlankClip(
+        format=vs.GRAYS,
+        width=ref_clip.width,
+        height=ref_clip.height,
+        length=min_length,
+        fpsnum=ref_clip.fps_num,
+        fpsden=ref_clip.fps_den
+    ) 
+
+    blank1 = core.std.BlankClip(
+        format=vs.GRAYS,
+        width=ref_clip.width,
+        height=ref_clip.height,
+        length=1,
+    ) 
+
+    def select_flip(n: int) -> vs.VideoNode:
+        try:
+            return vsflip_frame(
+                ref_clip,
+                test_clip,
+                range=range,
+                ref_frame=n,
+                test_frame=n+allignment_to_ref,
+                parameters=parameters,
+                save_flip_error_mask=False,
+                debug=debug,
+                blank=blank1
+            )
+        except Exception as e:
+            print(f"Error processing frame {n}: {e}")
+            return blank1 # Return a blank frame in case of error
+
+    return core.std.FrameEval(clip=blank, eval=select_flip)
+