<?php

/**
 * JCOGS Image Pro - Face Detection Parameter Package
 * ==================================================
 * Form interface for face detection quality parameter
 * 
 * @category   ExpressionEngine Add-on
 * @package    JCOGS Image Pro
 * @author     JCOGS Design <contact@jcogs.net>
 * @copyright  Copyright (c) 2021 - 2025 JCOGS Design
 * @license    https://jcogs.net/add-ons/license/jcogs_img_pro
 * @version    2.0.6
 * @link       https://JCOGS.net/
 * @since      v2.0.0 Face Detection Quality Modes
 */

namespace JCOGSDesign\JCOGSImagePro\Service\ParameterPackages;

/**
 * Face Detection Parameter Package
 * 
 * Provides quality mode selection for face detection operations used in
 * crop focus and other face-aware features.
 * 
 * Quality Modes:
 * - fast: 3-5x faster detection using simpler cascade and Canny pruning
 * - balanced: Standard detection with good speed/accuracy balance (default)
 * - accurate: Thorough detection using comprehensive cascade for maximum accuracy
 * 
 * Used by:
 * - crop="face_detect" - Focus crop on detected faces
 * - Face-aware positioning in transformations
 * 
 * Performance Guidelines:
 * - fast: ~100-200ms on typical images (suitable for batch operations)
 * - balanced: ~200-350ms on typical images (recommended default)
 * - accurate: ~400-700ms on typical images (use when face detection is critical)
 */
class FaceDetectionParameterPackage extends AbstractParameterPackage
{
    /**
     * Package identifier
     * 
     * @return string Package name
     */
    public function getName(): string 
    {
        return 'face_detection_parameter_package';
    }

    /**
     * Get the display label for this parameter package
     * 
     * @return string Package label
     */
    public function getLabel(): string
    {
        return 'Face Detection Quality';
    }

    /**
     * Get the description for this parameter package
     * 
     * @return string Package description
     */
    public function getDescription(): string
    {
        return 'Controls the quality and speed of face detection operations';
    }

    /**
     * Get the category for this parameter package
     * 
     * @return string Package category
     */
    public function getCategory(): string
    {
        return 'transformational';
    }

    /**
     * Parameters handled by this package
     * 
     * @return array List of parameter names
     */
    public function getParameters(): array 
    {
        return ['face_detection_quality'];
    }

    /**
     * Priority for face detection parameter package
     * 
     * @return int Priority order (lower numbers = higher priority)
     */
    public function getPriority(): int
    {
        return 50; // Standard priority for advanced features
    }

    /**
     * Get form fields for face detection quality parameter
     * 
     * @param array $current_values Current parameter values  
     * @return array Flat associative array of form fields
     */
    protected function getPackageFormFields(array $current_values = []): array
    {
        $current_quality = $current_values['face_detection_quality'] ?? 'balanced';
        
        return [
            'face_detection_quality' => [
                'type' => 'select',
                'label' => 'Face Detection Quality',
                'desc' => 'Choose the quality mode for face detection. Higher quality is more accurate but slower.',
                'value' => $current_quality,
                'choices' => [
                    'fast' => 'Fast - Quick detection for batch operations (~100-200ms)',
                    'balanced' => 'Balanced - Good speed and accuracy (recommended, ~200-350ms)',
                    'accurate' => 'Accurate - Maximum accuracy for critical applications (~400-700ms)'
                ],
                'placeholder' => 'balanced',
                'note' => 'Fast mode uses Canny edge pruning and a simpler cascade (20 stages). Accurate mode uses a comprehensive cascade (25 stages) with thorough search parameters.'
            ]
        ];
    }

    /**
     * Process form data to generate face_detection_quality parameter value
     * 
     * @param string $parameter_name Parameter name (should be 'face_detection_quality')
     * @param array $form_data Form submission data
     * @return string Quality mode value
     */
    public function processParameterFromForm(string $parameter_name, array $form_data): string 
    {
        $quality = trim($form_data['face_detection_quality'] ?? 'balanced');
        
        // Validate and return
        if (!in_array($quality, ['fast', 'balanced', 'accurate'])) {
            return 'balanced';
        }
        
        return $quality;
    }

    /**
     * Validate face_detection_quality parameter value
     * 
     * @param string $param_name Parameter name (should be 'face_detection_quality')
     * @param mixed $value Parameter value to validate
     * @return bool|string True if valid, error message if invalid
     */
    protected function validateParameter(string $param_name, $value)
    {
        if ($param_name !== 'face_detection_quality') {
            return parent::validateParameter($param_name, $value);
        }

        // Allow empty values (will default to 'balanced')
        if (empty($value)) {
            return true;
        }

        $quality = strtolower(trim((string)$value));
        
        // Validate against allowed quality modes
        if (!in_array($quality, ['fast', 'balanced', 'accurate'])) {
            return "Invalid face detection quality '{$value}'. Must be 'fast', 'balanced', or 'accurate'";
        }

        return true;
    }
}
