TonemapLIB

HDR Tone Mapping in Python.

Description

The TonemapLIB library provides an easy API for tone mapping high dynamic range (HDR) videos. TonemapLIB is built on VideoLIB, and was used to generate videos for the LIVE-TMHDR dataset. TonemapLIB provides the following salient features.

A standardized TMO class that defines tone mapping operator (TMO) behavior.
Options to specify and vary TMO arguments using .py files (refer to the tmo_args/ folder for examples).
Tone Mapping in three temporal modes - framewise, shot, and smooth. The three modes are described in detail in this paper.
Open-source implementations of ten TMOs from the literature.
- Reinhard02 [Paper] [Code]
- Durand02 [Paper] [Code]
- Hable [Paper] [Code]
- Shan12 [Paper] [Code]
- Reinhard12 [Paper] [Code]
- Eilertsen15 [Paper] [Code]
- Oskarsson17 [Paper] [Paper]
- Rana19 [Paper] [Code]
- Yang21 [Paper] [Code]
- ITU21 [Paper] [Code]

Note: The implementations may not be identical to their descriptions in the cited papers.

Usage

The usage example provided below offers a glimpse into the degree to which VideoLIB simplifies video processing tasks.

Tone Mapping an HDR Video

from videolib import Video, standards
from tonemaplib import get_tmoclass

TMOClass = get_tmoclass('Reinhard02')
tmo = TMOClass()
with Video('hdr_video_path.mp4', standards.rec_2100_pq, 'r') as v:
    tmo(v, 'sdr_video_path.mp4')

Setting TMO parameters

from videolib import Video, standards
from tonemaplib import get_tmoclass

TMOClass = get_tmoclass('Reinhard02')
print(TMOClass.params)
tmo = TMOClass(key=0.2, desat=0.01, video_mode='shot')
with Video('hdr_video_path.mp4', standards.rec_2100_pq, 'r') as v:
    tmo(v, 'sdr_video_path.mp4')

Installation

To use TonemapLIB, you will need Python >= 3.7.0. In addition, using virtual environments such as virtualenv or conda is recommended. The code has been tested on Linux and it is expected to be compatible with Unix/MacOS platforms.

Creating a virtual environment

python3 -m virtualenv .venv/
source .venv/bin/activate

Install preqrequisites and TonemapLIB

pip install -r requirements.txt
pip install .

Install using pip

pip install git+github.com/abhinaukumar/tonemaplib

Issues, Suggestions, and Contributions

Please file an issue if you would like to suggest a feature, or flag any bugs/issues, and I will respond to them as promptly as I can. Contributions that add features and/or resolve any issues are also welcome! Please create a pull request with your contribution and I will review it at the earliest.

Contact Me

If you would like to contact me personally regarding TonemapLIB, please email me at either abhinaukumar@utexas.edu or ab.kumr98@gmail.com.

License

TonemapLIB is covered under the MIT License, as shown in the LICENSE file.