import logging import traceback import random from typing import Dict, List, Optional, Any from cultural_templates import CULTURAL_TEMPLATES class CulturalContextError(Exception): """文化語境分析過程中的自定義異常""" pass class CulturalContextAnalyzer: """ 文化語境分析器 - 檢測場景中的文化特徵並生成相關的描述 該類別負責識別場景中的文化語境線索，包括建築風格、標誌特徵 和物件配置，然後生成適當的文化描述元素。 """ def __init__(self, cultural_templates: Optional[Dict] = None): """ 初始化文化語境分析器 Args: cultural_templates: 可選的自定義文化模板，如果提供則會與默認模板合併 """ self.logger = logging.getLogger(self.__class__.__name__) try: # 載入文化模板 self.cultural_templates = self._load_cultural_templates() # 如果提供了自定義模板，進行合併 if cultural_templates: self._merge_custom_templates(cultural_templates) # 初始化場景類型到文化語境的映射 self.scene_cultural_mapping = self._initialize_scene_cultural_mapping() self.logger.info("CulturalContextAnalyzer initialized with %d cultural templates", len(self.cultural_templates)) except Exception as e: error_msg = f"Failed to initialize CulturalContextAnalyzer: {str(e)}" self.logger.error(f"{error_msg}\n{traceback.format_exc()}") raise CulturalContextError(error_msg) from e def _load_cultural_templates(self) -> Dict: """ 載入文化模板 Returns: Dict: 文化模板字典 Raises: CulturalContextError: 當模板載入失敗時 """ try: self.logger.debug("Loading cultural templates") # 從配置模組載入文化模板 templates = CULTURAL_TEMPLATES.copy() # 確保模板結構正確 self._validate_cultural_templates(templates) # 如果沒有載入到模板，使用默認模板 if not templates: self.logger.warning("No cultural templates loaded, using defaults") templates = self._get_default_cultural_templates() self.logger.debug("Successfully loaded %d cultural template categories", len(templates)) return templates except ImportError as e: self.logger.warning(f"Failed to import cultural templates: {str(e)}, using defaults") return self._get_default_cultural_templates() except Exception as e: error_msg = f"Error loading cultural templates: {str(e)}" self.logger.error(f"{error_msg}\n{traceback.format_exc()}") raise CulturalContextError(error_msg) from e def _get_default_cultural_templates(self) -> Dict: """ 獲取默認文化模板 Returns: Dict: 默認文化模板字典 """ return { "asian": { "elements": [ "traditional architectural elements", "cultural signage", "Asian design features", "oriental decorative patterns", "traditional building materials", "characteristic roofline styles", "cultural landscaping elements" ], "description": "The scene displays distinctive Asian cultural characteristics with {elements}." }, "european": { "elements": [ "classical architecture", "European design elements", "historic features", "traditional stonework", "characteristic window styles", "ornamental facades", "heritage building elements" ], "description": "The scene exhibits European architectural and cultural elements including {elements}." }, "american": { "elements": [ "modern architectural styles", "contemporary design features", "commercial signage", "urban planning elements", "standardized building designs" ], "description": "The scene shows American urban characteristics featuring {elements}." }, "mediterranean": { "elements": [ "coastal architectural styles", "warm climate adaptations", "traditional building colors", "characteristic outdoor spaces" ], "description": "The scene reflects Mediterranean cultural influences with {elements}." } } def _validate_cultural_templates(self, templates: Dict): """ 驗證文化模板結構 Args: templates: 要驗證的模板字典 Raises: CulturalContextError: 當模板結構無效時 """ try: for culture, template_data in templates.items(): if not isinstance(template_data, dict): self.logger.warning(f"Invalid cultural template structure for '{culture}': not a dictionary") continue required_keys = ["elements", "description"] for key in required_keys: if key not in template_data: self.logger.warning(f"Missing required key '{key}' in cultural template '{culture}'") # 驗證元素列表 if "elements" in template_data: if not isinstance(template_data["elements"], list): self.logger.warning(f"Cultural template '{culture}' elements should be a list") elif not template_data["elements"]: self.logger.warning(f"Cultural template '{culture}' has empty elements list") # 驗證描述模板 if "description" in template_data: if not isinstance(template_data["description"], str): self.logger.warning(f"Cultural template '{culture}' description should be a string") elif "{elements}" not in template_data["description"]: self.logger.warning(f"Cultural template '{culture}' description missing {{elements}} placeholder") self.logger.debug("Cultural templates validation completed") except Exception as e: self.logger.warning(f"Error validating cultural templates: {str(e)}") def _merge_custom_templates(self, custom_templates: Dict): """ 合併自定義文化模板 Args: custom_templates: 自定義模板字典 """ try: for culture, template_data in custom_templates.items(): if culture in self.cultural_templates: # 合併現有文化的模板 if isinstance(self.cultural_templates[culture], dict) and isinstance(template_data, dict): # 合併元素列表 if "elements" in template_data and "elements" in self.cultural_templates[culture]: existing_elements = self.cultural_templates[culture]["elements"] new_elements = template_data["elements"] if isinstance(existing_elements, list) and isinstance(new_elements, list): self.cultural_templates[culture]["elements"] = existing_elements + new_elements # 更新其他鍵值 for key, value in template_data.items(): if key != "elements": self.cultural_templates[culture][key] = value else: self.cultural_templates[culture] = template_data else: # 添加新的文化模板 self.cultural_templates[culture] = template_data self.logger.debug(f"Merged custom template for culture: {culture}") self.logger.info("Successfully merged custom cultural templates") except Exception as e: self.logger.warning(f"Error merging custom cultural templates: {str(e)}") def _initialize_scene_cultural_mapping(self) -> Dict[str, str]: """ 初始化場景類型到文化語境的display Returns: Dict[str, str]: 場景類型到文化語境的映射字典 """ return { "asian_commercial_street": "asian", "asian_night_market": "asian", "asian_temple_area": "asian", "chinese_restaurant": "asian", "japanese_restaurant": "asian", "korean_restaurant": "asian", "european_plaza": "european", "european_cafe": "european", "mediterranean_restaurant": "mediterranean", "american_diner": "american", "american_fast_food": "american" } def detect_cultural_context(self, scene_type: str, detected_objects: List[Dict]) -> Optional[str]: """ 檢測場景的文化語境 Args: scene_type: 識別的場景類型 detected_objects: 檢測到的物件列表 Returns: Optional[str]: 檢測到的文化語境（asian, european等）或None """ try: self.logger.debug(f"Detecting cultural context for scene_type: {scene_type}") # 檢查場景類型是否直接指示文化語境 if scene_type in self.scene_cultural_mapping: cultural_context = self.scene_cultural_mapping[scene_type] self.logger.debug(f"Direct cultural mapping found: {scene_type} -> {cultural_context}") return cultural_context # 基於場景類型名稱的模式匹配 cultural_context = self._detect_from_scene_name_patterns(scene_type) if cultural_context: self.logger.debug(f"Cultural context detected from name patterns: {cultural_context}") return cultural_context # 基於檢測物件的文化特徵分析 cultural_context = self._detect_from_object_analysis(detected_objects) if cultural_context: self.logger.debug(f"Cultural context detected from object analysis: {cultural_context}") return cultural_context # 沒有檢測到特定文化語境 self.logger.debug("No specific cultural context detected") return None except Exception as e: self.logger.warning(f"Error detecting cultural context: {str(e)}") return None def _detect_from_scene_name_patterns(self, scene_type: str) -> Optional[str]: """ 基於場景類型名稱模式檢測文化語境 Args: scene_type: 場景類型名稱 Returns: Optional[str]: 檢測到的文化語境或None """ try: scene_lower = scene_type.lower() # Asia asian_keywords = [ "asian", "chinese", "japanese", "korean", "thai", "vietnamese", "temple", "pagoda", "zen", "oriental", "bamboo", "tatami" ] # Europe european_keywords = [ "european", "french", "italian", "spanish", "german", "british", "plaza", "piazza", "cathedral", "gothic", "baroque", "renaissance", "cafe", "bistro", "pub" ] # 地中海文化 mediterranean_keywords = [ "mediterranean", "greek", "turkish", "coastal", "terrace", "villa", "courtyard" ] # 美國 american_keywords = [ "american", "diner", "fast_food", "mall", "suburban", "downtown", "strip_mall" ] # 檢查各文化的key word if any(keyword in scene_lower for keyword in asian_keywords): return "asian" elif any(keyword in scene_lower for keyword in european_keywords): return "european" elif any(keyword in scene_lower for keyword in mediterranean_keywords): return "mediterranean" elif any(keyword in scene_lower for keyword in american_keywords): return "american" return None except Exception as e: self.logger.warning(f"Error detecting cultural context from scene name patterns: {str(e)}") return None def _detect_from_object_analysis(self, detected_objects: List[Dict]) -> Optional[str]: """ 基於檢測物件分析文化特徵 Args: detected_objects: 檢測到的物件列表 Returns: Optional[str]: 檢測到的文化語境或None """ try: if not detected_objects: return None # 統計文化相關物件 cultural_indicators = { "asian": 0, "european": 0, "american": 0, "mediterranean": 0 } for obj in detected_objects: class_name = obj.get("class_name", "").lower() # Asia 特色 if any(indicator in class_name for indicator in [ "lantern", "chopsticks", "rice", "noodles", "tea", "bamboo", "pagoda", "shrine", "torii" ]): cultural_indicators["asian"] += 1 # 歐洲的特色 elif any(indicator in class_name for indicator in [ "wine", "cheese", "bread", "fountain", "column", "statue", "cathedral", "clock_tower" ]): cultural_indicators["european"] += 1 # 地中海的特色 elif any(indicator in class_name for indicator in [ "olive", "terracotta", "pergola", "villa", "coastal", "maritime" ]): cultural_indicators["mediterranean"] += 1 # 美國的特色 elif any(indicator in class_name for indicator in [ "burger", "pizza", "hotdog", "soda", "drive_through", "parking_lot" ]): cultural_indicators["american"] += 1 # 找出得分最高的文化語境 if max(cultural_indicators.values()) > 0: dominant_culture = max(cultural_indicators.items(), key=lambda x: x[1])[0] max_score = cultural_indicators[dominant_culture] # 需要至少2個指標物件才算有效檢測 if max_score >= 2: return dominant_culture return None except Exception as e: self.logger.warning(f"Error detecting cultural context from object analysis: {str(e)}") return None def generate_cultural_elements(self, cultural_context: str) -> str: """ 為檢測到的文化語境生成描述元素 Args: cultural_context: 檢測到的文化語境 Returns: str: 文化元素描述 Raises: CulturalContextError: 當文化元素生成失敗時 """ try: if not cultural_context: return "" self.logger.debug(f"Generating cultural elements for context: {cultural_context}") # 獲取該文化語境的模板 if cultural_context not in self.cultural_templates: self.logger.warning(f"No template found for cultural context: {cultural_context}") return "" template = self.cultural_templates[cultural_context] elements = template.get("elements", []) if not elements: self.logger.warning(f"No elements found for cultural context: {cultural_context}") return "" # 選擇1-2個隨機元素 num_elements = min(len(elements), random.randint(1, 2)) selected_elements = random.sample(elements, num_elements) # 格式化元素列表 if len(selected_elements) == 1: elements_text = selected_elements[0] else: elements_text = " and ".join(selected_elements) # 填充模板 description_template = template.get("description", "") if not description_template: return f"The scene displays {cultural_context} cultural characteristics." # 替換佔位符 cultural_description = description_template.format(elements=elements_text) self.logger.debug(f"Generated cultural description: {cultural_description}") return cultural_description except Exception as e: error_msg = f"Error generating cultural elements for context '{cultural_context}': {str(e)}" self.logger.error(f"{error_msg}\n{traceback.format_exc()}") raise CulturalContextError(error_msg) from e def get_cultural_template(self, cultural_context: str) -> Dict[str, Any]: """ 獲取指定文化語境的模板 Args: cultural_context: 文化語境名稱 Returns: Dict[str, Any]: 文化模板字典 """ try: if cultural_context in self.cultural_templates: return self.cultural_templates[cultural_context].copy() # 返回備用模板 self.logger.warning(f"Cultural template not found for '{cultural_context}', using fallback") return { "elements": ["various cultural elements"], "description": f"The scene displays {cultural_context} cultural characteristics." } except Exception as e: self.logger.warning(f"Error getting cultural template for '{cultural_context}': {str(e)}") return { "elements": ["various elements"], "description": "The scene displays cultural characteristics." } def add_cultural_template(self, cultural_context: str, template: Dict[str, Any]): """ 添加或更新文化模板 Args: cultural_context: 文化語境名稱 template: 文化模板字典 Raises: CulturalContextError: 當模板格式無效時 """ try: # 驗證模板格式 if not isinstance(template, dict): raise CulturalContextError("Template must be a dictionary") required_keys = ["elements", "description"] for key in required_keys: if key not in template: raise CulturalContextError(f"Template missing required key: {key}") if not isinstance(template["elements"], list): raise CulturalContextError("Template 'elements' must be a list") if not isinstance(template["description"], str): raise CulturalContextError("Template 'description' must be a string") # 添加模板 self.cultural_templates[cultural_context] = template.copy() self.logger.info(f"Added cultural template for context: {cultural_context}") except CulturalContextError: raise except Exception as e: error_msg = f"Error adding cultural template for '{cultural_context}': {str(e)}" self.logger.error(f"{error_msg}\n{traceback.format_exc()}") raise CulturalContextError(error_msg) from e def get_supported_cultures(self) -> List[str]: """ 獲取所有支援的文化語境列表 Returns: List[str]: 支援的文化語境名稱列表 """ return list(self.cultural_templates.keys()) def has_cultural_context(self, cultural_context: str) -> bool: """ 檢查是否支援指定的文化語境 Args: cultural_context: 文化語境名稱 Returns: bool: 是否支援該文化語境 """ return cultural_context in self.cultural_templates def analyze_cultural_diversity(self, detected_objects: List[Dict]) -> Dict[str, int]: """ 分析場景中的文化多樣性 Args: detected_objects: 檢測到的物件列表 Returns: Dict[str, int]: 各文化語境的指標物件計數 """ try: cultural_scores = {culture: 0 for culture in self.cultural_templates.keys()} if not detected_objects: return cultural_scores for obj in detected_objects: class_name = obj.get("class_name", "").lower() # 為每個文化語境計算指標分數 for culture in cultural_scores: if self._is_cultural_indicator(class_name, culture): cultural_scores[culture] += 1 self.logger.debug(f"Cultural diversity analysis: {cultural_scores}") return cultural_scores except Exception as e: self.logger.warning(f"Error analyzing cultural diversity: {str(e)}") return {culture: 0 for culture in self.cultural_templates.keys()} def _is_cultural_indicator(self, object_name: str, culture: str) -> bool: """ 檢查物件名稱是否為特定文化的指標 Args: object_name: 物件名稱 culture: 文化語境 Returns: bool: 是否為該文化的指標物件 """ try: cultural_keywords = { "asian": [ "lantern", "chopsticks", "rice", "noodles", "tea", "bamboo", "pagoda", "shrine", "torii", "kimono", "sushi", "ramen", "dim_sum" ], "european": [ "wine", "cheese", "bread", "fountain", "column", "statue", "cathedral", "clock_tower", "baguette", "croissant", "espresso", "gelato" ], "mediterranean": [ "olive", "terracotta", "pergola", "villa", "coastal", "maritime", "cypress", "vineyard" ], "american": [ "burger", "pizza", "hotdog", "soda", "drive_through", "parking_lot", "diner", "strip_mall", "suburb" ] } if culture not in cultural_keywords: return False keywords = cultural_keywords[culture] return any(keyword in object_name for keyword in keywords) except Exception as e: self.logger.warning(f"Error checking cultural indicator for {object_name}, {culture}: {str(e)}") return False def get_template_summary(self) -> Dict[str, Dict[str, Any]]: """ 獲取所有文化模板的摘要信息 Returns: Dict[str, Dict[str, Any]]: 文化模板摘要 """ try: summary = {} for culture, template in self.cultural_templates.items(): summary[culture] = { "element_count": len(template.get("elements", [])), "has_description": bool(template.get("description", "")), "sample_elements": template.get("elements", [])[:3] # 前3個元素作為樣本 } return summary except Exception as e: self.logger.warning(f"Error generating template summary: {str(e)}") return {}