src/utils/visual_error_detection.py

"""

Visual Error Detection Utilities for Manim Code Analysis



This module provides utilities for detecting and analyzing visual errors in Manim animations,

specifically focusing on element overlap, positioning issues, and spatial constraint violations.

"""

import re
import logging
from typing import Dict, List, Tuple, Any, Optional
from pathlib import Path

logger = logging.getLogger(__name__)

# Visual error detection patterns
VISUAL_ERROR_PATTERNS = {
    'overlap_keywords': [
        'overlap', 'overlapping', 'collision', 'colliding', 'obscured', 'hidden',
        'blocked', 'covering', 'covered', 'behind', 'on top of'
    ],
    'boundary_keywords': [
        'out of bounds', 'outside frame', 'clipped', 'cut off', 'beyond edge',
        'outside safe area', 'margin violation', 'boundary violation'
    ],
    'spacing_keywords': [
        'too close', 'insufficient spacing', 'cramped', 'crowded', 'bunched up',
        'spacing violation', 'minimum distance', 'tight spacing'
    ],
    'positioning_keywords': [
        'misaligned', 'mispositioned', 'wrong position', 'incorrect placement',
        'poor arrangement', 'bad layout', 'disorganized'
    ]
}

# Critical visual issues that require immediate fixing
CRITICAL_VISUAL_ISSUES = [
    'text completely obscured',
    'formula unreadable',
    'important element hidden',
    'content outside frame',
    'major overlap',
    'critical positioning error'
]

# Safe area and spacing constraints (Manim units)
VISUAL_CONSTRAINTS = {
    'safe_area_margin': 0.5,  # Units from frame edge
    'minimum_spacing': 0.3,   # Units between elements
    'frame_width': 14.22,     # Manim frame width
    'frame_height': 8.0,      # Manim frame height
    'center_x': 0.0,          # Frame center X
    'center_y': 0.0,          # Frame center Y
    'x_bounds': (-7.0, 7.0),  # Safe X coordinate range
    'y_bounds': (-4.0, 4.0)   # Safe Y coordinate range
}

class VisualErrorDetector:
    """Utility class for detecting and categorizing visual errors in VLM responses."""
    
    def __init__(self):
        self.error_patterns = VISUAL_ERROR_PATTERNS
        self.critical_issues = CRITICAL_VISUAL_ISSUES
        self.constraints = VISUAL_CONSTRAINTS
    
    def detect_error_types(self, analysis_text: str) -> Dict[str, List[str]]:
        """

        Detect different types of visual errors from VLM analysis text.

        

        Args:

            analysis_text: Raw text from VLM visual analysis

            

        Returns:

            Dictionary categorizing detected errors by type

        """
        errors = {
            'overlap_errors': [],
            'boundary_errors': [],
            'spacing_errors': [],
            'positioning_errors': [],
            'critical_errors': []
        }
        
        analysis_lower = analysis_text.lower()
        
        # Check for overlap errors
        for keyword in self.error_patterns['overlap_keywords']:
            if keyword in analysis_lower:
                errors['overlap_errors'].append(self._extract_error_context(analysis_text, keyword))
        
        # Check for boundary errors
        for keyword in self.error_patterns['boundary_keywords']:
            if keyword in analysis_lower:
                errors['boundary_errors'].append(self._extract_error_context(analysis_text, keyword))
        
        # Check for spacing errors
        for keyword in self.error_patterns['spacing_keywords']:
            if keyword in analysis_lower:
                errors['spacing_errors'].append(self._extract_error_context(analysis_text, keyword))
        
        # Check for positioning errors
        for keyword in self.error_patterns['positioning_keywords']:
            if keyword in analysis_lower:
                errors['positioning_errors'].append(self._extract_error_context(analysis_text, keyword))
        
        # Check for critical issues
        for issue in self.critical_issues:
            if issue in analysis_lower:
                errors['critical_errors'].append(self._extract_error_context(analysis_text, issue))
        
        # Remove empty entries and duplicates
        for error_type in errors:
            errors[error_type] = list(set([e for e in errors[error_type] if e]))
        
        return errors
    
    def _extract_error_context(self, text: str, keyword: str, context_length: int = 100) -> str:
        """

        Extract context around a detected error keyword.

        

        Args:

            text: Full analysis text

            keyword: Error keyword found

            context_length: Characters to include around keyword

            

        Returns:

            Context string around the error keyword

        """
        try:
            # Find keyword position (case insensitive)
            lower_text = text.lower()
            keyword_pos = lower_text.find(keyword.lower())
            
            if keyword_pos == -1:
                return keyword
            
            # Extract context around keyword
            start = max(0, keyword_pos - context_length // 2)
            end = min(len(text), keyword_pos + len(keyword) + context_length // 2)
            
            context = text[start:end].strip()
            
            # Clean up context
            context = re.sub(r'\s+', ' ', context)
            
            return context
        except Exception as e:
            logger.warning(f"Error extracting context for keyword '{keyword}': {e}")
            return keyword
    
    def categorize_severity(self, errors: Dict[str, List[str]]) -> Dict[str, str]:
        """

        Categorize the severity of detected visual errors.

        

        Args:

            errors: Dictionary of detected errors by type

            

        Returns:

            Dictionary mapping error types to severity levels

        """
        severity_map = {}
        
        # Critical errors are always high severity
        if errors['critical_errors']:
            severity_map['critical'] = 'HIGH'
        
        # Overlap errors can vary in severity
        if errors['overlap_errors']:
            # Check if any overlap errors mention important elements
            important_keywords = ['text', 'formula', 'equation', 'title', 'label']
            has_important_overlap = any(
                any(keyword in error.lower() for keyword in important_keywords)
                for error in errors['overlap_errors']
            )
            severity_map['overlap'] = 'HIGH' if has_important_overlap else 'MEDIUM'
        
        # Boundary errors are typically medium to high severity
        if errors['boundary_errors']:
            severity_map['boundary'] = 'MEDIUM'
        
        # Spacing errors are usually low to medium severity
        if errors['spacing_errors']:
            severity_map['spacing'] = 'LOW'
        
        # Positioning errors vary based on context
        if errors['positioning_errors']:
            severity_map['positioning'] = 'MEDIUM'
        
        return severity_map
    
    def generate_fix_suggestions(self, errors: Dict[str, List[str]]) -> List[str]:
        """

        Generate specific code fix suggestions based on detected errors.

        

        Args:

            errors: Dictionary of detected errors by type

            

        Returns:

            List of specific fix suggestions

        """
        suggestions = []
        
        if errors['overlap_errors']:
            suggestions.extend([
                "Use `.next_to()` method to position elements relative to each other with proper spacing",
                "Apply `buff` parameter in positioning methods to ensure minimum 0.3 unit spacing",
                "Reorganize elements into VGroups for better spatial management",
                "Use `bring_to_front()` or `bring_to_back()` to manage z-order layering"
            ])
        
        if errors['boundary_errors']:
            suggestions.extend([
                "Ensure all elements are positioned within safe area bounds (-7 to 7 for X, -4 to 4 for Y)",
                "Use `move_to(ORIGIN)` and then apply relative positioning to keep elements centered",
                "Check element sizes and scale them down if they extend beyond frame boundaries",
                "Apply safe area margins of 0.5 units from frame edges"
            ])
        
        if errors['spacing_errors']:
            suggestions.extend([
                "Use `buff=0.3` or higher in `.next_to()` methods for proper spacing",
                "Apply `.shift()` method to adjust element positions for better spacing",
                "Consider using `.arrange()` method for VGroups to maintain consistent spacing",
                "Verify minimum 0.3 unit spacing between all visual elements"
            ])
        
        if errors['positioning_errors']:
            suggestions.extend([
                "Use relative positioning methods exclusively: `.next_to()`, `.align_to()`, `.shift()`",
                "Position elements relative to ORIGIN, other objects, or scene margins",
                "Ensure logical flow and visual hierarchy in element arrangement",
                "Group related elements using VGroup for coordinated positioning"
            ])
        
        # Remove duplicates while preserving order
        unique_suggestions = []
        for suggestion in suggestions:
            if suggestion not in unique_suggestions:
                unique_suggestions.append(suggestion)
        
        return unique_suggestions
    
    def validate_manim_constraints(self, code: str) -> Dict[str, List[str]]:
        """

        Validate Manim code against spatial constraints.

        

        Args:

            code: Manim code to validate

            

        Returns:

            Dictionary of constraint violations found in code

        """
        violations = {
            'absolute_coordinates': [],
            'unsafe_positioning': [],
            'missing_spacing': [],
            'out_of_bounds': []
        }
        
        lines = code.split('\n')
        
        for i, line in enumerate(lines, 1):
            # Check for absolute coordinates (potential issues)
            if re.search(r'move_to\s*\(\s*[-+]?\d+\.?\d*\s*,\s*[-+]?\d+\.?\d*', line):
                violations['absolute_coordinates'].append(f"Line {i}: {line.strip()}")
            
            # Check for potentially unsafe positioning
            if re.search(r'shift\s*\(\s*[^)]*[5-9]\d*', line):
                violations['unsafe_positioning'].append(f"Line {i}: Large shift detected - {line.strip()}")
            
            # Check for missing buff parameters in next_to calls
            if 'next_to' in line and 'buff' not in line:
                violations['missing_spacing'].append(f"Line {i}: Missing buff parameter - {line.strip()}")
            
            # Check for coordinates that might be out of bounds
            coord_matches = re.findall(r'[-+]?\d+\.?\d*', line)
            for coord in coord_matches:
                try:
                    val = float(coord)
                    if abs(val) > 10:  # Potentially problematic large coordinates
                        violations['out_of_bounds'].append(f"Line {i}: Large coordinate {val} - {line.strip()}")
                except ValueError:
                    continue
        
        return violations


def create_visual_fix_context(

    errors: Dict[str, List[str]], 

    suggestions: List[str], 

    constraints: Dict[str, Any]

) -> str:
    """

    Create a formatted context string for visual fix operations.

    

    Args:

        errors: Detected visual errors

        suggestions: Fix suggestions

        constraints: Visual constraints to enforce

        

    Returns:

        Formatted context string for LLM prompt

    """
    context_parts = []
    
    if any(errors.values()):
        context_parts.append("**DETECTED VISUAL ERRORS:**")
        
        for error_type, error_list in errors.items():
            if error_list:
                error_type_formatted = error_type.replace('_', ' ').title()
                context_parts.append(f"\n{error_type_formatted}:")
                for error in error_list:
                    context_parts.append(f"  - {error}")
    
    if suggestions:
        context_parts.append("\n\n**RECOMMENDED FIXES:**")
        for i, suggestion in enumerate(suggestions, 1):
            context_parts.append(f"{i}. {suggestion}")
    
    context_parts.append("\n\n**SPATIAL CONSTRAINTS TO ENFORCE:**")
    context_parts.append(f"- Safe area margin: {constraints['safe_area_margin']} units from edges")
    context_parts.append(f"- Minimum spacing: {constraints['minimum_spacing']} units between elements")
    context_parts.append(f"- X coordinate bounds: {constraints['x_bounds']}")
    context_parts.append(f"- Y coordinate bounds: {constraints['y_bounds']}")
    
    return '\n'.join(context_parts)


# Export main utilities
__all__ = [
    'VisualErrorDetector',
    'VISUAL_ERROR_PATTERNS',
    'CRITICAL_VISUAL_ISSUES', 
    'VISUAL_CONSTRAINTS',
    'create_visual_fix_context'
]