Skip to content

Latest commit

 

History

History
139 lines (111 loc) · 8.13 KB

README.md

File metadata and controls

139 lines (111 loc) · 8.13 KB

FLIP: A Tool for Visualizing and Communicating Errors in Rendered Images (v1.6)

By Pontus Ebelin and Tomas Akenine-Möller, with Jim Nilsson, Magnus Oskarsson, Kalle Åström, Mark D. Fairchild, and Peter Shirley.

This repository holds implementations of the LDR-FLIP and HDR-FLIP image error metrics in C++ and CUDA. It also holds code for the FLIP tool, presented in Ray Tracing Gems II.

Note that since v1.2, we use separated convolutions for the C++ and CUDA versions of FLIP. A note explaining those can be found here.

With v1.3, we have switched to a single header FLIP.h for easier integration into other projects.

Since v1.4, the majority of the code for the tool is contained in FLIPToolHelpers.h, but the tool is still run through FLIP-tool.cpp and FLIP-tool.cu, respectively.

License

Copyright © 2020-2025, NVIDIA Corporation & Affiliates. All rights reserved.

This work is made available under a BSD 3-Clause License.

The repository distributes code for tinyexr, which is subject to a BSD 3-Clause License,
and stb_image, which is subject to an MIT License.

For individual contributions to the project, please confer the Individual Contributor License Agreement.

For business inquiries, please visit our website and submit the form: NVIDIA Research Licensing.

C++ and CUDA (API and Tool)

  • If you want to use FLIP in your own project, it should suffice to use the header FLIP.h. Typical usage would be:

    #define FLIP_ENABLE_CUDA    // You need to define this if you want to run FLIP using CUDA. Otherwise, comment this out.
#include "FLIP.h"           // See the bottom of FLIP.h for four different FLIP::evaluate(...) functions that can be used. 

void someFunction()
{
    FLIP::evaluate(...);  // See FLIP-tool.cpp for an example of how to use one of these overloaded functions.
}

  • The FLIP.sln solution contains one CUDA backend project and one pure C++ backend project for the FLIP tool.

  • Compiling the CUDA project requires a CUDA compatible GPU. Instruction on how to install CUDA can be found here.

  • Alternatively, a CMake build can be done by creating a build directory in the src directory and invoking CMake on the source cpp directory (add --config Release to build release configuration on Windows):

    cd src
mkdir build
cd build
cmake ..
cmake --build . [--config Release]

    CUDA support is enabled via the FLIP_ENABLE_CUDA, which can be passed to CMake on the command line with -DFLIP_ENABLE_CUDA=ON or set interactively with ccmake or cmake-gui. FLIP_LIBRARY option allows to output a library rather than an executable.

  • Usage: flip[-cuda].exe --reference reference.{exr|png} --test test.{exr|png} [options], where the list of options can be seen by flip[-cuda].exe -h.

  • Tested on Windows 10 version 22H2 and Windows 11 version 23H2 with CUDA 12.6. Compiled with Visual Studio 2022. If you use another version of CUDA, you will need to change the CUDA 12.6 strings in the CUDA.vcxproj file accordingly.

  • src/tests/test.py contains simple tests used to test whether code updates alter results. Notice that those scripts require numpy and matplotlib, both of which may be installed using pip.

  • Weighted histograms are output as Python scripts. Running the script will create a PDF version of the histogram. Like the test script, these scripts require numpy and matplotlib, both of which may be installed using pip.

  • The naming convention used for the FLIP tool's output is as follows (where ppd is the assumed number of pixels per degree, tm is the tone mapper assumed by HDR-FLIP, cstart and cstop are the shortest and longest exposures, respectively, assumed by HDR-FLIP, with p indicating a positive value and m indicating a negative value, N is the number of exposures used in the HDR-FLIP calculation, nnn is a counter used to sort the intermediate results, and exp is the exposure used for the intermediate LDR image / FLIP map):

    Default:

    Low dynamic range images:

    LDR-FLIP: flip.<reference>.<test>.<ppd>ppd.ldr.png
    Weighted histogram: weighted_histogram.reference>.<test>.<ppd>ppd.ldr.py
    Overlapping weighted histogram: overlapping_weighted_histogram.<reference>.<test1>.<test2>.<ppd>ppd.ldr.py
    Text file: pooled_values.<reference>.<test>.<ppd>ppd.ldr.txt

    High dynamic range images:

    HDR-FLIP: flip.<reference>.<test>.<ppd>ppd.hdr.<tm>.<cstart>_to_<cstop>.<N>.png
    Exposure map: exposure_map.<reference>.<test>.<ppd>ppd.hdr.<tm>.<cstart>_to_<cstop>.<N>.png
    Intermediate LDR-FLIP maps: flip.<reference>.<test>.<ppd>ppd.ldr.<tm>.<nnn>.<exp>.png
    Intermediate LDR images: <reference|test>.<tm>.<nnn>.<exp>.png
    Weighted histogram: weighted_histogram.<reference>.<test>.<ppd>ppd.hdr.<tm>.<cstart>_to_<cstop>.<N>.py
    Overlapping weighted histogram: overlapping_weighted_histogram.<reference>.<test1>.<test2>.<ppd>ppd.hdr.<tm>.<cstart>_to_<cstop>.<N>.py
    Text file: pooled_values.<reference>.<test>.<ppd>ppd.hdr.<tm>.<cstart>_to_<cstop>.<N>.txt

    With --basename <name> (note: not applicable if more than one test image is evaluated):

    Low dynamic range images:

    LDR-FLIP: <name>.png
    Weighted histogram: <name>.py
    Overlapping weighted histogram: N/A
    Text file: <name>.txt

    High dynamic range images:

    HDR-FLIP: <name>.png
    Exposure map: <name>.exposure_map.png
    Intermediate LDR-FLIP maps: <name>.<nnn>.png
    Intermediate LDR images: <name>.reference|test.<nnn>.png
    Weighted histogram: <name>.py
    Overlapping weighted histogram: N/A
    Text file: <name>.txt

Example usage: After compiling the src/cpp/FLIP.sln project, navigate to the flip[-cuda].exe executable and try:

flip[-cuda].exe -r ../../../images/reference.exr -t ../../../images/test.exr

Assuming using the images in the source bundle, the result should be:

Invoking HDR-FLIP
      Pixels per degree: 67
      Assumed tone mapper: ACES
      Start exposure: -12.5423
      Stop exposure: 0.9427
      Number of exposures: 14

FLIP between reference image <reference.exr> and test image <test.exr>:
      Mean: 0.283478
      Weighted median: 0.339430
      1st weighted quartile: 0.251122
      3rd weighted quartile: 0.434673
      Min: 0.003123
      Max: 0.962022
      Evaluation time: <t> seconds
      FLIP error map location: <path/to/flipCudaDirectory/flip.reference.test.67ppd.hdr.aces.m12.5423_to_p0.9427.14.png>
      FLIP exposure map location: <path/to/flipCudaDirectory/exposure_map.reference.test.67ppd.hdr.aces.m12.5423_to_p0.9427.14.png>

where <t> is the time it took to evaluate HDR-FLIP. In addition, you will now find the files flip.reference.test.67ppd.hdr.aces.m12.5423_to_p0.9427.14.png and exposure_map.reference.test.67ppd.hdr.aces.m12.5423_to_p0.9427.14.png in the directory containing the flip[-cuda].exe executable, and we urge you to inspect those, which will reveal where the errors in the test image are located.