#!/usr/bin/env python
# -*- coding: utf-8 -*-

##
# @file gamma_curve_plot.py
# @brief Generates and visualizes gamma correction curves for comparison.
#
# @details
# This script creates a graph comparing multiple gamma correction curves
# against a linear reference (no gamma correction).
# The generated plot is intended for documentation and wiki usage
# to visually explain how different gamma values affect intensity mapping.
#
# Gamma correction is calculated using the formula:
# @f[
#   y = x^{(1/\gamma)}
# @f]
#
# The resulting graph is saved as a PNG image file.

import numpy as np
import matplotlib.pyplot as plt


##
# @brief Plots gamma correction curves and saves the graph as an image.
#
# @details
# This function generates a normalized input gradient from 0 to 1
# and applies multiple gamma correction transformations to it.
# The corrected curves are plotted alongside a linear reference curve
# to highlight the differences in brightness response.
#
# The output graph is saved locally and displayed on screen.
#
# @note
# This visualization is intended for explanatory purposes,
#
# @return None
def plot_gamma_curves():
    ##
    # @brief Generate input gradient values.
    #
    # @details
    # Creates a smooth range of normalized intensity values
    # from 0.0 to 1.0 for curve plotting.
    x = np.linspace(0, 1, 500)

    ##
    # @brief List of gamma values to compare.
    #
    # @details
    # These gamma values demonstrate different correction strengths,
    # from low (brightening) to very high (strong compression).
    gamma_values = [0.5, 3, 50]

    ##
    # @brief Initialize matplotlib figure.
    plt.figure(figsize=(10, 6))

    ##
    # @brief Plot linear reference curve (no gamma correction).
    #
    # @details
    # This dashed line represents a direct linear mapping (y = x)
    # and serves as a baseline for comparison.
    plt.plot(x, x, 'k--', label='Linear (No Correction)', alpha=0.5)

    ##
    # @brief Plot gamma-corrected curves.
    #
    # @details
    # Applies the gamma correction formula y = x^(1/gamma)
    # and plots each resulting curve.
    for gamma in gamma_values:
        y = np.power(x, 1.0 / gamma)
        plt.plot(
            x,
            y,
            linewidth=2.5,
            label=f'Gamma = {gamma} (Exp: 1/{gamma} ≈ {1.0 / gamma:.2f})'
        )

    ##
    # @brief Configure graph appearance and labels.
    plt.title('Gamma Correction Curves Comparison', fontsize=14)
    plt.xlabel('Input Value (Gradient 0 to 1)', fontsize=12)
    plt.ylabel('Corrected Output Value', fontsize=12)
    plt.legend()
    plt.grid(True, alpha=0.3)
    plt.ylim(0, 1.05)
    plt.xlim(0, 1.0)

    ##
    # @brief Save the generated graph to a file.
    #
    # @details
    # The image is saved in PNG format for easy embedding in documentation.
    output_filename = 'gamma_comparison_graph.png'
    plt.savefig(output_filename)
    print(f"Graph successfully saved as: {output_filename}")

    ##
    # @brief Display the graph window.
    plt.show()


##
# @brief Program entry point.
#
# @details
# Executes the gamma curve plotting function when the script
# is run directly.
if __name__ == "__main__":
    plot_gamma_curves()