Update deformes4D_engine.py

deformes4D_engine.py

@@ -29,7 +29,11 @@ logger = logging.getLogger(__name__)
 
 @dataclass
 class LatentConditioningItem:
-    """Representa uma âncora de condicionamento no espaço latente para a Câmera (Ψ)."""
+    """
+    Representa uma âncora de condicionamento no espaço latente para a Câmera (Ψ).
+    Cada item define um tensor, o frame exato onde sua influência é máxima,
+    e a força dessa influência.
+    """
     latent_tensor: torch.Tensor
     media_frame_number: int
     conditioning_strength: float
@@ -37,8 +41,9 @@ class LatentConditioningItem:
 class Deformes4DEngine:
     """
     Implementa a Câmera (Ψ) e o Destilador (Δ) da arquitetura ADUC-SDR.
-    É responsável pela execução da geração de fragmentos de vídeo e pela
-    extração dos contextos causais (Eco e Déjà-Vu).
+    Esta classe é o coração da execução, responsável pela geração de fragmentos de vídeo
+    e pela extração e aplicação dos contextos causais (Eco e Déjà-Vu) que garantem
+    a coerência de longa duração.
     """
     def __init__(self, ltx_manager, workspace_dir="deformes_workspace"):
         self.ltx_manager = ltx_manager
@@ -49,6 +54,7 @@ class Deformes4DEngine:
 
     @property
     def vae(self):
+        """Acessa o decodificador VAE de forma lazy, garantindo que ele esteja na GPU."""
         if self._vae is None:
             self._vae = self.ltx_manager.workers[0].pipeline.vae
         self._vae.to(self.device); self._vae.eval()
@@ -57,23 +63,28 @@ class Deformes4DEngine:
     # MÉTODOS AUXILIARES DE MANIPULAÇÃO DE DADOS E VÍDEO
     
     def save_latent_tensor(self, tensor: torch.Tensor, path: str):
+        """Salva um tensor PyTorch no disco."""
         torch.save(tensor.cpu(), path)
 
     def load_latent_tensor(self, path: str) -> torch.Tensor:
+        """Carrega um tensor PyTorch do disco para o dispositivo correto."""
         return torch.load(path, map_location=self.device)
 
     @torch.no_grad()
     def pixels_to_latents(self, tensor: torch.Tensor) -> torch.Tensor:
+        """Converte um tensor de pixels (vídeo) para o espaço latente usando o VAE."""
         tensor = tensor.to(self.device, dtype=self.vae.dtype)
         return vae_encode(tensor, self.vae, vae_per_channel_normalize=True)
 
     @torch.no_grad()
     def latents_to_pixels(self, latent_tensor: torch.Tensor, decode_timestep: float = 0.05) -> torch.Tensor:
+        """Converte um tensor latente de volta para um tensor de pixels (vídeo) usando o VAE."""
         latent_tensor = latent_tensor.to(self.device, dtype=self.vae.dtype)
         timestep_tensor = torch.tensor([decode_timestep] * latent_tensor.shape[0], device=self.device, dtype=latent_tensor.dtype)
         return vae_decode(latent_tensor, self.vae, is_video=True, timestep=timestep_tensor, vae_per_channel_normalize=True)
 
     def save_video_from_tensor(self, video_tensor: torch.Tensor, path: str, fps: int = 24):
+        """Salva um tensor de pixels como um arquivo de vídeo MP4."""
         if video_tensor is None or video_tensor.ndim != 5 or video_tensor.shape[2] == 0:
             logger.warning(f"Tentativa de salvar um tensor de vídeo inválido em {path}. Abortando.")
             return
@@ -84,11 +95,13 @@ class Deformes4DEngine:
             for frame in video_np: writer.append_data(frame)
 
     def _preprocess_image_for_latent_conversion(self, image: Image.Image, target_resolution: tuple) -> Image.Image:
+        """Redimensiona uma imagem para a resolução alvo antes de convertê-la para latente."""
         if image.size != target_resolution:
             return ImageOps.fit(image, target_resolution, Image.Resampling.LANCZOS)
         return image
 
     def pil_to_latent(self, pil_image: Image.Image) -> torch.Tensor:
+        """Converte uma imagem PIL para um tensor latente."""
         image_np = np.array(pil_image).astype(np.float32) / 255.0
         tensor = torch.from_numpy(image_np).permute(2, 0, 1).unsqueeze(0).unsqueeze(2)
         tensor = (tensor * 2.0) - 1.0
@@ -109,7 +122,11 @@ class Deformes4DEngine:
             return None
 
     def _trim_last_frame_ffmpeg(self, input_path: str, output_path: str) -> bool:
-        """Cria uma cópia de um vídeo, removendo o último frame."""
+        """
+        Cria uma cópia de um vídeo, removendo o último frame.
+        Esta etapa é CRUCIAL para resolver o problema do "frame n+1", onde o VAE
+        gera um frame extra, o que causaria "soluços" na concatenação.
+        """
         frame_count = self._get_video_frame_count(input_path)
         if frame_count is None or frame_count < 2:
             logger.warning(f"Não foi possível podar o último frame de {input_path}. O vídeo é muito curto ou ocorreu um erro.")
@@ -130,7 +147,8 @@ class Deformes4DEngine:
 
     def _generate_video_from_latents(self, latent_tensor, base_name: str) -> str:
         """
-        Gera um vídeo a partir de latentes, podando o último frame para garantir concatenação limpa.
+        Gera um vídeo a partir de latentes e aplica a poda do último frame.
+        Este processo de duas etapas garante que os fragmentos para concatenação sejam perfeitamente limpos.
         """
         untrimmed_video_path = os.path.join(self.workspace_dir, f"{base_name}_untrimmed.mp4")
         trimmed_video_path = os.path.join(self.workspace_dir, f"{base_name}.mp4")
@@ -155,7 +173,7 @@ class Deformes4DEngine:
         return trimmed_video_path
 
     def concatenate_videos_ffmpeg(self, video_paths: list[str], output_path: str) -> str:
-        """Concatena uma lista de arquivos de vídeo em um único arquivo usando FFmpeg."""
+        """Concatena uma lista de arquivos de vídeo em um único arquivo usando FFmpeg com o método 'concat'."""
         if not video_paths:
             raise gr.Error("Nenhum fragmento de vídeo para montar.")
         
@@ -181,11 +199,23 @@ class Deformes4DEngine:
                             handler_strength: float, destination_convergence_strength: float, 
                             video_resolution: int, use_continuity_director: bool, 
                             progress: gr.Progress = gr.Progress()):
+        """
+        Orquestra a geração de um filme completo, fragmento por fragmento, seguindo os princípios da ADUC-SDR.
+        
+        O processo para cada fragmento é:
+        1.  Consulta ao Maestro (Γ) para obter a intenção narrativa (motion_prompt).
+        2.  Montagem das âncoras causais {C, D, K} para a Câmera (Ψ).
+        3.  Execução da Geração Exploratória para criar o tensor bruto (V_bruto).
+        4.  Execução do Ciclo de Poda Causal pelo Destilador (Δ) para extrair o Eco (C) e o Déjà-Vu (D) para o próximo ciclo
+            e para definir o tensor de vídeo canônico (V_final).
+        5.  Renderização do fragmento final e, opcionalmente, de um clipe de diagnóstico do Eco.
+        6.  Repetição até que todos os keyframes sejam processados, seguida da montagem final.
+        """
         
         # 1. Definição dos Parâmetros da Geração com base na Tese
         FPS = 24
-        FRAMES_PER_LATENT_CHUNK = 8
-        ECO_LATENT_CHUNKS = 2
+        FRAMES_PER_LATENT_CHUNK = 8  # Fator de conversão: 1 índice na dimensão de tempo do tensor latente = 8 frames de vídeo.
+        ECO_LATENT_CHUNKS = 2        # Número de chunks latentes que compõem o Eco Causal (C) para carregar a inércia.
         
         total_frames_brutos = self._quantize_to_multiple(int(seconds_per_fragment * FPS), FRAMES_PER_LATENT_CHUNK)
         total_latents_brutos = total_frames_brutos // FRAMES_PER_LATENT_CHUNK
@@ -244,11 +274,11 @@ class Deformes4DEngine:
             conditioning_items = []
             logger.info("  [Ψ.1] Montando âncoras causais...")
             
-            if eco_latent_for_next_loop is None:
-               logger.info("    - Primeiro fragmento: Usando Keyframe inicial como âncora de partida.")
+            if eco_latent_for_next_loop is None: # Lógica para o primeiro fragmento ou um corte ("cut")
+               logger.info("    - Primeiro fragmento ou corte: Usando Keyframe inicial como âncora de partida.")
                img_start = self._preprocess_image_for_latent_conversion(Image.open(start_keyframe_path).convert("RGB"), target_resolution_tuple)
                conditioning_items.append(LatentConditioningItem(self.pil_to_latent(img_start), 0, 1.0))
-            else:
+            else: # Lógica para fragmentos contínuos
                logger.info("    - Âncora 1: Eco Causal (C) - Herança do passado.")
                conditioning_items.append(LatentConditioningItem(eco_latent_for_next_loop, 0, 1.0))
                logger.info("    - Âncora 2: Déjà-Vu (D) - Memória de um futuro idealizado.")
@@ -264,31 +294,31 @@ class Deformes4DEngine:
             latents_brutos = self._generate_latent_tensor_internal(conditioning_items, current_ltx_params, target_resolution_tuple, total_frames_brutos)
             logger.info(f"    - Geração concluída. Tensor latente bruto (V_bruto) criado com shape: {latents_brutos.shape}.")
 
-            # 3.4. Execução do Destilador (Δ): Implementação do Ciclo de Poda Causal (com workaround empírico)
+            # 3.4. Execução do Destilador (Δ): Implementação do Ciclo de Poda Causal com workaround empírico.
+            # Esta lógica foi refinada para contornar um bug do motor de difusão que gera os 2 primeiros chunks com
+            # artefatos, garantindo um resultado final limpo e mantendo a transferência causal.
             logger.info(f"  [Δ] Destilador (Δ) executando o Ciclo de Poda Causal...")
-
-
-            last_trim = latents_brutos[:, :, -(latents_a_podar+1):, :, :].clone()
-            eco_latent_for_next_loop = last_trim[:, :, :2, :, :].clone()   
-            dejavu_latent_for_next_loop = last_trim[:, :, -1:, :, :].clone()
             
-            latents_video = latents_brutos[:, :, :-(latents_a_podar-1), :, :].clone()
-            latents_video = latents_video[:, :, 1:, :, :]
-
-            logger.info(f"  [Δ] latents_video {latents_video.shape}")
-           
+            # Pega uma fatia da cauda de V_bruto que é grande o suficiente para conter o Eco e o Déjà-Vu.
+            last_trim = latents_brutos[:, :, -(latents_a_podar + 2):, :, :].clone()
             
-            #last_trim = latents_brutos[:, :, -(latents_a_podar + 2):, :, :].clone()
-            #eco_latent_for_next_loop = last_trim[:, :, :ECO_LATENT_CHUNKS, :, :].clone()
-            #dejavu_latent_for_next_loop = last_trim[:, :, -1:, :, :].clone()
+            # Extrai o Eco (C) dos 2 chunks iniciais desta fatia.
+            eco_latent_for_next_loop = last_trim[:, :, :ECO_LATENT_CHUNKS, :, :].clone()
             
-            #latents_video = latents_brutos[:, :, :-(latents_a_podar + 2), :, :].clone()
-            #latents_video = latents_video[:, :, 2:, :, :]
+            # Extrai o Déjà-Vu (D) do último chunk absoluto desta fatia (que é também o último de V_bruto).
+            dejavu_latent_for_next_loop = last_trim[:, :, -1:, :, :].clone()
+            
+            # Define o tensor para o vídeo final (V_final) removendo a cauda inteira, incluindo os chunks usados pelo Eco.
+            latents_video = latents_brutos[:, :, :-(latents_a_podar + 2), :, :].clone()
+            
+            # Remove cirurgicamente os 2 primeiros chunks instáveis do vídeo final.
+            latents_video = latents_video[:, :, 2:, :, :]
 
-            #logger.info(f"  [Δ] Shape do tensor para vídeo final: {latents_video.shape}")
+            logger.info(f"  [Δ] Shape do tensor para vídeo final: {latents_video.shape}")
             logger.info(f"    - (Δ.1) Déjà-Vu (D) destilado. Shape: {dejavu_latent_for_next_loop.shape}")
             logger.info(f"    - (Δ.2) Eco Causal (C) extraído. Shape: {eco_latent_for_next_loop.shape}")
 
+            # Se o Maestro decidiu por um "corte", a memória causal é resetada para o próximo ciclo.
             if transition_type == "cut":
                 logger.warning("  - DECISÃO DO MAESTRO: Corte ('cut'). Resetando a memória causal (Eco e Déjà-Vu).")
                 eco_latent_for_next_loop = None
@@ -300,15 +330,14 @@ class Deformes4DEngine:
             video_clips_paths.append(video_path)
             logger.info(f"--- FRAGMENTO {fragment_index} FINALIZADO E SALVO EM: {video_path} ---")
 
-            # Bloco de Diagnóstico: Gera um vídeo a partir do tensor do Eco
+            # Bloco de Diagnóstico: Gera um vídeo a partir do tensor do Eco para validação visual.
             if eco_latent_for_next_loop is not None:
                 logger.info("--- GERANDO VÍDEO DE DIAGNÓSTICO DO ECO CAUSAL ---")
                 eco_base_name = f"fragment_{fragment_index}_eco_diagnostic_{int(time.time())}"
                 eco_video_path = self._generate_video_from_latents(eco_latent_for_next_loop, eco_base_name)
-                #video_clips_paths.append(eco_video_path)
+                video_clips_paths.append(eco_video_path)
                 logger.info(f"Vídeo de diagnóstico do Eco salvo em: {eco_video_path} e adicionado à concatenação.")
-                yield {"fragment_path": eco_video_path}
-           
+
             yield {"fragment_path": video_path}
                  
         # 4. Montagem Final do Filme
@@ -319,6 +348,7 @@ class Deformes4DEngine:
         yield {"final_path": final_movie_path}
 
     def _generate_latent_tensor_internal(self, conditioning_items, ltx_params, target_resolution, total_frames_to_generate):
+        """Função de baixo nível que invoca o motor de difusão para a geração do tensor latente."""
         final_ltx_params = {
             **ltx_params, 'width': target_resolution[0], 'height': target_resolution[1],
             'video_total_frames': total_frames_to_generate, 'video_fps': 24,
@@ -330,6 +360,7 @@ class Deformes4DEngine:
         return new_full_latents
 
     def _quantize_to_multiple(self, n, m):
+        """Garante que um número 'n' seja um múltiplo de 'm', necessário para o fatiamento de tensores."""
         if m == 0: return n
         quantized = int(round(n / m) * m)
         return m if n > 0 and quantized == 0 else quantized