# /// script
# requires-python = ">=3.10"
# dependencies = ["numpy", "opencv-python"]
# ///
"""
@effect saturation
@version 1.0.0
@author artdag

@description
Adjusts color saturation. 0 = grayscale, 1 = original, 2 = oversaturated.
Uses HSV color space for accurate saturation control.

@param factor float
  @range 0 3
  @default 1.0
  Saturation multiplier. 0 = grayscale, 1 = unchanged, 2 = double saturation.

@example
  (effect saturation :factor 0)  ; grayscale

@example
  (effect saturation :factor 1.5)  ; vibrant colors

@example
  ;; Desaturate on quiet parts, saturate on loud
  (effect saturation :factor (bind energy :range [0.5 2.0]))
"""

import numpy as np
import cv2


def process_frame(frame: np.ndarray, params: dict, state: dict) -> tuple:
    """
    Adjust saturation of a video frame.

    Args:
        frame: Input frame as numpy array (H, W, 3) RGB uint8
        params: Effect parameters
            - factor: saturation multiplier (default 1.0)
        state: Persistent state dict (unused)

    Returns:
        Tuple of (processed_frame, new_state)
    """
    factor = params.get("factor", 1.0)

    if factor == 1.0:
        return frame, state

    # Convert RGB to HSV
    hsv = cv2.cvtColor(frame, cv2.COLOR_RGB2HSV).astype(np.float32)

    # Scale saturation channel (index 1)
    hsv[:, :, 1] = np.clip(hsv[:, :, 1] * factor, 0, 255)

    # Convert back to RGB
    result = cv2.cvtColor(hsv.astype(np.uint8), cv2.COLOR_HSV2RGB)

    return result, state