metrics/gradient_field_pca.py

# Dependencies
import numpy as np
from utils.logger import get_logger
from config.schemas import MetricResult
from config.constants import MetricType
from utils.image_processor import ImageProcessor
from config.constants import GRADIENT_FIELD_PCA_PARAMS

# Suppress NumPy warning 
np.seterr(divide  = 'ignore', 
          invalid = 'ignore',
         )


# Setup Logging
logger = get_logger(__name__)


class GradientFieldPCADetector:
    """
    Detects AI-generated images by analyzing gradient field consistency. Real photos have consistent gradient 
    patterns shaped by physics (lighting, optics). Diffusion models struggle to maintain physically consistent
    gradients due to denoising
    
    Core principle:
    ---------------
    - Real photos : Gradients align with physical light sources (low-dimensional structure)
    - AI images   : Gradients are inconsistent due to patch-based denoising (high-dimensional)
    
    Method:
    -------
    1. Convert to luminance
    2. Compute Sobel gradients (Gx, Gy)
    3. Flatten to gradient vectors per pixel
    4. Compute covariance matrix
    5. PCA eigenvalue analysis
    """
    def __init__(self):
        """
        Initialize Gradient-Field PCA Detector class
        """
        self._range          = np.random.default_rng(seed = GRADIENT_FIELD_PCA_PARAMS.RANDOM_SEED)
        self.image_processor = ImageProcessor()
    

    def detect(self, image: np.ndarray) -> MetricResult:
        """
        Run gradient PCA detection
        
        Arguments:
        ----------
            image { np.ndarray } : RGB image array (H, W, 3)
        
        Returns:
        --------
            { MetricResult }     : Structured metric result containing:
                                   - score      : Suspicion score [0.0, 1.0] (0 = natural, 1 = suspicious)
                                   - confidence : Confidence of this metric's assessment [0.0, 1.0]
                                   - details    : Explainability metadata for UI and reports
        """
        try:
            logger.debug(f"Running gradient PCA detection on image shape {image.shape}")
            
            # Convert image to luminance
            luminance             = self.image_processor.rgb_to_luminance(image = image)
            
            # Compute gradients
            gx, gy                = self.image_processor.compute_gradients(luminance = luminance)
            
            # Flatten and sample gradient vectors
            gradient_vectors      = self._prepare_and_sample_gradients(gx = gx, 
                                                                       gy = gy,
                                                                      )
            
            # Perform PCA
            eigenvalue_ratio      = self._compute_eigenvalue_ratio(gradient_vectors = gradient_vectors)

            if ((len(gradient_vectors) < GRADIENT_FIELD_PCA_PARAMS.MIN_SAMPLES) or (eigenvalue_ratio == GRADIENT_FIELD_PCA_PARAMS.NEUTRAL_SCORE)):
                return MetricResult(metric_type = MetricType.GRADIENT,
                                    score       = GRADIENT_FIELD_PCA_PARAMS.NEUTRAL_SCORE,
                                    confidence  = 0.0,
                                    details     = {"reason"           : "insufficient_gradient_information",
                                                   "original_pixels"  : int(gx.size),
                                                   "filtered_vectors" : int(len(gradient_vectors)),
                                                  },
                                   )
            
            # Convert to suspicion score
            suspicion_score       = self._eigenvalue_to_suspicion(eigenvalue_ratio = eigenvalue_ratio)

            # Confidence inverted relative to suspicion: High eigenvalue_ratio = natural, High suspicion_score = AI-like
            confidence            = abs(eigenvalue_ratio - GRADIENT_FIELD_PCA_PARAMS.EIGENVALUE_RATIO_THRESHOLD)
            normalized_confidence = np.clip((confidence / GRADIENT_FIELD_PCA_PARAMS.EIGENVALUE_RATIO_THRESHOLD), 0.0, 1.0)
            
            logger.debug(f"Gradient PCA: eigenvalue_ratio={eigenvalue_ratio:.3f}, suspicion_score={suspicion_score:.3f}")
            
            return MetricResult(metric_type = MetricType.GRADIENT,
                                score       = float(suspicion_score),
                                confidence  = float(normalized_confidence),
                                details     = {"gradient_vectors_sampled" : len(gradient_vectors),
                                               "eigenvalue_ratio"         : float(eigenvalue_ratio),
                                               "threshold"                : GRADIENT_FIELD_PCA_PARAMS.EIGENVALUE_RATIO_THRESHOLD,
                                               "original_pixels"          : int(gx.size),
                                               "filtered_vectors"         : int(len(gradient_vectors)),
                                              },
                               )
            
        except Exception as e:
            logger.error(f"Gradient PCA detection failed: {e}")
            
            # Return neutral score on error
            return MetricResult(metric_type = MetricType.GRADIENT,
                                score       = GRADIENT_FIELD_PCA_PARAMS.NEUTRAL_SCORE,
                                confidence  = 0.0,
                                details     = {"error" : "Gradient PCA detection failed"},
                               )
    

    def _prepare_and_sample_gradients(self, gx: np.ndarray, gy: np.ndarray) -> np.ndarray:
        """
        Flatten gradients into vectors and sample
        
        Arguments:
        ----------
            gx { np.ndarray } : Gradient in x direction

            gy { np.ndarray } : Gradient in y direction
        
        Returns:
        --------
            { np.ndarray }    : Array of gradient vectors (N, 2) where N <= SAMPLE_SIZE
        """
        # Flatten to vectors
        gx_flat                   = gx.flatten()
        gy_flat                   = gy.flatten()

        # Stack into (N, 2) array
        gradient_vectors          = np.stack([gx_flat, gy_flat], axis = 1)
        original_n                = len(gradient_vectors)

        # Remove zero gradients (uniform regions)
        magnitude                 = np.linalg.norm(gradient_vectors, axis = 1)
        non_zero_mask             = (magnitude > GRADIENT_FIELD_PCA_PARAMS.MAGNITUDE_THRESHOLD)
        finite_mask               = np.isfinite(gradient_vectors).all(axis = 1)

        # Filtering Gradient Vector
        filtered_gradient_vectors = gradient_vectors[non_zero_mask & finite_mask]
        filtered_n                = len(filtered_gradient_vectors)
        
        # Sample if too many points without replacement
        if (len(filtered_gradient_vectors) > GRADIENT_FIELD_PCA_PARAMS.SAMPLE_SIZE):
            indices                   = self._range.choice(a       = len(filtered_gradient_vectors), 
                                                           size    = GRADIENT_FIELD_PCA_PARAMS.SAMPLE_SIZE, 
                                                           replace = False,
                                                          )

            sampled_gradient_vectors  = filtered_gradient_vectors[indices]
        
        else:
            sampled_gradient_vectors  = filtered_gradient_vectors


        sampled_n = len(sampled_gradient_vectors)

        logger.debug(f"Gradient PCA sampling: original={original_n}, filtered={filtered_n}, sampled={sampled_n}")
        
        return sampled_gradient_vectors
    

    def _compute_eigenvalue_ratio(self, gradient_vectors: np.ndarray) -> float:
        """
        Compute ratio of first eigenvalue to total variance
        
        -  Lower ratio  = more diffuse structure = suspicious
        -  Higher ratio = concentrated structure = natural
        
        Arguments:
        ----------
            gradient_vectors { np.ndarray } : Array of gradient vectors (N, 2)
        
        Returns:
        --------
                     { float }              : Ratio of first eigenvalue to sum of eigenvalues
        """
        if (len(gradient_vectors) < GRADIENT_FIELD_PCA_PARAMS.MIN_SAMPLES):
            logger.warning("Insufficient gradient samples for PCA")
            return GRADIENT_FIELD_PCA_PARAMS.NEUTRAL_SCORE
        
        # Compute covariance matrix
        covariance       = np.cov(m    = gradient_vectors.T,
                                  bias = True,
                                 )
        
        # Compute eigenvalues
        eigenvalues      = np.linalg.eigvalsh(covariance)

        # Sort in descending order
        eigenvalues      = np.sort(eigenvalues)[::-1]  
        
        # Ratio of largest eigenvalue to sum
        total_variance   = np.sum(eigenvalues)
        
        if (total_variance < GRADIENT_FIELD_PCA_PARAMS.VARIANCE_THRESHOLD):
            return GRADIENT_FIELD_PCA_PARAMS.NEUTRAL_SCORE
        
        eigenvalue_ratio = eigenvalues[0] / total_variance

        return float(eigenvalue_ratio)
    

    def _eigenvalue_to_suspicion(self, eigenvalue_ratio: float) -> float:
        """
        Convert eigenvalue ratio to suspicion score
        
        - Real photos : High ratio (0.85-0.95) -> Low suspicion
        - AI images   : Low ratio (0.50-0.75) -> High suspicion
        
        Arguments:
        ----------
            eigenvalue_ratio { float } : PCA eigenvalue ratio
        
        Returns:
        --------
                    { float }          : Suspicion score [0.0, 1.0]
        """
        # Invert and scale: higher ratio = lower suspicion
        # Real photos typically have ratio > 0.85 & AI images typically have ratio < 0.75
        if (eigenvalue_ratio >= GRADIENT_FIELD_PCA_PARAMS.EIGENVALUE_RATIO_THRESHOLD):
            # Strong gradient alignment = likely real
            suspicion = max(0.0, (1.0 - eigenvalue_ratio) * 2.0)

        else:
            # Weak alignment = suspicious
            suspicion = 1.0 - (eigenvalue_ratio / GRADIENT_FIELD_PCA_PARAMS.EIGENVALUE_RATIO_THRESHOLD)
        
        return float(np.clip(suspicion, 0.0, 1.0))