Initial commit

.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+
+# Model checkpoints and data (downloaded from HuggingFace)
+checkpoints/
+*.pt
+*.pth
+*.ckpt
+*.safetensors
+
+# Output files
+outputs/
+*.ply
+*.mp4
+
+# Examples (if large)
+examples/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Gradio cache
+gradio_cached_examples/
+flagged/
+

README.md

@@ -10,4 +10,42 @@ pinned: false
 license: cc-by-nc-sa-4.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# FaceLift: Single Image 3D Face Reconstruction
+
+Transform a single portrait image into a complete 3D head model using multi-view diffusion and Gaussian Splatting.
+
+## Features
+
+- **Single Image Input**: Upload any portrait photo
+- **Automatic Face Detection**: Optional auto-cropping and alignment
+- **Multi-view Generation**: Creates 6 consistent views using diffusion models
+- **3D Reconstruction**: Generates high-quality 3D Gaussian splats
+- **Turntable Animation**: Exports rotating 360° video
+- **Downloadable Model**: Get the 3D model as a .ply file
+
+## Usage
+
+1. Upload a portrait image
+2. Adjust parameters (optional):
+   - Auto Cropping: Enable for automatic face detection
+   - Guidance Scale: Controls generation quality (default: 3.0)
+   - Random Seed: For reproducible results
+   - Generation Steps: Higher = better quality but slower
+3. Click Submit and wait for processing
+4. Download the 3D model or turntable video
+
+## Citation
+
+```
+@article{facelift2025,
+  title={FaceLift: Single Image 3D Face Reconstruction},
+  author={FaceLift Research Group},
+  year={2025}
+}
+```
+
+## License
+
+This software is free for non-commercial, research and evaluation use under the CC-BY-NC-SA-4.0 license.
+
+For commercial use inquiries, contact: wlyu3@ucmerced.edu

app.py

@@ -1,7 +1,272 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+
+"""
+FaceLift: Single Image 3D Face Reconstruction
+Generates 3D head models from single images using multi-view diffusion and GS-LRM.
+"""
+
+import json
+from pathlib import Path
+from datetime import datetime
+
 import gradio as gr
+import numpy as np
+import torch
+import yaml
+from easydict import EasyDict as edict
+from einops import rearrange
+from PIL import Image
+from huggingface_hub import snapshot_download
+
+from gslrm.model.gaussians_renderer import render_turntable, imageseq2video
+from mvdiffusion.pipelines.pipeline_mvdiffusion_unclip import StableUnCLIPImg2ImgPipeline
+from utils_folder.face_utils import preprocess_image, preprocess_image_without_cropping
+
+# HuggingFace repository configuration
+HF_REPO_ID = "wlyu/OpenFaceLift"
+
+def download_weights_from_hf() -> Path:
+    """Download model weights from HuggingFace if not already present.
+    
+    Returns:
+        Path to the downloaded repository
+    """
+    workspace_dir = Path(__file__).parent
+    
+    # Check if weights already exist locally
+    mvdiffusion_path = workspace_dir / "checkpoints/mvdiffusion/pipeckpts"
+    gslrm_path = workspace_dir / "checkpoints/gslrm/ckpt_0000000000021125.pt"
+    
+    if mvdiffusion_path.exists() and gslrm_path.exists():
+        print("Using local model weights")
+        return workspace_dir
+    
+    print(f"Downloading model weights from HuggingFace: {HF_REPO_ID}")
+    print("This may take a few minutes on first run...")
+    
+    # Download to local directory
+    snapshot_download(
+        repo_id=HF_REPO_ID,
+        local_dir=str(workspace_dir / "checkpoints"),
+        local_dir_use_symlinks=False,
+    )
+    
+    print("Model weights downloaded successfully!")
+    return workspace_dir
+
+class FaceLiftPipeline:
+    """Pipeline for FaceLift 3D head generation from single images."""
+    
+    def __init__(self):
+        # Download weights from HuggingFace if needed
+        workspace_dir = download_weights_from_hf()
+        
+        # Setup paths
+        self.output_dir = workspace_dir / "outputs"
+        self.examples_dir = workspace_dir / "examples"
+        self.output_dir.mkdir(exist_ok=True)
+        
+        # Parameters
+        self.device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
+        self.image_size = 512
+        self.camera_indices = [2, 1, 0, 5, 4, 3]
+        
+        # Load models
+        print("Loading models...")
+        self.mvdiffusion_pipeline = StableUnCLIPImg2ImgPipeline.from_pretrained(
+            str(workspace_dir / "checkpoints/mvdiffusion/pipeckpts"),
+            torch_dtype=torch.float16,
+        )
+        self.mvdiffusion_pipeline.unet.enable_xformers_memory_efficient_attention()
+        self.mvdiffusion_pipeline.to(self.device)
+        
+        with open(workspace_dir / "configs/gslrm.yaml", "r") as f:
+            config = edict(yaml.safe_load(f))
+        
+        module_name, class_name = config.model.class_name.rsplit(".", 1)
+        module = __import__(module_name, fromlist=[class_name])
+        ModelClass = getattr(module, class_name)
+        
+        self.gs_lrm_model = ModelClass(config)
+        checkpoint = torch.load(
+            workspace_dir / "checkpoints/gslrm/ckpt_0000000000021125.pt",
+            map_location="cpu"
+        )
+        self.gs_lrm_model.load_state_dict(checkpoint["model"])
+        self.gs_lrm_model.to(self.device)
+        
+        self.color_prompt_embedding = torch.load(
+            workspace_dir / "mvdiffusion/fixed_prompt_embeds_6view/clr_embeds.pt",
+            map_location=self.device
+        )
+        
+        with open(workspace_dir / "utils_folder/opencv_cameras.json", 'r') as f:
+            self.cameras_data = json.load(f)["frames"]
+        
+        print("Models loaded successfully!")
+    
+    def generate_3d_head(self, image_path, auto_crop=True, guidance_scale=3.0, 
+                         random_seed=4, num_steps=50):
+        """Generate 3D head from single image."""
+        try:
+            # Setup output directory
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            output_dir = self.output_dir / timestamp
+            output_dir.mkdir(exist_ok=True)
+            
+            # Preprocess input
+            original_img = np.array(Image.open(image_path))
+            input_image = preprocess_image(original_img) if auto_crop else \
+                         preprocess_image_without_cropping(original_img)
+            
+            if input_image.size != (self.image_size, self.image_size):
+                input_image = input_image.resize((self.image_size, self.image_size))
+            
+            input_path = output_dir / "input.png"
+            input_image.save(input_path)
+            
+            # Generate multi-view images
+            generator = torch.Generator(device=self.mvdiffusion_pipeline.unet.device)
+            generator.manual_seed(random_seed)
+            
+            result = self.mvdiffusion_pipeline(
+                input_image, None,
+                prompt_embeds=self.color_prompt_embedding,
+                guidance_scale=guidance_scale,
+                num_images_per_prompt=1,
+                num_inference_steps=num_steps,
+                generator=generator,
+                eta=1.0,
+            )
+            
+            selected_views = result.images[:6]
+            
+            # Save multi-view composite
+            multiview_image = Image.new("RGB", (self.image_size * 6, self.image_size))
+            for i, view in enumerate(selected_views):
+                multiview_image.paste(view, (self.image_size * i, 0))
+            
+            multiview_path = output_dir / "multiview.png"
+            multiview_image.save(multiview_path)
+            
+            # Prepare 3D reconstruction input
+            view_arrays = [np.array(view) for view in selected_views]
+            lrm_input = torch.from_numpy(np.stack(view_arrays, axis=0)).float()
+            lrm_input = lrm_input[None].to(self.device) / 255.0
+            lrm_input = rearrange(lrm_input, "b v h w c -> b v c h w")
+            
+            # Prepare camera parameters
+            selected_cameras = [self.cameras_data[i] for i in self.camera_indices]
+            fxfycxcy_list = [[c["fx"], c["fy"], c["cx"], c["cy"]] for c in selected_cameras]
+            c2w_list = [np.linalg.inv(np.array(c["w2c"])) for c in selected_cameras]
+            
+            fxfycxcy = torch.from_numpy(np.stack(fxfycxcy_list, axis=0).astype(np.float32))
+            c2w = torch.from_numpy(np.stack(c2w_list, axis=0).astype(np.float32))
+            fxfycxcy = fxfycxcy[None].to(self.device)
+            c2w = c2w[None].to(self.device)
+            
+            batch_indices = torch.stack([
+                torch.zeros(lrm_input.size(1)).long(),
+                torch.arange(lrm_input.size(1)).long(),
+            ], dim=-1)[None].to(self.device)
+            
+            batch = edict({
+                "image": lrm_input,
+                "c2w": c2w,
+                "fxfycxcy": fxfycxcy,
+                "index": batch_indices,
+            })
+            
+            # Run 3D reconstruction
+            with torch.autocast(enabled=True, device_type="cuda", dtype=torch.float16):
+                result = self.gs_lrm_model.forward(batch, create_visual=False, split_data=True)
+            
+            comp_image = result.render[0].unsqueeze(0).detach()
+            gaussians = result.gaussians[0]
+            
+            # Save filtered gaussians
+            filtered_gaussians = gaussians.apply_all_filters(
+                cam_origins=None,
+                opacity_thres=0.04,
+                scaling_thres=0.2,
+                floater_thres=0.75,
+                crop_bbx=[-0.91, 0.91, -0.91, 0.91, -1.0, 1.0],
+                nearfar_percent=(0.0001, 1.0),
+            )
+            
+            ply_path = output_dir / "gaussians.ply"
+            filtered_gaussians.save_ply(str(ply_path))
+            
+            # Save output image
+            comp_image = rearrange(comp_image, "x v c h w -> (x h) (v w) c")
+            comp_image = (comp_image.cpu().numpy() * 255.0).clip(0, 255).astype(np.uint8)
+            output_path = output_dir / "output.png"
+            Image.fromarray(comp_image).save(output_path)
+            
+            # Generate turntable video
+            turntable_frames = render_turntable(gaussians, rendering_resolution=self.image_size, 
+                                               num_views=180)
+            turntable_frames = rearrange(turntable_frames, "h (v w) c -> v h w c", v=180)
+            turntable_frames = np.ascontiguousarray(turntable_frames)
+            
+            turntable_path = output_dir / "turntable.mp4"
+            imageseq2video(turntable_frames, str(turntable_path), fps=30)
+            
+            return str(input_path), str(multiview_path), str(output_path), \
+                   str(turntable_path), str(ply_path)
+            
+        except Exception as e:
+            raise gr.Error(f"Generation failed: {str(e)}")
+
+
+def main():
+    """Run the FaceLift application."""
+    pipeline = FaceLiftPipeline()
+    
+    # Load examples
+    examples = []
+    if pipeline.examples_dir.exists():
+        examples = [[str(f)] for f in sorted(pipeline.examples_dir.iterdir()) 
+                   if f.suffix.lower() in {'.png', '.jpg', '.jpeg'}]
+    
+    # Create interface
+    demo = gr.Interface(
+        fn=pipeline.generate_3d_head,
+        title="FaceLift: Single Image 3D Face Reconstruction",
+        description="""
+        Transform a single portrait image into a complete 3D head model.
+        
+        **Tips:**
+        - Use high-quality portrait images with clear facial features
+        - If face detection fails, try disabling auto-cropping and manually crop to square
+        """,
+        inputs=[
+            gr.Image(type="filepath", label="Input Portrait Image"),
+            gr.Checkbox(value=True, label="Auto Cropping"),
+            gr.Slider(1.0, 10.0, 3.0, step=0.1, label="Guidance Scale"),
+            gr.Number(value=4, label="Random Seed"),
+            gr.Slider(10, 100, 50, step=5, label="Generation Steps"),
+        ],
+        outputs=[
+            gr.Image(label="Processed Input"),
+            gr.Image(label="Multi-view Generation"),
+            gr.Image(label="3D Reconstruction"),
+            gr.PlayableVideo(label="Turntable Animation"),
+            gr.File(label="3D Model (.ply)"),
+        ],
+        examples=examples,
+        allow_flagging="never",
+    )
+    
+    demo.queue(max_size=10)
+    demo.launch(share=True, server_name="0.0.0.0", server_port=7860, show_error=True)
 
-def greet(name):
-    return "Hello " + name + "!!"
 
-demo = gr.Interface(fn=greet, inputs="text", outputs="text")
-demo.launch()
+if __name__ == "__main__":
+    main()

configs/gslrm.yaml

@@ -0,0 +1,140 @@
+# =============================================================================
+# General Configuration
+# =============================================================================
+profile: false
+debug: false
+
+# =============================================================================
+# Model Configuration
+# =============================================================================
+model:
+  class_name: gslrm.model.gslrm.GSLRM
+  
+  # Image processing settings
+  image_tokenizer:
+    image_size: 512
+    patch_size: 8
+    in_channels: 9  # 3 RGB + 3 direction + 3 Reference
+
+  # Transformer architecture
+  transformer:
+    d: 1024
+    d_head: 64
+    n_layer: 24
+  
+  # Gaussian splatting configuration
+  gaussians:
+    n_gaussians: 2  # 12288
+    sh_degree: 0
+    
+    upsampler:
+      upsample_factor: 1
+
+  # Model behavior flags
+  add_refsrc_marker: false
+  hard_pixelalign: true
+  use_custom_plucker: true
+  clip_xyz: true
+
+# =============================================================================
+# Training Configuration
+# =============================================================================
+training:
+  # Training runtime settings
+  runtime:
+    use_tf32: true
+    use_amp: true
+    amp_dtype: "bf16"
+    torch_compile: false
+    grad_accum_steps: 1
+    grad_clip_norm: 1.0
+    grad_checkpoint_every: 1
+  
+  # Dataset configuration
+  dataset:
+    dataset_path: "data_sample/gslrm/data_gslrm_train.txt"
+    
+    # View configuration
+    maximize_view_overlap: true
+    num_views: 8
+    num_input_views: 6 # In training, we set it as 4. In inference, we set it as 6.
+    target_has_input: true
+    
+    # Data preprocessing
+    normalize_distance_to: 0.0
+    remove_alpha: false
+    background_color: "white"
+  
+  # Data loader settings
+  dataloader:
+    batch_size_per_gpu: 2
+    num_workers: 4
+    num_threads: 32
+    prefetch_factor: 32
+  
+  # Loss function weights
+  losses:
+    l2_loss_weight: 1.0
+    lpips_loss_weight: 0.0
+    perceptual_loss_weight: 0.5
+    ssim_loss_weight: 0.0
+    pixelalign_loss_weight: 0.0
+    masked_pixelalign_loss: true
+    pointsdist_loss_weight: 0.0
+    warmup_pointsdist: false
+    distill_loss_weight: 0.0
+  
+  # Optimizer configuration (AdamW)
+  optimizer:
+    lr: 0.0001
+    beta1: 0.9
+    beta2: 0.95
+    weight_decay: 0.05
+    reset_lr: false
+    reset_weight_decay: false
+    reset_training_state: true
+  
+  # Training schedule
+  schedule:
+    num_epochs: 100000          # dataset epochs
+    early_stop_after_epochs: 100000  # 40
+    max_fwdbwd_passes: 20000    # forward/backward pass steps
+    warmup: 500                 # parameter update steps
+    l2_warmup_steps: 500
+  
+  # Checkpointing
+  checkpointing:
+    resume_ckpt: "checkpoints/gslrm/stage_2"
+    checkpoint_every: 5000       # forward/backward pass steps
+    checkpoint_dir: "checkpoints/gslrm/stage_3"
+  
+  # Logging and monitoring
+  logging:
+    print_every: 20             # forward/backward pass steps
+    vis_every: 250              # forward/backward pass steps
+    
+    # Weights & Biases configuration
+    wandb:
+      project: "facelift_gslrm"
+      exp_name: "stage_3"
+      group: "facelift"
+      job_type: "train"
+      log_every: 50             # forward/backward pass steps
+      offline: false
+
+
+# =============================================================================
+# Inference Configuration
+# =============================================================================
+inference:
+  enabled: false
+  output_dir: "outputs/inference/gslrm/stage_3"
+
+# =============================================================================
+# Validation Configuration
+# =============================================================================
+validation:
+  enabled: true
+  val_every: 5000
+  output_dir: "outputs/validation/gslrm/stage_3"
+  dataset_path: "data_sample/gslrm/data_gslrm_val.txt"

gslrm/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+

gslrm/model/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+

gslrm/model/gaussians_renderer.py

@@ -0,0 +1,1028 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+
+import math
+import os
+
+import cv2
+import matplotlib
+import numpy as np
+import torch
+from diff_gaussian_rasterization import (
+    GaussianRasterizationSettings,
+    GaussianRasterizer,
+)
+from einops import rearrange
+from plyfile import PlyData, PlyElement
+from torch import nn
+
+from collections import OrderedDict
+import videoio
+
+@torch.no_grad()
+def get_turntable_cameras(
+    hfov=50,
+    num_views=8,
+    w=384,
+    h=384,
+    radius=2.7,
+    elevation=20,
+    up_vector=np.array([0, 0, 1]),
+):
+    fx = w / (2 * np.tan(np.deg2rad(hfov) / 2.0))
+    fy = fx
+    cx, cy = w / 2.0, h / 2.0
+    fxfycxcy = (
+        np.array([fx, fy, cx, cy]).reshape(1, 4).repeat(num_views, axis=0)
+    )  # [num_views, 4]
+    # azimuths = np.linspace(0, 360, num_views, endpoint=False)
+    azimuths = np.linspace(270, 630, num_views, endpoint=False)
+    elevations = np.ones_like(azimuths) * elevation
+    c2ws = []
+    for elev, azim in zip(elevations, azimuths):
+        elev, azim = np.deg2rad(elev), np.deg2rad(azim)
+        z = radius * np.sin(elev)
+        base = radius * np.cos(elev)
+        x = base * np.cos(azim)
+        y = base * np.sin(azim)
+        cam_pos = np.array([x, y, z])
+        forward = -cam_pos / np.linalg.norm(cam_pos)
+        right = np.cross(forward, up_vector)
+        right = right / np.linalg.norm(right)
+        up = np.cross(right, forward)
+        up = up / np.linalg.norm(up)
+        R = np.stack((right, -up, forward), axis=1)
+        c2w = np.eye(4)
+        c2w[:3, :4] = np.concatenate((R, cam_pos[:, None]), axis=1)
+        c2ws.append(c2w)
+    c2ws = np.stack(c2ws, axis=0)  # [num_views, 4, 4]
+    return w, h, num_views, fxfycxcy, c2ws
+
+def imageseq2video(images, filename, fps=24):
+    # if images is uint8, convert to float32
+    if images.dtype == np.uint8:
+        images = images.astype(np.float32) / 255.0
+
+    videoio.videosave(filename, images, lossless=True, preset="veryfast", fps=fps)
+
+
+# copied from: utils.general_utils
+def strip_lowerdiag(L):
+    uncertainty = torch.zeros((L.shape[0], 6), dtype=torch.float, device=L.device)
+
+    uncertainty[:, 0] = L[:, 0, 0]
+    uncertainty[:, 1] = L[:, 0, 1]
+    uncertainty[:, 2] = L[:, 0, 2]
+    uncertainty[:, 3] = L[:, 1, 1]
+    uncertainty[:, 4] = L[:, 1, 2]
+    uncertainty[:, 5] = L[:, 2, 2]
+    return uncertainty
+
+
+def strip_symmetric(sym):
+    return strip_lowerdiag(sym)
+
+
+def build_rotation(r):
+    norm = torch.sqrt(
+        r[:, 0] * r[:, 0] + r[:, 1] * r[:, 1] + r[:, 2] * r[:, 2] + r[:, 3] * r[:, 3]
+    )
+
+    q = r / norm[:, None]
+
+    R = torch.zeros((q.size(0), 3, 3), device=r.device)
+
+    r = q[:, 0]
+    x = q[:, 1]
+    y = q[:, 2]
+    z = q[:, 3]
+
+    R[:, 0, 0] = 1 - 2 * (y * y + z * z)
+    R[:, 0, 1] = 2 * (x * y - r * z)
+    R[:, 0, 2] = 2 * (x * z + r * y)
+    R[:, 1, 0] = 2 * (x * y + r * z)
+    R[:, 1, 1] = 1 - 2 * (x * x + z * z)
+    R[:, 1, 2] = 2 * (y * z - r * x)
+    R[:, 2, 0] = 2 * (x * z - r * y)
+    R[:, 2, 1] = 2 * (y * z + r * x)
+    R[:, 2, 2] = 1 - 2 * (x * x + y * y)
+    return R
+
+
+def build_scaling_rotation(s, r):
+    L = torch.zeros((s.shape[0], 3, 3), dtype=torch.float, device=s.device)
+    R = build_rotation(r)
+
+    L[:, 0, 0] = s[:, 0]
+    L[:, 1, 1] = s[:, 1]
+    L[:, 2, 2] = s[:, 2]
+
+    L = R @ L
+    return L
+
+
+# copied from: utils.sh_utils
+C0 = 0.28209479177387814
+C1 = 0.4886025119029199
+C2 = [
+    1.0925484305920792,
+    -1.0925484305920792,
+    0.31539156525252005,
+    -1.0925484305920792,
+    0.5462742152960396,
+]
+C3 = [
+    -0.5900435899266435,
+    2.890611442640554,
+    -0.4570457994644658,
+    0.3731763325901154,
+    -0.4570457994644658,
+    1.445305721320277,
+    -0.5900435899266435,
+]
+C4 = [
+    2.5033429417967046,
+    -1.7701307697799304,
+    0.9461746957575601,
+    -0.6690465435572892,
+    0.10578554691520431,
+    -0.6690465435572892,
+    0.47308734787878004,
+    -1.7701307697799304,
+    0.6258357354491761,
+]
+
+
+def eval_sh(deg, sh, dirs):
+    """
+    Evaluate spherical harmonics at unit directions
+    using hardcoded SH polynomials.
+    Works with torch/np/jnp.
+    ... Can be 0 or more batch dimensions.
+    Args:
+        deg: int SH deg. Currently, 0-3 supported
+        sh: jnp.ndarray SH coeffs [..., C, (deg + 1) ** 2]
+        dirs: jnp.ndarray unit directions [..., 3]
+    Returns:
+        [..., C]
+    """
+    assert deg <= 4 and deg >= 0
+    coeff = (deg + 1) ** 2
+    assert sh.shape[-1] >= coeff
+
+    result = C0 * sh[..., 0]
+    if deg > 0:
+        x, y, z = dirs[..., 0:1], dirs[..., 1:2], dirs[..., 2:3]
+        result = (
+            result - C1 * y * sh[..., 1] + C1 * z * sh[..., 2] - C1 * x * sh[..., 3]
+        )
+
+        if deg > 1:
+            xx, yy, zz = x * x, y * y, z * z
+            xy, yz, xz = x * y, y * z, x * z
+            result = (
+                result
+                + C2[0] * xy * sh[..., 4]
+                + C2[1] * yz * sh[..., 5]
+                + C2[2] * (2.0 * zz - xx - yy) * sh[..., 6]
+                + C2[3] * xz * sh[..., 7]
+                + C2[4] * (xx - yy) * sh[..., 8]
+            )
+
+            if deg > 2:
+                result = (
+                    result
+                    + C3[0] * y * (3 * xx - yy) * sh[..., 9]
+                    + C3[1] * xy * z * sh[..., 10]
+                    + C3[2] * y * (4 * zz - xx - yy) * sh[..., 11]
+                    + C3[3] * z * (2 * zz - 3 * xx - 3 * yy) * sh[..., 12]
+                    + C3[4] * x * (4 * zz - xx - yy) * sh[..., 13]
+                    + C3[5] * z * (xx - yy) * sh[..., 14]
+                    + C3[6] * x * (xx - 3 * yy) * sh[..., 15]
+                )
+
+                if deg > 3:
+                    result = (
+                        result
+                        + C4[0] * xy * (xx - yy) * sh[..., 16]
+                        + C4[1] * yz * (3 * xx - yy) * sh[..., 17]
+                        + C4[2] * xy * (7 * zz - 1) * sh[..., 18]
+                        + C4[3] * yz * (7 * zz - 3) * sh[..., 19]
+                        + C4[4] * (zz * (35 * zz - 30) + 3) * sh[..., 20]
+                        + C4[5] * xz * (7 * zz - 3) * sh[..., 21]
+                        + C4[6] * (xx - yy) * (7 * zz - 1) * sh[..., 22]
+                        + C4[7] * xz * (xx - 3 * yy) * sh[..., 23]
+                        + C4[8]
+                        * (xx * (xx - 3 * yy) - yy * (3 * xx - yy))
+                        * sh[..., 24]
+                    )
+    return result
+
+
+def RGB2SH(rgb):
+    return (rgb - 0.5) / C0
+
+
+def SH2RGB(sh):
+    return sh * C0 + 0.5
+
+
+def create_video(image_folder, output_video_file, framerate=30):
+    # Get all image file paths to a list.
+    images = [img for img in os.listdir(image_folder) if img.endswith(".png")]
+    images.sort()
+
+    # Read the first image to know the height and width
+    frame = cv2.imread(os.path.join(image_folder, images[0]))
+    height, width, layers = frame.shape
+
+    video = cv2.VideoWriter(
+        output_video_file, cv2.VideoWriter_fourcc(*"mp4v"), framerate, (width, height)
+    )
+
+    # iterate over each image and add it to the video sequence
+    for image in images:
+        video.write(cv2.imread(os.path.join(image_folder, image)))
+
+    cv2.destroyAllWindows()
+    video.release()
+
+
+class Camera(nn.Module):
+    def __init__(self, C2W, fxfycxcy, h, w):
+        """
+        C2W: 4x4 camera-to-world matrix; opencv convention
+        fxfycxcy: 4
+        """
+        super().__init__()
+        self.C2W = C2W.clone().float()
+        self.W2C = self.C2W.inverse()
+        self.h = h
+        self.w = w
+
+        self.znear = 0.01
+        self.zfar = 100.0
+
+        fx, fy, cx, cy = fxfycxcy[0], fxfycxcy[1], fxfycxcy[2], fxfycxcy[3]
+        self.tanfovX = w / (2 * fx)
+        self.tanfovY = h / (2 * fy)
+
+        def getProjectionMatrix(W, H, fx, fy, cx, cy, znear, zfar):
+            P = torch.zeros(4, 4, device=fx.device)
+            P[0, 0] = 2 * fx / W
+            P[1, 1] = 2 * fy / H
+            P[0, 2] = 2 * (cx / W) - 1
+            P[1, 2] = 2 * (cy / H) - 1
+            P[2, 2] = -(zfar + znear) / (zfar - znear)
+            P[3, 2] = 1.0
+            P[2, 3] = -(2 * zfar * znear) / (zfar - znear)
+            return P
+
+        self.world_view_transform = self.W2C.transpose(0, 1)
+        self.projection_matrix = getProjectionMatrix(
+            self.w, self.h, fx, fy, cx, cy, self.znear, self.zfar
+        ).transpose(0, 1)
+        self.full_proj_transform = (
+            self.world_view_transform.unsqueeze(0).bmm(
+                self.projection_matrix.unsqueeze(0)
+            )
+        ).squeeze(0)
+        self.camera_center = self.C2W[:3, 3]
+
+
+# modified from scene/gaussian_model.py
+class GaussianModel:
+    def setup_functions(self):
+        def build_covariance_from_scaling_rotation(scaling, scaling_modifier, rotation):
+            L = build_scaling_rotation(scaling_modifier * scaling, rotation)
+            actual_covariance = L @ L.transpose(1, 2)
+            symm = strip_symmetric(actual_covariance)
+            return symm
+
+        self.scaling_activation = torch.exp
+        self.inv_scaling_activation = torch.log
+        self.rotation_activation = torch.nn.functional.normalize
+        self.opacity_activation = torch.sigmoid
+        self.covariance_activation = build_covariance_from_scaling_rotation
+
+    def __init__(self, sh_degree: int, scaling_modifier=None):
+        self.sh_degree = sh_degree
+        self._xyz = torch.empty(0)
+        self._features_dc = torch.empty(0)
+        if self.sh_degree > 0:
+            self._features_rest = torch.empty(0)
+        else:
+            self._features_rest = None
+        self._scaling = torch.empty(0)
+        self._rotation = torch.empty(0)
+        self._opacity = torch.empty(0)
+        self.setup_functions()
+
+        self.scaling_modifier = scaling_modifier
+
+    def empty(self):
+        self.__init__(self.sh_degree, self.scaling_modifier)
+
+    def set_data(self, xyz, features, scaling, rotation, opacity):
+        """
+        xyz : torch.tensor of shape (N, 3)
+        features : torch.tensor of shape (N, (self.sh_degree + 1) ** 2, 3)
+        scaling : torch.tensor of shape (N, 3)
+        rotation : torch.tensor of shape (N, 4)
+        opacity : torch.tensor of shape (N, 1)
+        """
+        self._xyz = xyz
+        self._features_dc = features[:, :1, :].contiguous()
+        if self.sh_degree > 0:
+            self._features_rest = features[:, 1:, :].contiguous()
+        else:
+            self._features_rest = None
+        self._scaling = scaling
+        self._rotation = rotation
+        self._opacity = opacity
+        return self
+
+    def to(self, device):
+        self._xyz = self._xyz.to(device)
+        self._features_dc = self._features_dc.to(device)
+        if self.sh_degree > 0:
+            self._features_rest = self._features_rest.to(device)
+        self._scaling = self._scaling.to(device)
+        self._rotation = self._rotation.to(device)
+        self._opacity = self._opacity.to(device)
+        return self
+
+    def filter(self, valid_mask):
+        self._xyz = self._xyz[valid_mask]
+        self._features_dc = self._features_dc[valid_mask]
+        if self.sh_degree > 0:
+            self._features_rest = self._features_rest[valid_mask]
+        self._scaling = self._scaling[valid_mask]
+        self._rotation = self._rotation[valid_mask]
+        self._opacity = self._opacity[valid_mask]
+        return self
+
+    def crop(self, crop_bbx=[-1, 1, -1, 1, -1, 1]):
+        x_min, x_max, y_min, y_max, z_min, z_max = crop_bbx
+        xyz = self._xyz
+        invalid_mask = (
+            (xyz[:, 0] < x_min)
+            | (xyz[:, 0] > x_max)
+            | (xyz[:, 1] < y_min)
+            | (xyz[:, 1] > y_max)
+            | (xyz[:, 2] < z_min)
+            | (xyz[:, 2] > z_max)
+        )
+        valid_mask = ~invalid_mask
+
+        return self.filter(valid_mask)
+
+    def crop_by_xyz(self, floater_thres=0.75):
+        xyz = self._xyz
+        invalid_mask = (
+            (((xyz[:, 0] < -floater_thres) & (xyz[:, 1] < -floater_thres))
+            | ((xyz[:, 0] < -floater_thres) & (xyz[:, 1] > floater_thres))
+            | ((xyz[:, 0] > floater_thres) & (xyz[:, 1] < -floater_thres))
+            | ((xyz[:, 0] > floater_thres) & (xyz[:, 1] > floater_thres)))
+            & (xyz[:, 2] < -floater_thres)
+        )
+        valid_mask = ~invalid_mask
+
+        return self.filter(valid_mask)
+
+    def prune(self, opacity_thres=0.05):
+        opacity = self.get_opacity.squeeze(1)
+        valid_mask = opacity > opacity_thres
+
+        return self.filter(valid_mask)
+    
+    def prune_by_scaling(self, scaling_thres=0.1):
+        scaling = self.get_scaling
+        valid_mask = scaling.max(dim=1).values < scaling_thres
+        position_mask = self._xyz[:, 2] > 0
+
+        valid_mask = valid_mask | position_mask
+
+        return self.filter(valid_mask)
+
+    def prune_by_nearfar(self, cam_origins, nearfar_percent=(0.01, 0.99)):
+        # cam_origins: [num_cams, 3]
+        # nearfar_percent: [near, far]
+        assert len(nearfar_percent) == 2
+        assert nearfar_percent[0] < nearfar_percent[1]
+        assert nearfar_percent[0] >= 0 and nearfar_percent[1] <= 1
+
+        device = self._xyz.device
+        # compute distance of all points to all cameras
+        # [num_points, num_cams]
+        dists = torch.cdist(self._xyz[None], cam_origins[None].to(device))[0]
+        # [2, num_cams]
+        dists_percentile = torch.quantile(
+            dists, torch.tensor(nearfar_percent).to(device), dim=0
+        )
+        # prune all points that are outside the percentile range
+        # [num_points, num_cams]
+        # goal: prune points that are too close or too far from any camera
+        reject_mask = (dists < dists_percentile[0:1, :]) | (
+            dists > dists_percentile[1:2, :]
+        )
+        reject_mask = reject_mask.any(dim=1)
+        valid_mask = ~reject_mask
+
+        return self.filter(valid_mask)
+
+    def apply_all_filters(
+        self,
+        opacity_thres=0.05,
+        scaling_thres=None,
+        floater_thres=None,
+        crop_bbx=[-1, 1, -1, 1, -1, 1],
+        cam_origins=None,
+        nearfar_percent=(0.005, 1.0),
+    ):
+        self.prune(opacity_thres)
+        if scaling_thres is not None:
+            self.prune_by_scaling(scaling_thres)
+        if floater_thres is not None:
+            self.crop_by_xyz(floater_thres)
+        if crop_bbx is not None:
+            self.crop(crop_bbx)
+        if cam_origins is not None:
+            self.prune_by_nearfar(cam_origins, nearfar_percent)
+        return self
+
+    def shrink_bbx(self, drop_ratio=0.05):
+        xyz = self._xyz
+        xyz_min, xyz_max = torch.quantile(
+            xyz,
+            torch.tensor([drop_ratio, 1 - drop_ratio]).float().to(xyz.device),
+            dim=0,
+        )  # [2, N]
+        xyz_min = xyz_min.detach().cpu().numpy()
+        xyz_max = xyz_max.detach().cpu().numpy()
+        crop_bbx = [
+            xyz_min[0],
+            xyz_max[0],
+            xyz_min[1],
+            xyz_max[1],
+            xyz_min[2],
+            xyz_max[2],
+        ]
+        print(f"Shrinking bbx to {crop_bbx}")
+        return self.crop(crop_bbx)
+
+    def report_stats(self):
+        print(
+            f"xyz: {self._xyz.shape}, {self._xyz.min().item()}, {self._xyz.max().item()}"
+        )
+        print(
+            f"features_dc: {self._features_dc.shape}, {self._features_dc.min().item()}, {self._features_dc.max().item()}"
+        )
+        if self.sh_degree > 0:
+            print(
+                f"features_rest: {self._features_rest.shape}, {self._features_rest.min().item()}, {self._features_rest.max().item()}"
+            )
+        print(
+            f"scaling: {self._scaling.shape}, {self._scaling.min().item()}, {self._scaling.max().item()}"
+        )
+        print(
+            f"rotation: {self._rotation.shape}, {self._rotation.min().item()}, {self._rotation.max().item()}"
+        )
+        print(
+            f"opacity: {self._opacity.shape}, {self._opacity.min().item()}, {self._opacity.max().item()}"
+        )
+
+        print(
+            f"after activation, xyz: {self.get_xyz.shape}, {self.get_xyz.min().item()}, {self.get_xyz.max().item()}"
+        )
+        print(
+            f"after activation, features: {self.get_features.shape}, {self.get_features.min().item()}, {self.get_features.max().item()}"
+        )
+        print(
+            f"after activation, scaling: {self.get_scaling.shape}, {self.get_scaling.min().item()}, {self.get_scaling.max().item()}"
+        )
+        print(
+            f"after activation, rotation: {self.get_rotation.shape}, {self.get_rotation.min().item()}, {self.get_rotation.max().item()}"
+        )
+        print(
+            f"after activation, opacity: {self.get_opacity.shape}, {self.get_opacity.min().item()}, {self.get_opacity.max().item()}"
+        )
+        print(
+            f"after activation, covariance: {self.get_covariance().shape}, {self.get_covariance().min().item()}, {self.get_covariance().max().item()}"
+        )
+
+    @property
+    def get_scaling(self):
+        if self.scaling_modifier is not None:
+            return self.scaling_activation(self._scaling) * self.scaling_modifier
+        else:
+            return self.scaling_activation(self._scaling)
+
+    @property
+    def get_rotation(self):
+        return self.rotation_activation(self._rotation)
+
+    @property
+    def get_xyz(self):
+        return self._xyz
+
+    @property
+    def get_features(self):
+        if self.sh_degree > 0:
+            features_dc = self._features_dc
+            features_rest = self._features_rest
+            return torch.cat((features_dc, features_rest), dim=1)
+        else:
+            return self._features_dc
+
+    @property
+    def get_opacity(self):
+        return self.opacity_activation(self._opacity)
+
+    def get_covariance(self, scaling_modifier=1):
+        return self.covariance_activation(
+            self.get_scaling, scaling_modifier, self._rotation
+        )
+
+    def construct_dtypes(self, use_fp16=False, enable_gs_viewer=True):
+        if not use_fp16:
+            l = [
+                ("x", "f4"),
+                ("y", "f4"),
+                ("z", "f4"),
+                ("red", "u1"),
+                ("green", "u1"),
+                ("blue", "u1"),
+            ]
+            # All channels except the 3 DC
+            for i in range(self._features_dc.shape[1] * self._features_dc.shape[2]):
+                l.append((f"f_dc_{i}", "f4"))
+
+            if enable_gs_viewer:
+                assert self.sh_degree <= 3, "GS viewer only supports SH up to degree 3"
+                sh_degree = 3
+                for i in range(((sh_degree + 1) ** 2 - 1) * 3):
+                    l.append((f"f_rest_{i}", "f4"))
+            else:
+                if self.sh_degree > 0:
+                    for i in range(
+                        self._features_rest.shape[1] * self._features_rest.shape[2]
+                    ):
+                        l.append((f"f_rest_{i}", "f4"))
+
+            l.append(("opacity", "f4"))
+            for i in range(self._scaling.shape[1]):
+                l.append((f"scale_{i}", "f4"))
+            for i in range(self._rotation.shape[1]):
+                l.append((f"rot_{i}", "f4"))
+        else:
+            l = [
+                ("x", "f2"),
+                ("y", "f2"),
+                ("z", "f2"),
+                ("red", "u1"),
+                ("green", "u1"),
+                ("blue", "u1"),
+            ]
+            # All channels except the 3 DC
+            for i in range(self._features_dc.shape[1] * self._features_dc.shape[2]):
+                l.append((f"f_dc_{i}", "f2"))
+
+            if self.sh_degree > 0:
+                for i in range(
+                    self._features_rest.shape[1] * self._features_rest.shape[2]
+                ):
+                    l.append((f"f_rest_{i}", "f2"))
+            l.append(("opacity", "f2"))
+            for i in range(self._scaling.shape[1]):
+                l.append((f"scale_{i}", "f2"))
+            for i in range(self._rotation.shape[1]):
+                l.append((f"rot_{i}", "f2"))
+        return l
+
+    def save_ply(
+        self,
+        path,
+        use_fp16=False,
+        enable_gs_viewer=True,
+        color_code=False,
+        filter_mask=None,
+    ):
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+
+        xyz = self._xyz.detach().cpu().numpy()
+        f_dc = (
+            self._features_dc.detach()
+            .transpose(1, 2)
+            .flatten(start_dim=1)
+            .contiguous()
+            .cpu()
+            .numpy()
+        )
+        if not color_code:
+            rgb = (SH2RGB(f_dc) * 255.0).clip(0.0, 255.0).astype(np.uint8)
+        else:
+            # use an color map to color code the index of points
+            index = np.linspace(0, 1, xyz.shape[0])
+            rgb = matplotlib.colormaps["viridis"](index)[..., :3]
+            rgb = (rgb * 255.0).clip(0.0, 255.0).astype(np.uint8)
+
+        opacities = self._opacity.detach().cpu().numpy()
+        if self.scaling_modifier is not None:
+            scale = self.inv_scaling_activation(self.get_scaling).detach().cpu().numpy()
+        else:
+            scale = self._scaling.detach().cpu().numpy()
+        rotation = self._rotation.detach().cpu().numpy()
+
+        dtype_full = self.construct_dtypes(use_fp16, enable_gs_viewer)
+        elements = np.empty(xyz.shape[0], dtype=dtype_full)
+
+        f_rest = None
+        if self.sh_degree > 0:
+            f_rest = (
+                self._features_rest.detach()
+                .transpose(1, 2)
+                .flatten(start_dim=1)
+                .contiguous()
+                .cpu()
+                .numpy()
+            )  # (3, (self.sh_degree + 1) ** 2 - 1)
+
+        if enable_gs_viewer:
+            sh_degree = 3
+            if f_rest is None:
+                f_rest = np.zeros(
+                    (xyz.shape[0], 3 * ((sh_degree + 1) ** 2 - 1)), dtype=np.float32
+                )
+            elif f_rest.shape[1] < 3 * ((sh_degree + 1) ** 2 - 1):
+                f_rest_pad = np.zeros(
+                    (xyz.shape[0], 3 * ((sh_degree + 1) ** 2 - 1)), dtype=np.float32
+                )
+                f_rest_pad[:, : f_rest.shape[1]] = f_rest
+                f_rest = f_rest_pad
+
+        if f_rest is not None:
+            attributes = np.concatenate(
+                (xyz, rgb, f_dc, f_rest, opacities, scale, rotation), axis=1
+            )
+        else:
+            attributes = np.concatenate(
+                (xyz, rgb, f_dc, opacities, scale, rotation), axis=1
+            )
+
+        if filter_mask is not None:
+            attributes = attributes[filter_mask]
+            elements = elements[filter_mask]
+
+        elements[:] = list(map(tuple, attributes))
+        el = PlyElement.describe(elements, "vertex")
+        PlyData([el]).write(path)
+
+    def load_ply(self, path):
+        plydata = PlyData.read(path)
+
+        xyz = np.stack(
+            (
+                np.asarray(plydata.elements[0]["x"]),
+                np.asarray(plydata.elements[0]["y"]),
+                np.asarray(plydata.elements[0]["z"]),
+            ),
+            axis=1,
+        )
+        opacities = np.asarray(plydata.elements[0]["opacity"])[..., np.newaxis]
+
+        features_dc = np.zeros((xyz.shape[0], 3, 1))
+        features_dc[:, 0, 0] = np.asarray(plydata.elements[0]["f_dc_0"])
+        features_dc[:, 1, 0] = np.asarray(plydata.elements[0]["f_dc_1"])
+        features_dc[:, 2, 0] = np.asarray(plydata.elements[0]["f_dc_2"])
+
+        if self.sh_degree > 0:
+            extra_f_names = [
+                p.name
+                for p in plydata.elements[0].properties
+                if p.name.startswith("f_rest_")
+            ]
+            extra_f_names = sorted(extra_f_names, key=lambda x: int(x.split("_")[-1]))
+            assert len(extra_f_names) == 3 * (self.sh_degree + 1) ** 2 - 3
+            features_extra = np.zeros((xyz.shape[0], len(extra_f_names)))
+            for idx, attr_name in enumerate(extra_f_names):
+                features_extra[:, idx] = np.asarray(plydata.elements[0][attr_name])
+            # Reshape (P,F*SH_coeffs) to (P, F, SH_coeffs except DC)
+            features_extra = features_extra.reshape(
+                (features_extra.shape[0], 3, (self.sh_degree + 1) ** 2 - 1)
+            )
+
+        scale_names = [
+            p.name
+            for p in plydata.elements[0].properties
+            if p.name.startswith("scale_")
+        ]
+        scale_names = sorted(scale_names, key=lambda x: int(x.split("_")[-1]))
+        scales = np.zeros((xyz.shape[0], len(scale_names)))
+        for idx, attr_name in enumerate(scale_names):
+            scales[:, idx] = np.asarray(plydata.elements[0][attr_name])
+
+        rot_names = [
+            p.name for p in plydata.elements[0].properties if p.name.startswith("rot")
+        ]
+        rot_names = sorted(rot_names, key=lambda x: int(x.split("_")[-1]))
+        rots = np.zeros((xyz.shape[0], len(rot_names)))
+        for idx, attr_name in enumerate(rot_names):
+            rots[:, idx] = np.asarray(plydata.elements[0][attr_name])
+
+        self._xyz = torch.from_numpy(xyz.astype(np.float32))
+        self._features_dc = (
+            torch.from_numpy(features_dc.astype(np.float32))
+            .transpose(1, 2)
+            .contiguous()
+        )
+        if self.sh_degree > 0:
+            self._features_rest = (
+                torch.from_numpy(features_extra.astype(np.float32))
+                .transpose(1, 2)
+                .contiguous()
+            )
+        self._opacity = torch.from_numpy(
+            np.copy(opacities).astype(np.float32)
+        ).contiguous()
+        self._scaling = torch.from_numpy(scales.astype(np.float32)).contiguous()
+        self._rotation = torch.from_numpy(rots.astype(np.float32)).contiguous()
+
+
+def render_opencv_cam(
+    pc: GaussianModel,
+    height: int,
+    width: int,
+    C2W: torch.Tensor,
+    fxfycxcy: torch.Tensor,
+    bg_color=(1.0, 1.0, 1.0),
+    scaling_modifier=1.0,
+):
+    """
+    Render the scene.
+
+    Background tensor (bg_color) must be on GPU!
+    """
+    # Create zero tensor. We will use it to make pytorch return gradients of the 2D (screen-space) means
+    screenspace_points = torch.empty_like(
+        pc.get_xyz, dtype=pc.get_xyz.dtype, requires_grad=True, device="cuda"
+    )
+    # try:
+    #     screenspace_points.retain_grad()
+    # except:
+    #     pass
+
+    viewpoint_camera = Camera(C2W=C2W, fxfycxcy=fxfycxcy, h=height, w=width)
+
+    bg_color = torch.tensor(list(bg_color), dtype=torch.float32, device=C2W.device)
+
+    # Set up rasterization configuration
+    raster_settings = GaussianRasterizationSettings(
+        image_height=int(viewpoint_camera.h),
+        image_width=int(viewpoint_camera.w),
+        tanfovx=viewpoint_camera.tanfovX,
+        tanfovy=viewpoint_camera.tanfovY,
+        bg=bg_color,
+        scale_modifier=scaling_modifier,
+        viewmatrix=viewpoint_camera.world_view_transform,
+        projmatrix=viewpoint_camera.full_proj_transform,
+        sh_degree=pc.sh_degree,
+        campos=viewpoint_camera.camera_center,
+        prefiltered=False,
+        debug=False,
+    )
+
+    rasterizer = GaussianRasterizer(raster_settings=raster_settings)
+
+    means3D = pc.get_xyz
+    means2D = screenspace_points
+    opacity = pc.get_opacity
+    scales = pc.get_scaling
+    rotations = pc.get_rotation
+    shs = pc.get_features
+
+    # Rasterize visible Gaussians to image, obtain their radii (on screen).
+    rendered_image, radii, _, _ = rasterizer(
+        means3D=means3D,
+        means2D=means2D,
+        shs=shs,
+        colors_precomp=None,
+        opacities=opacity,
+        scales=scales,
+        rotations=rotations,
+        cov3D_precomp=None,
+    )
+
+    # Those Gaussians that were frustum culled or had a radius of 0 were not visible.
+    # They will be excluded from value updates used in the splitting criteria.
+    return {
+        "render": rendered_image,
+        "viewspace_points": screenspace_points,
+        "visibility_filter": radii > 0,
+        "radii": radii,
+    }
+
+
+class DeferredGaussianRender(torch.autograd.Function):
+    @staticmethod
+    def forward(
+        ctx,
+        xyz,
+        features,
+        scaling,
+        rotation,
+        opacity,
+        height,
+        width,
+        C2W,
+        fxfycxcy,
+        scaling_modifier=None,
+    ):
+        """
+        xyz: [b, n_gaussians, 3]
+        features: [b, n_gaussians, (sh_degree+1)^2, 3]
+        scaling: [b, n_gaussians, 3]
+        rotation: [b, n_gaussians, 4]
+        opacity: [b, n_gaussians, 1]
+
+        height: int
+        width: int
+        C2W: [b, v, 4, 4]
+        fxfycxcy: [b, v, 4]
+
+        output: [b, v, 3, height, width]
+        """
+        ctx.scaling_modifier = scaling_modifier
+
+        # Infer sh_degree from features
+        sh_degree = int(math.sqrt(features.shape[-2])) - 1
+
+        # Create a temp class to hold the data and for rendering
+        gaussians_model = GaussianModel(sh_degree, scaling_modifier)
+
+        with torch.no_grad():
+            b, v = C2W.size(0), C2W.size(1)
+            renders = []
+            for i in range(b):
+                pc = gaussians_model.set_data(
+                    xyz[i], features[i], scaling[i], rotation[i], opacity[i]
+                )
+                for j in range(v):
+                    renders.append(
+                        render_opencv_cam(pc, height, width, C2W[i, j], fxfycxcy[i, j])[
+                            "render"
+                        ]
+                    )
+            renders = torch.stack(renders, dim=0)
+            renders = renders.reshape(b, v, 3, height, width)
+
+        renders = renders.requires_grad_()
+
+        # Save_for_backward only supports tensors
+        ctx.save_for_backward(xyz, features, scaling, rotation, opacity, C2W, fxfycxcy)
+        ctx.rendering_size = (height, width)
+        ctx.sh_degree = sh_degree
+
+        # Release the temp class; do not save it.
+        del gaussians_model
+
+        return renders
+
+    @staticmethod
+    def backward(ctx, grad_output):
+        # Restore params
+        xyz, features, scaling, rotation, opacity, C2W, fxfycxcy = ctx.saved_tensors
+        height, width = ctx.rendering_size
+        sh_degree = ctx.sh_degree
+
+        # **The order of this dict should not be changed**
+        input_dict = OrderedDict(
+            [
+                ("xyz", xyz),
+                ("features", features),
+                ("scaling", scaling),
+                ("rotation", rotation),
+                ("opacity", opacity),
+            ]
+        )
+        input_dict = {k: v.detach().requires_grad_() for k, v in input_dict.items()}
+
+        # Create a temp class to hold the data and for rendering
+        gaussians_model = GaussianModel(sh_degree, ctx.scaling_modifier)
+
+        with torch.enable_grad():
+            b, v = C2W.size(0), C2W.size(1)
+            for i in range(b):
+                for j in range(v):
+                    # The backward will remove the diff graph, thus each time we need a copy
+                    pc = gaussians_model.set_data(
+                        **{k: v[i] for k, v in input_dict.items()}
+                    )
+
+                    # Forward
+                    render = render_opencv_cam(
+                        pc, height, width, C2W[i, j], fxfycxcy[i, j]
+                    )["render"]
+
+                    # Backward, suppose that only values in input_dict will get gradients.
+                    render.backward(grad_output[i, j])
+
+        del gaussians_model
+
+        return *[var.grad for var in input_dict.values()], None, None, None, None, None
+
+
+# Function for the class
+deferred_gaussian_render = DeferredGaussianRender.apply
+
+@torch.no_grad()
+@torch.cuda.amp.custom_fwd(cast_inputs=torch.float32)
+def render_turntable(pc: GaussianModel, rendering_resolution=384, num_views=8):
+    w, h, v, fxfycxcy, c2w = get_turntable_cameras(
+        h=rendering_resolution, w=rendering_resolution, num_views=num_views,
+        elevation=0,  # For MAX SNEAK
+    )
+
+    device = pc._xyz.device
+    fxfycxcy = torch.from_numpy(fxfycxcy).float().to(device)  # [v, 4]
+    c2w = torch.from_numpy(c2w).float().to(device)  # [v, 4, 4]
+
+    renderings = torch.zeros(v, 3, h, w, dtype=torch.float32, device=device)
+    for j in range(v):
+        renderings[j] = render_opencv_cam(pc, h, w, c2w[j], fxfycxcy[j])["render"]
+    torch.cuda.empty_cache()  # free up memory on GPU
+    renderings = renderings.detach().cpu().numpy()
+    renderings = (renderings * 255).clip(0, 255).astype(np.uint8)
+    renderings = rearrange(renderings, "v c h w -> h (v w) c")
+    return renderings
+
+
+if __name__ == "__main__":
+    import json
+
+    from PIL import Image
+    from tqdm import tqdm
+
+    out_dir = "/mnt/localssd/debug-3dgs"
+    os.makedirs(out_dir, exist_ok=True)
+
+    os.system(
+        f"wget https://phidias.s3.us-west-2.amazonaws.com/kaiz/neural-capture/eval-3dgs-lowres/AWS_test_set/results/1.fashion_boots_rubber_boots__short__Feb_21__2023_at_5_19_25_PM_yf/point_cloud/iteration_30000_fg/point_cloud.ply -O {out_dir}/point_cloud.ply"
+    )
+    os.system(
+        f"wget https://neural-capture.s3.us-west-2.amazonaws.com/data/AWS_test_set/preprocessed/1.fashion_boots_rubber_boots__short__Feb_21__2023_at_5_19_25_PM_yf/opencv_cameras_traj_norm.json -O {out_dir}/opencv_cameras_traj_norm.json"
+    )
+
+    device = "cuda:0"
+
+    pc = GaussianModel(sh_degree=3)
+    pc.load_ply(f"{out_dir}/point_cloud.ply")
+    pc = pc.to(device)
+
+    # pc.save_ply(f"{out_dir}/point_cloud_shrink.ply")
+    # pc.load_ply(f"{out_dir}/point_cloud_shrink.ply")
+    # pc = pc.to(device)
+
+    # pc.prune(opacity_thres=0.05)
+    # pc.save_ply(f"{out_dir}/point_cloud_shrink_prune.ply")
+    # pc = pc.to(device)
+
+    # pc.shrink_bbx(drop_ratio=0.01)
+    # pc.save_ply(f"{out_dir}/point_cloud_shrink_prune.ply")
+    # pc = pc.to(device)
+
+    pc.report_stats()
+
+    with open(f"{out_dir}/opencv_cameras_traj_norm.json", "r") as f:
+        cam_traj = json.load(f)
+
+    for i, cam in tqdm(enumerate(cam_traj["frames"]), desc="Rendering progress"):
+        w2c = np.array(cam["w2c"])
+        c2w = np.linalg.inv(w2c)
+        c2w = torch.from_numpy(c2w.astype(np.float32)).to(device)
+
+        fx = cam["fx"]
+        fy = cam["fy"]
+        cx = cam["cx"]
+        cy = cam["cy"]
+        cx = cx - 5
+        cy = cy + 4
+        fxfycxcy = torch.tensor([fx, fy, cx, cy], dtype=torch.float32, device=device)
+
+        h = cam["h"]
+        w = cam["w"]
+
+        im = render_opencv_cam(pc, h, w, c2w, fxfycxcy, bg_color=[0.0, 0.0, 0.0])[
+            "render"
+        ]
+        im = im.detach().cpu().numpy().transpose(1, 2, 0)
+        im = (im * 255).astype(np.uint8)
+        Image.fromarray(im).save(f"{out_dir}/render_{i:08d}.png")
+
+    create_video(out_dir, f"{out_dir}/render.mp4", framerate=30)
+    print(f"Saved {out_dir}/render.mp4")

gslrm/model/gslrm.py

@@ -0,0 +1,1647 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+
+"""
+GSLRM (Gaussian Splatting Large Reconstruction Model)
+
+This module implements a transformer-based model for generating 3D Gaussian splats
+from multi-view images. The model uses a combination of image tokenization,
+transformer processing, and Gaussian splatting for novel view synthesis.
+
+Classes:
+    Renderer: Handles Gaussian splatting rendering operations
+    GaussiansUpsampler: Converts transformer tokens to Gaussian parameters
+    LossComputer: Computes various loss functions for training
+    TransformTarget: Handles target image transformations (cropping, etc.)
+    GSLRM: Main model class that orchestrates the entire pipeline
+"""
+
+import copy
+import os
+import time
+from typing import Dict, List, Optional, Tuple, Union
+
+import cv2
+import lpips
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from easydict import EasyDict as edict
+from einops import rearrange
+from einops.layers.torch import Rearrange
+from PIL import Image
+
+# Local imports
+from .utils_losses import PerceptualLoss, SsimLoss
+from .gaussians_renderer import (
+    GaussianModel,
+    RGB2SH,
+    deferred_gaussian_render,
+    imageseq2video,
+    render_opencv_cam,
+    render_turntable,
+)
+from .transform_data import SplitData, TransformInput, TransformTarget
+from .utils_transformer import (
+    TransformerBlock,
+    _init_weights,
+)
+
+class Renderer(nn.Module):
+    """
+    Handles Gaussian splatting rendering operations.
+    
+    Supports both deferred rendering (for training with gradients) and
+    standard rendering (for inference).
+    """
+    
+    def __init__(self, config: edict):
+        super().__init__()
+        self.config = config
+        
+        # Initialize Gaussian model with scaling modifier
+        self.scaling_modifier = config.model.gaussians.get("scaling_modifier", None)
+        self.gaussians_model = GaussianModel(
+            config.model.gaussians.sh_degree, 
+            self.scaling_modifier
+        )
+        
+        print(f"Renderer initialized with scaling_modifier: {self.scaling_modifier}")
+
+    @torch.cuda.amp.custom_fwd(cast_inputs=torch.float32)
+    def forward(
+        self,
+        xyz: torch.Tensor,           # [b, n_gaussians, 3]
+        features: torch.Tensor,      # [b, n_gaussians, (sh_degree+1)^2, 3]
+        scaling: torch.Tensor,       # [b, n_gaussians, 3]
+        rotation: torch.Tensor,      # [b, n_gaussians, 4]
+        opacity: torch.Tensor,       # [b, n_gaussians, 1]
+        height: int,
+        width: int,
+        C2W: torch.Tensor,          # [b, v, 4, 4]
+        fxfycxcy: torch.Tensor,     # [b, v, 4]
+        deferred: bool = True,
+    ) -> torch.Tensor:              # [b, v, 3, height, width]
+        """
+        Render Gaussian splats to images.
+        
+        Args:
+            xyz: Gaussian positions
+            features: Gaussian spherical harmonic features
+            scaling: Gaussian scaling parameters
+            rotation: Gaussian rotation quaternions
+            opacity: Gaussian opacity values
+            height: Output image height
+            width: Output image width
+            C2W: Camera-to-world transformation matrices
+            fxfycxcy: Camera intrinsics (fx, fy, cx, cy)
+            deferred: Whether to use deferred rendering (maintains gradients)
+            
+        Returns:
+            Rendered images
+        """
+        if deferred:
+            return deferred_gaussian_render(
+                xyz, features, scaling, rotation, opacity,
+                height, width, C2W, fxfycxcy, self.scaling_modifier
+            )
+        else:
+            return self._render_sequential(
+                xyz, features, scaling, rotation, opacity,
+                height, width, C2W, fxfycxcy
+            )
+    
+    def _render_sequential(
+        self, xyz, features, scaling, rotation, opacity,
+        height, width, C2W, fxfycxcy
+    ) -> torch.Tensor:
+        """Sequential rendering without gradient support (used for inference)."""
+        b, v = C2W.size(0), C2W.size(1)
+        renderings = torch.zeros(
+            b, v, 3, height, width, dtype=torch.float32, device=xyz.device
+        )
+        
+        for i in range(b):
+            pc = self.gaussians_model.set_data(
+                xyz[i], features[i], scaling[i], rotation[i], opacity[i]
+            )
+            for j in range(v):
+                renderings[i, j] = render_opencv_cam(
+                    pc, height, width, C2W[i, j], fxfycxcy[i, j]
+                )["render"]
+                
+        return renderings
+
+
+class GaussiansUpsampler(nn.Module):
+    """
+    Converts transformer output tokens to Gaussian splatting parameters.
+    
+    Takes high-dimensional transformer features and projects them to the
+    concatenated Gaussian parameter space (xyz + features + scaling + rotation + opacity).
+    """
+    
+    def __init__(self, config: edict):
+        super().__init__()
+        self.config = config
+        
+        # Layer normalization before final projection
+        self.layernorm = nn.LayerNorm(config.model.transformer.d, bias=False)
+        
+        # Calculate output dimension for Gaussian parameters
+        sh_dim = (config.model.gaussians.sh_degree + 1) ** 2 * 3
+        gaussian_param_dim = 3 + sh_dim + 3 + 4 + 1  # xyz + features + scaling + rotation + opacity
+        
+        # Check upsampling factor (currently only supports 1x)
+        upsample_factor = config.model.gaussians.upsampler.upsample_factor
+        if upsample_factor > 1:
+            raise NotImplementedError("GaussiansUpsampler only supports upsample_factor=1")
+        
+        # Linear projection to Gaussian parameters
+        self.linear = nn.Linear(
+            config.model.transformer.d,
+            gaussian_param_dim,
+            bias=False,
+        )
+
+    def forward(
+        self, 
+        gaussians: torch.Tensor,  # [b, n_gaussians, d]
+        images: torch.Tensor      # [b, l, d] (unused but kept for interface compatibility)
+    ) -> torch.Tensor:           # [b, n_gaussians, gaussian_param_dim]
+        """
+        Convert transformer tokens to Gaussian parameters.
+        
+        Args:
+            gaussians: Transformer output tokens for Gaussians
+            images: Image tokens (unused but kept for compatibility)
+            
+        Returns:
+            Raw Gaussian parameters (before conversion to final format)
+        """
+        upsample_factor = self.config.model.gaussians.upsampler.upsample_factor
+        if upsample_factor > 1:
+            raise NotImplementedError("GaussiansUpsampler only supports upsample_factor=1")
+        
+        return self.linear(self.layernorm(gaussians))
+
+    def to_gs(self, gaussians: torch.Tensor) -> Tuple[torch.Tensor, ...]:
+        """
+        Convert raw Gaussian parameters to final format.
+        
+        Args:
+            gaussians: Raw Gaussian parameters [b, n_gaussians, param_dim]
+            
+        Returns:
+            Tuple of (xyz, features, scaling, rotation, opacity)
+        """
+        sh_dim = (self.config.model.gaussians.sh_degree + 1) ** 2 * 3
+        
+        # Split concatenated parameters
+        xyz, features, scaling, rotation, opacity = gaussians.split(
+            [3, sh_dim, 3, 4, 1], dim=2
+        )
+        
+        # Reshape features to proper spherical harmonics format
+        features = features.reshape(
+            features.size(0),
+            features.size(1),
+            (self.config.model.gaussians.sh_degree + 1) ** 2,
+            3,
+        )
+        
+        # Apply activation functions with specific biases
+        # Scaling: exp(x - 2.3) clamped to prevent too large values
+        scaling = (scaling - 2.3).clamp(max=-1.20)
+        
+        # Opacity: sigmoid(x - 2.0) to get values in [0, 1]
+        opacity = opacity - 2.0
+        
+        return xyz, features, scaling, rotation, opacity
+
+
+class LossComputer(nn.Module):
+    """
+    Computes various loss functions for training the GSLRM model.
+    
+    Supports multiple loss types:
+    - L2 (MSE) loss
+    - LPIPS perceptual loss
+    - Custom perceptual loss
+    - SSIM loss
+    - Pixel alignment loss
+    - Point distance regularization loss
+    """
+    
+    def __init__(self, config: edict):
+        super().__init__()
+        self.config = config
+        
+        # Initialize loss modules based on config
+        self._init_loss_modules()
+    
+    def _init_loss_modules(self):
+        """Initialize the various loss computation modules."""
+        # LPIPS loss
+        if self.config.training.losses.lpips_loss_weight > 0.0:
+            self.lpips_loss_module = lpips.LPIPS(net="vgg")
+            self.lpips_loss_module.eval()
+            # Freeze LPIPS parameters
+            for param in self.lpips_loss_module.parameters():
+                param.requires_grad = False
+
+        # Perceptual loss
+        if self.config.training.losses.perceptual_loss_weight > 0.0:
+            self.perceptual_loss_module = PerceptualLoss()
+            self.perceptual_loss_module.eval()
+            # Freeze perceptual loss parameters
+            for param in self.perceptual_loss_module.parameters():
+                param.requires_grad = False
+
+        # SSIM loss
+        if self.config.training.losses.ssim_loss_weight > 0.0:
+            self.ssim_loss_module = SsimLoss()
+            self.ssim_loss_module.eval()
+            # Freeze SSIM parameters
+            for param in self.ssim_loss_module.parameters():
+                param.requires_grad = False
+
+    def forward(
+        self,
+        rendering: torch.Tensor,        # [b, v, 3, h, w]
+        target: torch.Tensor,           # [b, v, 3, h, w]
+        img_aligned_xyz: torch.Tensor,  # [b, v, 3, h, w]
+        input: edict,
+        result_softpa: Optional[edict] = None,
+        create_visual: bool = False,
+    ) -> edict:
+        """
+        Compute all losses between rendered and target images.
+        
+        Args:
+            rendering: Rendered images in range [0, 1]
+            target: Target images in range [0, 1]
+            img_aligned_xyz: Image-aligned 3D positions
+            input: Input data containing ray information
+            result_softpa: Additional results (unused)
+            create_visual: Whether to create visualization images
+            
+        Returns:
+            Dictionary containing all loss values and metrics
+        """
+        b, v, _, h, w = rendering.size()
+        rendering_flat = rendering.reshape(b * v, -1, h, w)
+        target_flat = target.reshape(b * v, -1, h, w)
+        
+        # Handle alpha channel if present
+        mask = None
+        if target_flat.size(1) == 4:
+            target_flat, mask = target_flat.split([3, 1], dim=1)
+        
+        # Compute individual losses
+        losses = self._compute_all_losses(
+            rendering_flat, target_flat, img_aligned_xyz, input, mask, b, v, h, w
+        )
+        
+        # Compute total weighted loss
+        total_loss = self._compute_total_loss(losses)
+        
+        # Create visualization if requested
+        visual = self._create_visual(rendering_flat, target_flat, v) if create_visual else None
+        
+        # Compile loss metrics
+        return self._compile_loss_metrics(losses, total_loss, visual)
+    
+    def _compute_all_losses(self, rendering, target, img_aligned_xyz, input, mask, b, v, h, w):
+        """Compute all individual loss components."""
+        losses = {}
+        
+        # L2 (MSE) loss
+        losses['l2'] = self._compute_l2_loss(rendering, target)
+        losses['psnr'] = -10.0 * torch.log10(losses['l2'])
+        
+        # LPIPS loss
+        losses['lpips'] = self._compute_lpips_loss(rendering, target)
+        
+        # Perceptual loss
+        losses['perceptual'] = self._compute_perceptual_loss(rendering, target)
+        
+        # SSIM loss
+        losses['ssim'] = self._compute_ssim_loss(rendering, target)
+        
+        # Pixel alignment loss
+        losses['pixelalign'] = self._compute_pixelalign_loss(
+            img_aligned_xyz, input, mask, b, v, h, w
+        )
+        
+        # Point distance loss
+        losses['pointsdist'] = self._compute_pointsdist_loss(
+            img_aligned_xyz, input, b, v, h, w
+        )
+        
+        return losses
+    
+    def _compute_l2_loss(self, rendering, target):
+        """Compute L2 (MSE) loss."""
+        if self.config.training.losses.l2_loss_weight > 0.0:
+            return F.mse_loss(rendering, target)
+        return torch.tensor(1e-8, device=rendering.device)
+    
+    def _compute_lpips_loss(self, rendering, target):
+        """Compute LPIPS perceptual loss."""
+        if self.config.training.losses.lpips_loss_weight > 0.0:
+            # LPIPS expects inputs in range [-1, 1]
+            return self.lpips_loss_module(
+                rendering * 2.0 - 1.0, target * 2.0 - 1.0
+            ).mean()
+        return torch.tensor(0.0, device=rendering.device)
+    
+    def _compute_perceptual_loss(self, rendering, target):
+        """Compute custom perceptual loss."""
+        if self.config.training.losses.perceptual_loss_weight > 0.0:
+            return self.perceptual_loss_module(rendering, target)
+        return torch.tensor(0.0, device=rendering.device)
+    
+    def _compute_ssim_loss(self, rendering, target):
+        """Compute SSIM loss."""
+        if self.config.training.losses.ssim_loss_weight > 0.0:
+            return self.ssim_loss_module(rendering, target)
+        return torch.tensor(0.0, device=rendering.device)
+    
+    def _compute_pixelalign_loss(self, img_aligned_xyz, input, mask, b, v, h, w):
+        """Compute pixel alignment loss."""
+        if self.config.training.losses.pixelalign_loss_weight > 0.0:
+            # Compute orthogonal component to ray direction
+            xyz_vec = img_aligned_xyz - input.ray_o
+            ortho_vec = (
+                xyz_vec
+                - torch.sum(xyz_vec.detach() * input.ray_d, dim=2, keepdim=True)
+                * input.ray_d
+            )
+            
+            # Apply mask if enabled
+            if self.config.training.losses.get("masked_pixelalign_loss", False):
+                assert mask is not None, "mask is None but masked_pixelalign_loss is enabled"
+                mask_reshaped = mask.view(b, v, 1, h, w)
+                ortho_vec = ortho_vec * mask_reshaped
+            
+            return torch.mean(ortho_vec.norm(dim=2, p=2))
+        
+        return torch.tensor(0.0, device=img_aligned_xyz.device)
+    
+    def _compute_pointsdist_loss(self, img_aligned_xyz, input, b, v, h, w):
+        """Compute point distance regularization loss."""
+        if self.config.training.losses.pointsdist_loss_weight > 0.0:
+            # Target mean distance (distance from origin to ray origin)
+            target_mean_dist = torch.norm(input.ray_o, dim=2, p=2, keepdim=True)
+            target_std_dist = 0.5
+            
+            # Predicted distance
+            pred_dist = (img_aligned_xyz - input.ray_o).norm(dim=2, p=2, keepdim=True)
+            
+            # Normalize to target distribution
+            pred_dist_detach = pred_dist.detach()
+            pred_mean = pred_dist_detach.mean(dim=(2, 3, 4), keepdim=True)
+            pred_std = pred_dist_detach.std(dim=(2, 3, 4), keepdim=True)
+            
+            target_dist = (pred_dist_detach - pred_mean) / (pred_std + 1e-8) * target_std_dist + target_mean_dist
+            
+            return torch.mean((pred_dist - target_dist) ** 2)
+        
+        return torch.tensor(0.0, device=img_aligned_xyz.device)
+    
+    def _compute_total_loss(self, losses):
+        """Compute weighted sum of all losses."""
+        weights = self.config.training.losses
+        return (
+            weights.l2_loss_weight * losses['l2']
+            + weights.lpips_loss_weight * losses['lpips']
+            + weights.perceptual_loss_weight * losses['perceptual']
+            + weights.ssim_loss_weight * losses['ssim']
+            + weights.pixelalign_loss_weight * losses['pixelalign']
+            + weights.pointsdist_loss_weight * losses['pointsdist']
+        )
+    
+    def _create_visual(self, rendering, target, v):
+        """Create visualization by concatenating target and rendering."""
+        visual = torch.cat((target, rendering), dim=3).detach().cpu()  # [b*v, c, h, w*2]
+        visual = rearrange(visual, "(b v) c h (m w) -> (b h) (v m w) c", v=v, m=2)
+        return (visual.numpy() * 255.0).clip(0.0, 255.0).astype(np.uint8)
+    
+    def _compile_loss_metrics(self, losses, total_loss, visual):
+        """Compile all loss metrics into a dictionary."""
+        l2_loss = losses['l2']
+        
+        return edict(
+            loss=total_loss,
+            l2_loss=l2_loss,
+            psnr=losses['psnr'],
+            lpips_loss=losses['lpips'],
+            perceptual_loss=losses['perceptual'],
+            ssim_loss=losses['ssim'],
+            pixelalign_loss=losses['pixelalign'],
+            pointsdist_loss=losses['pointsdist'],
+            visual=visual,
+            # Normalized losses for logging
+            norm_perceptual_loss=losses['perceptual'] / l2_loss,
+            norm_lpips_loss=losses['lpips'] / l2_loss,
+            norm_ssim_loss=losses['ssim'] / l2_loss,
+            norm_pixelalign_loss=losses['pixelalign'] / l2_loss,
+            norm_pointsdist_loss=losses['pointsdist'] / l2_loss,
+        )
+
+
+class GSLRM(nn.Module):
+    """
+    Gaussian Splatting Large Reconstruction Model.
+    
+    A transformer-based model that generates 3D Gaussian splats from multi-view images.
+    The model processes input images through tokenization, transformer layers, and
+    generates Gaussian parameters for novel view synthesis.
+    
+    Architecture:
+    1. Image tokenization with patch-based encoding
+    2. Transformer processing with Gaussian positional embeddings
+    3. Gaussian parameter generation and upsampling
+    4. Rendering and loss computation
+    """
+    
+    def __init__(self, config: edict):
+        super().__init__()
+        self.config = config
+        
+        # Initialize data processing modules
+        self._init_data_processors(config)
+        
+        # Initialize core model components
+        self._init_tokenizer(config)
+        self._init_positional_embeddings(config)
+        self._init_transformer(config)
+        self._init_gaussian_modules(config)
+        self._init_rendering_modules(config)
+        
+        # Initialize training state management
+        self._init_training_state(config)
+    
+    def _init_data_processors(self, config: edict) -> None:
+        """Initialize data splitting and transformation modules."""
+        self.data_splitter = SplitData(config)
+        self.input_transformer = TransformInput(config)
+        self.target_transformer = TransformTarget(config)
+    
+    def _init_tokenizer(self, config: edict) -> None:
+        """Initialize image tokenization pipeline."""
+        patch_size = config.model.image_tokenizer.patch_size
+        input_channels = config.model.image_tokenizer.in_channels
+        hidden_dim = config.model.transformer.d
+        
+        self.patch_embedder = nn.Sequential(
+            Rearrange(
+                "batch views channels (height patch_h) (width patch_w) -> (batch views) (height width) (patch_h patch_w channels)",
+                patch_h=patch_size,
+                patch_w=patch_size,
+            ),
+            nn.Linear(
+                input_channels * (patch_size ** 2),
+                hidden_dim,
+                bias=False,
+            ),
+        )
+        self.patch_embedder.apply(_init_weights)
+    
+    def _init_positional_embeddings(self, config: edict) -> None:
+        """Initialize positional embeddings for reference/source markers and Gaussians."""
+        hidden_dim = config.model.transformer.d
+        
+        # Optional reference/source view markers
+        self.view_type_embeddings = None
+        if config.model.get("add_refsrc_marker", False):
+            self.view_type_embeddings = nn.Parameter(
+                torch.randn(2, hidden_dim)  # [reference_marker, source_marker]
+            )
+            nn.init.trunc_normal_(self.view_type_embeddings, std=0.02)
+        
+        # Gaussian positional embeddings
+        num_gaussians = config.model.gaussians.n_gaussians
+        self.gaussian_position_embeddings = nn.Parameter(
+            torch.randn(num_gaussians, hidden_dim)
+        )
+        nn.init.trunc_normal_(self.gaussian_position_embeddings, std=0.02)
+    
+    def _init_transformer(self, config: edict) -> None:
+        """Initialize transformer architecture."""
+        hidden_dim = config.model.transformer.d
+        head_dim = config.model.transformer.d_head
+        num_layers = config.model.transformer.n_layer
+        
+        self.input_layer_norm = nn.LayerNorm(hidden_dim, bias=False)
+        self.transformer_layers = nn.ModuleList([
+            TransformerBlock(hidden_dim, head_dim)
+            for _ in range(num_layers)
+        ])
+        self.transformer_layers.apply(_init_weights)
+    
+    def _init_gaussian_modules(self, config: edict) -> None:
+        """Initialize Gaussian parameter generation modules."""
+        hidden_dim = config.model.transformer.d
+        patch_size = config.model.image_tokenizer.patch_size
+        sh_degree = config.model.gaussians.sh_degree
+        
+        # Calculate output dimension for pixel-aligned Gaussians
+        # Components: xyz(3) + sh_features((sh_degree+1)^2*3) + scaling(3) + rotation(4) + opacity(1)
+        gaussian_param_dim = 3 + (sh_degree + 1) ** 2 * 3 + 3 + 4 + 1
+        
+        # Gaussian upsampler for transformer tokens
+        self.gaussian_upsampler = GaussiansUpsampler(config)
+        self.gaussian_upsampler.apply(_init_weights)
+        
+        # Pixel-aligned Gaussian decoder
+        self.pixel_gaussian_decoder = nn.Sequential(
+            nn.LayerNorm(hidden_dim, bias=False),
+            nn.Linear(
+                hidden_dim,
+                (patch_size ** 2) * gaussian_param_dim,
+                bias=False,
+            ),
+        )
+        self.pixel_gaussian_decoder.apply(_init_weights)
+    
+    def _init_rendering_modules(self, config: edict) -> None:
+        """Initialize rendering and loss computation modules."""
+        self.gaussian_renderer = Renderer(config)
+        self.loss_calculator = LossComputer(config)
+    
+    def _init_training_state(self, config: edict) -> None:
+        """Initialize training state management variables."""
+        self.training_step = None
+        self.training_start_step = None
+        self.training_max_step = None
+        self.original_config = copy.deepcopy(config)
+
+    def set_training_step(self, current_step: int, start_step: int, max_step: int) -> None:
+        """
+        Update training step and dynamically adjust configuration based on training phase.
+        
+        Args:
+            current_step: Current training step
+            start_step: Starting step of training
+            max_step: Maximum training steps
+        """
+        self.training_step = current_step
+        self.training_start_step = start_step
+        self.training_max_step = max_step
+
+        # Determine if config modification is needed based on warmup settings
+        needs_config_modification = self._should_modify_config_for_warmup(current_step)
+        
+        if needs_config_modification:
+            # Always use original config as base for modifications
+            self.config = copy.deepcopy(self.original_config)
+            self._apply_warmup_modifications(current_step)
+        else:
+            # Restore original configuration
+            self.config = self.original_config
+
+        # Update loss calculator with current config
+        self.loss_calculator.config = self.config
+    
+    def _should_modify_config_for_warmup(self, current_step: int) -> bool:
+        """Check if configuration should be modified for warmup phases."""
+        pointsdist_warmup = (
+            self.config.training.losses.get("warmup_pointsdist", False) 
+            and current_step < 1000
+        )
+        l2_warmup = (
+            self.config.training.schedule.get("l2_warmup_steps", 0) > 0 
+            and current_step < self.config.training.schedule.l2_warmup_steps
+        )
+        return pointsdist_warmup or l2_warmup
+    
+    def _apply_warmup_modifications(self, current_step: int) -> None:
+        """Apply configuration modifications for warmup phases."""
+        # Point distance warmup phase
+        if (self.config.training.losses.get("warmup_pointsdist", False) 
+            and current_step < 1000):
+            self.config.training.losses.l2_loss_weight = 0.0
+            self.config.training.losses.perceptual_loss_weight = 0.0
+            self.config.training.losses.pointsdist_loss_weight = 0.1
+            self.config.model.clip_xyz = False  # Disable xyz clipping during warmup
+
+        # L2 loss warmup phase
+        if (self.config.training.schedule.get("l2_warmup_steps", 0) > 0 
+            and current_step < self.config.training.schedule.l2_warmup_steps):
+            self.config.training.losses.perceptual_loss_weight = 0.0
+            self.config.training.losses.lpips_loss_weight = 0.0
+    
+    def set_current_step(self, current_step: int, start_step: int, max_step: int) -> None:
+        """Backward compatibility wrapper for set_training_step."""
+        self.set_training_step(current_step, start_step, max_step)
+
+    def train(self, mode: bool = True) -> None:
+        """
+        Override train method to keep frozen modules in eval mode.
+        
+        Args:
+            mode: Whether to set training mode (True) or evaluation mode (False)
+        """
+        super().train(mode)
+        # Keep loss calculator in eval mode to prevent training of frozen components
+        if self.loss_calculator is not None:
+            self.loss_calculator.eval()
+
+    def get_parameter_overview(self) -> edict:
+        """
+        Get overview of trainable parameters in each module.
+        
+        Returns:
+            Dictionary containing parameter counts for each major component
+        """
+        def count_trainable_params(module: nn.Module) -> int:
+            return sum(p.numel() for p in module.parameters() if p.requires_grad)
+
+        return edict(
+            patch_embedder=count_trainable_params(self.patch_embedder),
+            gaussian_position_embeddings=self.gaussian_position_embeddings.data.numel(),
+            transformer_total=(
+                count_trainable_params(self.transformer_layers) +
+                count_trainable_params(self.input_layer_norm)
+            ),
+            gaussian_upsampler=count_trainable_params(self.gaussian_upsampler),
+            pixel_gaussian_decoder=count_trainable_params(self.pixel_gaussian_decoder),
+        )
+    
+    def get_overview(self) -> edict:
+        """Backward compatibility wrapper for get_parameter_overview."""
+        return self.get_parameter_overview()
+
+    def _create_transformer_layer_runner(self, start_layer: int, end_layer: int):
+        """
+        Create a function to run a subset of transformer layers.
+        
+        Args:
+            start_layer: Starting layer index
+            end_layer: Ending layer index (exclusive)
+            
+        Returns:
+            Function that processes tokens through specified layers
+        """
+        def run_transformer_layers(token_sequence: torch.Tensor) -> torch.Tensor:
+            for layer_idx in range(start_layer, min(end_layer, len(self.transformer_layers))):
+                token_sequence = self.transformer_layers[layer_idx](token_sequence)
+            return token_sequence
+        return run_transformer_layers
+    
+    def _create_posed_images_with_plucker(self, input_data: edict) -> torch.Tensor:
+        """
+        Create posed images by concatenating RGB with Plucker coordinates.
+        
+        Args:
+            input_data: Input data containing images and ray information
+            
+        Returns:
+            Posed images with Plucker coordinates [batch, views, channels, height, width]
+        """
+        # Normalize RGB to [-1, 1] range
+        normalized_rgb = input_data.image[:, :, :3, :, :] * 2.0 - 1.0
+        
+        if self.config.model.get("use_custom_plucker", False):
+            # Custom Plucker: RGB + ray_direction + nearest_points
+            ray_origin_dot_direction = torch.sum(
+                -input_data.ray_o * input_data.ray_d, dim=2, keepdim=True
+            )
+            nearest_points = input_data.ray_o + ray_origin_dot_direction * input_data.ray_d
+            
+            return torch.cat([
+                normalized_rgb,
+                input_data.ray_d,
+                nearest_points,
+            ], dim=2)
+            
+        elif self.config.model.get("use_aug_plucker", False):
+            # Augmented Plucker: RGB + cross_product + ray_direction + nearest_points
+            ray_cross_product = torch.cross(input_data.ray_o, input_data.ray_d, dim=2)
+            ray_origin_dot_direction = torch.sum(
+                -input_data.ray_o * input_data.ray_d, dim=2, keepdim=True
+            )
+            nearest_points = input_data.ray_o + ray_origin_dot_direction * input_data.ray_d
+            
+            return torch.cat([
+                normalized_rgb,
+                ray_cross_product,
+                input_data.ray_d,
+                nearest_points,
+            ], dim=2)
+            
+        else:
+            # Standard Plucker: RGB + cross_product + ray_direction
+            ray_cross_product = torch.cross(input_data.ray_o, input_data.ray_d, dim=2)
+            
+            return torch.cat([
+                normalized_rgb,
+                ray_cross_product,
+                input_data.ray_d,
+            ], dim=2)
+    
+    def _add_view_type_embeddings(
+        self, 
+        image_tokens: torch.Tensor, 
+        batch_size: int, 
+        num_views: int, 
+        num_patches: int, 
+        hidden_dim: int
+    ) -> torch.Tensor:
+        """Add view type embeddings to distinguish reference vs source views."""
+        image_tokens = image_tokens.reshape(batch_size, num_views, num_patches, hidden_dim)
+        
+        # Create view type markers: first view is reference, rest are source
+        view_markers = [self.view_type_embeddings[0]] + [
+            self.view_type_embeddings[1] for _ in range(1, num_views)
+        ]
+        view_markers = torch.stack(view_markers, dim=0)[None, :, None, :]  # [1, views, 1, hidden_dim]
+        
+        # Add markers to image tokens
+        image_tokens = image_tokens + view_markers
+        return image_tokens.reshape(batch_size, num_views * num_patches, hidden_dim)
+    
+    def _process_through_transformer(
+        self, 
+        gaussian_tokens: torch.Tensor, 
+        image_tokens: torch.Tensor
+    ) -> torch.Tensor:
+        """Process combined tokens through transformer with gradient checkpointing."""
+        # Combine Gaussian and image tokens
+        combined_tokens = torch.cat((gaussian_tokens, image_tokens), dim=1)
+        combined_tokens = self.input_layer_norm(combined_tokens)
+        
+        # Process through transformer layers with gradient checkpointing
+        checkpoint_interval = self.config.training.runtime.grad_checkpoint_every
+        num_layers = len(self.transformer_layers)
+        
+        for start_idx in range(0, num_layers, checkpoint_interval):
+            end_idx = start_idx + checkpoint_interval
+            layer_runner = self._create_transformer_layer_runner(start_idx, end_idx)
+            
+            combined_tokens = torch.utils.checkpoint.checkpoint(
+                layer_runner,
+                combined_tokens,
+                use_reentrant=False,
+            )
+        
+        return combined_tokens
+    
+    def _apply_hard_pixel_alignment(
+        self, 
+        pixel_aligned_xyz: torch.Tensor, 
+        input_data: edict
+    ) -> torch.Tensor:
+        """Apply hard pixel alignment to ensure Gaussians align with ray directions."""
+        depth_bias = self.config.model.get("depth_preact_bias", 0.0)
+        
+        # Apply sigmoid activation to depth values
+        depth_values = torch.sigmoid(
+            pixel_aligned_xyz.mean(dim=2, keepdim=True) + depth_bias
+        )
+        
+        # Apply different depth computation strategies
+        if (self.config.model.get("use_aug_plucker", False) or 
+            self.config.model.get("use_custom_plucker", False)):
+            # For Plucker coordinates: use dot product offset
+            ray_origin_dot_direction = torch.sum(
+                -input_data.ray_o * input_data.ray_d, dim=2, keepdim=True
+            )
+            depth_values = (2.0 * depth_values - 1.0) * 1.8 + ray_origin_dot_direction
+            
+        elif (self.config.model.get("depth_min", -1.0) > 0.0 and 
+              self.config.model.get("depth_max", -1.0) > 0.0):
+            # Use explicit depth range
+            depth_min = self.config.model.depth_min
+            depth_max = self.config.model.depth_max
+            depth_values = depth_values * (depth_max - depth_min) + depth_min
+            
+        elif self.config.model.get("depth_reference_origin", False):
+            # Reference from ray origin norm
+            ray_origin_norm = input_data.ray_o.norm(dim=2, p=2, keepdim=True)
+            depth_values = (2.0 * depth_values - 1.0) * 1.8 + ray_origin_norm
+            
+        else:
+            # Default depth computation
+            depth_values = (2.0 * depth_values - 1.0) * 1.5 + 2.7
+        
+        # Compute final 3D positions along rays
+        aligned_positions = input_data.ray_o + depth_values * input_data.ray_d
+        
+        # Apply coordinate clipping if enabled (only during training)
+        if (self.config.model.get("clip_xyz", False) and 
+            not self.config.inference):
+            aligned_positions = aligned_positions.clamp(-1.0, 1.0)
+        
+        return aligned_positions
+    
+    @staticmethod
+    def translate_legacy_state_dict(state_dict: Dict[str, torch.Tensor]) -> Dict[str, torch.Tensor]:
+        """
+        Translate legacy model parameter names to new parameter names.
+        
+        This function allows loading models saved with the old variable names
+        by mapping them to the new, cleaner variable names.
+        
+        Args:
+            state_dict: Dictionary containing model parameters with old names
+            
+        Returns:
+            Dictionary with parameters mapped to new names
+        """
+        # Define the mapping from old names to new names
+        name_mapping = {
+            # Data processors
+            'split_data.': 'data_splitter.',
+            'transform_input.': 'input_transformer.',
+            'transform_target.': 'target_transformer.',
+            
+            # Tokenizer
+            'image_tokenizer.': 'patch_embedder.',
+            
+            # Positional embeddings
+            'refsrc_marker': 'view_type_embeddings',
+            'gaussians_pos_embedding': 'gaussian_position_embeddings',
+            
+            # Transformer
+            'transformer_input_layernorm.': 'input_layer_norm.',
+            'transformer.': 'transformer_layers.',
+            
+            # Gaussian modules
+            'upsampler.': 'gaussian_upsampler.',
+            'image_token_decoder.': 'pixel_gaussian_decoder.',
+            
+            # Rendering modules
+            'renderer.': 'gaussian_renderer.',
+            'loss_computer.': 'loss_calculator.',
+        }
+        
+        # Create new state dict with translated names
+        new_state_dict = {}
+        
+        for old_key, value in state_dict.items():
+            new_key = old_key
+            
+            # Apply name mappings
+            for old_pattern, new_pattern in name_mapping.items():
+                if old_key.startswith(old_pattern):
+                    new_key = old_key.replace(old_pattern, new_pattern, 1)
+                    break
+            
+            # Fix specific key naming issues
+            # Change loss_computer.perceptual_loss_module.Net to loss_computer.perceptual_loss_module.net
+            if "loss_computer.perceptual_loss_module.Net" in new_key:
+                old_net_key = new_key
+                new_key = new_key.replace("loss_computer.perceptual_loss_module.Net", "loss_computer.perceptual_loss_module.net")
+                print(f"Renamed checkpoint key: {old_net_key} -> {new_key}")
+            # Also handle the new naming convention
+            elif "loss_calculator.perceptual_loss_module.Net" in new_key:
+                old_net_key = new_key
+                new_key = new_key.replace("loss_calculator.perceptual_loss_module.Net", "loss_calculator.perceptual_loss_module.net")
+                print(f"Renamed checkpoint key: {old_net_key} -> {new_key}")
+            
+            new_state_dict[new_key] = value
+        
+        return new_state_dict
+    
+    def load_state_dict(self, state_dict: Dict[str, torch.Tensor], strict: bool = True):
+        """
+        Load model state dict with automatic legacy name translation.
+        
+        Args:
+            state_dict: Model state dictionary (potentially with old parameter names)
+            strict: Whether to strictly enforce parameter name matching
+        """
+        # Check if this is a legacy state dict by looking for old parameter names
+        legacy_indicators = [
+            'image_tokenizer.',
+            'refsrc_marker',
+            'gaussians_pos_embedding',
+            'transformer_input_layernorm.',
+            'upsampler.',
+            'image_token_decoder.',
+            'renderer.',
+            'loss_computer.'
+        ]
+        
+        is_legacy = any(
+            any(key.startswith(indicator) for key in state_dict.keys())
+            for indicator in legacy_indicators
+        )
+        
+        if is_legacy:
+            print("Detected legacy model format. Translating parameter names...")
+            state_dict = self.translate_legacy_state_dict(state_dict)
+            print("Parameter name translation completed.")
+        
+        # Load the (potentially translated) state dict
+        return super().load_state_dict(state_dict, strict=strict)
+    
+    @classmethod
+    def load_from_checkpoint(
+        cls, 
+        checkpoint_path: str, 
+        config: edict, 
+        map_location: Optional[str] = None
+    ) -> 'GSLRM':
+        """
+        Load model from checkpoint with automatic legacy name translation.
+        
+        Args:
+            checkpoint_path: Path to the checkpoint file
+            config: Model configuration
+            map_location: Device to map tensors to (e.g., 'cpu', 'cuda:0')
+            
+        Returns:
+            Loaded GSLRM model
+        """
+        # Create model instance
+        model = cls(config)
+        
+        # Load checkpoint
+        checkpoint = torch.load(checkpoint_path, map_location=map_location)
+        
+        # Extract state dict (handle different checkpoint formats)
+        if isinstance(checkpoint, dict):
+            if 'model_state_dict' in checkpoint:
+                state_dict = checkpoint['model_state_dict']
+            elif 'state_dict' in checkpoint:
+                state_dict = checkpoint['state_dict']
+            else:
+                state_dict = checkpoint
+        else:
+            state_dict = checkpoint
+        
+        # Load state dict with automatic translation
+        model.load_state_dict(state_dict)
+        
+        print(f"Successfully loaded model from {checkpoint_path}")
+        return model
+    
+    def _create_gaussian_models_and_stats(
+        self,
+        xyz: torch.Tensor,
+        features: torch.Tensor, 
+        scaling: torch.Tensor,
+        rotation: torch.Tensor,
+        opacity: torch.Tensor,
+        num_pixel_aligned: int,
+        num_views: int,
+        height: int,
+        width: int,
+        patch_size: int
+    ) -> Tuple[List, torch.Tensor, List[float]]:
+        """
+        Create Gaussian models for each batch item and compute usage statistics.
+        
+        Returns:
+            Tuple of (gaussian_models, pixel_aligned_positions, usage_statistics)
+        """
+        gaussian_models = []
+        pixel_aligned_positions_list = []
+        usage_statistics = []
+        
+        batch_size = xyz.size(0)
+        opacity_threshold = 0.05
+        
+        for batch_idx in range(batch_size):
+            # Create fresh Gaussian model for this batch item
+            self.gaussian_renderer.gaussians_model.empty()
+            gaussian_model = copy.deepcopy(self.gaussian_renderer.gaussians_model)
+            
+            # Set Gaussian data
+            gaussian_model = gaussian_model.set_data(
+                xyz[batch_idx].detach().float(),
+                features[batch_idx].detach().float(),
+                scaling[batch_idx].detach().float(),
+                rotation[batch_idx].detach().float(),
+                opacity[batch_idx].detach().float(),
+            )
+            gaussian_models.append(gaussian_model)
+
+            # Compute usage statistics (fraction of Gaussians above opacity threshold)
+            opacity_mask = gaussian_model.get_opacity > opacity_threshold
+            usage_ratio = opacity_mask.sum() / opacity_mask.numel()
+            if torch.is_tensor(usage_ratio):
+                usage_ratio = usage_ratio.item()
+            usage_statistics.append(usage_ratio)
+
+            # Extract pixel-aligned positions and reshape
+            pixel_xyz = gaussian_model.get_xyz[-num_pixel_aligned:, :]
+            pixel_xyz_reshaped = rearrange(
+                pixel_xyz,
+                "(views height width patch_h patch_w) coords -> views coords (height patch_h) (width patch_w)",
+                views=num_views,
+                height=height // patch_size,
+                width=width // patch_size,
+                patch_h=patch_size,
+                patch_w=patch_size,
+            )
+            pixel_aligned_positions_list.append(pixel_xyz_reshaped)
+        
+        # Stack pixel-aligned positions
+        pixel_aligned_positions = torch.stack(pixel_aligned_positions_list, dim=0)
+        
+        return gaussian_models, pixel_aligned_positions, usage_statistics
+
+    def forward(
+        self, 
+        batch_data: edict, 
+        create_visual: bool = False, 
+        split_data: bool = True
+    ) -> edict:
+        """
+        Forward pass of the GSLRM model.
+        
+        Args:
+            batch_data: Input batch containing:
+                - image: Multi-view images [batch, views, channels, height, width]
+                - fxfycxcy: Camera intrinsics [batch, views, 4]
+                - c2w: Camera-to-world matrices [batch, views, 4, 4]
+            create_visual: Whether to create visualization outputs
+            split_data: Whether to split input/target data
+            
+        Returns:
+            Dictionary containing model outputs including Gaussians, renders, and losses
+        """
+        with torch.no_grad():
+            target_data = None
+            if split_data:
+                batch_data, target_data = self.data_splitter(
+                    batch_data, self.config.training.dataset.target_has_input
+                )
+                target_data = self.target_transformer(target_data)
+
+            input_data = self.input_transformer(batch_data)
+
+            # Prepare posed images with Plucker coordinates [batch, views, channels, height, width]
+            posed_images = self._create_posed_images_with_plucker(input_data)
+
+        # Process images through tokenization and transformer
+        batch_size, num_views, channels, height, width = posed_images.size()
+        
+        # Tokenize images into patches
+        image_patch_tokens = self.patch_embedder(posed_images)  # [batch*views, num_patches, hidden_dim]
+        _, num_patches, hidden_dim = image_patch_tokens.size()
+        image_patch_tokens = image_patch_tokens.reshape(
+            batch_size, num_views * num_patches, hidden_dim
+        )  # [batch, views*patches, hidden_dim]
+
+        # Add view type embeddings if enabled (reference vs source views)
+        if self.view_type_embeddings is not None:
+            image_patch_tokens = self._add_view_type_embeddings(
+                image_patch_tokens, batch_size, num_views, num_patches, hidden_dim
+            )
+
+        # Prepare Gaussian tokens with positional embeddings
+        gaussian_tokens = self.gaussian_position_embeddings.expand(batch_size, -1, -1)
+
+        # Process through transformer with gradient checkpointing
+        combined_tokens = self._process_through_transformer(
+            gaussian_tokens, image_patch_tokens
+        )
+
+        # Split back into Gaussian and image tokens
+        num_gaussians = self.config.model.gaussians.n_gaussians
+        gaussian_tokens, image_patch_tokens = combined_tokens.split(
+            [num_gaussians, num_views * num_patches], dim=1
+        )
+        
+        # Generate Gaussian parameters from transformer outputs
+        gaussian_params = self.gaussian_upsampler(gaussian_tokens, image_patch_tokens)
+
+        # Generate pixel-aligned Gaussians from image tokens
+        pixel_aligned_gaussian_params = self.pixel_gaussian_decoder(image_patch_tokens)
+        
+        # Calculate Gaussian parameter dimensions
+        sh_degree = self.config.model.gaussians.sh_degree
+        gaussian_param_dim = 3 + (sh_degree + 1) ** 2 * 3 + 3 + 4 + 1
+        
+        pixel_aligned_gaussian_params = pixel_aligned_gaussian_params.reshape(
+            batch_size, -1, gaussian_param_dim
+        )  # [batch, views*pixels, gaussian_params]
+        num_pixel_aligned_gaussians = pixel_aligned_gaussian_params.size(1)
+
+        # Combine all Gaussian parameters
+        all_gaussian_params = torch.cat((gaussian_params, pixel_aligned_gaussian_params), dim=1)
+        
+        # Convert to final Gaussian format
+        xyz, features, scaling, rotation, opacity = self.gaussian_upsampler.to_gs(all_gaussian_params)
+
+        # Extract pixel-aligned Gaussian positions for processing
+        pixel_aligned_xyz = xyz[:, -num_pixel_aligned_gaussians:, :]
+        patch_size = self.config.model.image_tokenizer.patch_size
+        
+        pixel_aligned_xyz = rearrange(
+            pixel_aligned_xyz,
+            "batch (views height width patch_h patch_w) coords -> batch views coords (height patch_h) (width patch_w)",
+            views=num_views,
+            height=height // patch_size,
+            width=width // patch_size,
+            patch_h=patch_size,
+            patch_w=patch_size,
+        )
+
+        # Apply hard pixel alignment if enabled
+        if self.config.model.hard_pixelalign:
+            pixel_aligned_xyz = self._apply_hard_pixel_alignment(
+                pixel_aligned_xyz, input_data
+            )
+            
+            # Reshape back to flat format and update xyz
+            pixel_aligned_xyz_flat = rearrange(
+                pixel_aligned_xyz,
+                "batch views coords (height patch_h) (width patch_w) -> batch (views height width patch_h patch_w) coords",
+                patch_h=patch_size,
+                patch_w=patch_size,
+            )
+            
+            # Replace pixel-aligned Gaussians in the full xyz tensor
+            xyz = torch.cat(
+                (xyz[:, :-num_pixel_aligned_gaussians, :], pixel_aligned_xyz_flat), 
+                dim=1
+            )
+
+        # Create Gaussian splatting result structure
+        gaussian_splat_result = edict(
+            xyz=xyz,
+            features=features,
+            scaling=scaling,
+            rotation=rotation,
+            opacity=opacity,
+        )
+
+        # Perform rendering and loss computation if target data is available
+        loss_metrics = None
+        rendered_images = None
+        
+        if target_data is not None:
+            target_height, target_width = target_data.image.size(3), target_data.image.size(4)
+            
+            # Render images using Gaussian splatting
+            rendered_images = self.gaussian_renderer(
+                xyz, features, scaling, rotation, opacity,
+                target_height, target_width,
+                C2W=target_data.c2w,
+                fxfycxcy=target_data.fxfycxcy,
+            )
+            
+            # Compute losses if rendered and target have matching dimensions
+            if rendered_images.shape[1] == target_data.image.shape[1]:
+                loss_metrics = self.loss_calculator(
+                    rendered_images,
+                    target_data.image,
+                    pixel_aligned_xyz,
+                    input_data,
+                    create_visual=create_visual,
+                    result_softpa=gaussian_splat_result,
+                )
+
+        # Create Gaussian models for each batch item and compute usage statistics
+        gaussian_models, pixel_aligned_positions, usage_statistics = self._create_gaussian_models_and_stats(
+            xyz, features, scaling, rotation, opacity, 
+            num_pixel_aligned_gaussians, num_views, height, width, patch_size
+        )
+
+        # Add usage statistics to loss metrics for logging
+        if loss_metrics is not None:
+            loss_metrics.gaussians_usage = torch.tensor(
+                np.mean(np.array(usage_statistics))
+            ).float()
+
+        # Compile final results
+        return edict(
+            input=input_data,
+            target=target_data,
+            gaussians=gaussian_models,
+            pixelalign_xyz=pixel_aligned_positions,
+            img_tokens=image_patch_tokens,
+            loss_metrics=loss_metrics,
+            render=rendered_images,
+        )
+
+    @torch.no_grad()
+    def save_visualization_outputs(
+        self, 
+        output_directory: str, 
+        model_results: edict, 
+        batch_data: edict, 
+        save_all_items: bool = False
+    ) -> None:
+        """
+        Save visualization outputs including rendered images and Gaussian models.
+        
+        Args:
+            output_directory: Directory to save outputs
+            model_results: Results from model forward pass
+            batch_data: Original batch data
+            save_all_items: Whether to save all batch items or just the first
+        """
+        os.makedirs(output_directory, exist_ok=True)
+
+        input_data, target_data = model_results.input, model_results.target
+        
+        # Save supervision visualization if available
+        if (model_results.loss_metrics is not None and 
+            model_results.loss_metrics.visual is not None):
+            
+            batch_uids = [
+                target_data.index[b, 0, -1].item() 
+                for b in range(target_data.index.size(0))
+            ]
+
+            uid_range = f"{batch_uids[0]:08}_{batch_uids[-1]:08}"
+            
+            # Save supervision comparison image
+            Image.fromarray(model_results.loss_metrics.visual).save(
+                os.path.join(output_directory, f"supervision_{uid_range}.jpg")
+            )
+            
+            # Save UIDs for reference
+            with open(os.path.join(output_directory, "uids.txt"), "w") as f:
+                uid_string = "_".join([f"{uid:08}" for uid in batch_uids])
+                f.write(uid_string)
+
+            # Save input images
+            input_visualization = rearrange(
+                input_data.image, "batch views channels height width -> (batch height) (views width) channels"
+            )
+            input_visualization = (
+                (input_visualization.cpu().numpy() * 255.0).clip(0.0, 255.0).astype(np.uint8)
+            )
+            Image.fromarray(input_visualization[..., :3]).save(
+                os.path.join(output_directory, f"input_{uid_range}.jpg")
+            )
+
+        # Process each batch item individually
+        batch_size = input_data.image.size(0)
+        for batch_idx in range(batch_size):
+            item_uid = input_data.index[batch_idx, 0, -1].item()
+
+            # Render turntable visualization
+            turntable_image = render_turntable(model_results.gaussians[batch_idx])
+            Image.fromarray(turntable_image).save(
+                os.path.join(output_directory, f"turntable_{item_uid}.jpg")
+            )
+
+            # Save individual input images during inference
+            if self.config.inference:
+                individual_input = rearrange(
+                    input_data.image[batch_idx], "views channels height width -> height (views width) channels"
+                )
+                individual_input = (
+                    (individual_input.cpu().numpy() * 255.0).clip(0.0, 255.0).astype(np.uint8)
+                )
+                Image.fromarray(individual_input[..., :3]).save(
+                    os.path.join(output_directory, f"input_{item_uid}.jpg")
+                )
+
+            # Extract image dimensions and create opacity/depth visualizations
+            _, num_views, _, img_height, img_width = input_data.image.size()
+            patch_size = self.config.model.image_tokenizer.patch_size
+            
+            # Get opacity values for pixel-aligned Gaussians
+            gaussian_opacity = model_results.gaussians[batch_idx].get_opacity
+            pixel_opacity = gaussian_opacity[-num_views * img_height * img_width:]
+            
+            # Reshape opacity to image format
+            opacity_visualization = rearrange(
+                pixel_opacity,
+                "(views height width patch_h patch_w) channels -> (height patch_h) (views width patch_w) channels",
+                views=num_views,
+                height=img_height // patch_size,
+                width=img_width // patch_size,
+                patch_h=patch_size,
+                patch_w=patch_size,
+            ).squeeze(-1).cpu().numpy()
+            opacity_visualization = (opacity_visualization * 255.0).clip(0.0, 255.0).astype(np.uint8)
+
+            # Get 3D positions and compute depth visualization
+            gaussian_positions = model_results.gaussians[batch_idx].get_xyz
+            pixel_positions = gaussian_positions[-num_views * img_height * img_width:]
+            
+            # Reshape positions to image format
+            pixel_positions_reshaped = rearrange(
+                pixel_positions,
+                "(views height width patch_h patch_w) coords -> views coords (height patch_h) (width patch_w)",
+                views=num_views,
+                height=img_height // patch_size,
+                width=img_width // patch_size,
+                patch_h=patch_size,
+                patch_w=patch_size,
+            )
+            
+            # Compute distances from ray origins
+            ray_distances = (pixel_positions_reshaped - input_data.ray_o[batch_idx]).norm(dim=1, p=2)
+            distance_visualization = rearrange(ray_distances, "views height width -> height (views width)")
+            distance_visualization = distance_visualization.cpu().numpy()
+            
+            # Normalize distances for visualization
+            dist_min, dist_max = distance_visualization.min(), distance_visualization.max()
+            distance_visualization = (distance_visualization - dist_min) / (dist_max - dist_min)
+            distance_visualization = (distance_visualization * 255.0).clip(0.0, 255.0).astype(np.uint8)
+
+            # Combine opacity and depth visualizations
+            combined_visualization = np.concatenate([opacity_visualization, distance_visualization], axis=0)
+            Image.fromarray(combined_visualization).save(
+                os.path.join(output_directory, f"aligned_gs_opacity_depth_{item_uid}.jpg")
+            )
+
+            # Save unfiltered Gaussian model for small images during early training
+            if (self.config.model.image_tokenizer.image_size <= 256 and 
+                self.training_step is not None and self.training_step <= 5000):
+                model_results.gaussians[batch_idx].save_ply(
+                    os.path.join(output_directory, f"gaussians_{item_uid}_unfiltered.ply")
+                )
+
+            # Save filtered Gaussian model
+            camera_origins = None  # Could use input_data.ray_o[batch_idx, :, :, 0, 0] if needed
+            default_crop_box = [-0.91, 0.91, -0.91, 0.91, -0.91, 0.91]
+            
+            model_results.gaussians[batch_idx].apply_all_filters(
+                opacity_thres=0.02,
+                crop_bbx=default_crop_box,
+                cam_origins=camera_origins,
+                nearfar_percent=(0.0001, 1.0),
+            ).save_ply(os.path.join(output_directory, f"gaussians_{item_uid}.ply"))
+            
+            print(f"Saved visualization for UID: {item_uid}")
+
+            # Break after first item unless saving all
+            if not save_all_items:
+                break
+    
+    @torch.no_grad()
+    def save_visuals(self, out_dir: str, result: edict, batch: edict, save_all: bool = False) -> None:
+        """Backward compatibility wrapper for save_visualization_outputs."""
+        self.save_visualization_outputs(out_dir, result, batch, save_all)
+
+    @torch.no_grad()
+    def save_evaluation_results(
+        self, 
+        output_directory: str, 
+        model_results: edict, 
+        batch_data: edict, 
+        dataset
+    ) -> None:
+        """Save comprehensive evaluation results including metrics, visualizations, and 3D models."""
+        from .utils_metrics import compute_psnr, compute_lpips, compute_ssim
+
+        os.makedirs(output_directory, exist_ok=True)
+        input_data, target_data = model_results.input, model_results.target
+        
+        for batch_idx in range(input_data.image.size(0)):
+            item_uid = input_data.index[batch_idx, 0, -1].item()
+            item_output_dir = os.path.join(output_directory, f"{item_uid:08d}")
+            os.makedirs(item_output_dir, exist_ok=True)
+            
+            # Save input image
+            input_image = rearrange(
+                input_data.image[batch_idx], "views channels height width -> height (views width) channels"
+            )
+            input_image = (input_image.cpu().numpy() * 255.0).clip(0.0, 255.0).astype(np.uint8)
+            Image.fromarray(input_image[..., :3]).save(os.path.join(item_output_dir, "input.png"))
+
+            # Save ground truth vs prediction comparison
+            comparison_image = torch.stack((target_data.image[batch_idx], model_results.render[batch_idx]), dim=0)
+            num_views = comparison_image.size(1)
+            if num_views > 10:
+                comparison_image = comparison_image[:, ::num_views // 10, :, :, :]
+            comparison_image = rearrange(
+                comparison_image, "comparison_type views channels height width -> (comparison_type height) (views width) channels"
+            )
+            comparison_image = (comparison_image.cpu().numpy() * 255.0).clip(0.0, 255.0).astype(np.uint8)
+            Image.fromarray(comparison_image).save(os.path.join(item_output_dir, "gt_vs_pred.png"))
+            
+            # Compute and save metrics
+            per_view_psnr = compute_psnr(target_data.image[batch_idx], model_results.render[batch_idx])
+            per_view_lpips = compute_lpips(target_data.image[batch_idx], model_results.render[batch_idx])
+            per_view_ssim = compute_ssim(target_data.image[batch_idx], model_results.render[batch_idx])
+
+            # Save per-view metrics
+            view_ids = target_data.index[batch_idx, :, 0].cpu().numpy()
+            with open(os.path.join(item_output_dir, "perview_metrics.txt"), "w") as f:
+                for i in range(per_view_psnr.size(0)):
+                    f.write(
+                        f"view {view_ids[i]:0>6}, psnr: {per_view_psnr[i].item():.4f}, "
+                        f"lpips: {per_view_lpips[i].item():.4f}, ssim: {per_view_ssim[i].item():.4f}\n"
+                    )
+
+            # Save average metrics
+            avg_psnr = per_view_psnr.mean().item()
+            avg_lpips = per_view_lpips.mean().item()
+            avg_ssim = per_view_ssim.mean().item()
+            
+            with open(os.path.join(item_output_dir, "metrics.txt"), "w") as f:
+                f.write(f"psnr: {avg_psnr:.4f}\nlpips: {avg_lpips:.4f}\nssim: {avg_ssim:.4f}\n")
+            
+            print(f"UID {item_uid}: PSNR={avg_psnr:.4f}, LPIPS={avg_lpips:.4f}, SSIM={avg_ssim:.4f}")
+            
+            # Save Gaussian model
+            crop_box = None
+            if self.config.model.get("clip_xyz", False):
+                if self.config.model.get("half_bbx_size", None) is not None:
+                    half_size = self.config.model.half_bbx_size
+                    crop_box = [-half_size, half_size, -half_size, half_size, -half_size, half_size]
+                else:
+                    crop_box = [-0.91, 0.91, -0.91, 0.91, -0.91, 0.91]
+            
+            model_results.gaussians[batch_idx].apply_all_filters(
+                opacity_thres=0.02, crop_bbx=crop_box, cam_origins=None, nearfar_percent=(0.0001, 1.0)
+            ).save_ply(os.path.join(item_output_dir, "gaussians.ply"))
+            
+            # Create turntable visualization
+            num_turntable_views = 150
+            render_resolution = input_image.shape[0]
+            
+            turntable_frames = render_turntable(
+                model_results.gaussians[batch_idx], rendering_resolution=render_resolution, num_views=num_turntable_views
+            )
+            turntable_frames = rearrange(
+                turntable_frames, "height (views width) channels -> views height width channels", views=num_turntable_views
+            )
+            turntable_frames = np.ascontiguousarray(turntable_frames)
+            
+            # Save basic turntable video
+            imageseq2video(turntable_frames, os.path.join(item_output_dir, "turntable.mp4"), fps=30)
+            
+            # Save description and preview if available
+            try:
+                description = dataset.get_description(item_uid)["prompt"]
+                if len(description) > 0:
+                    with open(os.path.join(item_output_dir, "description.txt"), "w") as f:
+                        f.write(description)
+                    
+                    # Create preview image (subsample to 10 views)
+                    preview_frames = turntable_frames[::num_turntable_views // 10]
+                    preview_image = rearrange(preview_frames, "views height width channels -> height (views width) channels")
+                    Image.fromarray(preview_image).save(os.path.join(item_output_dir, "turntable_preview.png"))
+            except (AttributeError, KeyError):
+                pass
+            
+            # Create turntable with input overlay
+            border_width = 2
+            target_width = render_resolution
+            target_height = int(input_image.shape[0] / input_image.shape[1] * target_width)
+            
+            resized_input = cv2.resize(
+                input_image, (target_width - border_width * 2, target_height - border_width * 2), interpolation=cv2.INTER_AREA
+            )
+            bordered_input = np.pad(
+                resized_input, ((border_width, border_width), (border_width, border_width), (0, 0)), 
+                mode="constant", constant_values=200
+            )
+            
+            input_sequence = np.tile(bordered_input[None], (turntable_frames.shape[0], 1, 1, 1))
+            combined_frames = np.concatenate((turntable_frames, input_sequence), axis=1)
+            
+            imageseq2video(combined_frames, os.path.join(item_output_dir, "turntable_with_input.mp4"), fps=30)
+    
+    @torch.no_grad()
+    def save_evaluations(self, out_dir: str, result: edict, batch: edict, dataset) -> None:
+        """Backward compatibility wrapper for save_evaluation_results."""
+        self.save_evaluation_results(out_dir, result, batch, dataset)
+
+    @torch.no_grad()
+    def save_validation_results(
+        self, 
+        output_directory: str, 
+        model_results: edict, 
+        batch_data: edict, 
+        dataset, 
+        save_visualizations: bool = False
+    ) -> Dict[str, float]:
+        """Save validation results and compute aggregated metrics."""
+        from .utils_metrics import compute_psnr, compute_lpips, compute_ssim
+
+        os.makedirs(output_directory, exist_ok=True)
+        input_data, target_data = model_results.input, model_results.target
+        validation_metrics = {"psnr": [], "lpips": [], "ssim": []}
+
+        for batch_idx in range(input_data.image.size(0)):
+            item_uid = input_data.index[batch_idx, 0, -1].item()
+            should_save_visuals = (batch_idx == 0) and save_visualizations
+            
+            # Compute metrics (RGB only)
+            target_image = target_data.image[batch_idx][:, :3, ...]
+            per_view_psnr = compute_psnr(target_image, model_results.render[batch_idx])
+            per_view_lpips = compute_lpips(target_image, model_results.render[batch_idx])
+            per_view_ssim = compute_ssim(target_image, model_results.render[batch_idx])
+            
+            avg_psnr = per_view_psnr.mean().item()
+            avg_lpips = per_view_lpips.mean().item()
+            avg_ssim = per_view_ssim.mean().item()
+            
+            validation_metrics["psnr"].append(avg_psnr)
+            validation_metrics["lpips"].append(avg_lpips)
+            validation_metrics["ssim"].append(avg_ssim)
+            
+            # Save visualizations only for first item if requested
+            if should_save_visuals:
+                item_output_dir = os.path.join(output_directory, f"{item_uid:08d}")
+                os.makedirs(item_output_dir, exist_ok=True)
+                
+                # Save input image
+                input_image = rearrange(
+                    input_data.image[batch_idx][:, :3, ...], "views channels height width -> height (views width) channels"
+                )
+                input_image = (input_image.cpu().numpy() * 255.0).clip(0.0, 255.0).astype(np.uint8)
+                Image.fromarray(input_image).save(os.path.join(item_output_dir, "input.png"))
+                
+                # Save ground truth vs prediction comparison
+                comparison_image = torch.stack((target_image, model_results.render[batch_idx]), dim=0)
+                num_views = comparison_image.size(1)
+                if num_views > 10:
+                    comparison_image = comparison_image[:, ::num_views // 10, :, :, :]
+                comparison_image = rearrange(
+                    comparison_image, "comparison_type views channels height width -> (comparison_type height) (views width) channels"
+                )
+                comparison_image = (comparison_image.cpu().numpy() * 255.0).clip(0.0, 255.0).astype(np.uint8)
+                Image.fromarray(comparison_image).save(os.path.join(item_output_dir, "gt_vs_pred.png"))
+                
+                # Save per-view metrics
+                view_ids = target_data.index[batch_idx, :, 0].cpu().numpy()
+                with open(os.path.join(item_output_dir, "perview_metrics.txt"), "w") as f:
+                    for i in range(per_view_psnr.size(0)):
+                        f.write(
+                            f"view {view_ids[i]:0>6}, psnr: {per_view_psnr[i].item():.4f}, "
+                            f"lpips: {per_view_lpips[i].item():.4f}, ssim: {per_view_ssim[i].item():.4f}\n"
+                        )
+                
+                # Save averaged metrics
+                with open(os.path.join(item_output_dir, "metrics.txt"), "w") as f:
+                    f.write(f"psnr: {avg_psnr:.4f}\nlpips: {avg_lpips:.4f}\nssim: {avg_ssim:.4f}\n")
+                
+                print(f"Validation UID {item_uid}: PSNR={avg_psnr:.4f}, LPIPS={avg_lpips:.4f}, SSIM={avg_ssim:.4f}")
+                
+                # Save Gaussian model
+                crop_box = None
+                if self.config.model.get("clip_xyz", False):
+                    if self.config.model.get("half_bbx_size", None) is not None:
+                        half_size = self.config.model.half_bbx_size
+                        crop_box = [-half_size, half_size, -half_size, half_size, -half_size, half_size]
+                    else:
+                        crop_box = [-0.91, 0.91, -0.91, 0.91, -0.91, 0.91]
+                
+                model_results.gaussians[batch_idx].apply_all_filters(
+                    opacity_thres=0.02, crop_bbx=crop_box, cam_origins=None, nearfar_percent=(0.0001, 1.0)
+                ).save_ply(os.path.join(item_output_dir, "gaussians.ply"))
+                
+                # Create turntable visualization
+                num_turntable_views = 150
+                render_resolution = input_image.shape[0]
+                
+                turntable_frames = render_turntable(
+                    model_results.gaussians[batch_idx], rendering_resolution=render_resolution, num_views=num_turntable_views
+                )
+                turntable_frames = rearrange(
+                    turntable_frames, "height (views width) channels -> views height width channels", views=num_turntable_views
+                )
+                turntable_frames = np.ascontiguousarray(turntable_frames)
+                
+                imageseq2video(turntable_frames, os.path.join(item_output_dir, "turntable.mp4"), fps=30)
+                
+                # Create turntable with input overlay
+                border_width = 2
+                target_width = render_resolution
+                target_height = int(input_image.shape[0] / input_image.shape[1] * target_width)
+                
+                resized_input = cv2.resize(
+                    input_image, (target_width - border_width * 2, target_height - border_width * 2), interpolation=cv2.INTER_AREA
+                )
+                bordered_input = np.pad(
+                    resized_input, ((border_width, border_width), (border_width, border_width), (0, 0)), 
+                    mode="constant", constant_values=200
+                )
+                
+                input_sequence = np.tile(bordered_input[None], (turntable_frames.shape[0], 1, 1, 1))
+                combined_frames = np.concatenate((turntable_frames, input_sequence), axis=1)
+                
+                imageseq2video(combined_frames, os.path.join(item_output_dir, "turntable_with_input.mp4"), fps=30)
+        
+        # Return averaged metrics
+        return {
+            "psnr": torch.tensor(validation_metrics["psnr"]).mean().item(),
+            "lpips": torch.tensor(validation_metrics["lpips"]).mean().item(),
+            "ssim": torch.tensor(validation_metrics["ssim"]).mean().item(),
+        }
+    
+    @torch.no_grad()
+    def save_validations(
+        self, 
+        out_dir: str, 
+        result: edict, 
+        batch: edict, 
+        dataset, 
+        save_img: bool = False
+    ) -> Dict[str, float]:
+        """Backward compatibility wrapper for save_validation_results."""
+        return self.save_validation_results(out_dir, result, batch, dataset, save_img)

gslrm/model/transform_data.py

@@ -0,0 +1,410 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+
+"""
+Data transformation utilities for GSLRM model.
+
+This module contains classes and utilities for transforming input and target data
+for training and inference in the GSLRM (Gaussian Splatting Latent Radiance Model).
+"""
+
+import itertools
+import random
+from typing import Dict, Optional, Tuple, Union
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from easydict import EasyDict as edict
+
+# =============================================================================
+# Utility Functions
+# =============================================================================
+
+def compute_camera_rays(
+    fxfycxcy: torch.Tensor, 
+    c2w: torch.Tensor, 
+    h: int, 
+    w: int, 
+    device: torch.device
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    """
+    Compute camera rays for given intrinsics and extrinsics.
+    
+    Args:
+        fxfycxcy: Camera intrinsics [b*v, 4]
+        c2w: Camera-to-world matrices [b*v, 4, 4]
+        h: Image height
+        w: Image width
+        device: Target device
+        
+    Returns:
+        Tuple of (ray_origins, ray_directions, ray_directions_camera)
+    """
+    y, x = torch.meshgrid(torch.arange(h), torch.arange(w), indexing="ij")
+    y, x = y.to(device), x.to(device)
+    
+    b_v = fxfycxcy.size(0)
+    x = x[None, :, :].expand(b_v, -1, -1).reshape(b_v, -1)
+    y = y[None, :, :].expand(b_v, -1, -1).reshape(b_v, -1)
+    
+    # Convert to normalized camera coordinates
+    x = (x + 0.5 - fxfycxcy[:, 2:3]) / fxfycxcy[:, 0:1]
+    y = (y + 0.5 - fxfycxcy[:, 3:4]) / fxfycxcy[:, 1:2]
+    z = torch.ones_like(x)
+    
+    ray_d_cam = torch.stack([x, y, z], dim=2)  # [b*v, h*w, 3]
+    ray_d_cam = ray_d_cam / torch.norm(ray_d_cam, dim=2, keepdim=True)
+    
+    # Transform to world coordinates
+    ray_d = torch.bmm(ray_d_cam, c2w[:, :3, :3].transpose(1, 2))
+    ray_d = ray_d / torch.norm(ray_d, dim=2, keepdim=True)
+    ray_o = c2w[:, :3, 3][:, None, :].expand_as(ray_d)
+    
+    return ray_o, ray_d, ray_d_cam
+
+
+def sample_patch_rays(
+    image: torch.Tensor,
+    fxfycxcy: torch.Tensor,
+    c2w: torch.Tensor,
+    patch_size: int,
+    h: int,
+    w: int
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+    """
+    Sample rays at patch centers for efficient processing.
+    
+    Args:
+        image: Input images [b*v, c, h, w]
+        fxfycxcy: Camera intrinsics [b*v, 4]
+        c2w: Camera-to-world matrices [b*v, 4, 4]
+        patch_size: Size of patches
+        h: Image height
+        w: Image width
+        
+    Returns:
+        Tuple of (colors, ray_origins, ray_directions, xy_norm, projection_matrices)
+    """
+    b_v, c = image.shape[:2]
+    device = image.device
+    
+    start_patch_center = patch_size / 2.0
+    y, x = torch.meshgrid(
+        torch.arange(h // patch_size) * patch_size + start_patch_center,
+        torch.arange(w // patch_size) * patch_size + start_patch_center,
+        indexing="ij",
+    )
+    y, x = y.to(device), x.to(device)
+    
+    x_flat = x[None, :, :].expand(b_v, -1, -1).reshape(b_v, -1)
+    y_flat = y[None, :, :].expand(b_v, -1, -1).reshape(b_v, -1)
+    
+    # Sample colors at patch centers
+    ray_color = F.grid_sample(
+        image,
+        torch.stack([x_flat / w * 2.0 - 1.0, y_flat / h * 2.0 - 1.0], dim=2).reshape(
+            b_v, -1, 1, 2
+        ),
+        align_corners=False,
+    ).squeeze(-1).permute(0, 2, 1).contiguous()
+    
+    # Compute normalized coordinates
+    ray_xy_norm = torch.stack([x_flat / w, y_flat / h], dim=2)
+    
+    # Compute projection matrices
+    K_norm = torch.eye(3, device=device).unsqueeze(0).repeat(b_v, 1, 1)
+    K_norm[:, 0, 0] = fxfycxcy[:, 0] / w
+    K_norm[:, 1, 1] = fxfycxcy[:, 1] / h
+    K_norm[:, 0, 2] = fxfycxcy[:, 2] / w
+    K_norm[:, 1, 2] = fxfycxcy[:, 3] / h
+    
+    w2c = torch.inverse(c2w)
+    proj_mat = torch.bmm(K_norm, w2c[:, :3, :4])
+    proj_mat = proj_mat.reshape(b_v, 12)
+    proj_mat = proj_mat / (proj_mat.norm(dim=1, keepdim=True) + 1e-6)
+    proj_mat = proj_mat.reshape(b_v, 3, 4)
+    proj_mat = proj_mat * proj_mat[:, 0:1, 0:1].sign()
+    
+    # Compute ray directions
+    x_norm = (x_flat - fxfycxcy[:, 2:3]) / fxfycxcy[:, 0:1]
+    y_norm = (y_flat - fxfycxcy[:, 3:4]) / fxfycxcy[:, 1:2]
+    z_norm = torch.ones_like(x_norm)
+    
+    ray_d = torch.stack([x_norm, y_norm, z_norm], dim=2)
+    ray_d = torch.bmm(ray_d, c2w[:, :3, :3].transpose(1, 2))
+    ray_d = ray_d / torch.norm(ray_d, dim=2, keepdim=True)
+    ray_o = c2w[:, :3, 3][:, None, :].expand_as(ray_d)
+    
+    return ray_color, ray_o, ray_d, ray_xy_norm, proj_mat
+
+
+# =============================================================================
+# Main Classes
+# =============================================================================
+
+class SplitData(nn.Module):
+    """
+    Split data batch into input and target views for training.
+    """
+    
+    def __init__(self, config):
+        super().__init__()
+        self.config = config
+
+    @torch.no_grad()
+    def forward(self, data_batch: Dict[str, torch.Tensor], target_has_input: bool = True) -> Tuple[edict, edict]:
+        """
+        Split data into input and target views.
+        
+        Args:
+            data_batch: Dictionary containing batch data
+            target_has_input: Whether target views can overlap with input views
+            
+        Returns:
+            Tuple of (input_data, target_data)
+        """
+        input_data, target_data = {}, {}
+        index = None
+        
+        for key, value in data_batch.items():
+            # Always use first N views as input
+            input_data[key] = value[:, :self.config.training.dataset.num_input_views, ...]
+            
+            # Calculate num_target_views from num_views (not explicitly in config)
+            num_target_views = self.config.training.dataset.num_views
+            
+            if num_target_views >= value.size(1):
+                target_data[key] = value
+            else:
+                if index is None:
+                    index = self._generate_target_indices(
+                        value, target_has_input
+                    )
+                
+                target_data[key] = self._gather_target_data(value, index)
+        
+        return edict(input_data), edict(target_data)
+    
+    def _generate_target_indices(self, value: torch.Tensor, target_has_input: bool) -> torch.Tensor:
+        """Generate indices for target view selection."""
+        b, v = value.shape[:2]
+        
+        # Get config values
+        num_input_views = self.config.training.dataset.num_input_views
+        num_views = self.config.training.dataset.num_views
+        num_target_views = num_views  # Use all views as targets
+        
+        if target_has_input:
+            # Random sampling from all views
+            index = np.array([
+                random.sample(range(v), num_target_views)
+                for _ in range(b)
+            ])
+        else:
+            # Use last N views to avoid overlap with input views
+            assert (
+                num_input_views + num_target_views <= num_views
+            ), "num_input_views + num_target_views must <= num_views to avoid duplicate views"
+            
+            index = np.array([
+                [num_views - 1 - j for j in range(num_target_views)]
+                for _ in range(b)
+            ])
+        
+        return torch.from_numpy(index).long().to(value.device)
+    
+    def _gather_target_data(self, value: torch.Tensor, index: torch.Tensor) -> torch.Tensor:
+        """Gather target data using provided indices."""
+        value_index = index
+        if value.dim() > 2:
+            dummy_dims = [1] * (value.dim() - 2)
+            value_index = index.reshape(index.size(0), index.size(1), *dummy_dims)
+        
+        try:
+            return torch.gather(
+                value,
+                dim=1,
+                index=value_index.expand(-1, -1, *value.size()[2:]),
+            )
+        except Exception as e:
+            print(f"Error gathering data for key with value shape: {value.size()}")
+            print(f"Index shape: {value_index.size()}")
+            raise e
+
+
+class TransformInput(nn.Module):
+    """
+    Transform input data for feeding into the transformer network.
+    """
+    
+    def __init__(self, config):
+        super().__init__()
+        self.config = config
+
+    @torch.no_grad()
+    def forward(self, data_batch: edict, patch_size: Optional[int] = None) -> edict:
+        """
+        Transform input images to rays and other representations.
+        
+        Args:
+            data_batch: Input data batch
+            patch_size: Optional patch size for patch-based processing
+            
+        Returns:
+            Transformed input data
+        """
+        self._validate_input(data_batch)
+        
+        image, fxfycxcy, c2w, index = (
+            data_batch.image, data_batch.fxfycxcy, 
+            data_batch.c2w, data_batch.index
+        )
+        
+        b, v, c, h, w = image.size()
+        
+        # Reshape for processing
+        image_flat = image.reshape(b * v, c, h * w)
+        fxfycxcy_flat = fxfycxcy.reshape(b * v, 4)
+        c2w_flat = c2w.reshape(b * v, 4, 4)
+        
+        # Compute normalized coordinates for full image
+        xy_norm = self._compute_normalized_coordinates(b, v, h, w, image.device)
+        
+        # Compute camera rays
+        ray_o, ray_d, ray_d_cam = compute_camera_rays(
+            fxfycxcy_flat, c2w_flat, h, w, image.device
+        )
+        
+        # Process patches if patch_size is provided
+        patch_data = self._process_patches(
+            image_flat, fxfycxcy_flat, c2w_flat, patch_size, h, w, b, v, c
+        ) if patch_size is not None else (None, None, None, None, None)
+        
+        # Reshape outputs
+        ray_o = ray_o.reshape(b, v, h, w, 3).permute(0, 1, 4, 2, 3)
+        ray_d = ray_d.reshape(b, v, h, w, 3).permute(0, 1, 4, 2, 3)
+        ray_d_cam = ray_d_cam.reshape(b, v, h, w, 3).permute(0, 1, 4, 2, 3)
+        
+        return edict(
+            image=image,
+            ray_o=ray_o,
+            ray_d=ray_d,
+            ray_d_cam=ray_d_cam,
+            fxfycxcy=fxfycxcy,
+            c2w=c2w,
+            index=index,
+            xy_norm=xy_norm,
+            ray_color_patch=patch_data[0],
+            ray_o_patch=patch_data[1],
+            ray_d_patch=patch_data[2],
+            ray_xy_norm_patch=patch_data[3],
+            proj_mat=patch_data[4],
+        )
+    
+    def _validate_input(self, data_batch: edict) -> None:
+        """Validate input data dimensions."""
+        assert data_batch.image.dim() == 5, f"image dim should be 5, got {data_batch.image.dim()}"
+        assert data_batch.fxfycxcy.dim() == 3, f"fxfycxcy dim should be 3, got {data_batch.fxfycxcy.dim()}"
+        assert data_batch.c2w.dim() == 4, f"c2w dim should be 4, got {data_batch.c2w.dim()}"
+    
+    def _compute_normalized_coordinates(self, b: int, v: int, h: int, w: int, device: torch.device) -> torch.Tensor:
+        """Compute normalized coordinates for the full image."""
+        y, x = torch.meshgrid(torch.arange(h), torch.arange(w), indexing="ij")
+        y, x = y.to(device), x.to(device)
+        
+        y_norm = (y + 0.5) / h * 2 - 1
+        x_norm = (x + 0.5) / w * 2 - 1
+        
+        return torch.stack([x_norm, y_norm], dim=0)[None, None, :, :, :].expand(b, v, -1, -1, -1)
+    
+    def _process_patches(
+        self, 
+        image: torch.Tensor, 
+        fxfycxcy: torch.Tensor, 
+        c2w: torch.Tensor,
+        patch_size: int, 
+        h: int, 
+        w: int, 
+        b: int, 
+        v: int, 
+        c: int
+    ) -> Tuple[Optional[torch.Tensor], ...]:
+        """Process patch-based data if patch_size is provided."""
+        ray_color, ray_o, ray_d, ray_xy_norm, proj_mat = sample_patch_rays(
+            image.reshape(b * v, c, h, w), fxfycxcy, c2w, patch_size, h, w
+        )
+        
+        n_patch = ray_color.size(1)
+        
+        return (
+            ray_color.reshape(b, v, n_patch, c),
+            ray_o.reshape(b, v, n_patch, 3),
+            ray_d.reshape(b, v, n_patch, 3),
+            ray_xy_norm.reshape(b, v, n_patch, 2),
+            proj_mat.reshape(b, v, 3, 4),
+        )
+
+
+class TransformTarget(nn.Module):
+    """
+    Handles target image transformations during training.
+    
+    Currently implements random cropping for data augmentation.
+    """
+    
+    def __init__(self, config: edict):
+        super().__init__()
+        self.config = config
+
+    @torch.no_grad()
+    def forward(self, data_batch: edict) -> edict:
+        """
+        Apply transformations to target data.
+        
+        Args:
+            data_batch: Dictionary containing 'image' and 'fxfycxcy'
+            
+        Returns:
+            Transformed data batch
+        """
+        image = data_batch["image"]      # [b, v, c, h, w]
+        fxfycxcy = data_batch["fxfycxcy"]  # [b, v, 4]
+        
+        b, v, c, h, w = image.size()
+        crop_size = getattr(self.config.training, 'crop_size', min(h, w))
+        
+        # Apply random cropping if image is larger than crop size
+        if h > crop_size or w > crop_size:
+            crop_image = torch.zeros(
+                (b, v, c, crop_size, crop_size), 
+                dtype=image.dtype, 
+                device=image.device
+            )
+            crop_fxfycxcy = fxfycxcy.clone()
+            
+            for i in range(b):
+                for j in range(v):
+                    # Random crop position
+                    idx_x = torch.randint(low=0, high=w - crop_size, size=(1,)).item()
+                    idx_y = torch.randint(low=0, high=h - crop_size, size=(1,)).item()
+                    
+                    # Apply crop
+                    crop_image[i, j] = image[
+                        i, j, :, idx_y:idx_y + crop_size, idx_x:idx_x + crop_size
+                    ]
+                    
+                    # Adjust camera intrinsics
+                    crop_fxfycxcy[i, j, 2] -= idx_x  # cx
+                    crop_fxfycxcy[i, j, 3] -= idx_y  # cy
+            
+            data_batch["image"] = crop_image
+            data_batch["fxfycxcy"] = crop_fxfycxcy
+        
+        return data_batch

gslrm/model/utils_losses.py

@@ -0,0 +1,309 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+
+"""
+Perceptual Loss Implementation using VGG19 and SSIM Loss Implementation.
+
+Adapted from https://github.com/zhengqili/Crowdsampling-the-Plenoptic-Function/blob/f5216f312cf82d77f8d20454b5eeb3930324630a/models/networks.py#L1478
+"""
+import os
+from typing import List, Tuple, Union, Optional
+
+import scipy.io
+import torch
+import torch.nn as nn
+from pytorch_msssim import SSIM
+
+# VGG19 ImageNet normalization constants
+IMAGENET_MEAN = [123.6800, 116.7790, 103.9390]
+
+# VGG19 layer configuration
+VGG19_LAYER_INDICES = [0, 2, 5, 7, 10, 12, 14, 16, 19, 21, 23, 25, 28, 30, 32, 34]
+VGG19_LAYER_NAMES = [
+    "conv1", "conv2", "conv3", "conv4", "conv5", "conv6", "conv7", "conv8",
+    "conv9", "conv10", "conv11", "conv12", "conv13", "conv14", "conv15", "conv16"
+]
+VGG19_CHANNEL_SIZES = [64, 64, 128, 128, 256, 256, 256, 256, 512, 512, 512, 512, 512, 512, 512, 512]
+
+# Perceptual loss weighting factors
+LAYER_WEIGHTS = [1.0, 1/2.6, 1/4.8, 1/3.7, 1/5.6, 10/1.5]
+
+class VGG19(nn.Module):
+    """
+    VGG19 network implementation for perceptual loss computation.
+    
+    This class implements the VGG19 architecture with specific layer outputs
+    used for computing perceptual losses at different scales.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize VGG19 network layers."""
+        super(VGG19, self).__init__()
+        self.conv1 = nn.Conv2d(3, 64, kernel_size=3, stride=1, padding=1, bias=True)
+        self.relu1 = nn.ReLU(inplace=True)
+
+        self.conv2 = nn.Conv2d(64, 64, kernel_size=3, stride=1, padding=1, bias=True)
+        self.relu2 = nn.ReLU(inplace=True)
+        self.max1 = nn.AvgPool2d(kernel_size=2, stride=2)
+
+        self.conv3 = nn.Conv2d(64, 128, kernel_size=3, padding=1, bias=True)
+        self.relu3 = nn.ReLU(inplace=True)
+
+        self.conv4 = nn.Conv2d(128, 128, kernel_size=3, padding=1, bias=True)
+        self.relu4 = nn.ReLU(inplace=True)
+        self.max2 = nn.AvgPool2d(kernel_size=2, stride=2)
+
+        self.conv5 = nn.Conv2d(128, 256, kernel_size=3, padding=1, bias=True)
+        self.relu5 = nn.ReLU(inplace=True)
+
+        self.conv6 = nn.Conv2d(256, 256, kernel_size=3, padding=1, bias=True)
+        self.relu6 = nn.ReLU(inplace=True)
+
+        self.conv7 = nn.Conv2d(256, 256, kernel_size=3, padding=1, bias=True)
+        self.relu7 = nn.ReLU(inplace=True)
+
+        self.conv8 = nn.Conv2d(256, 256, kernel_size=3, padding=1, bias=True)
+        self.relu8 = nn.ReLU(inplace=True)
+        self.max3 = nn.AvgPool2d(kernel_size=2, stride=2)
+
+        self.conv9 = nn.Conv2d(256, 512, kernel_size=3, padding=1, bias=True)
+        self.relu9 = nn.ReLU(inplace=True)
+
+        self.conv10 = nn.Conv2d(512, 512, kernel_size=3, padding=1, bias=True)
+        self.relu10 = nn.ReLU(inplace=True)
+
+        self.conv11 = nn.Conv2d(512, 512, kernel_size=3, padding=1, bias=True)
+        self.relu11 = nn.ReLU(inplace=True)
+
+        self.conv12 = nn.Conv2d(512, 512, kernel_size=3, padding=1, bias=True)
+        self.relu12 = nn.ReLU(inplace=True)
+        self.max4 = nn.AvgPool2d(kernel_size=2, stride=2)
+
+        self.conv13 = nn.Conv2d(512, 512, kernel_size=3, padding=1, bias=True)
+        self.relu13 = nn.ReLU(inplace=True)
+
+        self.conv14 = nn.Conv2d(512, 512, kernel_size=3, padding=1, bias=True)
+        self.relu14 = nn.ReLU(inplace=True)
+
+        self.conv15 = nn.Conv2d(512, 512, kernel_size=3, padding=1, bias=True)
+        self.relu15 = nn.ReLU(inplace=True)
+
+        self.conv16 = nn.Conv2d(512, 512, kernel_size=3, padding=1, bias=True)
+        self.relu16 = nn.ReLU(inplace=True)
+        self.max5 = nn.AvgPool2d(kernel_size=2, stride=2)
+
+    def forward(self, x: torch.Tensor, return_style: int) -> Union[List[torch.Tensor], Tuple[torch.Tensor, ...]]:
+        """
+        Forward pass through VGG19 network.
+        
+        Args:
+            x: Input tensor of shape [B, 3, H, W]
+            return_style: If > 0, return style features as list; otherwise return content features as tuple
+            
+        Returns:
+            Either a list of style features or tuple of content features from different layers
+        """
+        out1 = self.conv1(x)
+        out2 = self.relu1(out1)
+
+        out3 = self.conv2(out2)
+        out4 = self.relu2(out3)
+        out5 = self.max1(out4)
+
+        out6 = self.conv3(out5)
+        out7 = self.relu3(out6)
+        out8 = self.conv4(out7)
+        out9 = self.relu4(out8)
+        out10 = self.max2(out9)
+        out11 = self.conv5(out10)
+        out12 = self.relu5(out11)
+        out13 = self.conv6(out12)
+        out14 = self.relu6(out13)
+        out15 = self.conv7(out14)
+        out16 = self.relu7(out15)
+        out17 = self.conv8(out16)
+        out18 = self.relu8(out17)
+        out19 = self.max3(out18)
+        out20 = self.conv9(out19)
+        out21 = self.relu9(out20)
+        out22 = self.conv10(out21)
+        out23 = self.relu10(out22)
+        out24 = self.conv11(out23)
+        out25 = self.relu11(out24)
+        out26 = self.conv12(out25)
+        out27 = self.relu12(out26)
+        out28 = self.max4(out27)
+        out29 = self.conv13(out28)
+        out30 = self.relu13(out29)
+        out31 = self.conv14(out30)
+        out32 = self.relu14(out31)
+
+        if return_style > 0:
+            return [out2, out7, out12, out21, out30]
+        else:
+            return out4, out9, out14, out23, out32
+
+
+class PerceptualLoss(nn.Module):
+    """
+    Perceptual Loss module using pre-trained VGG19.
+    
+    This class implements perceptual loss by comparing features extracted from
+    different layers of a pre-trained VGG19 network. It computes weighted
+    differences across multiple scales to capture both low-level and high-level
+    visual differences between images.
+    """
+    
+    def __init__(self, device: str = "cpu", weight_file: Optional[str] = None) -> None:
+        """
+        Initialize PerceptualLoss module.
+        
+        Args:
+            device: Device to run computations on ('cpu' or 'cuda')
+            weight_file: Path to VGG19 weight file. If None, uses default path or environment variable.
+            
+        Raises:
+            FileNotFoundError: If weight file is not found
+            RuntimeError: If weight file cannot be loaded
+        """
+        super().__init__()
+        self.device = device
+        self.net = VGG19()
+
+        # Determine weight file path
+        if weight_file is None:
+            # Check environment variable first
+            weight_file = os.environ.get('VGG19_WEIGHTS_PATH')
+            if weight_file is None:
+                # Fallback to default path
+                weight_file = "/sensei-fs/users/kaiz/repos/weight-collections/imagenet-vgg-verydeep-19.mat"
+
+        # Load VGG19 weights
+        if not os.path.isfile(weight_file):
+            raise FileNotFoundError(
+                f"VGG19 weight file not found: {weight_file}\n"
+                f"Download it from: https://www.vlfeat.org/matconvnet/models/imagenet-vgg-verydeep-19.mat\n"
+                f"Expected MD5: 106118b7cf60435e6d8e04f6a6dc3657"
+            )
+        
+        try:
+            vgg_rawnet = scipy.io.loadmat(weight_file)
+            vgg_layers = vgg_rawnet["layers"][0]
+        except Exception as e:
+            raise RuntimeError(f"Failed to load VGG19 weights from {weight_file}: {e}")
+
+        # Load pre-trained weights into the network
+        self._load_pretrained_weights(vgg_layers)
+        
+        # Set network to evaluation mode and freeze parameters
+        self.net = self.net.eval().to(device)
+        for param in self.net.parameters():
+            param.requires_grad = False
+            
+    def _load_pretrained_weights(self, vgg_layers) -> None:
+        """Load pre-trained VGG19 weights into the network."""
+        for layer_idx in range(len(VGG19_LAYER_NAMES)):
+            layer_name = VGG19_LAYER_NAMES[layer_idx]
+            mat_layer_idx = VGG19_LAYER_INDICES[layer_idx]
+            channel_size = VGG19_CHANNEL_SIZES[layer_idx]
+            
+            # Extract weights and biases from MATLAB format
+            layer_weights = torch.from_numpy(
+                vgg_layers[mat_layer_idx][0][0][2][0][0]
+            ).permute(3, 2, 0, 1)
+            layer_biases = torch.from_numpy(
+                vgg_layers[mat_layer_idx][0][0][2][0][1]
+            ).view(channel_size)
+            
+            # Assign to network
+            getattr(self.net, layer_name).weight = nn.Parameter(layer_weights)
+            getattr(self.net, layer_name).bias = nn.Parameter(layer_biases)
+
+    def _compute_l1_error(self, truth: torch.Tensor, pred: torch.Tensor) -> torch.Tensor:
+        """
+        Compute L1 (Mean Absolute Error) between two tensors.
+        
+        Args:
+            truth: Ground truth tensor
+            pred: Predicted tensor
+            
+        Returns:
+            L1 error as a scalar tensor
+        """
+        return torch.mean(torch.abs(truth - pred))
+
+    def forward(self, pred_img: torch.Tensor, real_img: torch.Tensor) -> torch.Tensor:
+        """
+        Compute perceptual loss between predicted and real images.
+        
+        Args:
+            pred_img: Predicted image tensor of shape [B, 3, H, W] in range [0, 1]
+            real_img: Real image tensor of shape [B, 3, H, W] in range [0, 1]
+            
+        Returns:
+            Perceptual loss as a scalar tensor
+        """
+        # Convert to ImageNet normalization (RGB -> BGR and subtract mean)
+        imagenet_mean = torch.tensor(IMAGENET_MEAN, dtype=torch.float32, device=pred_img.device)
+        imagenet_mean = imagenet_mean.view(1, 3, 1, 1)
+
+        # Scale to [0, 255] and apply ImageNet normalization
+        real_img_normalized = real_img * 255.0 - imagenet_mean
+        pred_img_normalized = pred_img * 255.0 - imagenet_mean
+
+        # Extract features from both images
+        real_features = self.net(real_img_normalized, return_style=0)
+        pred_features = self.net(pred_img_normalized, return_style=0)
+
+        # Compute weighted L1 losses at different scales
+        losses = []
+        
+        # Raw image loss
+        raw_loss = self._compute_l1_error(real_img_normalized, pred_img_normalized)
+        losses.append(raw_loss * LAYER_WEIGHTS[0])
+        
+        # Feature losses at different VGG layers
+        for i, (real_feat, pred_feat) in enumerate(zip(real_features, pred_features)):
+            feature_loss = self._compute_l1_error(real_feat, pred_feat)
+            losses.append(feature_loss * LAYER_WEIGHTS[i + 1])
+
+        # Combine all losses and normalize
+        total_loss = sum(losses) / 255.0
+        return total_loss
+
+class SsimLoss(nn.Module):
+    """
+    SSIM Loss module that computes 1 - SSIM for image similarity.
+    
+    Args:
+        data_range: Range of input data (default: 1.0 for [0,1] range)
+    """
+    
+    def __init__(self, data_range: float = 1.0) -> None:
+        super().__init__()
+        self.data_range = data_range
+        self.ssim_module = SSIM(
+            win_size=11,
+            win_sigma=1.5,
+            data_range=self.data_range,
+            size_average=True,
+            channel=3,
+        )
+
+    def forward(self, x: torch.Tensor, y: torch.Tensor) -> torch.Tensor:
+        """
+        Compute SSIM loss between two image tensors.
+        
+        Args:
+            x: Image tensor of shape (N, C, H, W)
+            y: Image tensor of shape (N, C, H, W)
+            
+        Returns:
+            SSIM loss (1 - SSIM similarity)
+        """
+        return 1.0 - self.ssim_module(x, y)

gslrm/model/utils_transformer.py

@@ -0,0 +1,295 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+
+"""
+Transformer utilities for GSLRM.
+
+This module contains the core transformer components used by the GSLRM model,
+including self-attention, MLP layers, and transformer blocks.
+"""
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from einops import rearrange
+
+try:
+    import xformers.ops as xops
+except ImportError as e:
+    print("Please install xformers to use flashatt v2")
+    raise e
+
+
+def _init_weights(module):
+    """
+    Initialize weights for transformer modules.
+    
+    Reference: https://github.com/karpathy/nanoGPT/blob/eba36e84649f3c6d840a93092cb779a260544d08/model.py#L162-L168
+    
+    Args:
+        module: Neural network module to initialize
+    """
+    if isinstance(module, nn.Linear):
+        torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)
+        if module.bias is not None:
+            torch.nn.init.zeros_(module.bias)
+    elif isinstance(module, nn.Embedding):
+        torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)
+
+
+class MLP(nn.Module):
+    """
+    Multi-layer perceptron with GELU activation.
+    
+    Reference: https://github.com/facebookresearch/dino/blob/7c446df5b9f45747937fb0d72314eb9f7b66930a/vision_transformer.py#L49-L65
+    """
+
+    def __init__(
+        self,
+        d,
+        mlp_ratio=4,
+        mlp_bias=False,
+        mlp_dropout=0.0,
+        mlp_dim=None,
+    ):
+        """
+        Initialize MLP layer.
+        
+        Args:
+            d: Input/output dimension
+            mlp_ratio: Hidden dimension ratio (hidden_dim = d * mlp_ratio)
+            mlp_bias: Whether to use bias in linear layers
+            mlp_dropout: Dropout probability
+            mlp_dim: Explicit hidden dimension (overrides mlp_ratio if provided)
+        """
+        super().__init__()
+        if mlp_dim is None:
+            mlp_dim = d * mlp_ratio
+            
+        self.mlp = nn.Sequential(
+            nn.Linear(d, mlp_dim, bias=mlp_bias),
+            nn.GELU(),
+            nn.Linear(mlp_dim, d, bias=mlp_bias),
+            nn.Dropout(mlp_dropout),
+        )
+
+    def forward(self, x):
+        """
+        Forward pass through MLP.
+        
+        Args:
+            x: Input tensor of shape (batch, seq_len, d)
+            
+        Returns:
+            Output tensor of shape (batch, seq_len, d)
+        """
+        return self.mlp(x)
+
+
+class SelfAttention(nn.Module):
+    """
+    Multi-head self-attention with flash attention support.
+    
+    Reference: https://github.com/facebookresearch/dino/blob/7c446df5b9f45747937fb0d72314eb9f7b66930a/vision_transformer.py#L68-L92
+    """
+
+    def __init__(
+        self,
+        d,
+        d_head,
+        attn_qkv_bias=False,
+        attn_dropout=0.0,
+        attn_fc_bias=False,
+        attn_fc_dropout=0.0,
+        use_flashatt_v2=True,
+    ):
+        """
+        Initialize self-attention layer.
+        
+        Args:
+            d: Token dimension
+            d_head: Head dimension
+            attn_qkv_bias: Whether to use bias in QKV projection
+            attn_dropout: Attention dropout probability
+            attn_fc_bias: Whether to use bias in output projection
+            attn_fc_dropout: Output projection dropout probability
+            use_flashatt_v2: Whether to use flash attention v2
+        """
+        super().__init__()
+        assert d % d_head == 0, f"Token dimension {d} should be divisible by head dimension {d_head}"
+        
+        self.d = d
+        self.d_head = d_head
+        self.attn_dropout = attn_dropout
+        self.use_flashatt_v2 = use_flashatt_v2
+
+        # QKV projection (projects to 3*d for Q, K, V)
+        self.to_qkv = nn.Linear(d, 3 * d, bias=attn_qkv_bias)
+        
+        # Output projection
+        self.fc = nn.Linear(d, d, bias=attn_fc_bias)
+        self.attn_fc_dropout = nn.Dropout(attn_fc_dropout)
+
+    def forward(self, x, subset_attention_size=None):
+        """
+        Forward pass through self-attention.
+        
+        Args:
+            x: Input tensor of shape (batch, seq_len, d)
+            subset_attention_size: Optional size for subset attention
+            
+        Returns:
+            Output tensor of shape (batch, seq_len, d)
+        """
+        # Generate Q, K, V
+        q, k, v = self.to_qkv(x).split(self.d, dim=2)
+
+        if self.use_flashatt_v2:
+            # Use xformers flash attention
+            q, k, v = map(
+                lambda t: rearrange(t, "b l (nh dh) -> b l nh dh", dh=self.d_head),
+                (q, k, v),
+            )
+
+            if subset_attention_size is not None and subset_attention_size < q.shape[1]:
+                # Handle subset attention for memory efficiency
+                x_subset = xops.memory_efficient_attention(
+                    q[:, :subset_attention_size, :, :].contiguous(),
+                    k[:, :subset_attention_size, :, :].contiguous(),
+                    v[:, :subset_attention_size, :, :].contiguous(),
+                    attn_bias=None,
+                    op=(xops.fmha.flash.FwOp, xops.fmha.flash.BwOp),
+                )
+                x_rest = xops.memory_efficient_attention(
+                    q[:, subset_attention_size:, :, :].contiguous(),
+                    k,
+                    v,
+                    attn_bias=None,
+                    op=(xops.fmha.flash.FwOp, xops.fmha.flash.BwOp),
+                )
+                x = torch.cat([x_subset, x_rest], dim=1)
+            else:
+                # Standard flash attention
+                x = xops.memory_efficient_attention(
+                    q, k, v,
+                    attn_bias=None,
+                    op=(xops.fmha.flash.FwOp, xops.fmha.flash.BwOp),
+                )
+                
+            x = rearrange(x, "b l nh dh -> b l (nh dh)")
+        else:
+            # Use PyTorch scaled dot product attention
+            q, k, v = (
+                rearrange(q, "b l (nh dh) -> b nh l dh", dh=self.d_head),
+                rearrange(k, "b l (nh dh) -> b nh l dh", dh=self.d_head),
+                rearrange(v, "b l (nh dh) -> b nh l dh", dh=self.d_head),
+            )
+            
+            dropout_p = self.attn_dropout if self.training else 0.0
+            
+            if subset_attention_size is not None and subset_attention_size < q.shape[2]:
+                # Handle subset attention
+                x_subset = F.scaled_dot_product_attention(
+                    q[:, :, :subset_attention_size, :].contiguous(),
+                    k[:, :, :subset_attention_size, :].contiguous(),
+                    v[:, :, :subset_attention_size, :].contiguous(),
+                    dropout_p=dropout_p,
+                )
+                x_rest = F.scaled_dot_product_attention(
+                    q[:, :, subset_attention_size:, :].contiguous(),
+                    k, v,
+                    dropout_p=dropout_p,
+                )
+                x = torch.cat([x_subset, x_rest], dim=2)
+            else:
+                # Standard attention
+                x = F.scaled_dot_product_attention(q, k, v, dropout_p=dropout_p)
+                
+            x = rearrange(x, "b nh l dh -> b l (nh dh)")
+
+        # Apply output projection and dropout
+        return self.attn_fc_dropout(self.fc(x))
+
+
+class TransformerBlock(nn.Module):
+    """
+    Standard transformer block with pre-normalization.
+    
+    Reference: https://github.com/facebookresearch/dino/blob/7c446df5b9f45747937fb0d72314eb9f7b66930a/vision_transformer.py#L95-L113
+    """
+
+    def __init__(
+        self,
+        d,
+        d_head,
+        ln_bias=False,
+        attn_qkv_bias=False,
+        attn_dropout=0.0,
+        attn_fc_bias=False,
+        attn_fc_dropout=0.0,
+        mlp_ratio=4,
+        mlp_bias=False,
+        mlp_dropout=0.0,
+    ):
+        """
+        Initialize transformer block.
+        
+        Args:
+            d: Token dimension
+            d_head: Attention head dimension
+            ln_bias: Whether to use bias in layer norm
+            attn_qkv_bias: Whether to use bias in attention QKV projection
+            attn_dropout: Attention dropout probability
+            attn_fc_bias: Whether to use bias in attention output projection
+            attn_fc_dropout: Attention output dropout probability
+            mlp_ratio: MLP hidden dimension ratio
+            mlp_bias: Whether to use bias in MLP layers
+            mlp_dropout: MLP dropout probability
+        """
+        super().__init__()
+        
+        # Layer normalization
+        self.norm1 = nn.LayerNorm(d, bias=ln_bias)
+        self.norm2 = nn.LayerNorm(d, bias=ln_bias)
+        
+        # Self-attention
+        self.attn = SelfAttention(
+            d=d,
+            d_head=d_head,
+            attn_qkv_bias=attn_qkv_bias,
+            attn_dropout=attn_dropout,
+            attn_fc_bias=attn_fc_bias,
+            attn_fc_dropout=attn_fc_dropout,
+        )
+        
+        # MLP
+        self.mlp = MLP(
+            d=d,
+            mlp_ratio=mlp_ratio,
+            mlp_bias=mlp_bias,
+            mlp_dropout=mlp_dropout,
+        )
+
+    def forward(self, x, subset_attention_size=None):
+        """
+        Forward pass through transformer block.
+        
+        Args:
+            x: Input tensor of shape (batch, seq_len, d)
+            subset_attention_size: Optional size for subset attention
+            
+        Returns:
+            Output tensor of shape (batch, seq_len, d)
+        """
+        # Pre-norm attention with residual connection
+        x = x + self.attn(self.norm1(x), subset_attention_size=subset_attention_size)
+        
+        # Pre-norm MLP with residual connection
+        x = x + self.mlp(self.norm2(x))
+        
+        return x

mvdiffusion/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+

mvdiffusion/models/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+

mvdiffusion/models/transformer_mv2d_image.py

@@ -0,0 +1,1016 @@
+# Copyright 2023 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import torch
+import torch.nn.functional as F
+from torch import nn
+
+from diffusers.configuration_utils import ConfigMixin, register_to_config
+from diffusers.models.embeddings import ImagePositionalEmbeddings
+from diffusers.utils import BaseOutput, deprecate
+from diffusers.utils.torch_utils import maybe_allow_in_graph
+from diffusers.models.attention import FeedForward, AdaLayerNorm, AdaLayerNormZero, Attention
+from diffusers.models.embeddings import PatchEmbed
+from diffusers.models.lora import LoRACompatibleConv, LoRACompatibleLinear
+from diffusers.models.modeling_utils import ModelMixin
+from diffusers.utils.import_utils import is_xformers_available
+
+from einops import rearrange, repeat
+import pdb
+import random
+
+
+if is_xformers_available():
+    import xformers
+    import xformers.ops
+else:
+    xformers = None
+
+def my_repeat(tensor, num_repeats):
+    """
+    Repeat a tensor along a given dimension
+    """
+    if len(tensor.shape) == 3:
+        return repeat(tensor,  "b d c -> (b v) d c", v=num_repeats)
+    elif len(tensor.shape) == 4:
+        return repeat(tensor,  "a b d c -> (a v) b d c", v=num_repeats)
+    
+
+@dataclass
+class TransformerMV2DModelOutput(BaseOutput):
+    """
+    The output of [`Transformer2DModel`].
+
+    Args:
+        sample (`torch.FloatTensor` of shape `(batch_size, num_channels, height, width)` or `(batch size, num_vector_embeds - 1, num_latent_pixels)` if [`Transformer2DModel`] is discrete):
+            The hidden states output conditioned on the `encoder_hidden_states` input. If discrete, returns probability
+            distributions for the unnoised latent pixels.
+    """
+
+    sample: torch.FloatTensor
+
+
+class TransformerMV2DModel(ModelMixin, ConfigMixin):
+    """
+    A 2D Transformer model for image-like data.
+
+    Parameters:
+        num_attention_heads (`int`, *optional*, defaults to 16): The number of heads to use for multi-head attention.
+        attention_head_dim (`int`, *optional*, defaults to 88): The number of channels in each head.
+        in_channels (`int`, *optional*):
+            The number of channels in the input and output (specify if the input is **continuous**).
+        num_layers (`int`, *optional*, defaults to 1): The number of layers of Transformer blocks to use.
+        dropout (`float`, *optional*, defaults to 0.0): The dropout probability to use.
+        cross_attention_dim (`int`, *optional*): The number of `encoder_hidden_states` dimensions to use.
+        sample_size (`int`, *optional*): The width of the latent images (specify if the input is **discrete**).
+            This is fixed during training since it is used to learn a number of position embeddings.
+        num_vector_embeds (`int`, *optional*):
+            The number of classes of the vector embeddings of the latent pixels (specify if the input is **discrete**).
+            Includes the class for the masked latent pixel.
+        activation_fn (`str`, *optional*, defaults to `"geglu"`): Activation function to use in feed-forward.
+        num_embeds_ada_norm ( `int`, *optional*):
+            The number of diffusion steps used during training. Pass if at least one of the norm_layers is
+            `AdaLayerNorm`. This is fixed during training since it is used to learn a number of embeddings that are
+            added to the hidden states.
+
+            During inference, you can denoise for up to but not more steps than `num_embeds_ada_norm`.
+        attention_bias (`bool`, *optional*):
+            Configure if the `TransformerBlocks` attention should contain a bias parameter.
+    """
+
+    @register_to_config
+    def __init__(
+        self,
+        num_attention_heads: int = 16,
+        attention_head_dim: int = 88,
+        in_channels: Optional[int] = None,
+        out_channels: Optional[int] = None,
+        num_layers: int = 1,
+        dropout: float = 0.0,
+        norm_num_groups: int = 32,
+        cross_attention_dim: Optional[int] = None,
+        attention_bias: bool = False,
+        sample_size: Optional[int] = None,
+        num_vector_embeds: Optional[int] = None,
+        patch_size: Optional[int] = None,
+        activation_fn: str = "geglu",
+        num_embeds_ada_norm: Optional[int] = None,
+        use_linear_projection: bool = False,
+        only_cross_attention: bool = False,
+        upcast_attention: bool = False,
+        norm_type: str = "layer_norm",
+        norm_elementwise_affine: bool = True,
+        num_views: int = 1,
+        cd_attention_last: bool=False,
+        cd_attention_mid: bool=False,
+        multiview_attention: bool=True,
+        sparse_mv_attention: bool = False,
+    ):
+        super().__init__()
+        self.use_linear_projection = use_linear_projection
+        self.num_attention_heads = num_attention_heads
+        self.attention_head_dim = attention_head_dim
+        inner_dim = num_attention_heads * attention_head_dim
+
+        # 1. Transformer2DModel can process both standard continuous images of shape `(batch_size, num_channels, width, height)` as well as quantized image embeddings of shape `(batch_size, num_image_vectors)`
+        # Define whether input is continuous or discrete depending on configuration
+        self.is_input_continuous = (in_channels is not None) and (patch_size is None)
+        self.is_input_vectorized = num_vector_embeds is not None
+        self.is_input_patches = in_channels is not None and patch_size is not None
+
+        if norm_type == "layer_norm" and num_embeds_ada_norm is not None:
+            deprecation_message = (
+                f"The configuration file of this model: {self.__class__} is outdated. `norm_type` is either not set or"
+                " incorrectly set to `'layer_norm'`.Make sure to set `norm_type` to `'ada_norm'` in the config."
+                " Please make sure to update the config accordingly as leaving `norm_type` might led to incorrect"
+                " results in future versions. If you have downloaded this checkpoint from the Hugging Face Hub, it"
+                " would be very nice if you could open a Pull request for the `transformer/config.json` file"
+            )
+            deprecate("norm_type!=num_embeds_ada_norm", "1.0.0", deprecation_message, standard_warn=False)
+            norm_type = "ada_norm"
+
+        if self.is_input_continuous and self.is_input_vectorized:
+            raise ValueError(
+                f"Cannot define both `in_channels`: {in_channels} and `num_vector_embeds`: {num_vector_embeds}. Make"
+                " sure that either `in_channels` or `num_vector_embeds` is None."
+            )
+        elif self.is_input_vectorized and self.is_input_patches:
+            raise ValueError(
+                f"Cannot define both `num_vector_embeds`: {num_vector_embeds} and `patch_size`: {patch_size}. Make"
+                " sure that either `num_vector_embeds` or `num_patches` is None."
+            )
+        elif not self.is_input_continuous and not self.is_input_vectorized and not self.is_input_patches:
+            raise ValueError(
+                f"Has to define `in_channels`: {in_channels}, `num_vector_embeds`: {num_vector_embeds}, or patch_size:"
+                f" {patch_size}. Make sure that `in_channels`, `num_vector_embeds` or `num_patches` is not None."
+            )
+
+        # 2. Define input layers
+        if self.is_input_continuous:
+            self.in_channels = in_channels
+
+            self.norm = torch.nn.GroupNorm(num_groups=norm_num_groups, num_channels=in_channels, eps=1e-6, affine=True)
+            if use_linear_projection:
+                self.proj_in = LoRACompatibleLinear(in_channels, inner_dim)
+            else:
+                self.proj_in = LoRACompatibleConv(in_channels, inner_dim, kernel_size=1, stride=1, padding=0)
+        elif self.is_input_vectorized:
+            assert sample_size is not None, "Transformer2DModel over discrete input must provide sample_size"
+            assert num_vector_embeds is not None, "Transformer2DModel over discrete input must provide num_embed"
+
+            self.height = sample_size
+            self.width = sample_size
+            self.num_vector_embeds = num_vector_embeds
+            self.num_latent_pixels = self.height * self.width
+
+            self.latent_image_embedding = ImagePositionalEmbeddings(
+                num_embed=num_vector_embeds, embed_dim=inner_dim, height=self.height, width=self.width
+            )
+        elif self.is_input_patches:
+            assert sample_size is not None, "Transformer2DModel over patched input must provide sample_size"
+
+            self.height = sample_size
+            self.width = sample_size
+
+            self.patch_size = patch_size
+            self.pos_embed = PatchEmbed(
+                height=sample_size,
+                width=sample_size,
+                patch_size=patch_size,
+                in_channels=in_channels,
+                embed_dim=inner_dim,
+            )
+
+        # 3. Define transformers blocks
+        self.transformer_blocks = nn.ModuleList(
+            [
+                BasicMVTransformerBlock(
+                    inner_dim,
+                    num_attention_heads,
+                    attention_head_dim,
+                    dropout=dropout,
+                    cross_attention_dim=cross_attention_dim,
+                    activation_fn=activation_fn,
+                    num_embeds_ada_norm=num_embeds_ada_norm,
+                    attention_bias=attention_bias,
+                    only_cross_attention=only_cross_attention,
+                    upcast_attention=upcast_attention,
+                    norm_type=norm_type,
+                    norm_elementwise_affine=norm_elementwise_affine,
+                    num_views=num_views,
+                    cd_attention_last=cd_attention_last,
+                    cd_attention_mid=cd_attention_mid,
+                    multiview_attention=multiview_attention,
+                    sparse_mv_attention=sparse_mv_attention
+                )
+                for d in range(num_layers)
+            ]
+        )
+
+        # 4. Define output layers
+        self.out_channels = in_channels if out_channels is None else out_channels
+        if self.is_input_continuous:
+            # TODO: should use out_channels for continuous projections
+            if use_linear_projection:
+                self.proj_out = LoRACompatibleLinear(inner_dim, in_channels)
+            else:
+                self.proj_out = LoRACompatibleConv(inner_dim, in_channels, kernel_size=1, stride=1, padding=0)
+        elif self.is_input_vectorized:
+            self.norm_out = nn.LayerNorm(inner_dim)
+            self.out = nn.Linear(inner_dim, self.num_vector_embeds - 1)
+        elif self.is_input_patches:
+            self.norm_out = nn.LayerNorm(inner_dim, elementwise_affine=False, eps=1e-6)
+            self.proj_out_1 = nn.Linear(inner_dim, 2 * inner_dim)
+            self.proj_out_2 = nn.Linear(inner_dim, patch_size * patch_size * self.out_channels)
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: Optional[torch.Tensor] = None,
+        dino_feature: Optional[torch.Tensor] = None,
+        timestep: Optional[torch.LongTensor] = None,
+        class_labels: Optional[torch.LongTensor] = None,
+        cross_attention_kwargs: Dict[str, Any] = None,
+        attention_mask: Optional[torch.Tensor] = None,
+        encoder_attention_mask: Optional[torch.Tensor] = None,
+        return_dict: bool = True,
+    ):
+        """
+        The [`Transformer2DModel`] forward method.
+
+        Args:
+            hidden_states (`torch.LongTensor` of shape `(batch size, num latent pixels)` if discrete, `torch.FloatTensor` of shape `(batch size, channel, height, width)` if continuous):
+                Input `hidden_states`.
+            encoder_hidden_states ( `torch.FloatTensor` of shape `(batch size, sequence len, embed dims)`, *optional*):
+                Conditional embeddings for cross attention layer. If not given, cross-attention defaults to
+                self-attention.
+            timestep ( `torch.LongTensor`, *optional*):
+                Used to indicate denoising step. Optional timestep to be applied as an embedding in `AdaLayerNorm`.
+            class_labels ( `torch.LongTensor` of shape `(batch size, num classes)`, *optional*):
+                Used to indicate class labels conditioning. Optional class labels to be applied as an embedding in
+                `AdaLayerZeroNorm`.
+            encoder_attention_mask ( `torch.Tensor`, *optional*):
+                Cross-attention mask applied to `encoder_hidden_states`. Two formats supported:
+
+                    * Mask `(batch, sequence_length)` True = keep, False = discard.
+                    * Bias `(batch, 1, sequence_length)` 0 = keep, -10000 = discard.
+
+                If `ndim == 2`: will be interpreted as a mask, then converted into a bias consistent with the format
+                above. This bias will be added to the cross-attention scores.
+            return_dict (`bool`, *optional*, defaults to `True`):
+                Whether or not to return a [`~models.unet_2d_condition.UNet2DConditionOutput`] instead of a plain
+                tuple.
+
+        Returns:
+            If `return_dict` is True, an [`~models.transformer_2d.Transformer2DModelOutput`] is returned, otherwise a
+            `tuple` where the first element is the sample tensor.
+        """
+        # ensure attention_mask is a bias, and give it a singleton query_tokens dimension.
+        #   we may have done this conversion already, e.g. if we came here via UNet2DConditionModel#forward.
+        #   we can tell by counting dims; if ndim == 2: it's a mask rather than a bias.
+        # expects mask of shape:
+        #   [batch, key_tokens]
+        # adds singleton query_tokens dimension:
+        #   [batch,                    1, key_tokens]
+        # this helps to broadcast it as a bias over attention scores, which will be in one of the following shapes:
+        #   [batch,  heads, query_tokens, key_tokens] (e.g. torch sdp attn)
+        #   [batch * heads, query_tokens, key_tokens] (e.g. xformers or classic attn)
+        if attention_mask is not None and attention_mask.ndim == 2:
+            # assume that mask is expressed as:
+            #   (1 = keep,      0 = discard)
+            # convert mask into a bias that can be added to attention scores:
+            #       (keep = +0,     discard = -10000.0)
+            attention_mask = (1 - attention_mask.to(hidden_states.dtype)) * -10000.0
+            attention_mask = attention_mask.unsqueeze(1)
+
+        # convert encoder_attention_mask to a bias the same way we do for attention_mask
+        if encoder_attention_mask is not None and encoder_attention_mask.ndim == 2:
+            encoder_attention_mask = (1 - encoder_attention_mask.to(hidden_states.dtype)) * -10000.0
+            encoder_attention_mask = encoder_attention_mask.unsqueeze(1)
+
+        # 1. Input
+        if self.is_input_continuous:
+            batch, _, height, width = hidden_states.shape
+            residual = hidden_states
+
+            hidden_states = self.norm(hidden_states)
+            if not self.use_linear_projection:
+                hidden_states = self.proj_in(hidden_states)
+                inner_dim = hidden_states.shape[1]
+                hidden_states = hidden_states.permute(0, 2, 3, 1).reshape(batch, height * width, inner_dim)
+            else:
+                inner_dim = hidden_states.shape[1]
+                hidden_states = hidden_states.permute(0, 2, 3, 1).reshape(batch, height * width, inner_dim)
+                hidden_states = self.proj_in(hidden_states)
+        elif self.is_input_vectorized:
+            hidden_states = self.latent_image_embedding(hidden_states)
+        elif self.is_input_patches:
+            hidden_states = self.pos_embed(hidden_states)
+
+        # 2. Blocks
+        for block in self.transformer_blocks:
+            hidden_states = block(
+                hidden_states,
+                attention_mask=attention_mask,
+                encoder_hidden_states=encoder_hidden_states,
+                encoder_attention_mask=encoder_attention_mask,
+                timestep=timestep,
+                cross_attention_kwargs=cross_attention_kwargs,
+                class_labels=class_labels,
+            )
+
+        # 3. Output
+        if self.is_input_continuous:
+            if not self.use_linear_projection:
+                hidden_states = hidden_states.reshape(batch, height, width, inner_dim).permute(0, 3, 1, 2).contiguous()
+                hidden_states = self.proj_out(hidden_states)
+            else:
+                hidden_states = self.proj_out(hidden_states)
+                hidden_states = hidden_states.reshape(batch, height, width, inner_dim).permute(0, 3, 1, 2).contiguous()
+
+            output = hidden_states + residual
+        elif self.is_input_vectorized:
+            hidden_states = self.norm_out(hidden_states)
+            logits = self.out(hidden_states)
+            # (batch, self.num_vector_embeds - 1, self.num_latent_pixels)
+            logits = logits.permute(0, 2, 1)
+
+            # log(p(x_0))
+            output = F.log_softmax(logits.double(), dim=1).float()
+        elif self.is_input_patches:
+            # TODO: cleanup!
+            conditioning = self.transformer_blocks[0].norm1.emb(
+                timestep, class_labels, hidden_dtype=hidden_states.dtype
+            )
+            shift, scale = self.proj_out_1(F.silu(conditioning)).chunk(2, dim=1)
+            hidden_states = self.norm_out(hidden_states) * (1 + scale[:, None]) + shift[:, None]
+            hidden_states = self.proj_out_2(hidden_states)
+
+            # unpatchify
+            height = width = int(hidden_states.shape[1] ** 0.5)
+            hidden_states = hidden_states.reshape(
+                shape=(-1, height, width, self.patch_size, self.patch_size, self.out_channels)
+            )
+            hidden_states = torch.einsum("nhwpqc->nchpwq", hidden_states)
+            output = hidden_states.reshape(
+                shape=(-1, self.out_channels, height * self.patch_size, width * self.patch_size)
+            )
+
+        if not return_dict:
+            return (output,)
+
+        return TransformerMV2DModelOutput(sample=output)
+
+
+@maybe_allow_in_graph
+class BasicMVTransformerBlock(nn.Module):
+    r"""
+    A basic Transformer block.
+
+    Parameters:
+        dim (`int`): The number of channels in the input and output.
+        num_attention_heads (`int`): The number of heads to use for multi-head attention.
+        attention_head_dim (`int`): The number of channels in each head.
+        dropout (`float`, *optional*, defaults to 0.0): The dropout probability to use.
+        cross_attention_dim (`int`, *optional*): The size of the encoder_hidden_states vector for cross attention.
+        only_cross_attention (`bool`, *optional*):
+            Whether to use only cross-attention layers. In this case two cross attention layers are used.
+        double_self_attention (`bool`, *optional*):
+            Whether to use two self-attention layers. In this case no cross attention layers are used.
+        activation_fn (`str`, *optional*, defaults to `"geglu"`): Activation function to be used in feed-forward.
+        num_embeds_ada_norm (:
+            obj: `int`, *optional*): The number of diffusion steps used during training. See `Transformer2DModel`.
+        attention_bias (:
+            obj: `bool`, *optional*, defaults to `False`): Configure if the attentions should contain a bias parameter.
+    """
+
+    def __init__(
+        self,
+        dim: int,
+        num_attention_heads: int,
+        attention_head_dim: int,
+        dropout=0.0,
+        cross_attention_dim: Optional[int] = None,
+        activation_fn: str = "geglu",
+        num_embeds_ada_norm: Optional[int] = None,
+        attention_bias: bool = False,
+        only_cross_attention: bool = False,
+        double_self_attention: bool = False,
+        upcast_attention: bool = False,
+        norm_elementwise_affine: bool = True,
+        norm_type: str = "layer_norm",
+        final_dropout: bool = False,
+        num_views: int = 1,
+        cd_attention_last: bool = False,
+        cd_attention_mid: bool = False,
+        multiview_attention: bool = True,
+        sparse_mv_attention: bool = False
+    ):
+        super().__init__()
+        self.only_cross_attention = only_cross_attention
+
+        self.use_ada_layer_norm_zero = (num_embeds_ada_norm is not None) and norm_type == "ada_norm_zero"
+        self.use_ada_layer_norm = (num_embeds_ada_norm is not None) and norm_type == "ada_norm"
+
+        if norm_type in ("ada_norm", "ada_norm_zero") and num_embeds_ada_norm is None:
+            raise ValueError(
+                f"`norm_type` is set to {norm_type}, but `num_embeds_ada_norm` is not defined. Please make sure to"
+                f" define `num_embeds_ada_norm` if setting `norm_type` to {norm_type}."
+            )
+
+        # Define 3 blocks. Each block has its own normalization layer.
+        # 1. Self-Attn
+        if self.use_ada_layer_norm:
+            self.norm1 = AdaLayerNorm(dim, num_embeds_ada_norm)
+        elif self.use_ada_layer_norm_zero:
+            self.norm1 = AdaLayerNormZero(dim, num_embeds_ada_norm)
+        else:
+            self.norm1 = nn.LayerNorm(dim, elementwise_affine=norm_elementwise_affine)
+
+        self.multiview_attention = multiview_attention
+        self.sparse_mv_attention = sparse_mv_attention
+        
+        self.attn1 = CustomAttention(
+            query_dim=dim,
+            heads=num_attention_heads,
+            dim_head=attention_head_dim,
+            dropout=dropout,
+            bias=attention_bias,
+            cross_attention_dim=cross_attention_dim if only_cross_attention else None,
+            upcast_attention=upcast_attention,
+            processor=MVAttnProcessor()
+        )
+
+        # 2. Cross-Attn
+        if cross_attention_dim is not None or double_self_attention:
+            # We currently only use AdaLayerNormZero for self attention where there will only be one attention block.
+            # I.e. the number of returned modulation chunks from AdaLayerZero would not make sense if returned during
+            # the second cross attention block.
+            self.norm2 = (
+                AdaLayerNorm(dim, num_embeds_ada_norm)
+                if self.use_ada_layer_norm
+                else nn.LayerNorm(dim, elementwise_affine=norm_elementwise_affine)
+            )
+            self.attn2 = Attention(
+                query_dim=dim,
+                cross_attention_dim=cross_attention_dim if not double_self_attention else None,
+                heads=num_attention_heads,
+                dim_head=attention_head_dim,
+                dropout=dropout,
+                bias=attention_bias,
+                upcast_attention=upcast_attention,
+            )  # is self-attn if encoder_hidden_states is none
+        else:
+            self.norm2 = None
+            self.attn2 = None
+
+        # 3. Feed-forward
+        self.norm3 = nn.LayerNorm(dim, elementwise_affine=norm_elementwise_affine)
+        self.ff = FeedForward(dim, dropout=dropout, activation_fn=activation_fn, final_dropout=final_dropout)
+
+        # let chunk size default to None
+        self._chunk_size = None
+        self._chunk_dim = 0
+
+        self.num_views = num_views
+
+        self.cd_attention_last = cd_attention_last
+
+        if self.cd_attention_last:
+            # Joint task -Attn
+            self.attn_joint_last = CustomJointAttention(
+                query_dim=dim,
+                heads=num_attention_heads,
+                dim_head=attention_head_dim,
+                dropout=dropout,
+                bias=attention_bias,
+                cross_attention_dim=cross_attention_dim if only_cross_attention else None,
+                upcast_attention=upcast_attention,
+                processor=JointAttnProcessor()
+            )
+            nn.init.zeros_(self.attn_joint_last.to_out[0].weight.data)
+            self.norm_joint_last = AdaLayerNorm(dim, num_embeds_ada_norm) if self.use_ada_layer_norm else nn.LayerNorm(dim)
+
+
+        self.cd_attention_mid = cd_attention_mid
+
+        if self.cd_attention_mid:
+            print("cross-domain attn in the middle")
+            # Joint task -Attn
+            self.attn_joint_mid = CustomJointAttention(
+                query_dim=dim,
+                heads=num_attention_heads,
+                dim_head=attention_head_dim,
+                dropout=dropout,
+                bias=attention_bias,
+                cross_attention_dim=cross_attention_dim if only_cross_attention else None,
+                upcast_attention=upcast_attention,
+                processor=JointAttnProcessor()
+            )
+            nn.init.zeros_(self.attn_joint_mid.to_out[0].weight.data)
+            self.norm_joint_mid = AdaLayerNorm(dim, num_embeds_ada_norm) if self.use_ada_layer_norm else nn.LayerNorm(dim)
+
+    def set_chunk_feed_forward(self, chunk_size: Optional[int], dim: int):
+        # Sets chunk feed-forward
+        self._chunk_size = chunk_size
+        self._chunk_dim = dim
+
+    def forward(
+        self,
+        hidden_states: torch.FloatTensor,
+        attention_mask: Optional[torch.FloatTensor] = None,
+        encoder_hidden_states: Optional[torch.FloatTensor] = None,
+        encoder_attention_mask: Optional[torch.FloatTensor] = None,
+        timestep: Optional[torch.LongTensor] = None,
+        cross_attention_kwargs: Dict[str, Any] = None,
+        class_labels: Optional[torch.LongTensor] = None,
+    ):
+        assert attention_mask is None # not supported yet
+        # Notice that normalization is always applied before the real computation in the following blocks.
+        # 1. Self-Attention
+        if self.use_ada_layer_norm:
+            norm_hidden_states = self.norm1(hidden_states, timestep)
+        elif self.use_ada_layer_norm_zero:
+            norm_hidden_states, gate_msa, shift_mlp, scale_mlp, gate_mlp = self.norm1(
+                hidden_states, timestep, class_labels, hidden_dtype=hidden_states.dtype
+            )
+        else:
+            norm_hidden_states = self.norm1(hidden_states)
+
+        cross_attention_kwargs = cross_attention_kwargs if cross_attention_kwargs is not None else {}
+
+        attn_output = self.attn1(
+            norm_hidden_states,
+            encoder_hidden_states=encoder_hidden_states if self.only_cross_attention else None,
+            attention_mask=attention_mask,
+            num_views=self.num_views,
+            multiview_attention=self.multiview_attention,
+            sparse_mv_attention=self.sparse_mv_attention,
+            **cross_attention_kwargs,
+        )
+
+
+        if self.use_ada_layer_norm_zero:
+            attn_output = gate_msa.unsqueeze(1) * attn_output
+        hidden_states = attn_output + hidden_states
+
+        # joint attention twice
+        if self.cd_attention_mid:
+            norm_hidden_states = (
+                self.norm_joint_mid(hidden_states, timestep) if self.use_ada_layer_norm else self.norm_joint_mid(hidden_states)
+            )
+            hidden_states = self.attn_joint_mid(norm_hidden_states) + hidden_states
+
+        # 2. Cross-Attention
+        if self.attn2 is not None:
+            norm_hidden_states = (
+                self.norm2(hidden_states, timestep) if self.use_ada_layer_norm else self.norm2(hidden_states)
+            )
+
+            attn_output = self.attn2(
+                norm_hidden_states,
+                encoder_hidden_states=encoder_hidden_states,
+                attention_mask=encoder_attention_mask,
+                **cross_attention_kwargs,
+            )
+            hidden_states = attn_output + hidden_states
+
+        # 3. Feed-forward
+        norm_hidden_states = self.norm3(hidden_states)
+
+        if self.use_ada_layer_norm_zero:
+            norm_hidden_states = norm_hidden_states * (1 + scale_mlp[:, None]) + shift_mlp[:, None]
+
+        if self._chunk_size is not None:
+            # "feed_forward_chunk_size" can be used to save memory
+            if norm_hidden_states.shape[self._chunk_dim] % self._chunk_size != 0:
+                raise ValueError(
+                    f"`hidden_states` dimension to be chunked: {norm_hidden_states.shape[self._chunk_dim]} has to be divisible by chunk size: {self._chunk_size}. Make sure to set an appropriate `chunk_size` when calling `unet.enable_forward_chunking`."
+                )
+
+            num_chunks = norm_hidden_states.shape[self._chunk_dim] // self._chunk_size
+            ff_output = torch.cat(
+                [self.ff(hid_slice) for hid_slice in norm_hidden_states.chunk(num_chunks, dim=self._chunk_dim)],
+                dim=self._chunk_dim,
+            )
+        else:
+            ff_output = self.ff(norm_hidden_states)
+
+        if self.use_ada_layer_norm_zero:
+            ff_output = gate_mlp.unsqueeze(1) * ff_output
+
+        hidden_states = ff_output + hidden_states
+
+        if self.cd_attention_last:
+            norm_hidden_states = (
+                self.norm_joint_last(hidden_states, timestep) if self.use_ada_layer_norm else self.norm_joint_last(hidden_states)
+            )
+            hidden_states = self.attn_joint_last(norm_hidden_states) + hidden_states
+
+        return hidden_states
+    
+
+class CustomAttention(Attention):
+    def set_use_memory_efficient_attention_xformers(
+        self, use_memory_efficient_attention_xformers: bool, *args, **kwargs
+    ):
+        processor = XFormersMVAttnProcessor()
+        self.set_processor(processor)
+        # print("using xformers attention processor")
+
+
+class CustomJointAttention(Attention):
+    def set_use_memory_efficient_attention_xformers(
+        self, use_memory_efficient_attention_xformers: bool, *args, **kwargs
+    ):
+        processor = XFormersJointAttnProcessor()
+        self.set_processor(processor)
+        # print("using xformers attention processor")
+
+class MVAttnProcessor:
+    r"""
+    Default processor for performing attention-related computations.
+    """
+
+    def __call__(
+        self,
+        attn: Attention,
+        hidden_states,
+        encoder_hidden_states=None,
+        attention_mask=None,
+        temb=None,
+        num_views=1,
+        multiview_attention=True
+    ):
+        residual = hidden_states
+
+        if attn.spatial_norm is not None:
+            hidden_states = attn.spatial_norm(hidden_states, temb)
+
+        input_ndim = hidden_states.ndim
+
+        if input_ndim == 4:
+            batch_size, channel, height, width = hidden_states.shape
+            hidden_states = hidden_states.view(batch_size, channel, height * width).transpose(1, 2)
+
+        batch_size, sequence_length, _ = (
+            hidden_states.shape if encoder_hidden_states is None else encoder_hidden_states.shape
+        )
+        attention_mask = attn.prepare_attention_mask(attention_mask, sequence_length, batch_size)
+
+        if attn.group_norm is not None:
+            hidden_states = attn.group_norm(hidden_states.transpose(1, 2)).transpose(1, 2)
+
+        query = attn.to_q(hidden_states)
+
+        if encoder_hidden_states is None:
+            encoder_hidden_states = hidden_states
+        elif attn.norm_cross:
+            encoder_hidden_states = attn.norm_encoder_hidden_states(encoder_hidden_states)
+
+        key = attn.to_k(encoder_hidden_states)
+        value = attn.to_v(encoder_hidden_states)
+
+        # print('query', query.shape, 'key', key.shape, 'value', value.shape)
+        #([bx4, 1024, 320]) key torch.Size([bx4, 1024, 320]) value torch.Size([bx4, 1024, 320])
+        # pdb.set_trace()
+        # multi-view self-attention
+        if multiview_attention:
+            if num_views <= 6:
+                # after use xformer; possible to train with 6 views
+                key = rearrange(key, "(b t) d c -> b (t d) c", t=num_views).repeat_interleave(num_views, dim=0)
+                value = rearrange(value, "(b t) d c -> b (t d) c", t=num_views).repeat_interleave(num_views, dim=0)
+            else:# apply sparse attention
+                pass
+                # print("use sparse attention")  
+                # # seems that the sparse random sampling cause problems
+                # # don't use random sampling, just fix the indexes
+                # onekey = rearrange(key, "(b t) d c -> b t d c", t=num_views) 
+                # onevalue = rearrange(value, "(b t) d c -> b t d c", t=num_views)
+                # allkeys = []
+                # allvalues = []
+                # all_indexes = {
+                #     0 : [0, 2, 3, 4],
+                #     1: [0, 1, 3, 5],
+                #     2: [0, 2, 3, 4],
+                #     3: [0, 2, 3, 4],
+                #     4: [0, 2, 3, 4],
+                #     5: [0, 1, 3, 5]
+                # }
+                # for jj in range(num_views):
+                #     # valid_index = [x for x in range(0, num_views) if x!= jj]
+                #     # indexes = random.sample(valid_index, 3) + [jj] + [0]
+                #     indexes = all_indexes[jj]
+
+                #     indexes = torch.tensor(indexes).long().to(key.device)
+                #     allkeys.append(onekey[:, indexes])
+                #     allvalues.append(onevalue[:, indexes])
+                # keys = torch.stack(allkeys, dim=1) # checked, should be dim=1
+                # values = torch.stack(allvalues, dim=1) 
+                # key = rearrange(keys, 'b t f d c -> (b t) (f d) c')
+                # value = rearrange(values, 'b t f d c -> (b t) (f d) c')
+
+
+        query = attn.head_to_batch_dim(query).contiguous()
+        key = attn.head_to_batch_dim(key).contiguous()
+        value = attn.head_to_batch_dim(value).contiguous()
+        
+        attention_probs = attn.get_attention_scores(query, key, attention_mask)
+        hidden_states = torch.bmm(attention_probs, value)
+        hidden_states = attn.batch_to_head_dim(hidden_states)
+
+        # linear proj
+        hidden_states = attn.to_out[0](hidden_states)
+        # dropout
+        hidden_states = attn.to_out[1](hidden_states)
+
+        if input_ndim == 4:
+            hidden_states = hidden_states.transpose(-1, -2).reshape(batch_size, channel, height, width)
+
+        if attn.residual_connection:
+            hidden_states = hidden_states + residual
+
+        hidden_states = hidden_states / attn.rescale_output_factor
+        
+        return hidden_states
+
+
+class XFormersMVAttnProcessor:
+    r"""
+    Default processor for performing attention-related computations.
+    """
+
+    def __call__(
+        self,
+        attn: Attention,
+        hidden_states,
+        encoder_hidden_states=None,
+        attention_mask=None,
+        temb=None,
+        num_views=1.,
+        multiview_attention=True,
+        sparse_mv_attention=False,
+    ):
+        residual = hidden_states
+
+        if attn.spatial_norm is not None:
+            hidden_states = attn.spatial_norm(hidden_states, temb)
+
+        input_ndim = hidden_states.ndim
+
+        if input_ndim == 4:
+            batch_size, channel, height, width = hidden_states.shape
+            hidden_states = hidden_states.view(batch_size, channel, height * width).transpose(1, 2)
+
+        batch_size, sequence_length, _ = (
+            hidden_states.shape if encoder_hidden_states is None else encoder_hidden_states.shape
+        )
+        attention_mask = attn.prepare_attention_mask(attention_mask, sequence_length, batch_size)
+
+        # from yuancheng; here attention_mask is None
+        if attention_mask is not None:
+            # expand our mask's singleton query_tokens dimension:
+            #   [batch*heads,            1, key_tokens] ->
+            #   [batch*heads, query_tokens, key_tokens]
+            # so that it can be added as a bias onto the attention scores that xformers computes:
+            #   [batch*heads, query_tokens, key_tokens]
+            # we do this explicitly because xformers doesn't broadcast the singleton dimension for us.
+            _, query_tokens, _ = hidden_states.shape
+            attention_mask = attention_mask.expand(-1, query_tokens, -1)
+
+        if attn.group_norm is not None:
+            hidden_states = attn.group_norm(hidden_states.transpose(1, 2)).transpose(1, 2)
+
+        query = attn.to_q(hidden_states)
+
+        if encoder_hidden_states is None:
+            encoder_hidden_states = hidden_states
+        elif attn.norm_cross:
+            encoder_hidden_states = attn.norm_encoder_hidden_states(encoder_hidden_states)
+
+        key_raw = attn.to_k(encoder_hidden_states)
+        value_raw = attn.to_v(encoder_hidden_states)
+
+        # print('query', query.shape, 'key', key.shape, 'value', value.shape)
+        #([bx4, 1024, 320]) key torch.Size([bx4, 1024, 320]) value torch.Size([bx4, 1024, 320])
+        # pdb.set_trace()
+        # multi-view self-attention
+        if multiview_attention:
+            if not sparse_mv_attention:
+                key = my_repeat(rearrange(key_raw, "(b t) d c -> b (t d) c", t=num_views), num_views)
+                value = my_repeat(rearrange(value_raw, "(b t) d c -> b (t d) c", t=num_views), num_views)
+            else:
+                key_front = my_repeat(rearrange(key_raw, "(b t) d c -> b t d c", t=num_views)[:, 0, :, :], num_views) # [(b t), d, c]
+                value_front = my_repeat(rearrange(value_raw, "(b t) d c -> b t d c", t=num_views)[:, 0, :, :], num_views)
+                key = torch.cat([key_front, key_raw], dim=1) # shape (b t) (2 d) c
+                value = torch.cat([value_front, value_raw], dim=1)
+
+
+        else:
+            # print("don't use multiview attention.")
+            key = key_raw
+            value = value_raw
+
+        query = attn.head_to_batch_dim(query)
+        key = attn.head_to_batch_dim(key)
+        value = attn.head_to_batch_dim(value)
+
+        hidden_states = xformers.ops.memory_efficient_attention(query, key, value, attn_bias=attention_mask)
+        hidden_states = attn.batch_to_head_dim(hidden_states)
+
+        # linear proj
+        hidden_states = attn.to_out[0](hidden_states)
+        # dropout
+        hidden_states = attn.to_out[1](hidden_states)
+
+        if input_ndim == 4:
+            hidden_states = hidden_states.transpose(-1, -2).reshape(batch_size, channel, height, width)
+
+        if attn.residual_connection:
+            hidden_states = hidden_states + residual
+
+        hidden_states = hidden_states / attn.rescale_output_factor
+        
+        return hidden_states
+
+
+
+class XFormersJointAttnProcessor:
+    r"""
+    Default processor for performing attention-related computations.
+    """
+
+    def __call__(
+        self,
+        attn: Attention,
+        hidden_states,
+        encoder_hidden_states=None,
+        attention_mask=None,
+        temb=None,
+        num_tasks=2
+    ):
+        
+        residual = hidden_states
+
+        if attn.spatial_norm is not None:
+            hidden_states = attn.spatial_norm(hidden_states, temb)
+
+        input_ndim = hidden_states.ndim
+
+        if input_ndim == 4:
+            batch_size, channel, height, width = hidden_states.shape
+            hidden_states = hidden_states.view(batch_size, channel, height * width).transpose(1, 2)
+
+        batch_size, sequence_length, _ = (
+            hidden_states.shape if encoder_hidden_states is None else encoder_hidden_states.shape
+        )
+        attention_mask = attn.prepare_attention_mask(attention_mask, sequence_length, batch_size)
+
+        # from yuancheng; here attention_mask is None
+        if attention_mask is not None:
+            # expand our mask's singleton query_tokens dimension:
+            #   [batch*heads,            1, key_tokens] ->
+            #   [batch*heads, query_tokens, key_tokens]
+            # so that it can be added as a bias onto the attention scores that xformers computes:
+            #   [batch*heads, query_tokens, key_tokens]
+            # we do this explicitly because xformers doesn't broadcast the singleton dimension for us.
+            _, query_tokens, _ = hidden_states.shape
+            attention_mask = attention_mask.expand(-1, query_tokens, -1)
+
+        if attn.group_norm is not None:
+            hidden_states = attn.group_norm(hidden_states.transpose(1, 2)).transpose(1, 2)
+
+        query = attn.to_q(hidden_states)
+
+        if encoder_hidden_states is None:
+            encoder_hidden_states = hidden_states
+        elif attn.norm_cross:
+            encoder_hidden_states = attn.norm_encoder_hidden_states(encoder_hidden_states)
+
+        key = attn.to_k(encoder_hidden_states)
+        value = attn.to_v(encoder_hidden_states)
+
+        assert num_tasks == 2  # only support two tasks now
+
+        key_0, key_1 = torch.chunk(key, dim=0, chunks=2)  # keys shape (b t) d c
+        value_0, value_1 = torch.chunk(value, dim=0, chunks=2)
+        key = torch.cat([key_0, key_1], dim=1)  # (b t) 2d c
+        value = torch.cat([value_0, value_1], dim=1)  # (b t) 2d c
+        key = torch.cat([key]*2, dim=0)   # ( 2 b t) 2d c
+        value = torch.cat([value]*2, dim=0)  # (2 b t) 2d c
+
+        
+        query = attn.head_to_batch_dim(query).contiguous()
+        key = attn.head_to_batch_dim(key).contiguous()
+        value = attn.head_to_batch_dim(value).contiguous()
+
+        hidden_states = xformers.ops.memory_efficient_attention(query, key, value, attn_bias=attention_mask)
+        hidden_states = attn.batch_to_head_dim(hidden_states)
+
+        # linear proj
+        hidden_states = attn.to_out[0](hidden_states)
+        # dropout
+        hidden_states = attn.to_out[1](hidden_states)
+
+        if input_ndim == 4:
+            hidden_states = hidden_states.transpose(-1, -2).reshape(batch_size, channel, height, width)
+
+        if attn.residual_connection:
+            hidden_states = hidden_states + residual
+
+        hidden_states = hidden_states / attn.rescale_output_factor
+        
+        return hidden_states
+
+
+class JointAttnProcessor:
+    r"""
+    Default processor for performing attention-related computations.
+    """
+
+    def __call__(
+        self,
+        attn: Attention,
+        hidden_states,
+        encoder_hidden_states=None,
+        attention_mask=None,
+        temb=None,
+        num_tasks=2
+    ):
+        
+        residual = hidden_states
+
+        if attn.spatial_norm is not None:
+            hidden_states = attn.spatial_norm(hidden_states, temb)
+
+        input_ndim = hidden_states.ndim
+
+        if input_ndim == 4:
+            batch_size, channel, height, width = hidden_states.shape
+            hidden_states = hidden_states.view(batch_size, channel, height * width).transpose(1, 2)
+
+        batch_size, sequence_length, _ = (
+            hidden_states.shape if encoder_hidden_states is None else encoder_hidden_states.shape
+        )
+        attention_mask = attn.prepare_attention_mask(attention_mask, sequence_length, batch_size)
+
+
+        if attn.group_norm is not None:
+            hidden_states = attn.group_norm(hidden_states.transpose(1, 2)).transpose(1, 2)
+
+        query = attn.to_q(hidden_states)
+
+        if encoder_hidden_states is None:
+            encoder_hidden_states = hidden_states
+        elif attn.norm_cross:
+            encoder_hidden_states = attn.norm_encoder_hidden_states(encoder_hidden_states)
+
+        key = attn.to_k(encoder_hidden_states)
+        value = attn.to_v(encoder_hidden_states)
+
+        assert num_tasks == 2  # only support two tasks now
+
+        key_0, key_1 = torch.chunk(key, dim=0, chunks=2)  # keys shape (b t) d c
+        value_0, value_1 = torch.chunk(value, dim=0, chunks=2)
+        key = torch.cat([key_0, key_1], dim=1)  # (b t) 2d c
+        value = torch.cat([value_0, value_1], dim=1)  # (b t) 2d c
+        key = torch.cat([key]*2, dim=0)   # ( 2 b t) 2d c
+        value = torch.cat([value]*2, dim=0)  # (2 b t) 2d c
+
+        
+        query = attn.head_to_batch_dim(query).contiguous()
+        key = attn.head_to_batch_dim(key).contiguous()
+        value = attn.head_to_batch_dim(value).contiguous()
+
+        attention_probs = attn.get_attention_scores(query, key, attention_mask)
+        hidden_states = torch.bmm(attention_probs, value)
+        hidden_states = attn.batch_to_head_dim(hidden_states)
+
+        # linear proj
+        hidden_states = attn.to_out[0](hidden_states)
+        # dropout
+        hidden_states = attn.to_out[1](hidden_states)
+
+        if input_ndim == 4:
+            hidden_states = hidden_states.transpose(-1, -2).reshape(batch_size, channel, height, width)
+
+        if attn.residual_connection:
+            hidden_states = hidden_states + residual
+
+        hidden_states = hidden_states / attn.rescale_output_factor
+        
+        return hidden_states

mvdiffusion/models/unet_mv2d_blocks.py

@@ -0,0 +1,932 @@
+# Copyright 2023 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+from torch import nn
+
+from diffusers.utils import is_torch_version, logging
+# from diffusers.models.normalization import AdaGroupNorm
+from diffusers.models.attention_processor import Attention, AttnAddedKVProcessor, AttnAddedKVProcessor2_0
+from diffusers.models.transformers.dual_transformer_2d import DualTransformer2DModel
+from diffusers.models.resnet import Downsample2D, FirDownsample2D, FirUpsample2D, KDownsample2D, KUpsample2D, ResnetBlock2D, Upsample2D
+
+from diffusers.models.unets.unet_2d_blocks import DownBlock2D, ResnetDownsampleBlock2D, AttnDownBlock2D, CrossAttnDownBlock2D, SimpleCrossAttnDownBlock2D, SkipDownBlock2D, AttnSkipDownBlock2D, DownEncoderBlock2D, AttnDownEncoderBlock2D, KDownBlock2D, KCrossAttnDownBlock2D
+from diffusers.models.unets.unet_2d_blocks import UpBlock2D, ResnetUpsampleBlock2D, CrossAttnUpBlock2D, SimpleCrossAttnUpBlock2D, AttnUpBlock2D, SkipUpBlock2D, AttnSkipUpBlock2D, UpDecoderBlock2D, AttnUpDecoderBlock2D, KUpBlock2D, KCrossAttnUpBlock2D
+
+
+logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
+
+
+def get_down_block(
+    down_block_type,
+    num_layers,
+    in_channels,
+    out_channels,
+    temb_channels,
+    add_downsample,
+    resnet_eps,
+    resnet_act_fn,
+    transformer_layers_per_block=1,
+    num_attention_heads=None,
+    resnet_groups=None,
+    cross_attention_dim=None,
+    downsample_padding=None,
+    dual_cross_attention=False,
+    use_linear_projection=False,
+    only_cross_attention=False,
+    upcast_attention=False,
+    resnet_time_scale_shift="default",
+    resnet_skip_time_act=False,
+    resnet_out_scale_factor=1.0,
+    cross_attention_norm=None,
+    attention_head_dim=None,
+    downsample_type=None,
+    num_views=1,
+    cd_attention_last: bool = False,
+    cd_attention_mid: bool = False,
+    multiview_attention: bool = True,
+    sparse_mv_attention: bool = False,
+    selfattn_block: str = "custom",
+):
+    # If attn head dim is not defined, we default it to the number of heads
+    if attention_head_dim is None:
+        logger.warn(
+            f"It is recommended to provide `attention_head_dim` when calling `get_down_block`. Defaulting `attention_head_dim` to {num_attention_heads}."
+        )
+        attention_head_dim = num_attention_heads
+
+    down_block_type = down_block_type[7:] if down_block_type.startswith("UNetRes") else down_block_type
+    if down_block_type == "DownBlock2D":
+        return DownBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            downsample_padding=downsample_padding,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    elif down_block_type == "ResnetDownsampleBlock2D":
+        return ResnetDownsampleBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            skip_time_act=resnet_skip_time_act,
+            output_scale_factor=resnet_out_scale_factor,
+        )
+    elif down_block_type == "AttnDownBlock2D":
+        if add_downsample is False:
+            downsample_type = None
+        else:
+            downsample_type = downsample_type or "conv"  # default to 'conv'
+        return AttnDownBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            downsample_padding=downsample_padding,
+            attention_head_dim=attention_head_dim,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            downsample_type=downsample_type,
+        )
+    elif down_block_type == "CrossAttnDownBlock2D":
+        if cross_attention_dim is None:
+            raise ValueError("cross_attention_dim must be specified for CrossAttnDownBlock2D")
+        return CrossAttnDownBlock2D(
+            num_layers=num_layers,
+            transformer_layers_per_block=transformer_layers_per_block,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            downsample_padding=downsample_padding,
+            cross_attention_dim=cross_attention_dim,
+            num_attention_heads=num_attention_heads,
+            dual_cross_attention=dual_cross_attention,
+            use_linear_projection=use_linear_projection,
+            only_cross_attention=only_cross_attention,
+            upcast_attention=upcast_attention,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    # custom MV2D attention block
+    elif down_block_type == "CrossAttnDownBlockMV2D":
+        if cross_attention_dim is None:
+            raise ValueError("cross_attention_dim must be specified for CrossAttnDownBlockMV2D")
+        return CrossAttnDownBlockMV2D(
+            num_layers=num_layers,
+            transformer_layers_per_block=transformer_layers_per_block,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            downsample_padding=downsample_padding,
+            cross_attention_dim=cross_attention_dim,
+            num_attention_heads=num_attention_heads,
+            dual_cross_attention=dual_cross_attention,
+            use_linear_projection=use_linear_projection,
+            only_cross_attention=only_cross_attention,
+            upcast_attention=upcast_attention,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            num_views=num_views,
+            cd_attention_last=cd_attention_last,
+            cd_attention_mid=cd_attention_mid,
+            multiview_attention=multiview_attention,
+            sparse_mv_attention=sparse_mv_attention,
+            selfattn_block=selfattn_block,
+        )
+    elif down_block_type == "SimpleCrossAttnDownBlock2D":
+        if cross_attention_dim is None:
+            raise ValueError("cross_attention_dim must be specified for SimpleCrossAttnDownBlock2D")
+        return SimpleCrossAttnDownBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            cross_attention_dim=cross_attention_dim,
+            attention_head_dim=attention_head_dim,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            skip_time_act=resnet_skip_time_act,
+            output_scale_factor=resnet_out_scale_factor,
+            only_cross_attention=only_cross_attention,
+            cross_attention_norm=cross_attention_norm,
+        )
+    elif down_block_type == "SkipDownBlock2D":
+        return SkipDownBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            downsample_padding=downsample_padding,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    elif down_block_type == "AttnSkipDownBlock2D":
+        return AttnSkipDownBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            attention_head_dim=attention_head_dim,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    elif down_block_type == "DownEncoderBlock2D":
+        return DownEncoderBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            downsample_padding=downsample_padding,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    elif down_block_type == "AttnDownEncoderBlock2D":
+        return AttnDownEncoderBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            downsample_padding=downsample_padding,
+            attention_head_dim=attention_head_dim,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    elif down_block_type == "KDownBlock2D":
+        return KDownBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+        )
+    elif down_block_type == "KCrossAttnDownBlock2D":
+        return KCrossAttnDownBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_downsample=add_downsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            cross_attention_dim=cross_attention_dim,
+            attention_head_dim=attention_head_dim,
+            add_self_attention=True if not add_downsample else False,
+        )
+    raise ValueError(f"{down_block_type} does not exist.")
+
+
+def get_up_block(
+    up_block_type,
+    num_layers,
+    in_channels,
+    out_channels,
+    prev_output_channel,
+    temb_channels,
+    add_upsample,
+    resnet_eps,
+    resnet_act_fn,
+    transformer_layers_per_block=1,
+    num_attention_heads=None,
+    resnet_groups=None,
+    cross_attention_dim=None,
+    dual_cross_attention=False,
+    use_linear_projection=False,
+    only_cross_attention=False,
+    upcast_attention=False,
+    resnet_time_scale_shift="default",
+    resnet_skip_time_act=False,
+    resnet_out_scale_factor=1.0,
+    cross_attention_norm=None,
+    attention_head_dim=None,
+    upsample_type=None,
+    num_views=1,
+    cd_attention_last: bool = False,
+    cd_attention_mid: bool = False,
+    multiview_attention: bool = True,
+    sparse_mv_attention: bool = False,
+    selfattn_block: str = "custom",
+):
+    # If attn head dim is not defined, we default it to the number of heads
+    if attention_head_dim is None:
+        logger.warn(
+            f"It is recommended to provide `attention_head_dim` when calling `get_up_block`. Defaulting `attention_head_dim` to {num_attention_heads}."
+        )
+        attention_head_dim = num_attention_heads
+
+    up_block_type = up_block_type[7:] if up_block_type.startswith("UNetRes") else up_block_type
+    if up_block_type == "UpBlock2D":
+        return UpBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            prev_output_channel=prev_output_channel,
+            temb_channels=temb_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    elif up_block_type == "ResnetUpsampleBlock2D":
+        return ResnetUpsampleBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            prev_output_channel=prev_output_channel,
+            temb_channels=temb_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            skip_time_act=resnet_skip_time_act,
+            output_scale_factor=resnet_out_scale_factor,
+        )
+    elif up_block_type == "CrossAttnUpBlock2D":
+        if cross_attention_dim is None:
+            raise ValueError("cross_attention_dim must be specified for CrossAttnUpBlock2D")
+        return CrossAttnUpBlock2D(
+            num_layers=num_layers,
+            transformer_layers_per_block=transformer_layers_per_block,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            prev_output_channel=prev_output_channel,
+            temb_channels=temb_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            cross_attention_dim=cross_attention_dim,
+            num_attention_heads=num_attention_heads,
+            dual_cross_attention=dual_cross_attention,
+            use_linear_projection=use_linear_projection,
+            only_cross_attention=only_cross_attention,
+            upcast_attention=upcast_attention,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    # custom MV2D attention block
+    elif up_block_type == "CrossAttnUpBlockMV2D":
+        if cross_attention_dim is None:
+            raise ValueError("cross_attention_dim must be specified for CrossAttnUpBlockMV2D")
+        return CrossAttnUpBlockMV2D(
+            num_layers=num_layers,
+            transformer_layers_per_block=transformer_layers_per_block,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            prev_output_channel=prev_output_channel,
+            temb_channels=temb_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            cross_attention_dim=cross_attention_dim,
+            num_attention_heads=num_attention_heads,
+            dual_cross_attention=dual_cross_attention,
+            use_linear_projection=use_linear_projection,
+            only_cross_attention=only_cross_attention,
+            upcast_attention=upcast_attention,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            num_views=num_views,
+            cd_attention_last=cd_attention_last,
+            cd_attention_mid=cd_attention_mid,
+            multiview_attention=multiview_attention,
+            sparse_mv_attention=sparse_mv_attention,
+            selfattn_block=selfattn_block,
+        )    
+    elif up_block_type == "SimpleCrossAttnUpBlock2D":
+        if cross_attention_dim is None:
+            raise ValueError("cross_attention_dim must be specified for SimpleCrossAttnUpBlock2D")
+        return SimpleCrossAttnUpBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            prev_output_channel=prev_output_channel,
+            temb_channels=temb_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            cross_attention_dim=cross_attention_dim,
+            attention_head_dim=attention_head_dim,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            skip_time_act=resnet_skip_time_act,
+            output_scale_factor=resnet_out_scale_factor,
+            only_cross_attention=only_cross_attention,
+            cross_attention_norm=cross_attention_norm,
+        )
+    elif up_block_type == "AttnUpBlock2D":
+        if add_upsample is False:
+            upsample_type = None
+        else:
+            upsample_type = upsample_type or "conv"  # default to 'conv'
+
+        return AttnUpBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            prev_output_channel=prev_output_channel,
+            temb_channels=temb_channels,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            attention_head_dim=attention_head_dim,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            upsample_type=upsample_type,
+        )
+    elif up_block_type == "SkipUpBlock2D":
+        return SkipUpBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            prev_output_channel=prev_output_channel,
+            temb_channels=temb_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    elif up_block_type == "AttnSkipUpBlock2D":
+        return AttnSkipUpBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            prev_output_channel=prev_output_channel,
+            temb_channels=temb_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            attention_head_dim=attention_head_dim,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+        )
+    elif up_block_type == "UpDecoderBlock2D":
+        return UpDecoderBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            temb_channels=temb_channels,
+        )
+    elif up_block_type == "AttnUpDecoderBlock2D":
+        return AttnUpDecoderBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            resnet_groups=resnet_groups,
+            attention_head_dim=attention_head_dim,
+            resnet_time_scale_shift=resnet_time_scale_shift,
+            temb_channels=temb_channels,
+        )
+    elif up_block_type == "KUpBlock2D":
+        return KUpBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+        )
+    elif up_block_type == "KCrossAttnUpBlock2D":
+        return KCrossAttnUpBlock2D(
+            num_layers=num_layers,
+            in_channels=in_channels,
+            out_channels=out_channels,
+            temb_channels=temb_channels,
+            add_upsample=add_upsample,
+            resnet_eps=resnet_eps,
+            resnet_act_fn=resnet_act_fn,
+            cross_attention_dim=cross_attention_dim,
+            attention_head_dim=attention_head_dim,
+        )
+
+    raise ValueError(f"{up_block_type} does not exist.")
+
+
+class UNetMidBlockMV2DCrossAttn(nn.Module):
+    def __init__(
+        self,
+        in_channels: int,
+        temb_channels: int,
+        dropout: float = 0.0,
+        num_layers: int = 1,
+        transformer_layers_per_block: int = 1,
+        resnet_eps: float = 1e-6,
+        resnet_time_scale_shift: str = "default",
+        resnet_act_fn: str = "swish",
+        resnet_groups: int = 32,
+        resnet_pre_norm: bool = True,
+        num_attention_heads=1,
+        output_scale_factor=1.0,
+        cross_attention_dim=1280,
+        dual_cross_attention=False,
+        use_linear_projection=False,
+        upcast_attention=False,
+        num_views: int = 1,
+        cd_attention_last: bool = False,
+        cd_attention_mid: bool = False,
+        multiview_attention: bool = True,
+        sparse_mv_attention: bool = False,
+        selfattn_block: str = "custom",
+    ):
+        super().__init__()
+
+        self.has_cross_attention = True
+        self.num_attention_heads = num_attention_heads
+        resnet_groups = resnet_groups if resnet_groups is not None else min(in_channels // 4, 32)
+        if selfattn_block == "custom":
+            from .transformer_mv2d_image import TransformerMV2DModel
+        else:
+            raise NotImplementedError
+        
+        # there is always at least one resnet
+        resnets = [
+            ResnetBlock2D(
+                in_channels=in_channels,
+                out_channels=in_channels,
+                temb_channels=temb_channels,
+                eps=resnet_eps,
+                groups=resnet_groups,
+                dropout=dropout,
+                time_embedding_norm=resnet_time_scale_shift,
+                non_linearity=resnet_act_fn,
+                output_scale_factor=output_scale_factor,
+                pre_norm=resnet_pre_norm,
+            )
+        ]
+        attentions = []
+
+        for _ in range(num_layers):
+            if not dual_cross_attention:
+                attentions.append(
+                    TransformerMV2DModel(
+                        num_attention_heads,
+                        in_channels // num_attention_heads,
+                        in_channels=in_channels,
+                        num_layers=transformer_layers_per_block,
+                        cross_attention_dim=cross_attention_dim,
+                        norm_num_groups=resnet_groups,
+                        use_linear_projection=use_linear_projection,
+                        upcast_attention=upcast_attention,
+                        num_views=num_views,
+                        cd_attention_last=cd_attention_last,
+                        cd_attention_mid=cd_attention_mid,
+                        multiview_attention=multiview_attention,
+                        sparse_mv_attention=sparse_mv_attention,
+                    )
+                )
+            else:
+                raise NotImplementedError
+            resnets.append(
+                ResnetBlock2D(
+                    in_channels=in_channels,
+                    out_channels=in_channels,
+                    temb_channels=temb_channels,
+                    eps=resnet_eps,
+                    groups=resnet_groups,
+                    dropout=dropout,
+                    time_embedding_norm=resnet_time_scale_shift,
+                    non_linearity=resnet_act_fn,
+                    output_scale_factor=output_scale_factor,
+                    pre_norm=resnet_pre_norm,
+                )
+            )
+
+        self.attentions = nn.ModuleList(attentions)
+        self.resnets = nn.ModuleList(resnets)
+
+    def forward(
+        self,
+        hidden_states: torch.FloatTensor,
+        temb: Optional[torch.FloatTensor] = None,
+        encoder_hidden_states: Optional[torch.FloatTensor] = None,
+        attention_mask: Optional[torch.FloatTensor] = None,
+        cross_attention_kwargs: Optional[Dict[str, Any]] = None,
+        encoder_attention_mask: Optional[torch.FloatTensor] = None,
+    ) -> torch.FloatTensor:
+        hidden_states = self.resnets[0](hidden_states, temb)
+        for attn, resnet in zip(self.attentions, self.resnets[1:]):
+            hidden_states = attn(
+                hidden_states,
+                encoder_hidden_states=encoder_hidden_states,
+                cross_attention_kwargs=cross_attention_kwargs,
+                attention_mask=attention_mask,
+                encoder_attention_mask=encoder_attention_mask,
+                return_dict=False,
+            )[0]
+            hidden_states = resnet(hidden_states, temb)
+
+        return hidden_states
+
+
+class CrossAttnUpBlockMV2D(nn.Module):
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        prev_output_channel: int,
+        temb_channels: int,
+        dropout: float = 0.0,
+        num_layers: int = 1,
+        transformer_layers_per_block: int = 1,
+        resnet_eps: float = 1e-6,
+        resnet_time_scale_shift: str = "default",
+        resnet_act_fn: str = "swish",
+        resnet_groups: int = 32,
+        resnet_pre_norm: bool = True,
+        num_attention_heads=1,
+        cross_attention_dim=1280,
+        output_scale_factor=1.0,
+        add_upsample=True,
+        dual_cross_attention=False,
+        use_linear_projection=False,
+        only_cross_attention=False,
+        upcast_attention=False,
+        num_views: int = 1,
+        cd_attention_last: bool = False,
+        cd_attention_mid: bool = False,
+        multiview_attention: bool = True,
+        sparse_mv_attention: bool = False,
+        selfattn_block: str = "custom",
+    ):
+        super().__init__()
+        resnets = []
+        attentions = []
+
+        self.has_cross_attention = True
+        self.num_attention_heads = num_attention_heads
+
+        if selfattn_block == "custom":
+            from .transformer_mv2d_image import TransformerMV2DModel
+        else:
+            raise NotImplementedError
+        
+        for i in range(num_layers):
+            res_skip_channels = in_channels if (i == num_layers - 1) else out_channels
+            resnet_in_channels = prev_output_channel if i == 0 else out_channels
+
+            resnets.append(
+                ResnetBlock2D(
+                    in_channels=resnet_in_channels + res_skip_channels,
+                    out_channels=out_channels,
+                    temb_channels=temb_channels,
+                    eps=resnet_eps,
+                    groups=resnet_groups,
+                    dropout=dropout,
+                    time_embedding_norm=resnet_time_scale_shift,
+                    non_linearity=resnet_act_fn,
+                    output_scale_factor=output_scale_factor,
+                    pre_norm=resnet_pre_norm,
+                )
+            )
+            if not dual_cross_attention:
+                attentions.append(
+                    TransformerMV2DModel(
+                        num_attention_heads,
+                        out_channels // num_attention_heads,
+                        in_channels=out_channels,
+                        num_layers=transformer_layers_per_block,
+                        cross_attention_dim=cross_attention_dim,
+                        norm_num_groups=resnet_groups,
+                        use_linear_projection=use_linear_projection,
+                        only_cross_attention=only_cross_attention,
+                        upcast_attention=upcast_attention,
+                        num_views=num_views,
+                        cd_attention_last=cd_attention_last,
+                        cd_attention_mid=cd_attention_mid,
+                        multiview_attention=multiview_attention,
+                        sparse_mv_attention=sparse_mv_attention,
+                    )
+                )
+            else:
+                raise NotImplementedError
+        self.attentions = nn.ModuleList(attentions)
+        self.resnets = nn.ModuleList(resnets)
+
+        if add_upsample:
+            self.upsamplers = nn.ModuleList([Upsample2D(out_channels, use_conv=True, out_channels=out_channels)])
+        else:
+            self.upsamplers = None
+
+        self.gradient_checkpointing = False
+
+    def forward(
+        self,
+        hidden_states: torch.FloatTensor,
+        res_hidden_states_tuple: Tuple[torch.FloatTensor, ...],
+        temb: Optional[torch.FloatTensor] = None,
+        encoder_hidden_states: Optional[torch.FloatTensor] = None,
+        cross_attention_kwargs: Optional[Dict[str, Any]] = None,
+        upsample_size: Optional[int] = None,
+        attention_mask: Optional[torch.FloatTensor] = None,
+        encoder_attention_mask: Optional[torch.FloatTensor] = None,
+    ):
+        for resnet, attn in zip(self.resnets, self.attentions):
+            # pop res hidden states
+            res_hidden_states = res_hidden_states_tuple[-1]
+            res_hidden_states_tuple = res_hidden_states_tuple[:-1]
+            hidden_states = torch.cat([hidden_states, res_hidden_states], dim=1)
+
+            if self.training and self.gradient_checkpointing:
+
+                def create_custom_forward(module, return_dict=None):
+                    def custom_forward(*inputs):
+                        if return_dict is not None and return_dict is not False:
+                            return module(*inputs, return_dict=return_dict)
+                        else:
+                            return module(*inputs)
+
+                    return custom_forward
+
+                ckpt_kwargs: Dict[str, Any] = {"use_reentrant": False} if is_torch_version(">=", "1.11.0") else {}
+                hidden_states = torch.utils.checkpoint.checkpoint(
+                    create_custom_forward(resnet),
+                    hidden_states,
+                    temb,
+                    **ckpt_kwargs,
+                )
+                hidden_states = torch.utils.checkpoint.checkpoint(
+                    create_custom_forward(attn, return_dict=False),
+                    hidden_states,
+                    encoder_hidden_states,
+                    None,  # timestep
+                    None,  # class_labels
+                    cross_attention_kwargs,
+                    attention_mask,
+                    encoder_attention_mask,
+                    **ckpt_kwargs,
+                )[0]
+            else:
+                hidden_states = resnet(hidden_states, temb)
+                hidden_states = attn(
+                    hidden_states,
+                    encoder_hidden_states=encoder_hidden_states,
+                    cross_attention_kwargs=cross_attention_kwargs,
+                    attention_mask=attention_mask,
+                    encoder_attention_mask=encoder_attention_mask,
+                    return_dict=False,
+                )[0]
+
+        if self.upsamplers is not None:
+            for upsampler in self.upsamplers:
+                hidden_states = upsampler(hidden_states, upsample_size)
+
+        return hidden_states
+
+
+class CrossAttnDownBlockMV2D(nn.Module):
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        temb_channels: int,
+        dropout: float = 0.0,
+        num_layers: int = 1,
+        transformer_layers_per_block: int = 1,
+        resnet_eps: float = 1e-6,
+        resnet_time_scale_shift: str = "default",
+        resnet_act_fn: str = "swish",
+        resnet_groups: int = 32,
+        resnet_pre_norm: bool = True,
+        num_attention_heads=1,
+        cross_attention_dim=1280,
+        output_scale_factor=1.0,
+        downsample_padding=1,
+        add_downsample=True,
+        dual_cross_attention=False,
+        use_linear_projection=False,
+        only_cross_attention=False,
+        upcast_attention=False,
+        num_views: int = 1,
+        cd_attention_last: bool = False,
+        cd_attention_mid: bool = False,
+        multiview_attention: bool = True,
+        sparse_mv_attention: bool = False,
+        selfattn_block: str = "custom",
+    ):
+        super().__init__()
+        resnets = []
+        attentions = []
+
+        self.has_cross_attention = True
+        self.num_attention_heads = num_attention_heads
+        if selfattn_block == "custom":
+            from .transformer_mv2d_image import TransformerMV2DModel
+        else:
+            raise NotImplementedError
+        
+        for i in range(num_layers):
+            in_channels = in_channels if i == 0 else out_channels
+            resnets.append(
+                ResnetBlock2D(
+                    in_channels=in_channels,
+                    out_channels=out_channels,
+                    temb_channels=temb_channels,
+                    eps=resnet_eps,
+                    groups=resnet_groups,
+                    dropout=dropout,
+                    time_embedding_norm=resnet_time_scale_shift,
+                    non_linearity=resnet_act_fn,
+                    output_scale_factor=output_scale_factor,
+                    pre_norm=resnet_pre_norm,
+                )
+            )
+            if not dual_cross_attention:
+                attentions.append(
+                    TransformerMV2DModel(
+                        num_attention_heads,
+                        out_channels // num_attention_heads,
+                        in_channels=out_channels,
+                        num_layers=transformer_layers_per_block,
+                        cross_attention_dim=cross_attention_dim,
+                        norm_num_groups=resnet_groups,
+                        use_linear_projection=use_linear_projection,
+                        only_cross_attention=only_cross_attention,
+                        upcast_attention=upcast_attention,
+                        num_views=num_views,
+                        cd_attention_last=cd_attention_last,
+                        cd_attention_mid=cd_attention_mid,
+                        multiview_attention=multiview_attention,
+                        sparse_mv_attention=sparse_mv_attention,
+                    )
+                )
+            else:
+                raise NotImplementedError
+        self.attentions = nn.ModuleList(attentions)
+        self.resnets = nn.ModuleList(resnets)
+
+        if add_downsample:
+            self.downsamplers = nn.ModuleList(
+                [
+                    Downsample2D(
+                        out_channels, use_conv=True, out_channels=out_channels, padding=downsample_padding, name="op"
+                    )
+                ]
+            )
+        else:
+            self.downsamplers = None
+
+        self.gradient_checkpointing = False
+
+    def forward(
+        self,
+        hidden_states: torch.FloatTensor,
+        temb: Optional[torch.FloatTensor] = None,
+        encoder_hidden_states: Optional[torch.FloatTensor] = None,
+        attention_mask: Optional[torch.FloatTensor] = None,
+        cross_attention_kwargs: Optional[Dict[str, Any]] = None,
+        encoder_attention_mask: Optional[torch.FloatTensor] = None,
+        additional_residuals=None,
+    ):
+        output_states = ()
+
+        blocks = list(zip(self.resnets, self.attentions))
+
+        for i, (resnet, attn) in enumerate(blocks):
+            if self.training and self.gradient_checkpointing:
+
+                def create_custom_forward(module, return_dict=None):
+                    def custom_forward(*inputs):
+                        if return_dict is not None and return_dict is not False:
+                            print("return_dict: ", return_dict)
+                            return module(*inputs, return_dict=return_dict)
+                        else:
+                            return module(*inputs)
+
+                    return custom_forward
+
+                ckpt_kwargs: Dict[str, Any] = {"use_reentrant": False} if is_torch_version(">=", "1.11.0") else {}
+                hidden_states = torch.utils.checkpoint.checkpoint(
+                    create_custom_forward(resnet),
+                    hidden_states,
+                    temb,
+                    **ckpt_kwargs,
+                )
+                hidden_states = torch.utils.checkpoint.checkpoint(
+                    create_custom_forward(attn, return_dict=False),
+                    hidden_states,
+                    encoder_hidden_states,
+                    None,  # timestep
+                    None,  # class_labels
+                    cross_attention_kwargs,
+                    attention_mask,
+                    encoder_attention_mask,
+                    **ckpt_kwargs,
+                )[0]
+            else:
+                hidden_states = resnet(hidden_states, temb)
+                hidden_states = attn(
+                    hidden_states,
+                    encoder_hidden_states=encoder_hidden_states,
+                    cross_attention_kwargs=cross_attention_kwargs,
+                    attention_mask=attention_mask,
+                    encoder_attention_mask=encoder_attention_mask,
+                    return_dict=False,
+                )[0]
+
+            # apply additional residuals to the output of the last pair of resnet and attention blocks
+            if i == len(blocks) - 1 and additional_residuals is not None:
+                hidden_states = hidden_states + additional_residuals
+
+            output_states = output_states + (hidden_states,)
+
+        if self.downsamplers is not None:
+            for downsampler in self.downsamplers:
+                hidden_states = downsampler(hidden_states)
+
+            output_states = output_states + (hidden_states,)
+
+        return hidden_states, output_states
+

mvdiffusion/models/unet_mv2d_condition.py

@@ -0,0 +1,1568 @@
+# Copyright 2023 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple, Union
+import os
+
+import torch
+import torch.nn as nn
+import torch.utils.checkpoint
+
+from diffusers.configuration_utils import ConfigMixin, register_to_config
+from diffusers.loaders import UNet2DConditionLoadersMixin
+from diffusers.utils import BaseOutput, logging
+from diffusers.models.activations import get_activation
+from diffusers.models.attention_processor import AttentionProcessor, AttnProcessor
+from diffusers.models.embeddings import (
+    GaussianFourierProjection,
+    ImageHintTimeEmbedding,
+    ImageProjection,
+    ImageTimeEmbedding,
+    TextImageProjection,
+    TextImageTimeEmbedding,
+    TextTimeEmbedding,
+    TimestepEmbedding,
+    Timesteps,
+)
+from diffusers.models.modeling_utils import ModelMixin, load_state_dict, _load_state_dict_into_model
+from diffusers.models.unets.unet_2d_blocks import (
+    CrossAttnDownBlock2D,
+    CrossAttnUpBlock2D,
+    DownBlock2D,
+    UNetMidBlock2DCrossAttn,
+    UNetMidBlock2DSimpleCrossAttn,
+    UpBlock2D,
+)
+from diffusers.utils import (
+    CONFIG_NAME,
+    FLAX_WEIGHTS_NAME,
+    SAFETENSORS_WEIGHTS_NAME,
+    WEIGHTS_NAME,
+    _add_variant,
+    _get_model_file,
+    deprecate,
+    is_torch_version,
+    logging,
+)
+from diffusers.utils.import_utils import is_accelerate_available 
+from diffusers.utils.hub_utils import HF_HUB_OFFLINE
+from huggingface_hub.constants import HUGGINGFACE_HUB_CACHE
+DIFFUSERS_CACHE = HUGGINGFACE_HUB_CACHE
+
+from diffusers import __version__
+from .unet_mv2d_blocks import (
+    CrossAttnDownBlockMV2D,
+    CrossAttnUpBlockMV2D,
+    UNetMidBlockMV2DCrossAttn,
+    get_down_block,
+    get_up_block,
+)
+from einops import rearrange, repeat
+
+logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
+
+
+@dataclass
+class UNetMV2DConditionOutput(BaseOutput):
+    """
+    The output of [`UNet2DConditionModel`].
+
+    Args:
+        sample (`torch.FloatTensor` of shape `(batch_size, num_channels, height, width)`):
+            The hidden states output conditioned on `encoder_hidden_states` input. Output of last layer of model.
+    """
+
+    sample: torch.FloatTensor = None
+
+
+class ResidualBlock(nn.Module):
+    def __init__(self, dim):
+        super(ResidualBlock, self).__init__()
+        self.linear1 = nn.Linear(dim, dim)
+        self.activation = nn.SiLU()
+        self.linear2 = nn.Linear(dim, dim)
+
+    def forward(self, x):
+        identity = x
+        out = self.linear1(x)
+        out = self.activation(out)
+        out = self.linear2(out)
+        out += identity  
+        out = self.activation(out)
+        return out
+    
+class ResidualLiner(nn.Module):
+    def __init__(self, in_features, out_features, dim, act=None, num_block=1):
+        super(ResidualLiner, self).__init__()
+        self.linear_in = nn.Sequential(nn.Linear(in_features, dim), nn.SiLU())
+        
+        blocks = nn.ModuleList()
+        for _ in range(num_block):
+            blocks.append(ResidualBlock(dim))
+        self.blocks = blocks    
+        
+        self.linear_out = nn.Linear(dim, out_features)
+        self.act = act
+
+    def forward(self, x):
+        out = self.linear_in(x)
+        for block in self.blocks:
+            out = block(out)
+        out = self.linear_out(out)
+        if self.act is not None:
+            out = self.act(out)
+        return out
+
+class BasicConvBlock(nn.Module):
+    def __init__(self, in_channels, out_channels, stride=1):
+        super(BasicConvBlock, self).__init__()
+        self.conv1 = nn.Conv2d(in_channels, out_channels, kernel_size=3, stride=stride, padding=1, bias=False)
+        self.norm1 = nn.GroupNorm(num_groups=8, num_channels=in_channels,  affine=True)
+        self.act = nn.SiLU()
+        self.conv2 = nn.Conv2d(out_channels, out_channels, kernel_size=3, stride=1, padding=1, bias=False)
+        self.norm2 = nn.GroupNorm(num_groups=8, num_channels=in_channels,  affine=True)
+        self.downsample = nn.Sequential()
+        if stride != 1 or in_channels != out_channels:
+            self.downsample = nn.Sequential(
+                nn.Conv2d(in_channels, out_channels, kernel_size=1, stride=stride, bias=False),
+                nn.GroupNorm(num_groups=8, num_channels=in_channels,  affine=True)
+            )
+
+    def forward(self, x):
+        identity = x
+        out = self.conv1(x)
+        out = self.norm1(out)
+        out = self.act(out)
+        out = self.conv2(out)
+        out = self.norm2(out)
+        out += self.downsample(identity)
+        out = self.act(out)
+        return out
+
+class UNetMV2DConditionModel(ModelMixin, ConfigMixin, UNet2DConditionLoadersMixin):
+    r"""
+    A conditional 2D UNet model that takes a noisy sample, conditional state, and a timestep and returns a sample
+    shaped output.
+
+    This model inherits from [`ModelMixin`]. Check the superclass documentation for it's generic methods implemented
+    for all models (such as downloading or saving).
+
+    Parameters:
+        sample_size (`int` or `Tuple[int, int]`, *optional*, defaults to `None`):
+            Height and width of input/output sample.
+        in_channels (`int`, *optional*, defaults to 4): Number of channels in the input sample.
+        out_channels (`int`, *optional*, defaults to 4): Number of channels in the output.
+        center_input_sample (`bool`, *optional*, defaults to `False`): Whether to center the input sample.
+        flip_sin_to_cos (`bool`, *optional*, defaults to `False`):
+            Whether to flip the sin to cos in the time embedding.
+        freq_shift (`int`, *optional*, defaults to 0): The frequency shift to apply to the time embedding.
+        down_block_types (`Tuple[str]`, *optional*, defaults to `("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`):
+            The tuple of downsample blocks to use.
+        mid_block_type (`str`, *optional*, defaults to `"UNetMidBlock2DCrossAttn"`):
+            Block type for middle of UNet, it can be either `UNetMidBlock2DCrossAttn` or
+            `UNetMidBlock2DSimpleCrossAttn`. If `None`, the mid block layer is skipped.
+        up_block_types (`Tuple[str]`, *optional*, defaults to `("UpBlock2D", "CrossAttnUpBlock2D", "CrossAttnUpBlock2D", "CrossAttnUpBlock2D")`):
+            The tuple of upsample blocks to use.
+        only_cross_attention(`bool` or `Tuple[bool]`, *optional*, default to `False`):
+            Whether to include self-attention in the basic transformer blocks, see
+            [`~models.attention.BasicTransformerBlock`].
+        block_out_channels (`Tuple[int]`, *optional*, defaults to `(320, 640, 1280, 1280)`):
+            The tuple of output channels for each block.
+        layers_per_block (`int`, *optional*, defaults to 2): The number of layers per block.
+        downsample_padding (`int`, *optional*, defaults to 1): The padding to use for the downsampling convolution.
+        mid_block_scale_factor (`float`, *optional*, defaults to 1.0): The scale factor to use for the mid block.
+        act_fn (`str`, *optional*, defaults to `"silu"`): The activation function to use.
+        norm_num_groups (`int`, *optional*, defaults to 32): The number of groups to use for the normalization.
+            If `None`, normalization and activation layers is skipped in post-processing.
+        norm_eps (`float`, *optional*, defaults to 1e-5): The epsilon to use for the normalization.
+        cross_attention_dim (`int` or `Tuple[int]`, *optional*, defaults to 1280):
+            The dimension of the cross attention features.
+        transformer_layers_per_block (`int` or `Tuple[int]`, *optional*, defaults to 1):
+            The number of transformer blocks of type [`~models.attention.BasicTransformerBlock`]. Only relevant for
+            [`~models.unet_2d_blocks.CrossAttnDownBlock2D`], [`~models.unet_2d_blocks.CrossAttnUpBlock2D`],
+            [`~models.unet_2d_blocks.UNetMidBlock2DCrossAttn`].
+        encoder_hid_dim (`int`, *optional*, defaults to None):
+            If `encoder_hid_dim_type` is defined, `encoder_hidden_states` will be projected from `encoder_hid_dim`
+            dimension to `cross_attention_dim`.
+        encoder_hid_dim_type (`str`, *optional*, defaults to `None`):
+            If given, the `encoder_hidden_states` and potentially other embeddings are down-projected to text
+            embeddings of dimension `cross_attention` according to `encoder_hid_dim_type`.
+        attention_head_dim (`int`, *optional*, defaults to 8): The dimension of the attention heads.
+        num_attention_heads (`int`, *optional*):
+            The number of attention heads. If not defined, defaults to `attention_head_dim`
+        resnet_time_scale_shift (`str`, *optional*, defaults to `"default"`): Time scale shift config
+            for ResNet blocks (see [`~models.resnet.ResnetBlock2D`]). Choose from `default` or `scale_shift`.
+        class_embed_type (`str`, *optional*, defaults to `None`):
+            The type of class embedding to use which is ultimately summed with the time embeddings. Choose from `None`,
+            `"timestep"`, `"identity"`, `"projection"`, or `"simple_projection"`.
+        addition_embed_type (`str`, *optional*, defaults to `None`):
+            Configures an optional embedding which will be summed with the time embeddings. Choose from `None` or
+            "text". "text" will use the `TextTimeEmbedding` layer.
+        addition_time_embed_dim: (`int`, *optional*, defaults to `None`):
+            Dimension for the timestep embeddings.
+        num_class_embeds (`int`, *optional*, defaults to `None`):
+            Input dimension of the learnable embedding matrix to be projected to `time_embed_dim`, when performing
+            class conditioning with `class_embed_type` equal to `None`.
+        time_embedding_type (`str`, *optional*, defaults to `positional`):
+            The type of position embedding to use for timesteps. Choose from `positional` or `fourier`.
+        time_embedding_dim (`int`, *optional*, defaults to `None`):
+            An optional override for the dimension of the projected time embedding.
+        time_embedding_act_fn (`str`, *optional*, defaults to `None`):
+            Optional activation function to use only once on the time embeddings before they are passed to the rest of
+            the UNet. Choose from `silu`, `mish`, `gelu`, and `swish`.
+        timestep_post_act (`str`, *optional*, defaults to `None`):
+            The second activation function to use in timestep embedding. Choose from `silu`, `mish` and `gelu`.
+        time_cond_proj_dim (`int`, *optional*, defaults to `None`):
+            The dimension of `cond_proj` layer in the timestep embedding.
+        conv_in_kernel (`int`, *optional*, default to `3`): The kernel size of `conv_in` layer.
+        conv_out_kernel (`int`, *optional*, default to `3`): The kernel size of `conv_out` layer.
+        projection_class_embeddings_input_dim (`int`, *optional*): The dimension of the `class_labels` input when
+            `class_embed_type="projection"`. Required when `class_embed_type="projection"`.
+        class_embeddings_concat (`bool`, *optional*, defaults to `False`): Whether to concatenate the time
+            embeddings with the class embeddings.
+        mid_block_only_cross_attention (`bool`, *optional*, defaults to `None`):
+            Whether to use cross attention with the mid block when using the `UNetMidBlock2DSimpleCrossAttn`. If
+            `only_cross_attention` is given as a single boolean and `mid_block_only_cross_attention` is `None`, the
+            `only_cross_attention` value is used as the value for `mid_block_only_cross_attention`. Default to `False`
+            otherwise.
+    """
+
+    _supports_gradient_checkpointing = True
+
+    @register_to_config
+    def __init__(
+        self,
+        sample_size: Optional[int] = None,
+        in_channels: int = 4,
+        out_channels: int = 4,
+        center_input_sample: bool = False,
+        flip_sin_to_cos: bool = True,
+        freq_shift: int = 0,
+        down_block_types: Tuple[str] = (
+            "CrossAttnDownBlockMV2D",
+            "CrossAttnDownBlockMV2D",
+            "CrossAttnDownBlockMV2D",
+            "DownBlock2D",
+        ),
+        mid_block_type: Optional[str] = "UNetMidBlockMV2DCrossAttn",
+        up_block_types: Tuple[str] = ("UpBlock2D", "CrossAttnUpBlockMV2D", "CrossAttnUpBlockMV2D", "CrossAttnUpBlockMV2D"),
+        only_cross_attention: Union[bool, Tuple[bool]] = False,
+        block_out_channels: Tuple[int] = (320, 640, 1280, 1280),
+        layers_per_block: Union[int, Tuple[int]] = 2,
+        downsample_padding: int = 1,
+        mid_block_scale_factor: float = 1,
+        act_fn: str = "silu",
+        norm_num_groups: Optional[int] = 32,
+        norm_eps: float = 1e-5,
+        cross_attention_dim: Union[int, Tuple[int]] = 1280,
+        transformer_layers_per_block: Union[int, Tuple[int]] = 1,
+        encoder_hid_dim: Optional[int] = None,
+        encoder_hid_dim_type: Optional[str] = None,
+        attention_head_dim: Union[int, Tuple[int]] = 8,
+        num_attention_heads: Optional[Union[int, Tuple[int]]] = None,
+        dual_cross_attention: bool = False,
+        use_linear_projection: bool = False,
+        class_embed_type: Optional[str] = None,
+        addition_embed_type: Optional[str] = None,
+        addition_time_embed_dim: Optional[int] = None,
+        num_class_embeds: Optional[int] = None,
+        upcast_attention: bool = False,
+        resnet_time_scale_shift: str = "default",
+        resnet_skip_time_act: bool = False,
+        resnet_out_scale_factor: int = 1.0,
+        time_embedding_type: str = "positional",
+        time_embedding_dim: Optional[int] = None,
+        time_embedding_act_fn: Optional[str] = None,
+        timestep_post_act: Optional[str] = None,
+        time_cond_proj_dim: Optional[int] = None,
+        conv_in_kernel: int = 3,
+        conv_out_kernel: int = 3,
+        projection_class_embeddings_input_dim: Optional[int] = None,
+        class_embeddings_concat: bool = False,
+        mid_block_only_cross_attention: Optional[bool] = None,
+        cross_attention_norm: Optional[str] = None,
+        addition_embed_type_num_heads=64,
+        num_views: int = 1,
+        cd_attention_last: bool = False,
+        cd_attention_mid: bool = False,
+        multiview_attention: bool = True,
+        sparse_mv_attention: bool = False,
+        selfattn_block: str = "custom",
+        addition_downsample: bool = False,
+        addition_channels: Optional[Tuple[int]] = (1280, 1280, 1280),
+    ):
+        super().__init__()
+
+        self.sample_size = sample_size
+        self.num_views = num_views
+
+        if num_attention_heads is not None:
+            raise ValueError(
+                "At the moment it is not possible to define the number of attention heads via `num_attention_heads` because of a naming issue as described in https://github.com/huggingface/diffusers/issues/2011#issuecomment-1547958131. Passing `num_attention_heads` will only be supported in diffusers v0.19."
+            )
+
+        # If `num_attention_heads` is not defined (which is the case for most models)
+        # it will default to `attention_head_dim`. This looks weird upon first reading it and it is.
+        # The reason for this behavior is to correct for incorrectly named variables that were introduced
+        # when this library was created. The incorrect naming was only discovered much later in https://github.com/huggingface/diffusers/issues/2011#issuecomment-1547958131
+        # Changing `attention_head_dim` to `num_attention_heads` for 40,000+ configurations is too backwards breaking
+        # which is why we correct for the naming here.
+        num_attention_heads = num_attention_heads or attention_head_dim
+
+        # Check inputs
+        if len(down_block_types) != len(up_block_types):
+            raise ValueError(
+                f"Must provide the same number of `down_block_types` as `up_block_types`. `down_block_types`: {down_block_types}. `up_block_types`: {up_block_types}."
+            )
+
+        if len(block_out_channels) != len(down_block_types):
+            raise ValueError(
+                f"Must provide the same number of `block_out_channels` as `down_block_types`. `block_out_channels`: {block_out_channels}. `down_block_types`: {down_block_types}."
+            )
+
+        if not isinstance(only_cross_attention, bool) and len(only_cross_attention) != len(down_block_types):
+            raise ValueError(
+                f"Must provide the same number of `only_cross_attention` as `down_block_types`. `only_cross_attention`: {only_cross_attention}. `down_block_types`: {down_block_types}."
+            )
+
+        if not isinstance(num_attention_heads, int) and len(num_attention_heads) != len(down_block_types):
+            raise ValueError(
+                f"Must provide the same number of `num_attention_heads` as `down_block_types`. `num_attention_heads`: {num_attention_heads}. `down_block_types`: {down_block_types}."
+            )
+
+        if not isinstance(attention_head_dim, int) and len(attention_head_dim) != len(down_block_types):
+            raise ValueError(
+                f"Must provide the same number of `attention_head_dim` as `down_block_types`. `attention_head_dim`: {attention_head_dim}. `down_block_types`: {down_block_types}."
+            )
+
+        if isinstance(cross_attention_dim, list) and len(cross_attention_dim) != len(down_block_types):
+            raise ValueError(
+                f"Must provide the same number of `cross_attention_dim` as `down_block_types`. `cross_attention_dim`: {cross_attention_dim}. `down_block_types`: {down_block_types}."
+            )
+
+        if not isinstance(layers_per_block, int) and len(layers_per_block) != len(down_block_types):
+            raise ValueError(
+                f"Must provide the same number of `layers_per_block` as `down_block_types`. `layers_per_block`: {layers_per_block}. `down_block_types`: {down_block_types}."
+            )
+
+        # input
+        conv_in_padding = (conv_in_kernel - 1) // 2
+        self.conv_in = nn.Conv2d(
+            in_channels, block_out_channels[0], kernel_size=conv_in_kernel, padding=conv_in_padding
+        )
+
+        # time
+        if time_embedding_type == "fourier":
+            time_embed_dim = time_embedding_dim or block_out_channels[0] * 2
+            if time_embed_dim % 2 != 0:
+                raise ValueError(f"`time_embed_dim` should be divisible by 2, but is {time_embed_dim}.")
+            self.time_proj = GaussianFourierProjection(
+                time_embed_dim // 2, set_W_to_weight=False, log=False, flip_sin_to_cos=flip_sin_to_cos
+            )
+            timestep_input_dim = time_embed_dim
+        elif time_embedding_type == "positional":
+            time_embed_dim = time_embedding_dim or block_out_channels[0] * 4
+
+            self.time_proj = Timesteps(block_out_channels[0], flip_sin_to_cos, freq_shift)
+            timestep_input_dim = block_out_channels[0]
+        else:
+            raise ValueError(
+                f"{time_embedding_type} does not exist. Please make sure to use one of `fourier` or `positional`."
+            )
+
+        self.time_embedding = TimestepEmbedding(
+            timestep_input_dim,
+            time_embed_dim,
+            act_fn=act_fn,
+            post_act_fn=timestep_post_act,
+            cond_proj_dim=time_cond_proj_dim,
+        )
+
+        if encoder_hid_dim_type is None and encoder_hid_dim is not None:
+            encoder_hid_dim_type = "text_proj"
+            self.register_to_config(encoder_hid_dim_type=encoder_hid_dim_type)
+            logger.info("encoder_hid_dim_type defaults to 'text_proj' as `encoder_hid_dim` is defined.")
+
+        if encoder_hid_dim is None and encoder_hid_dim_type is not None:
+            raise ValueError(
+                f"`encoder_hid_dim` has to be defined when `encoder_hid_dim_type` is set to {encoder_hid_dim_type}."
+            )
+
+        if encoder_hid_dim_type == "text_proj":
+            self.encoder_hid_proj = nn.Linear(encoder_hid_dim, cross_attention_dim)
+        elif encoder_hid_dim_type == "text_image_proj":
+            # image_embed_dim DOESN'T have to be `cross_attention_dim`. To not clutter the __init__ too much
+            # they are set to `cross_attention_dim` here as this is exactly the required dimension for the currently only use
+            # case when `addition_embed_type == "text_image_proj"` (Kadinsky 2.1)`
+            self.encoder_hid_proj = TextImageProjection(
+                text_embed_dim=encoder_hid_dim,
+                image_embed_dim=cross_attention_dim,
+                cross_attention_dim=cross_attention_dim,
+            )
+        elif encoder_hid_dim_type == "image_proj":
+            # Kandinsky 2.2
+            self.encoder_hid_proj = ImageProjection(
+                image_embed_dim=encoder_hid_dim,
+                cross_attention_dim=cross_attention_dim,
+            )
+        elif encoder_hid_dim_type is not None:
+            raise ValueError(
+                f"encoder_hid_dim_type: {encoder_hid_dim_type} must be None, 'text_proj' or 'text_image_proj'."
+            )
+        else:
+            self.encoder_hid_proj = None
+
+        # class embedding
+        if class_embed_type is None and num_class_embeds is not None:
+            self.class_embedding = nn.Embedding(num_class_embeds, time_embed_dim)
+        elif class_embed_type == "timestep":
+            self.class_embedding = TimestepEmbedding(timestep_input_dim, time_embed_dim, act_fn=act_fn)
+        elif class_embed_type == "identity":
+            self.class_embedding = nn.Identity(time_embed_dim, time_embed_dim)
+        elif class_embed_type == "projection":
+            if projection_class_embeddings_input_dim is None:
+                raise ValueError(
+                    "`class_embed_type`: 'projection' requires `projection_class_embeddings_input_dim` be set"
+                )
+            # The projection `class_embed_type` is the same as the timestep `class_embed_type` except
+            # 1. the `class_labels` inputs are not first converted to sinusoidal embeddings
+            # 2. it projects from an arbitrary input dimension.
+            #
+            # Note that `TimestepEmbedding` is quite general, being mainly linear layers and activations.
+            # When used for embedding actual timesteps, the timesteps are first converted to sinusoidal embeddings.
+            # As a result, `TimestepEmbedding` can be passed arbitrary vectors.
+            self.class_embedding = TimestepEmbedding(projection_class_embeddings_input_dim, time_embed_dim)
+        elif class_embed_type == "simple_projection":
+            if projection_class_embeddings_input_dim is None:
+                raise ValueError(
+                    "`class_embed_type`: 'simple_projection' requires `projection_class_embeddings_input_dim` be set"
+                )
+            self.class_embedding = nn.Linear(projection_class_embeddings_input_dim, time_embed_dim)
+        else:
+            self.class_embedding = None
+
+        if addition_embed_type == "text":
+            if encoder_hid_dim is not None:
+                text_time_embedding_from_dim = encoder_hid_dim
+            else:
+                text_time_embedding_from_dim = cross_attention_dim
+
+            self.add_embedding = TextTimeEmbedding(
+                text_time_embedding_from_dim, time_embed_dim, num_heads=addition_embed_type_num_heads
+            )
+        elif addition_embed_type == "text_image":
+            # text_embed_dim and image_embed_dim DON'T have to be `cross_attention_dim`. To not clutter the __init__ too much
+            # they are set to `cross_attention_dim` here as this is exactly the required dimension for the currently only use
+            # case when `addition_embed_type == "text_image"` (Kadinsky 2.1)`
+            self.add_embedding = TextImageTimeEmbedding(
+                text_embed_dim=cross_attention_dim, image_embed_dim=cross_attention_dim, time_embed_dim=time_embed_dim
+            )
+        elif addition_embed_type == "text_time":
+            self.add_time_proj = Timesteps(addition_time_embed_dim, flip_sin_to_cos, freq_shift)
+            self.add_embedding = TimestepEmbedding(projection_class_embeddings_input_dim, time_embed_dim)
+        elif addition_embed_type == "image":
+            # Kandinsky 2.2
+            self.add_embedding = ImageTimeEmbedding(image_embed_dim=encoder_hid_dim, time_embed_dim=time_embed_dim)
+        elif addition_embed_type == "image_hint":
+            # Kandinsky 2.2 ControlNet
+            self.add_embedding = ImageHintTimeEmbedding(image_embed_dim=encoder_hid_dim, time_embed_dim=time_embed_dim)
+        elif addition_embed_type is not None:
+            raise ValueError(f"addition_embed_type: {addition_embed_type} must be None, 'text' or 'text_image'.")
+
+        if time_embedding_act_fn is None:
+            self.time_embed_act = None
+        else:
+            self.time_embed_act = get_activation(time_embedding_act_fn)
+
+        self.down_blocks = nn.ModuleList([])
+        self.up_blocks = nn.ModuleList([])
+
+        if isinstance(only_cross_attention, bool):
+            if mid_block_only_cross_attention is None:
+                mid_block_only_cross_attention = only_cross_attention
+
+            only_cross_attention = [only_cross_attention] * len(down_block_types)
+
+        if mid_block_only_cross_attention is None:
+            mid_block_only_cross_attention = False
+
+        if isinstance(num_attention_heads, int):
+            num_attention_heads = (num_attention_heads,) * len(down_block_types)
+
+        if isinstance(attention_head_dim, int):
+            attention_head_dim = (attention_head_dim,) * len(down_block_types)
+
+        if isinstance(cross_attention_dim, int):
+            cross_attention_dim = (cross_attention_dim,) * len(down_block_types)
+
+        if isinstance(layers_per_block, int):
+            layers_per_block = [layers_per_block] * len(down_block_types)
+
+        if isinstance(transformer_layers_per_block, int):
+            transformer_layers_per_block = [transformer_layers_per_block] * len(down_block_types)
+
+        if class_embeddings_concat:
+            # The time embeddings are concatenated with the class embeddings. The dimension of the
+            # time embeddings passed to the down, middle, and up blocks is twice the dimension of the
+            # regular time embeddings
+            blocks_time_embed_dim = time_embed_dim * 2
+        else:
+            blocks_time_embed_dim = time_embed_dim
+
+        # down
+        output_channel = block_out_channels[0]
+        for i, down_block_type in enumerate(down_block_types):
+            input_channel = output_channel
+            output_channel = block_out_channels[i]
+            is_final_block = i == len(block_out_channels) - 1
+
+            down_block = get_down_block(
+                down_block_type,
+                num_layers=layers_per_block[i],
+                transformer_layers_per_block=transformer_layers_per_block[i],
+                in_channels=input_channel,
+                out_channels=output_channel,
+                temb_channels=blocks_time_embed_dim,
+                add_downsample=not is_final_block,
+                resnet_eps=norm_eps,
+                resnet_act_fn=act_fn,
+                resnet_groups=norm_num_groups,
+                cross_attention_dim=cross_attention_dim[i],
+                num_attention_heads=num_attention_heads[i],
+                downsample_padding=downsample_padding,
+                dual_cross_attention=dual_cross_attention,
+                use_linear_projection=use_linear_projection,
+                only_cross_attention=only_cross_attention[i],
+                upcast_attention=upcast_attention,
+                resnet_time_scale_shift=resnet_time_scale_shift,
+                resnet_skip_time_act=resnet_skip_time_act,
+                resnet_out_scale_factor=resnet_out_scale_factor,
+                cross_attention_norm=cross_attention_norm,
+                attention_head_dim=attention_head_dim[i] if attention_head_dim[i] is not None else output_channel,
+                num_views=num_views,
+                cd_attention_last=cd_attention_last,
+                cd_attention_mid=cd_attention_mid,
+                multiview_attention=multiview_attention,
+                sparse_mv_attention=sparse_mv_attention,
+                selfattn_block=selfattn_block,
+            )
+            self.down_blocks.append(down_block)
+
+        # mid
+        if mid_block_type == "UNetMidBlock2DCrossAttn":
+            self.mid_block = UNetMidBlock2DCrossAttn(
+                transformer_layers_per_block=transformer_layers_per_block[-1],
+                in_channels=block_out_channels[-1],
+                temb_channels=blocks_time_embed_dim,
+                resnet_eps=norm_eps,
+                resnet_act_fn=act_fn,
+                output_scale_factor=mid_block_scale_factor,
+                resnet_time_scale_shift=resnet_time_scale_shift,
+                cross_attention_dim=cross_attention_dim[-1],
+                num_attention_heads=num_attention_heads[-1],
+                resnet_groups=norm_num_groups,
+                dual_cross_attention=dual_cross_attention,
+                use_linear_projection=use_linear_projection,
+                upcast_attention=upcast_attention,
+            )
+        # custom MV2D attention block  
+        elif mid_block_type == "UNetMidBlockMV2DCrossAttn":
+            self.mid_block = UNetMidBlockMV2DCrossAttn(
+                transformer_layers_per_block=transformer_layers_per_block[-1],
+                in_channels=block_out_channels[-1],
+                temb_channels=blocks_time_embed_dim,
+                resnet_eps=norm_eps,
+                resnet_act_fn=act_fn,
+                output_scale_factor=mid_block_scale_factor,
+                resnet_time_scale_shift=resnet_time_scale_shift,
+                cross_attention_dim=cross_attention_dim[-1],
+                num_attention_heads=num_attention_heads[-1],
+                resnet_groups=norm_num_groups,
+                dual_cross_attention=dual_cross_attention,
+                use_linear_projection=use_linear_projection,
+                upcast_attention=upcast_attention,
+                num_views=num_views,
+                cd_attention_last=cd_attention_last,
+                cd_attention_mid=cd_attention_mid,
+                multiview_attention=multiview_attention,
+                sparse_mv_attention=sparse_mv_attention,
+                selfattn_block=selfattn_block,
+            )
+        elif mid_block_type == "UNetMidBlock2DSimpleCrossAttn":
+            self.mid_block = UNetMidBlock2DSimpleCrossAttn(
+                in_channels=block_out_channels[-1],
+                temb_channels=blocks_time_embed_dim,
+                resnet_eps=norm_eps,
+                resnet_act_fn=act_fn,
+                output_scale_factor=mid_block_scale_factor,
+                cross_attention_dim=cross_attention_dim[-1],
+                attention_head_dim=attention_head_dim[-1],
+                resnet_groups=norm_num_groups,
+                resnet_time_scale_shift=resnet_time_scale_shift,
+                skip_time_act=resnet_skip_time_act,
+                only_cross_attention=mid_block_only_cross_attention,
+                cross_attention_norm=cross_attention_norm,
+            )
+        elif mid_block_type is None:
+            self.mid_block = None
+        else:
+            raise ValueError(f"unknown mid_block_type : {mid_block_type}")
+        
+        self.addition_downsample = addition_downsample
+        if self.addition_downsample:
+            inc = block_out_channels[-1]
+            self.downsample = nn.MaxPool2d(kernel_size=3, stride=2, padding=1)
+            self.conv_block = nn.ModuleList()
+            self.conv_block.append(BasicConvBlock(inc, addition_channels[0], stride=1)) 
+            for dim_ in addition_channels[1:-1]:  
+                self.conv_block.append(BasicConvBlock(dim_, dim_, stride=1))    
+            self.conv_block.append(BasicConvBlock(dim_, inc))
+            self.addition_conv_out = nn.Conv2d(inc, inc, kernel_size=1, bias=False)
+            nn.init.zeros_(self.addition_conv_out.weight.data)
+            self.addition_act_out = nn.SiLU()
+            self.upsample = nn.Upsample(scale_factor=2, mode='bilinear', align_corners=True)
+
+        # count how many layers upsample the images
+        self.num_upsamplers = 0
+
+        # up
+        reversed_block_out_channels = list(reversed(block_out_channels))
+        reversed_num_attention_heads = list(reversed(num_attention_heads))
+        reversed_layers_per_block = list(reversed(layers_per_block))
+        reversed_cross_attention_dim = list(reversed(cross_attention_dim))
+        reversed_transformer_layers_per_block = list(reversed(transformer_layers_per_block))
+        only_cross_attention = list(reversed(only_cross_attention))
+
+        output_channel = reversed_block_out_channels[0]
+        for i, up_block_type in enumerate(up_block_types):
+            is_final_block = i == len(block_out_channels) - 1
+
+            prev_output_channel = output_channel
+            output_channel = reversed_block_out_channels[i]
+            input_channel = reversed_block_out_channels[min(i + 1, len(block_out_channels) - 1)]
+
+            # add upsample block for all BUT final layer
+            if not is_final_block:
+                add_upsample = True
+                self.num_upsamplers += 1
+            else:
+                add_upsample = False
+
+            up_block = get_up_block(
+                up_block_type,
+                num_layers=reversed_layers_per_block[i] + 1,
+                transformer_layers_per_block=reversed_transformer_layers_per_block[i],
+                in_channels=input_channel,
+                out_channels=output_channel,
+                prev_output_channel=prev_output_channel,
+                temb_channels=blocks_time_embed_dim,
+                add_upsample=add_upsample,
+                resnet_eps=norm_eps,
+                resnet_act_fn=act_fn,
+                resnet_groups=norm_num_groups,
+                cross_attention_dim=reversed_cross_attention_dim[i],
+                num_attention_heads=reversed_num_attention_heads[i],
+                dual_cross_attention=dual_cross_attention,
+                use_linear_projection=use_linear_projection,
+                only_cross_attention=only_cross_attention[i],
+                upcast_attention=upcast_attention,
+                resnet_time_scale_shift=resnet_time_scale_shift,
+                resnet_skip_time_act=resnet_skip_time_act,
+                resnet_out_scale_factor=resnet_out_scale_factor,
+                cross_attention_norm=cross_attention_norm,
+                attention_head_dim=attention_head_dim[i] if attention_head_dim[i] is not None else output_channel,
+                num_views=num_views,
+                cd_attention_last=cd_attention_last,
+                cd_attention_mid=cd_attention_mid,
+                multiview_attention=multiview_attention,
+                sparse_mv_attention=sparse_mv_attention,
+                selfattn_block=selfattn_block,
+            )
+            self.up_blocks.append(up_block)
+            prev_output_channel = output_channel
+
+        # out
+        if norm_num_groups is not None:
+            self.conv_norm_out = nn.GroupNorm(
+                num_channels=block_out_channels[0], num_groups=norm_num_groups, eps=norm_eps
+            )
+
+            self.conv_act = get_activation(act_fn)
+
+        else:
+            self.conv_norm_out = None
+            self.conv_act = None
+
+        conv_out_padding = (conv_out_kernel - 1) // 2
+        self.conv_out = nn.Conv2d(
+            block_out_channels[0], out_channels, kernel_size=conv_out_kernel, padding=conv_out_padding
+        )
+
+    @property
+    def attn_processors(self) -> Dict[str, AttentionProcessor]:
+        r"""
+        Returns:
+            `dict` of attention processors: A dictionary containing all attention processors used in the model with
+            indexed by its weight name.
+        """
+        # set recursively
+        processors = {}
+
+        def fn_recursive_add_processors(name: str, module: torch.nn.Module, processors: Dict[str, AttentionProcessor]):
+            if hasattr(module, "set_processor"):
+                processors[f"{name}.processor"] = module.processor
+
+            for sub_name, child in module.named_children():
+                fn_recursive_add_processors(f"{name}.{sub_name}", child, processors)
+
+            return processors
+
+        for name, module in self.named_children():
+            fn_recursive_add_processors(name, module, processors)
+
+        return processors
+
+    def set_attn_processor(self, processor: Union[AttentionProcessor, Dict[str, AttentionProcessor]]):
+        r"""
+        Sets the attention processor to use to compute attention.
+
+        Parameters:
+            processor (`dict` of `AttentionProcessor` or only `AttentionProcessor`):
+                The instantiated processor class or a dictionary of processor classes that will be set as the processor
+                for **all** `Attention` layers.
+
+                If `processor` is a dict, the key needs to define the path to the corresponding cross attention
+                processor. This is strongly recommended when setting trainable attention processors.
+
+        """
+        count = len(self.attn_processors.keys())
+
+        if isinstance(processor, dict) and len(processor) != count:
+            raise ValueError(
+                f"A dict of processors was passed, but the number of processors {len(processor)} does not match the"
+                f" number of attention layers: {count}. Please make sure to pass {count} processor classes."
+            )
+
+        def fn_recursive_attn_processor(name: str, module: torch.nn.Module, processor):
+            if hasattr(module, "set_processor"):
+                if not isinstance(processor, dict):
+                    module.set_processor(processor)
+                else:
+                    module.set_processor(processor.pop(f"{name}.processor"))
+
+            for sub_name, child in module.named_children():
+                fn_recursive_attn_processor(f"{name}.{sub_name}", child, processor)
+
+        for name, module in self.named_children():
+            fn_recursive_attn_processor(name, module, processor)
+
+    def set_default_attn_processor(self):
+        """
+        Disables custom attention processors and sets the default attention implementation.
+        """
+        self.set_attn_processor(AttnProcessor())
+
+    def set_attention_slice(self, slice_size):
+        r"""
+        Enable sliced attention computation.
+
+        When this option is enabled, the attention module splits the input tensor in slices to compute attention in
+        several steps. This is useful for saving some memory in exchange for a small decrease in speed.
+
+        Args:
+            slice_size (`str` or `int` or `list(int)`, *optional*, defaults to `"auto"`):
+                When `"auto"`, input to the attention heads is halved, so attention is computed in two steps. If
+                `"max"`, maximum amount of memory is saved by running only one slice at a time. If a number is
+                provided, uses as many slices as `attention_head_dim // slice_size`. In this case, `attention_head_dim`
+                must be a multiple of `slice_size`.
+        """
+        sliceable_head_dims = []
+
+        def fn_recursive_retrieve_sliceable_dims(module: torch.nn.Module):
+            if hasattr(module, "set_attention_slice"):
+                sliceable_head_dims.append(module.sliceable_head_dim)
+
+            for child in module.children():
+                fn_recursive_retrieve_sliceable_dims(child)
+
+        # retrieve number of attention layers
+        for module in self.children():
+            fn_recursive_retrieve_sliceable_dims(module)
+
+        num_sliceable_layers = len(sliceable_head_dims)
+
+        if slice_size == "auto":
+            # half the attention head size is usually a good trade-off between
+            # speed and memory
+            slice_size = [dim // 2 for dim in sliceable_head_dims]
+        elif slice_size == "max":
+            # make smallest slice possible
+            slice_size = num_sliceable_layers * [1]
+
+        slice_size = num_sliceable_layers * [slice_size] if not isinstance(slice_size, list) else slice_size
+
+        if len(slice_size) != len(sliceable_head_dims):
+            raise ValueError(
+                f"You have provided {len(slice_size)}, but {self.config} has {len(sliceable_head_dims)} different"
+                f" attention layers. Make sure to match `len(slice_size)` to be {len(sliceable_head_dims)}."
+            )
+
+        for i in range(len(slice_size)):
+            size = slice_size[i]
+            dim = sliceable_head_dims[i]
+            if size is not None and size > dim:
+                raise ValueError(f"size {size} has to be smaller or equal to {dim}.")
+
+        # Recursively walk through all the children.
+        # Any children which exposes the set_attention_slice method
+        # gets the message
+        def fn_recursive_set_attention_slice(module: torch.nn.Module, slice_size: List[int]):
+            if hasattr(module, "set_attention_slice"):
+                module.set_attention_slice(slice_size.pop())
+
+            for child in module.children():
+                fn_recursive_set_attention_slice(child, slice_size)
+
+        reversed_slice_size = list(reversed(slice_size))
+        for module in self.children():
+            fn_recursive_set_attention_slice(module, reversed_slice_size)
+
+    def _set_gradient_checkpointing(self, module, value=False):
+        if isinstance(module, (CrossAttnDownBlock2D, CrossAttnDownBlockMV2D, DownBlock2D, CrossAttnUpBlock2D, CrossAttnUpBlockMV2D, UpBlock2D)):
+            module.gradient_checkpointing = value
+
+    def forward(
+        self,
+        sample: torch.FloatTensor,
+        timestep: Union[torch.Tensor, float, int],
+        encoder_hidden_states: torch.Tensor = None,
+        class_labels: Optional[torch.Tensor] = None,
+        timestep_cond: Optional[torch.Tensor] = None,
+        attention_mask: Optional[torch.Tensor] = None,
+        cross_attention_kwargs: Optional[Dict[str, Any]] = None,
+        added_cond_kwargs: Optional[Dict[str, torch.Tensor]] = None,
+        down_block_additional_residuals: Optional[Tuple[torch.Tensor]] = None,
+        mid_block_additional_residual: Optional[torch.Tensor] = None,
+        encoder_attention_mask: Optional[torch.Tensor] = None,
+        return_dict: bool = True,
+        vis_max_min: bool = False,
+    ) -> Union[UNetMV2DConditionOutput, Tuple]:
+        r"""
+        The [`UNet2DConditionModel`] forward method.
+
+        Args:
+            sample (`torch.FloatTensor`):
+                The noisy input tensor with the following shape `(batch, channel, height, width)`.
+            timestep (`torch.FloatTensor` or `float` or `int`): The number of timesteps to denoise an input.
+            encoder_hidden_states (`torch.FloatTensor`):
+                The encoder hidden states with shape `(batch, sequence_length, feature_dim)`.
+            encoder_attention_mask (`torch.Tensor`):
+                A cross-attention mask of shape `(batch, sequence_length)` is applied to `encoder_hidden_states`. If
+                `True` the mask is kept, otherwise if `False` it is discarded. Mask will be converted into a bias,
+                which adds large negative values to the attention scores corresponding to "discard" tokens.
+            return_dict (`bool`, *optional*, defaults to `True`):
+                Whether or not to return a [`~models.unet_2d_condition.UNet2DConditionOutput`] instead of a plain
+                tuple.
+            cross_attention_kwargs (`dict`, *optional*):
+                A kwargs dictionary that if specified is passed along to the [`AttnProcessor`].
+            added_cond_kwargs: (`dict`, *optional*):
+                A kwargs dictionary containin additional embeddings that if specified are added to the embeddings that
+                are passed along to the UNet blocks.
+
+        Returns:
+            [`~models.unet_2d_condition.UNet2DConditionOutput`] or `tuple`:
+                If `return_dict` is True, an [`~models.unet_2d_condition.UNet2DConditionOutput`] is returned, otherwise
+                a `tuple` is returned where the first element is the sample tensor.
+        """
+        record_max_min = {}
+        # By default samples have to be AT least a multiple of the overall upsampling factor.
+        # The overall upsampling factor is equal to 2 ** (# num of upsampling layers).
+        # However, the upsampling interpolation output size can be forced to fit any upsampling size
+        # on the fly if necessary.
+        default_overall_up_factor = 2**self.num_upsamplers
+
+        # upsample size should be forwarded when sample is not a multiple of `default_overall_up_factor`
+        forward_upsample_size = False
+        upsample_size = None
+
+        if any(s % default_overall_up_factor != 0 for s in sample.shape[-2:]):
+            logger.info("Forward upsample size to force interpolation output size.")
+            forward_upsample_size = True
+
+        # ensure attention_mask is a bias, and give it a singleton query_tokens dimension
+        # expects mask of shape:
+        #   [batch, key_tokens]
+        # adds singleton query_tokens dimension:
+        #   [batch,                    1, key_tokens]
+        # this helps to broadcast it as a bias over attention scores, which will be in one of the following shapes:
+        #   [batch,  heads, query_tokens, key_tokens] (e.g. torch sdp attn)
+        #   [batch * heads, query_tokens, key_tokens] (e.g. xformers or classic attn)
+        if attention_mask is not None:
+            # assume that mask is expressed as:
+            #   (1 = keep,      0 = discard)
+            # convert mask into a bias that can be added to attention scores:
+            #       (keep = +0,     discard = -10000.0)
+            attention_mask = (1 - attention_mask.to(sample.dtype)) * -10000.0
+            attention_mask = attention_mask.unsqueeze(1)
+
+        # convert encoder_attention_mask to a bias the same way we do for attention_mask
+        if encoder_attention_mask is not None:
+            encoder_attention_mask = (1 - encoder_attention_mask.to(sample.dtype)) * -10000.0
+            encoder_attention_mask = encoder_attention_mask.unsqueeze(1)
+
+        # 0. center input if necessary
+        if self.config.center_input_sample:
+            sample = 2 * sample - 1.0
+        # 1. time
+        timesteps = timestep
+        if not torch.is_tensor(timesteps):
+            # TODO: this requires sync between CPU and GPU. So try to pass timesteps as tensors if you can
+            # This would be a good case for the `match` statement (Python 3.10+)
+            is_mps = sample.device.type == "mps"
+            if isinstance(timestep, float):
+                dtype = torch.float32 if is_mps else torch.float64
+            else:
+                dtype = torch.int32 if is_mps else torch.int64
+            timesteps = torch.tensor([timesteps], dtype=dtype, device=sample.device)
+        elif len(timesteps.shape) == 0:
+            timesteps = timesteps[None].to(sample.device)
+
+        # broadcast to batch dimension in a way that's compatible with ONNX/Core ML
+        timesteps = timesteps.expand(sample.shape[0])
+
+        t_emb = self.time_proj(timesteps)
+
+        # `Timesteps` does not contain any weights and will always return f32 tensors
+        # but time_embedding might actually be running in fp16. so we need to cast here.
+        # there might be better ways to encapsulate this.
+        t_emb = t_emb.to(dtype=sample.dtype)
+
+        emb = self.time_embedding(t_emb, timestep_cond)
+        aug_emb = None
+        if self.class_embedding is not None:
+            if class_labels is None:
+                raise ValueError("class_labels should be provided when num_class_embeds > 0")
+
+            if self.config.class_embed_type == "timestep":
+                class_labels = self.time_proj(class_labels)
+
+                # `Timesteps` does not contain any weights and will always return f32 tensors
+                # there might be better ways to encapsulate this.
+                class_labels = class_labels.to(dtype=sample.dtype)
+
+            class_emb = self.class_embedding(class_labels).to(dtype=sample.dtype)
+            if self.config.class_embeddings_concat:
+                emb = torch.cat([emb, class_emb], dim=-1)
+            else:
+                emb = emb + class_emb
+
+        if self.config.addition_embed_type == "text":
+            aug_emb = self.add_embedding(encoder_hidden_states)
+        elif self.config.addition_embed_type == "text_image":
+            # Kandinsky 2.1 - style
+            if "image_embeds" not in added_cond_kwargs:
+                raise ValueError(
+                    f"{self.__class__} has the config param `addition_embed_type` set to 'text_image' which requires the keyword argument `image_embeds` to be passed in `added_cond_kwargs`"
+                )
+
+            image_embs = added_cond_kwargs.get("image_embeds")
+            text_embs = added_cond_kwargs.get("text_embeds", encoder_hidden_states)
+            aug_emb = self.add_embedding(text_embs, image_embs)
+        elif self.config.addition_embed_type == "text_time":
+            # SDXL - style
+            if "text_embeds" not in added_cond_kwargs:
+                raise ValueError(
+                    f"{self.__class__} has the config param `addition_embed_type` set to 'text_time' which requires the keyword argument `text_embeds` to be passed in `added_cond_kwargs`"
+                )
+            text_embeds = added_cond_kwargs.get("text_embeds")
+            if "time_ids" not in added_cond_kwargs:
+                raise ValueError(
+                    f"{self.__class__} has the config param `addition_embed_type` set to 'text_time' which requires the keyword argument `time_ids` to be passed in `added_cond_kwargs`"
+                )
+            time_ids = added_cond_kwargs.get("time_ids")
+            time_embeds = self.add_time_proj(time_ids.flatten())
+            time_embeds = time_embeds.reshape((text_embeds.shape[0], -1))
+
+            add_embeds = torch.concat([text_embeds, time_embeds], dim=-1)
+            add_embeds = add_embeds.to(emb.dtype)
+            aug_emb = self.add_embedding(add_embeds)
+        elif self.config.addition_embed_type == "image":
+            # Kandinsky 2.2 - style
+            if "image_embeds" not in added_cond_kwargs:
+                raise ValueError(
+                    f"{self.__class__} has the config param `addition_embed_type` set to 'image' which requires the keyword argument `image_embeds` to be passed in `added_cond_kwargs`"
+                )
+            image_embs = added_cond_kwargs.get("image_embeds")
+            aug_emb = self.add_embedding(image_embs)
+        elif self.config.addition_embed_type == "image_hint":
+            # Kandinsky 2.2 - style
+            if "image_embeds" not in added_cond_kwargs or "hint" not in added_cond_kwargs:
+                raise ValueError(
+                    f"{self.__class__} has the config param `addition_embed_type` set to 'image_hint' which requires the keyword arguments `image_embeds` and `hint` to be passed in `added_cond_kwargs`"
+                )
+            image_embs = added_cond_kwargs.get("image_embeds")
+            hint = added_cond_kwargs.get("hint")
+            aug_emb, hint = self.add_embedding(image_embs, hint)
+            sample = torch.cat([sample, hint], dim=1)
+
+        emb = emb + aug_emb if aug_emb is not None else emb
+        emb_pre_act = emb
+        if self.time_embed_act is not None:
+            emb = self.time_embed_act(emb)
+
+        if self.encoder_hid_proj is not None and self.config.encoder_hid_dim_type == "text_proj":
+            encoder_hidden_states = self.encoder_hid_proj(encoder_hidden_states)
+        elif self.encoder_hid_proj is not None and self.config.encoder_hid_dim_type == "text_image_proj":
+            # Kadinsky 2.1 - style
+            if "image_embeds" not in added_cond_kwargs:
+                raise ValueError(
+                    f"{self.__class__} has the config param `encoder_hid_dim_type` set to 'text_image_proj' which requires the keyword argument `image_embeds` to be passed in  `added_conditions`"
+                )
+
+            image_embeds = added_cond_kwargs.get("image_embeds")
+            encoder_hidden_states = self.encoder_hid_proj(encoder_hidden_states, image_embeds)
+        elif self.encoder_hid_proj is not None and self.config.encoder_hid_dim_type == "image_proj":
+            # Kandinsky 2.2 - style
+            if "image_embeds" not in added_cond_kwargs:
+                raise ValueError(
+                    f"{self.__class__} has the config param `encoder_hid_dim_type` set to 'image_proj' which requires the keyword argument `image_embeds` to be passed in  `added_conditions`"
+                )
+            image_embeds = added_cond_kwargs.get("image_embeds")
+            encoder_hidden_states = self.encoder_hid_proj(image_embeds)
+        # 2. pre-process
+        sample = self.conv_in(sample)
+        # 3. down
+
+        is_controlnet = mid_block_additional_residual is not None and down_block_additional_residuals is not None
+        is_adapter = mid_block_additional_residual is None and down_block_additional_residuals is not None
+
+        down_block_res_samples = (sample,)
+        for i, downsample_block in enumerate(self.down_blocks):
+            if hasattr(downsample_block, "has_cross_attention") and downsample_block.has_cross_attention:
+                # For t2i-adapter CrossAttnDownBlock2D
+                additional_residuals = {}
+                if is_adapter and len(down_block_additional_residuals) > 0:
+                    additional_residuals["additional_residuals"] = down_block_additional_residuals.pop(0)
+
+                sample, res_samples = downsample_block(
+                    hidden_states=sample,
+                    temb=emb,
+                    encoder_hidden_states=encoder_hidden_states,
+                    attention_mask=attention_mask,
+                    cross_attention_kwargs=cross_attention_kwargs,
+                    encoder_attention_mask=encoder_attention_mask,
+                    **additional_residuals,
+                )
+            else:
+                sample, res_samples = downsample_block(hidden_states=sample, temb=emb)
+
+                if is_adapter and len(down_block_additional_residuals) > 0:
+                    sample += down_block_additional_residuals.pop(0)
+
+            down_block_res_samples += res_samples
+
+        if is_controlnet:
+            new_down_block_res_samples = ()
+
+            for down_block_res_sample, down_block_additional_residual in zip(
+                down_block_res_samples, down_block_additional_residuals
+            ):
+                down_block_res_sample = down_block_res_sample + down_block_additional_residual
+                new_down_block_res_samples = new_down_block_res_samples + (down_block_res_sample,)
+
+            down_block_res_samples = new_down_block_res_samples
+
+        if self.addition_downsample:
+            global_sample = sample
+            global_sample = self.downsample(global_sample)
+            for layer in self.conv_block:
+                global_sample = layer(global_sample)
+            global_sample = self.addition_act_out(self.addition_conv_out(global_sample))
+            global_sample = self.upsample(global_sample)
+        # 4. mid
+        if self.mid_block is not None:
+            sample = self.mid_block(
+                sample,
+                emb,
+                encoder_hidden_states=encoder_hidden_states,
+                attention_mask=attention_mask,
+                cross_attention_kwargs=cross_attention_kwargs,
+                encoder_attention_mask=encoder_attention_mask,
+            )
+            
+        if is_controlnet:
+            sample = sample + mid_block_additional_residual
+
+        if self.addition_downsample:
+            sample = sample + global_sample
+            
+        # 5. up
+        for i, upsample_block in enumerate(self.up_blocks):
+            is_final_block = i == len(self.up_blocks) - 1
+
+            res_samples = down_block_res_samples[-len(upsample_block.resnets) :]
+            down_block_res_samples = down_block_res_samples[: -len(upsample_block.resnets)]
+
+            # if we have not reached the final block and need to forward the
+            # upsample size, we do it here
+            if not is_final_block and forward_upsample_size:
+                upsample_size = down_block_res_samples[-1].shape[2:]
+
+            if hasattr(upsample_block, "has_cross_attention") and upsample_block.has_cross_attention:
+                sample = upsample_block(
+                    hidden_states=sample,
+                    temb=emb,
+                    res_hidden_states_tuple=res_samples,
+                    encoder_hidden_states=encoder_hidden_states,
+                    cross_attention_kwargs=cross_attention_kwargs,
+                    upsample_size=upsample_size,
+                    attention_mask=attention_mask,
+                    encoder_attention_mask=encoder_attention_mask,
+                )
+            else:
+                sample = upsample_block(
+                    hidden_states=sample, temb=emb, res_hidden_states_tuple=res_samples, upsample_size=upsample_size
+                )
+        if torch.isnan(sample).any() or torch.isinf(sample).any():
+            print("NAN in sample, stop training.")
+            exit() 
+        # 6. post-process
+        if self.conv_norm_out:
+            sample = self.conv_norm_out(sample)
+            sample = self.conv_act(sample)
+        sample = self.conv_out(sample)
+        if not return_dict:
+            return sample
+        return UNetMV2DConditionOutput(sample=sample)
+
+        
+    @classmethod
+    def from_pretrained_2d(
+            cls, pretrained_model_name_or_path: Optional[Union[str, os.PathLike]],
+            num_views: int, sample_size: int,
+            zero_init_conv_in: bool = True,
+            cd_attention_last: bool = False, 
+            cd_attention_mid: bool = False, multiview_attention: bool = True, 
+            sparse_mv_attention: bool = False, selfattn_block: str = 'custom',
+            in_channels: int = 8, out_channels: int = 4, unclip: bool = False, 
+            init_mvattn_with_selfattn: bool= False, addition_downsample: bool = False,
+            **kwargs
+        ):
+        r"""
+        Instantiate a pretrained PyTorch model from a pretrained model configuration.
+
+        The model is set in evaluation mode - `model.eval()` - by default, and dropout modules are deactivated. To
+        train the model, set it back in training mode with `model.train()`.
+
+        Parameters:
+            pretrained_model_name_or_path (`str` or `os.PathLike`, *optional*):
+                Can be either:
+
+                    - A string, the *model id* (for example `google/ddpm-celebahq-256`) of a pretrained model hosted on
+                      the Hub.
+                    - A path to a *directory* (for example `./my_model_directory`) containing the model weights saved
+                      with [`~ModelMixin.save_pretrained`].
+
+            cache_dir (`Union[str, os.PathLike]`, *optional*):
+                Path to a directory where a downloaded pretrained model configuration is cached if the standard cache
+                is not used.
+            torch_dtype (`str` or `torch.dtype`, *optional*):
+                Override the default `torch.dtype` and load the model with another dtype. If `"auto"` is passed, the
+                dtype is automatically derived from the model's weights.
+            force_download (`bool`, *optional*, defaults to `False`):
+                Whether or not to force the (re-)download of the model weights and configuration files, overriding the
+                cached versions if they exist.
+
+            proxies (`Dict[str, str]`, *optional*):
+                A dictionary of proxy servers to use by protocol or endpoint, for example, `{'http': 'foo.bar:3128',
+                'http://hostname': 'foo.bar:4012'}`. The proxies are used on each request.
+            output_loading_info (`bool`, *optional*, defaults to `False`):
+                Whether or not to also return a dictionary containing missing keys, unexpected keys and error messages.
+            local_files_only(`bool`, *optional*, defaults to `False`):
+                Whether to only load local model weights and configuration files or not. If set to `True`, the model
+                won't be downloaded from the Hub.
+            use_auth_token (`str` or *bool*, *optional*):
+                The token to use as HTTP bearer authorization for remote files. If `True`, the token generated from
+                `diffusers-cli login` (stored in `~/.huggingface`) is used.
+            revision (`str`, *optional*, defaults to `"main"`):
+                The specific model version to use. It can be a branch name, a tag name, a commit id, or any identifier
+                allowed by Git.
+            from_flax (`bool`, *optional*, defaults to `False`):
+                Load the model weights from a Flax checkpoint save file.
+            subfolder (`str`, *optional*, defaults to `""`):
+                The subfolder location of a model file within a larger model repository on the Hub or locally.
+            mirror (`str`, *optional*):
+                Mirror source to resolve accessibility issues if you're downloading a model in China. We do not
+                guarantee the timeliness or safety of the source, and you should refer to the mirror site for more
+                information.
+            device_map (`str` or `Dict[str, Union[int, str, torch.device]]`, *optional*):
+                A map that specifies where each submodule should go. It doesn't need to be defined for each
+                parameter/buffer name; once a given module name is inside, every submodule of it will be sent to the
+                same device.
+
+                Set `device_map="auto"` to have 🤗 Accelerate automatically compute the most optimized `device_map`. For
+                more information about each option see [designing a device
+                map](https://hf.co/docs/accelerate/main/en/usage_guides/big_modeling#designing-a-device-map).
+            max_memory (`Dict`, *optional*):
+                A dictionary device identifier for the maximum memory. Will default to the maximum memory available for
+                each GPU and the available CPU RAM if unset.
+            offload_folder (`str` or `os.PathLike`, *optional*):
+                The path to offload weights if `device_map` contains the value `"disk"`.
+            offload_state_dict (`bool`, *optional*):
+                If `True`, temporarily offloads the CPU state dict to the hard drive to avoid running out of CPU RAM if
+                the weight of the CPU state dict + the biggest shard of the checkpoint does not fit. Defaults to `True`
+                when there is some disk offload.
+            low_cpu_mem_usage (`bool`, *optional*, defaults to `True` if torch version >= 1.9.0 else `False`):
+                Speed up model loading only loading the pretrained weights and not initializing the weights. This also
+                tries to not use more than 1x model size in CPU memory (including peak memory) while loading the model.
+                Only supported for PyTorch >= 1.9.0. If you are using an older version of PyTorch, setting this
+                argument to `True` will raise an error.
+            variant (`str`, *optional*):
+                Load weights from a specified `variant` filename such as `"fp16"` or `"ema"`. This is ignored when
+                loading `from_flax`.
+            use_safetensors (`bool`, *optional*, defaults to `None`):
+                If set to `None`, the `safetensors` weights are downloaded if they're available **and** if the
+                `safetensors` library is installed. If set to `True`, the model is forcibly loaded from `safetensors`
+                weights. If set to `False`, `safetensors` weights are not loaded.
+
+        <Tip>
+
+        To use private or [gated models](https://huggingface.co/docs/hub/models-gated#gated-models), log-in with
+        `huggingface-cli login`. You can also activate the special
+        ["offline-mode"](https://huggingface.co/diffusers/installation.html#offline-mode) to use this method in a
+        firewalled environment.
+
+        </Tip>
+
+        Example:
+
+        ```py
+        from diffusers import UNet2DConditionModel
+
+        unet = UNet2DConditionModel.from_pretrained("runwayml/stable-diffusion-v1-5", subfolder="unet")
+        ```
+
+        If you get the error message below, you need to finetune the weights for your downstream task:
+
+        ```bash
+        Some weights of UNet2DConditionModel were not initialized from the model checkpoint at runwayml/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
+        - conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
+        You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
+        ```
+        """
+        cache_dir = kwargs.pop("cache_dir", DIFFUSERS_CACHE)
+        ignore_mismatched_sizes = kwargs.pop("ignore_mismatched_sizes", False)
+        force_download = kwargs.pop("force_download", False)
+        from_flax = kwargs.pop("from_flax", False)
+        resume_download = kwargs.pop("resume_download", False)
+        proxies = kwargs.pop("proxies", None)
+        output_loading_info = kwargs.pop("output_loading_info", False)
+        local_files_only = kwargs.pop("local_files_only", HF_HUB_OFFLINE)
+        use_auth_token = kwargs.pop("use_auth_token", None)
+        revision = kwargs.pop("revision", None)
+        torch_dtype = kwargs.pop("torch_dtype", None)
+        subfolder = kwargs.pop("subfolder", None)
+        device_map = kwargs.pop("device_map", None)
+        max_memory = kwargs.pop("max_memory", None)
+        offload_folder = kwargs.pop("offload_folder", None)
+        offload_state_dict = kwargs.pop("offload_state_dict", False)
+        variant = kwargs.pop("variant", None)
+        use_safetensors = kwargs.pop("use_safetensors", None)
+
+        if use_safetensors:
+            raise ValueError(
+                "`use_safetensors`=True but safetensors is not installed. Please install safetensors with `pip install safetensors"
+            )
+
+        allow_pickle = False
+        if use_safetensors is None:
+            use_safetensors = True
+            allow_pickle = True
+
+        if device_map is not None and not is_accelerate_available():
+            raise NotImplementedError(
+                "Loading and dispatching requires `accelerate`. Please make sure to install accelerate or set"
+                " `device_map=None`. You can install accelerate with `pip install accelerate`."
+            )
+
+        # Check if we can handle device_map and dispatching the weights
+        if device_map is not None and not is_torch_version(">=", "1.9.0"):
+            raise NotImplementedError(
+                "Loading and dispatching requires torch >= 1.9.0. Please either update your PyTorch version or set"
+                " `device_map=None`."
+            )
+
+        # Load config if we don't provide a configuration
+        config_path = pretrained_model_name_or_path
+
+        user_agent = {
+            "diffusers": __version__,
+            "file_type": "model",
+            "framework": "pytorch",
+        }
+
+        # load config
+        config, unused_kwargs, commit_hash = cls.load_config(
+            config_path,
+            cache_dir=cache_dir,
+            return_unused_kwargs=True,
+            return_commit_hash=True,
+            force_download=force_download,
+            resume_download=resume_download,
+            proxies=proxies,
+            local_files_only=local_files_only,
+            use_auth_token=use_auth_token,
+            revision=revision,
+            subfolder=subfolder,
+            device_map=device_map,
+            max_memory=max_memory,
+            offload_folder=offload_folder,
+            offload_state_dict=offload_state_dict,
+            user_agent=user_agent,
+            **kwargs,
+        )
+
+        # modify config
+        config["_class_name"] = cls.__name__
+        config['in_channels'] = in_channels
+        config['out_channels'] = out_channels
+        config['sample_size'] = sample_size # training resolution
+        config['num_views'] = num_views
+        config['cd_attention_last'] = cd_attention_last
+        config['cd_attention_mid'] = cd_attention_mid
+        config['multiview_attention'] = multiview_attention
+        config['sparse_mv_attention'] = sparse_mv_attention
+        config['selfattn_block'] = selfattn_block
+        config["down_block_types"] = [
+            "CrossAttnDownBlockMV2D",
+            "CrossAttnDownBlockMV2D",
+            "CrossAttnDownBlockMV2D",
+            "DownBlock2D"
+        ]
+        config['mid_block_type'] = "UNetMidBlockMV2DCrossAttn"
+        config["up_block_types"] = [
+            "UpBlock2D",
+            "CrossAttnUpBlockMV2D",
+            "CrossAttnUpBlockMV2D",
+            "CrossAttnUpBlockMV2D"
+        ]
+        
+        config['addition_downsample'] = addition_downsample
+        # load model
+        model_file = None
+        if from_flax:
+            raise NotImplementedError
+        else:
+            if use_safetensors:
+                try:
+                    model_file = _get_model_file(
+                        pretrained_model_name_or_path,
+                        weights_name=_add_variant(SAFETENSORS_WEIGHTS_NAME, variant),
+                        cache_dir=cache_dir,
+                        force_download=force_download,
+                        proxies=proxies,
+                        local_files_only=local_files_only,
+                        use_auth_token=use_auth_token,
+                        revision=revision,
+                        subfolder=subfolder,
+                        user_agent=user_agent,
+                        commit_hash=commit_hash,
+                    )
+                except IOError as e:
+                    if not allow_pickle:
+                        raise e
+                    pass
+            if model_file is None:
+                model_file = _get_model_file(
+                    pretrained_model_name_or_path,
+                    weights_name=_add_variant(WEIGHTS_NAME, variant),
+                    cache_dir=cache_dir,
+                    force_download=force_download,
+                    proxies=proxies,
+                    local_files_only=local_files_only,
+                    use_auth_token=use_auth_token,
+                    revision=revision,
+                    subfolder=subfolder,
+                    user_agent=user_agent,
+                    commit_hash=commit_hash,
+                )
+
+            model = cls.from_config(config, **unused_kwargs)
+            import copy
+            state_dict_pretrain = load_state_dict(model_file, variant=variant)
+            state_dict = copy.deepcopy(state_dict_pretrain)
+            
+            if init_mvattn_with_selfattn:
+                for key in state_dict_pretrain:
+                    if 'attn1' in key:
+                        key_mv = key.replace('attn1', 'attn_mv')
+                        state_dict[key_mv] = state_dict_pretrain[key]
+                        if 'to_out.0.weight' in key:
+                            nn.init.zeros_(state_dict[key_mv].data)
+                    if 'transformer_blocks' in key and 'norm1' in key: # in case that initialize the norm layer in resnet block
+                        key_mv = key.replace('norm1', 'norm_mv')
+                        state_dict[key_mv] = state_dict_pretrain[key]
+            # del state_dict_pretrain
+            
+            model._convert_deprecated_attention_blocks(state_dict)
+
+            conv_in_weight = state_dict['conv_in.weight']
+            conv_out_weight = state_dict['conv_out.weight']
+            model, missing_keys, unexpected_keys, mismatched_keys, error_msgs = cls._load_pretrained_model_2d(
+                model,
+                state_dict,
+                model_file,
+                pretrained_model_name_or_path,
+                ignore_mismatched_sizes=True,
+            )
+            if any([key == 'conv_in.weight' for key, _, _ in mismatched_keys]):
+                # initialize from the original SD structure
+                model.conv_in.weight.data[:,:4] = conv_in_weight
+
+            # whether to place all zero to new layers?
+            if zero_init_conv_in:
+                model.conv_in.weight.data[:,4:] = 0.
+
+            if any([key == 'conv_out.weight' for key, _, _ in mismatched_keys]):
+                # initialize from the original SD structure
+                model.conv_out.weight.data[:,:4] = conv_out_weight
+                if out_channels == 8: # copy for the last 4 channels
+                    model.conv_out.weight.data[:, 4:] = conv_out_weight
+
+            loading_info = {
+                "missing_keys": missing_keys,
+                "unexpected_keys": unexpected_keys,
+                "mismatched_keys": mismatched_keys,
+                "error_msgs": error_msgs,
+            }
+
+        if torch_dtype is not None and not isinstance(torch_dtype, torch.dtype):
+            raise ValueError(
+                f"{torch_dtype} needs to be of type `torch.dtype`, e.g. `torch.float16`, but is {type(torch_dtype)}."
+            )
+        elif torch_dtype is not None:
+            model = model.to(torch_dtype)
+
+        model.register_to_config(_name_or_path=pretrained_model_name_or_path)
+
+        # Set model in evaluation mode to deactivate DropOut modules by default
+        model.eval()
+        if output_loading_info:
+            return model, loading_info
+        return model
+
+    @classmethod
+    def _load_pretrained_model_2d(
+        cls,
+        model,
+        state_dict,
+        resolved_archive_file,
+        pretrained_model_name_or_path,
+        ignore_mismatched_sizes=False,
+    ):
+        # Retrieve missing & unexpected_keys
+        model_state_dict = model.state_dict()
+        loaded_keys = list(state_dict.keys())
+
+        expected_keys = list(model_state_dict.keys())
+
+        original_loaded_keys = loaded_keys
+
+        missing_keys = list(set(expected_keys) - set(loaded_keys))
+        unexpected_keys = list(set(loaded_keys) - set(expected_keys))
+
+        # Make sure we are able to load base models as well as derived models (with heads)
+        model_to_load = model
+
+        def _find_mismatched_keys(
+            state_dict,
+            model_state_dict,
+            loaded_keys,
+            ignore_mismatched_sizes,
+        ):
+            mismatched_keys = []
+            if ignore_mismatched_sizes:
+                for checkpoint_key in loaded_keys:
+                    model_key = checkpoint_key
+
+                    if (
+                        model_key in model_state_dict
+                        and state_dict[checkpoint_key].shape != model_state_dict[model_key].shape
+                    ):
+                        mismatched_keys.append(
+                            (checkpoint_key, state_dict[checkpoint_key].shape, model_state_dict[model_key].shape)
+                        )
+                        del state_dict[checkpoint_key]
+            return mismatched_keys
+
+        if state_dict is not None:
+            # Whole checkpoint
+            mismatched_keys = _find_mismatched_keys(
+                state_dict,
+                model_state_dict,
+                original_loaded_keys,
+                ignore_mismatched_sizes,
+            )
+            error_msgs = _load_state_dict_into_model(model_to_load, state_dict)
+
+        if len(error_msgs) > 0:
+            error_msg = "\n\t".join(error_msgs)
+            if "size mismatch" in error_msg:
+                error_msg += (
+                    "\n\tYou may consider adding `ignore_mismatched_sizes=True` in the model `from_pretrained` method."
+                )
+            raise RuntimeError(f"Error(s) in loading state_dict for {model.__class__.__name__}:\n\t{error_msg}")
+
+        if len(unexpected_keys) > 0:
+            logger.warning(
+                f"Some weights of the model checkpoint at {pretrained_model_name_or_path} were not used when"
+                f" initializing {model.__class__.__name__}: {unexpected_keys}\n- This IS expected if you are"
+                f" initializing {model.__class__.__name__} from the checkpoint of a model trained on another task"
+                " or with another architecture (e.g. initializing a BertForSequenceClassification model from a"
+                " BertForPreTraining model).\n- This IS NOT expected if you are initializing"
+                f" {model.__class__.__name__} from the checkpoint of a model that you expect to be exactly"
+                " identical (initializing a BertForSequenceClassification model from a"
+                " BertForSequenceClassification model)."
+            )
+        else:
+            logger.info(f"All model checkpoint weights were used when initializing {model.__class__.__name__}.\n")
+        if len(missing_keys) > 0:
+            logger.warning(
+                f"Some weights of {model.__class__.__name__} were not initialized from the model checkpoint at"
+                f" {pretrained_model_name_or_path} and are newly initialized: {missing_keys}\nYou should probably"
+                " TRAIN this model on a down-stream task to be able to use it for predictions and inference."
+            )
+        elif len(mismatched_keys) == 0:
+            logger.info(
+                f"All the weights of {model.__class__.__name__} were initialized from the model checkpoint at"
+                f" {pretrained_model_name_or_path}.\nIf your task is similar to the task the model of the"
+                f" checkpoint was trained on, you can already use {model.__class__.__name__} for predictions"
+                " without further training."
+            )
+        if len(mismatched_keys) > 0:
+            mismatched_warning = "\n".join(
+                [
+                    f"- {key}: found shape {shape1} in the checkpoint and {shape2} in the model instantiated"
+                    for key, shape1, shape2 in mismatched_keys
+                ]
+            )
+            logger.warning(
+                f"Some weights of {model.__class__.__name__} were not initialized from the model checkpoint at"
+                f" {pretrained_model_name_or_path} and are newly initialized because the shapes did not"
+                f" match:\n{mismatched_warning}\nYou should probably TRAIN this model on a down-stream task to be"
+                " able to use it for predictions and inference."
+            )
+
+        return model, missing_keys, unexpected_keys, mismatched_keys, error_msgs
+

mvdiffusion/pipelines/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+

mvdiffusion/pipelines/pipeline_mvdiffusion_unclip.py

@@ -0,0 +1,627 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+# 
+# Modified from https://github.com/pengHTYX/Era3D/blob/main/mvdiffusion/pipelines/pipeline_mvdiffusion_unclip.py
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+
+import inspect
+import warnings
+from typing import Callable, List, Optional, Union, Dict, Any
+import PIL
+import torch
+from packaging import version
+from transformers import CLIPImageProcessor, CLIPVisionModelWithProjection, CLIPFeatureExtractor, CLIPTokenizer, CLIPTextModel
+from diffusers.utils.import_utils import is_accelerate_available
+from diffusers.configuration_utils import FrozenDict
+from diffusers.image_processor import VaeImageProcessor
+from diffusers.models import AutoencoderKL, UNet2DConditionModel
+from diffusers.models.embeddings import get_timestep_embedding
+from diffusers.schedulers import KarrasDiffusionSchedulers
+from diffusers.utils import deprecate, logging
+from diffusers.utils.torch_utils import randn_tensor
+from diffusers.pipelines.pipeline_utils import DiffusionPipeline, ImagePipelineOutput
+from diffusers.pipelines.stable_diffusion.stable_unclip_image_normalizer import StableUnCLIPImageNormalizer
+import os
+import torchvision.transforms.functional as TF
+from einops import rearrange
+logger = logging.get_logger(__name__)
+
+class StableUnCLIPImg2ImgPipeline(DiffusionPipeline):
+    """
+    Pipeline for text-guided image to image generation using stable unCLIP.
+
+    This model inherits from [`DiffusionPipeline`]. Check the superclass documentation for the generic methods the
+    library implements for all the pipelines (such as downloading or saving, running on a particular device, etc.)
+
+    Args:
+        feature_extractor ([`CLIPFeatureExtractor`]):
+            Feature extractor for image pre-processing before being encoded.
+        image_encoder ([`CLIPVisionModelWithProjection`]):
+            CLIP vision model for encoding images.
+        image_normalizer ([`StableUnCLIPImageNormalizer`]):
+            Used to normalize the predicted image embeddings before the noise is applied and un-normalize the image
+            embeddings after the noise has been applied.
+        image_noising_scheduler ([`KarrasDiffusionSchedulers`]):
+            Noise schedule for adding noise to the predicted image embeddings. The amount of noise to add is determined
+            by `noise_level` in `StableUnCLIPPipeline.__call__`.
+        tokenizer (`CLIPTokenizer`):
+            Tokenizer of class
+            [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).
+        text_encoder ([`CLIPTextModel`]):
+            Frozen text-encoder.
+        unet ([`UNet2DConditionModel`]): Conditional U-Net architecture to denoise the encoded image latents.
+        scheduler ([`KarrasDiffusionSchedulers`]):
+            A scheduler to be used in combination with `unet` to denoise the encoded image latents.
+        vae ([`AutoencoderKL`]):
+            Variational Auto-Encoder (VAE) Model to encode and decode images to and from latent representations.
+    """
+    # image encoding components
+    feature_extractor: CLIPFeatureExtractor
+    image_encoder: CLIPVisionModelWithProjection
+    # image noising components
+    image_normalizer: StableUnCLIPImageNormalizer
+    image_noising_scheduler: KarrasDiffusionSchedulers
+    # regular denoising components
+    tokenizer: CLIPTokenizer
+    text_encoder: CLIPTextModel
+    unet: UNet2DConditionModel
+    scheduler: KarrasDiffusionSchedulers
+    vae: AutoencoderKL
+
+    def __init__(
+        self,
+        # image encoding components
+        feature_extractor: CLIPFeatureExtractor,
+        image_encoder: CLIPVisionModelWithProjection,
+        # image noising components
+        image_normalizer: StableUnCLIPImageNormalizer,
+        image_noising_scheduler: KarrasDiffusionSchedulers,
+        # regular denoising components
+        tokenizer: CLIPTokenizer,
+        text_encoder: CLIPTextModel,
+        unet: UNet2DConditionModel,
+        scheduler: KarrasDiffusionSchedulers,
+        # vae
+        vae: AutoencoderKL,
+        num_views: int = 6,
+    ):
+        super().__init__()
+
+        self.register_modules(
+            feature_extractor=feature_extractor,
+            image_encoder=image_encoder,
+            image_normalizer=image_normalizer,
+            image_noising_scheduler=image_noising_scheduler,
+            tokenizer=tokenizer,
+            text_encoder=text_encoder,
+            unet=unet,
+            scheduler=scheduler,
+            vae=vae,
+        )
+        self.vae_scale_factor = 2 ** (len(self.vae.config.block_out_channels) - 1)
+        self.image_processor = VaeImageProcessor(vae_scale_factor=self.vae_scale_factor)
+        self.num_views: int = num_views
+    # Copied from diffusers.pipelines.stable_diffusion.pipeline_stable_diffusion.StableDiffusionPipeline.enable_vae_slicing
+    def enable_vae_slicing(self):
+        r"""
+        Enable sliced VAE decoding.
+
+        When this option is enabled, the VAE will split the input tensor in slices to compute decoding in several
+        steps. This is useful to save some memory and allow larger batch sizes.
+        """
+        self.vae.enable_slicing()
+
+    # Copied from diffusers.pipelines.stable_diffusion.pipeline_stable_diffusion.StableDiffusionPipeline.disable_vae_slicing
+    def disable_vae_slicing(self):
+        r"""
+        Disable sliced VAE decoding. If `enable_vae_slicing` was previously invoked, this method will go back to
+        computing decoding in one step.
+        """
+        self.vae.disable_slicing()
+
+    def enable_sequential_cpu_offload(self, gpu_id=0):
+        r"""
+        Offloads all models to CPU using accelerate, significantly reducing memory usage. When called, the pipeline's
+        models have their state dicts saved to CPU and then are moved to a `torch.device('meta') and loaded to GPU only
+        when their specific submodule has its `forward` method called.
+        """
+        if is_accelerate_available():
+            from accelerate import cpu_offload
+        else:
+            raise ImportError("Please install accelerate via `pip install accelerate`")
+
+        device = torch.device(f"cuda:{gpu_id}")
+
+        # TODO: self.image_normalizer.{scale,unscale} are not covered by the offload hooks, so they fails if added to the list
+        models = [
+            self.image_encoder,
+            self.text_encoder,
+            self.unet,
+            self.vae,
+        ]
+        for cpu_offloaded_model in models:
+            if cpu_offloaded_model is not None:
+                cpu_offload(cpu_offloaded_model, device)
+
+    @property
+    # Copied from diffusers.pipelines.stable_diffusion.pipeline_stable_diffusion.StableDiffusionPipeline._execution_device
+    def _execution_device(self):
+        r"""
+        Returns the device on which the pipeline's models will be executed. After calling
+        `pipeline.enable_sequential_cpu_offload()` the execution device can only be inferred from Accelerate's module
+        hooks.
+        """
+        if not hasattr(self.unet, "_hf_hook"):
+            return self.device
+        for module in self.unet.modules():
+            if (
+                hasattr(module, "_hf_hook")
+                and hasattr(module._hf_hook, "execution_device")
+                and module._hf_hook.execution_device is not None
+            ):
+                return torch.device(module._hf_hook.execution_device)
+        return self.device
+
+    # Copied from diffusers.pipelines.stable_diffusion.pipeline_stable_diffusion.StableDiffusionPipeline._encode_prompt
+    def _encode_prompt(
+        self,
+        prompt,
+        device,
+        num_images_per_prompt,
+        do_classifier_free_guidance,
+        negative_prompt=None,
+        prompt_embeds: Optional[torch.FloatTensor] = None,
+        negative_prompt_embeds: Optional[torch.FloatTensor] = None,
+        lora_scale: Optional[float] = None,
+    ):
+        r"""
+        Encodes the prompt into text encoder hidden states.
+
+        Args:
+             prompt (`str` or `List[str]`, *optional*):
+                prompt to be encoded
+            device: (`torch.device`):
+                torch device
+            num_images_per_prompt (`int`):
+                number of images that should be generated per prompt
+            do_classifier_free_guidance (`bool`):
+                whether to use classifier free guidance or not
+            negative_prompt (`str` or `List[str]`, *optional*):
+                The prompt or prompts not to guide the image generation. If not defined, one has to pass
+                `negative_prompt_embeds`. instead. If not defined, one has to pass `negative_prompt_embeds`. instead.
+                Ignored when not using guidance (i.e., ignored if `guidance_scale` is less than `1`).
+            prompt_embeds (`torch.FloatTensor`, *optional*):
+                Pre-generated text embeddings. Can be used to easily tweak text inputs, *e.g.* prompt weighting. If not
+                provided, text embeddings will be generated from `prompt` input argument.
+            negative_prompt_embeds (`torch.FloatTensor`, *optional*):
+                Pre-generated negative text embeddings. Can be used to easily tweak text inputs, *e.g.* prompt
+                weighting. If not provided, negative_prompt_embeds will be generated from `negative_prompt` input
+                argument.
+        """
+        prompt_embeds = prompt_embeds.to(dtype=self.text_encoder.dtype, device=device)
+
+        if do_classifier_free_guidance:
+            # For classifier free guidance, we need to do two forward passes.
+            # Here we concatenate the unconditional and text embeddings into a single batch
+            # to avoid doing two forward passes
+            # normal_prompt_embeds, color_prompt_embeds = torch.chunk(prompt_embeds, 2, dim=0)
+            color_prompt_embeds = prompt_embeds
+            
+            prompt_embeds = torch.cat([color_prompt_embeds, color_prompt_embeds], 0)
+
+        return prompt_embeds
+
+    def _encode_image(
+        self,
+        image_pil,
+        device,
+        num_images_per_prompt,
+        do_classifier_free_guidance,
+        noise_level: int=0,
+        generator: Optional[torch.Generator] = None
+    ):
+        dtype = next(self.image_encoder.parameters()).dtype
+        # ______________________________clip image embedding______________________________ 
+        image = self.feature_extractor(images=image_pil, return_tensors="pt").pixel_values
+        image = image.to(device=device, dtype=dtype)
+        image_embeds = self.image_encoder(image).image_embeds
+        
+        image_embeds = self.noise_image_embeddings(
+            image_embeds=image_embeds,
+            noise_level=noise_level,
+            generator=generator,
+            )
+        # duplicate image embeddings for each generation per prompt, using mps friendly method
+        # image_embeds = image_embeds.unsqueeze(1)
+        # note: the condition input is same
+        image_embeds = image_embeds.repeat(num_images_per_prompt, 1)
+
+        if do_classifier_free_guidance:
+            # For classifier free guidance, we need to do two forward passes.
+            # Here we concatenate the unconditional and text embeddings into a single batch
+            # to avoid doing two forward passes
+            negative_prompt_embeds = torch.zeros_like(image_embeds)
+            image_embeds = torch.cat([negative_prompt_embeds, image_embeds])
+            
+        # _____________________________vae input latents__________________________________________________
+        image_pt = torch.stack([TF.to_tensor(img) for img in image_pil], dim=0).to(device)
+        image_pt = image_pt * 2.0 - 1.0
+        ###### Fix [RuntimeError: Input type (float) and bias type (c10::Half) should be the same] ######
+        image_pt = image_pt.to(torch.float16)
+        ###### Fix [RuntimeError: Input type (float) and bias type (c10::Half) should be the same] ######
+        image_latents = self.vae.encode(image_pt).latent_dist.mode() * self.vae.config.scaling_factor
+        # Note: repeat differently from official pipelines     
+        image_latents = image_latents.repeat(num_images_per_prompt, 1, 1, 1)
+
+        if do_classifier_free_guidance:
+            image_latents = torch.cat([torch.zeros_like(image_latents), image_latents])
+
+        return image_embeds, image_latents
+
+    # Copied from diffusers.pipelines.stable_diffusion.pipeline_stable_diffusion.StableDiffusionPipeline.decode_latents
+    def decode_latents(self, latents):
+        latents = 1 / self.vae.config.scaling_factor * latents
+        image = self.vae.decode(latents).sample
+        image = (image / 2 + 0.5).clamp(0, 1)
+        # we always cast to float32 as this does not cause significant overhead and is compatible with bfloat16
+        image = image.cpu().permute(0, 2, 3, 1).float().numpy()
+        return image
+
+    # Copied from diffusers.pipelines.stable_diffusion.pipeline_stable_diffusion.StableDiffusionPipeline.prepare_extra_step_kwargs
+    def prepare_extra_step_kwargs(self, generator, eta):
+        # prepare extra kwargs for the scheduler step, since not all schedulers have the same signature
+        # eta (η) is only used with the DDIMScheduler, it will be ignored for other schedulers.
+        # eta corresponds to η in DDIM paper: https://arxiv.org/abs/2010.02502
+        # and should be between [0, 1]
+
+        accepts_eta = "eta" in set(inspect.signature(self.scheduler.step).parameters.keys())
+        extra_step_kwargs = {}
+        if accepts_eta:
+            extra_step_kwargs["eta"] = eta
+
+        # check if the scheduler accepts generator
+        accepts_generator = "generator" in set(inspect.signature(self.scheduler.step).parameters.keys())
+        if accepts_generator:
+            extra_step_kwargs["generator"] = generator
+        return extra_step_kwargs
+
+    def check_inputs(
+        self,
+        prompt,
+        image,
+        height,
+        width,
+        callback_steps,
+        noise_level,
+    ):
+        if height % 8 != 0 or width % 8 != 0:
+            raise ValueError(f"`height` and `width` have to be divisible by 8 but are {height} and {width}.")
+
+        if (callback_steps is None) or (
+            callback_steps is not None and (not isinstance(callback_steps, int) or callback_steps <= 0)
+        ):
+            raise ValueError(
+                f"`callback_steps` has to be a positive integer but is {callback_steps} of type"
+                f" {type(callback_steps)}."
+            )
+
+        if prompt is not None and (not isinstance(prompt, str) and not isinstance(prompt, list)):
+            raise ValueError(f"`prompt` has to be of type `str` or `list` but is {type(prompt)}")
+
+
+        if noise_level < 0 or noise_level >= self.image_noising_scheduler.config.num_train_timesteps:
+            raise ValueError(
+                f"`noise_level` must be between 0 and {self.image_noising_scheduler.config.num_train_timesteps - 1}, inclusive."
+            )
+
+    # Copied from diffusers.pipelines.stable_diffusion.pipeline_stable_diffusion.StableDiffusionPipeline.prepare_latents
+    def prepare_latents(self, batch_size, num_channels_latents, height, width, dtype, device, generator, latents=None):
+        shape = (batch_size, num_channels_latents, height // self.vae_scale_factor, width // self.vae_scale_factor)
+        if isinstance(generator, list) and len(generator) != batch_size:
+            raise ValueError(
+                f"You have passed a list of generators of length {len(generator)}, but requested an effective batch"
+                f" size of {batch_size}. Make sure the batch size matches the length of the generators."
+            )
+
+        if latents is None:
+            latents = randn_tensor(shape, generator=generator, device=device, dtype=dtype)
+        else:
+            latents = latents.to(device)
+
+        # scale the initial noise by the standard deviation required by the scheduler
+        latents = latents * self.scheduler.init_noise_sigma
+        return latents
+
+    # Copied from diffusers.pipelines.stable_diffusion.pipeline_stable_unclip.StableUnCLIPPipeline.noise_image_embeddings
+    def noise_image_embeddings(
+        self,
+        image_embeds: torch.Tensor,
+        noise_level: int,
+        noise: Optional[torch.FloatTensor] = None,
+        generator: Optional[torch.Generator] = None,
+    ):
+        """
+        Add noise to the image embeddings. The amount of noise is controlled by a `noise_level` input. A higher
+        `noise_level` increases the variance in the final un-noised images.
+
+        The noise is applied in two ways
+        1. A noise schedule is applied directly to the embeddings
+        2. A vector of sinusoidal time embeddings are appended to the output.
+
+        In both cases, the amount of noise is controlled by the same `noise_level`.
+
+        The embeddings are normalized before the noise is applied and un-normalized after the noise is applied.
+        """
+        if noise is None:
+            noise = randn_tensor(
+                image_embeds.shape, generator=generator, device=image_embeds.device, dtype=image_embeds.dtype
+            )
+
+        noise_level = torch.tensor([noise_level] * image_embeds.shape[0], device=image_embeds.device)
+
+        image_embeds = self.image_normalizer.scale(image_embeds)
+
+        image_embeds = self.image_noising_scheduler.add_noise(image_embeds, timesteps=noise_level, noise=noise)
+
+        image_embeds = self.image_normalizer.unscale(image_embeds)
+
+        noise_level = get_timestep_embedding(
+            timesteps=noise_level, embedding_dim=image_embeds.shape[-1], flip_sin_to_cos=True, downscale_freq_shift=0
+        )
+
+        # `get_timestep_embeddings` does not contain any weights and will always return f32 tensors,
+        # but we might actually be running in fp16. so we need to cast here.
+        # there might be better ways to encapsulate this.
+        noise_level = noise_level.to(image_embeds.dtype)
+
+        image_embeds = torch.cat((image_embeds, noise_level), 1)
+
+        return image_embeds
+
+    @torch.no_grad()
+    # @replace_example_docstring(EXAMPLE_DOC_STRING)
+    def __call__(
+        self,
+        image: Union[torch.FloatTensor, PIL.Image.Image],
+        prompt: Union[str, List[str]],   
+        prompt_embeds: torch.FloatTensor = None,
+        height: Optional[int] = None,
+        width: Optional[int] = None,
+        num_inference_steps: int = 20,
+        guidance_scale: float = 10,
+        negative_prompt: Optional[Union[str, List[str]]] = None,
+        num_images_per_prompt: Optional[int] = 1,
+        eta: float = 0.0,
+        generator: Optional[torch.Generator] = None,
+        latents: Optional[torch.FloatTensor] = None,
+        negative_prompt_embeds: Optional[torch.FloatTensor] = None,
+        output_type: Optional[str] = "pil",
+        return_dict: bool = True,
+        callback: Optional[Callable[[int, int, torch.FloatTensor], None]] = None,
+        callback_steps: int = 1,
+        cross_attention_kwargs: Optional[Dict[str, Any]] = None,
+        noise_level: int = 0,
+        image_embeds: Optional[torch.FloatTensor] = None,
+        gt_img_in: Optional[torch.FloatTensor] = None,
+    ):
+        r"""
+        Function invoked when calling the pipeline for generation.
+
+        Args:
+            prompt (`str` or `List[str]`, *optional*):
+                The prompt or prompts to guide the image generation. If not defined, one has to pass `prompt_embeds`.
+                instead.
+            image (`torch.FloatTensor` or `PIL.Image.Image`):
+                `Image`, or tensor representing an image batch. The image will be encoded to its CLIP embedding which
+                the unet will be conditioned on. Note that the image is _not_ encoded by the vae and then used as the
+                latents in the denoising process such as in the standard stable diffusion text guided image variation
+                process.
+            height (`int`, *optional*, defaults to self.unet.config.sample_size * self.vae_scale_factor):
+                The height in pixels of the generated image.
+            width (`int`, *optional*, defaults to self.unet.config.sample_size * self.vae_scale_factor):
+                The width in pixels of the generated image.
+            num_inference_steps (`int`, *optional*, defaults to 20):
+                The number of denoising steps. More denoising steps usually lead to a higher quality image at the
+                expense of slower inference.
+            guidance_scale (`float`, *optional*, defaults to 10.0):
+                Guidance scale as defined in [Classifier-Free Diffusion Guidance](https://arxiv.org/abs/2207.12598).
+                `guidance_scale` is defined as `w` of equation 2. of [Imagen
+                Paper](https://arxiv.org/pdf/2205.11487.pdf). Guidance scale is enabled by setting `guidance_scale >
+                1`. Higher guidance scale encourages to generate images that are closely linked to the text `prompt`,
+                usually at the expense of lower image quality.
+            negative_prompt (`str` or `List[str]`, *optional*):
+                The prompt or prompts not to guide the image generation. If not defined, one has to pass
+                `negative_prompt_embeds`. instead. If not defined, one has to pass `negative_prompt_embeds`. instead.
+                Ignored when not using guidance (i.e., ignored if `guidance_scale` is less than `1`).
+            num_images_per_prompt (`int`, *optional*, defaults to 1):
+                The number of images to generate per prompt.
+            eta (`float`, *optional*, defaults to 0.0):
+                Corresponds to parameter eta (η) in the DDIM paper: https://arxiv.org/abs/2010.02502. Only applies to
+                [`schedulers.DDIMScheduler`], will be ignored for others.
+            generator (`torch.Generator` or `List[torch.Generator]`, *optional*):
+                One or a list of [torch generator(s)](https://pytorch.org/docs/stable/generated/torch.Generator.html)
+                to make generation deterministic.
+            latents (`torch.FloatTensor`, *optional*):
+                Pre-generated noisy latents, sampled from a Gaussian distribution, to be used as inputs for image
+                generation. Can be used to tweak the same generation with different prompts. If not provided, a latents
+                tensor will ge generated by sampling using the supplied random `generator`.
+            prompt_embeds (`torch.FloatTensor`, *optional*):
+                Pre-generated text embeddings. Can be used to easily tweak text inputs, *e.g.* prompt weighting. If not
+                provided, text embeddings will be generated from `prompt` input argument.
+            negative_prompt_embeds (`torch.FloatTensor`, *optional*):
+                Pre-generated negative text embeddings. Can be used to easily tweak text inputs, *e.g.* prompt
+                weighting. If not provided, negative_prompt_embeds will be generated from `negative_prompt` input
+                argument.
+            output_type (`str`, *optional*, defaults to `"pil"`):
+                The output format of the generate image. Choose between
+                [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` or `np.array`.
+            return_dict (`bool`, *optional*, defaults to `True`):
+                Whether or not to return a [`~pipelines.stable_diffusion.StableDiffusionPipelineOutput`] instead of a
+                plain tuple.
+            callback (`Callable`, *optional*):
+                A function that will be called every `callback_steps` steps during inference. The function will be
+                called with the following arguments: `callback(step: int, timestep: int, latents: torch.FloatTensor)`.
+            callback_steps (`int`, *optional*, defaults to 1):
+                The frequency at which the `callback` function will be called. If not specified, the callback will be
+                called at every step.
+            cross_attention_kwargs (`dict`, *optional*):
+                A kwargs dictionary that if specified is passed along to the `AttnProcessor` as defined under
+                `self.processor` in
+                [diffusers.cross_attention](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/cross_attention.py).
+            noise_level (`int`, *optional*, defaults to `0`):
+                The amount of noise to add to the image embeddings. A higher `noise_level` increases the variance in
+                the final un-noised images. See `StableUnCLIPPipeline.noise_image_embeddings` for details.
+            image_embeds (`torch.FloatTensor`, *optional*):
+                Pre-generated CLIP embeddings to condition the unet on. Note that these are not latents to be used in
+                the denoising process. If you want to provide pre-generated latents, pass them to `__call__` as
+                `latents`.
+
+        Examples:
+
+        Returns:
+            [`~pipelines.ImagePipelineOutput`] or `tuple`: [`~ pipeline_utils.ImagePipelineOutput`] if `return_dict` is
+            True, otherwise a `tuple`. When returning a tuple, the first element is a list with the generated images.
+        """
+        # 0. Default height and width to unet
+        height = height or self.unet.config.sample_size * self.vae_scale_factor
+        width = width or self.unet.config.sample_size * self.vae_scale_factor
+
+        # 1. Check inputs. Raise error if not correct
+        self.check_inputs(
+            prompt=prompt,
+            image=image,
+            height=height,
+            width=width,
+            callback_steps=callback_steps,
+            noise_level=noise_level
+        )
+
+        # 2. Define call parameters
+        if isinstance(image, list):
+            batch_size = len(image)
+        elif isinstance(image, torch.Tensor):
+            batch_size = image.shape[0]
+            assert batch_size >= self.num_views and batch_size % self.num_views == 0
+        elif isinstance(image, PIL.Image.Image):
+            image = [image]*self.num_views
+            batch_size = self.num_views
+
+        if isinstance(prompt, str):
+            prompt = [prompt] * self.num_views
+
+        device = self._execution_device
+
+        # here `guidance_scale` is defined analog to the guidance weight `w` of equation (2)
+        # of the Imagen paper: https://arxiv.org/pdf/2205.11487.pdf . `guidance_scale = 1`
+        # corresponds to doing no classifier free guidance.
+        do_classifier_free_guidance = guidance_scale != 1.0
+
+        # 3. Encode input prompt
+        text_encoder_lora_scale = (
+            cross_attention_kwargs.get("scale", None) if cross_attention_kwargs is not None else None
+        )
+        prompt_embeds = self._encode_prompt(
+            prompt=prompt,
+            device=device,
+            num_images_per_prompt=num_images_per_prompt,
+            do_classifier_free_guidance=do_classifier_free_guidance,
+            negative_prompt=negative_prompt,
+            prompt_embeds=prompt_embeds,
+            negative_prompt_embeds=negative_prompt_embeds,
+            lora_scale=text_encoder_lora_scale,
+        )
+        
+
+        # 4. Encoder input image
+        if isinstance(image, list):
+            image_pil = image
+        elif isinstance(image, torch.Tensor):
+            image_pil = [TF.to_pil_image(image[i]) for i in range(image.shape[0])]
+        noise_level = torch.tensor([noise_level], device=device)
+        image_embeds, image_latents = self._encode_image(
+            image_pil=image_pil,
+            device=device,
+            num_images_per_prompt=num_images_per_prompt,
+            do_classifier_free_guidance=do_classifier_free_guidance,
+            noise_level=noise_level,
+            generator=generator,
+        )
+
+        # 5. Prepare timesteps
+        self.scheduler.set_timesteps(num_inference_steps, device=device)
+        timesteps = self.scheduler.timesteps
+
+        # 6. Prepare latent variables
+        num_channels_latents = self.unet.config.out_channels
+        if gt_img_in is not None:
+            latents = gt_img_in * self.scheduler.init_noise_sigma
+        else:
+            latents = self.prepare_latents(
+                batch_size=batch_size,
+                num_channels_latents=num_channels_latents,
+                height=height,
+                width=width,
+                dtype=prompt_embeds.dtype,
+                device=device,
+                generator=generator,
+                latents=latents,
+            )
+
+        # 7. Prepare extra step kwargs. TODO: Logic should ideally just be moved out of the pipeline
+        extra_step_kwargs = self.prepare_extra_step_kwargs(generator, eta)
+
+        eles, focals = [], []
+        # 8. Denoising loop
+        for i, t in enumerate(self.progress_bar(timesteps)):
+            if do_classifier_free_guidance:
+                latent_model_input = torch.cat([latents, latents], 0)
+            else:
+                latent_model_input = latents
+            latent_model_input = torch.cat([
+                    latent_model_input, image_latents
+                ], dim=1)
+            latent_model_input = self.scheduler.scale_model_input(latent_model_input, t)
+
+            # predict the noise residual
+            unet_out = self.unet(
+                latent_model_input,
+                t,
+                encoder_hidden_states=prompt_embeds,
+                class_labels=image_embeds,
+                cross_attention_kwargs=cross_attention_kwargs,
+                return_dict=False)
+            
+            noise_pred = unet_out
+                
+            # perform guidance
+            if do_classifier_free_guidance:
+                noise_pred_uncond, noise_pred_text = noise_pred.chunk(2)
+                noise_pred = noise_pred_uncond + guidance_scale * (noise_pred_text - noise_pred_uncond)
+
+            # compute the previous noisy sample x_t -> x_t-1
+            latents = self.scheduler.step(noise_pred, t, latents, **extra_step_kwargs, return_dict=False)[0]
+
+            if callback is not None and i % callback_steps == 0:
+                callback(i, t, latents)
+
+        # 9. Post-processing
+        if not output_type == "latent":
+            if num_channels_latents == 8:
+                latents = torch.cat([latents[:, :4], latents[:, 4:]], dim=0)
+            with torch.no_grad():
+                image = self.vae.decode(latents / self.vae.config.scaling_factor, return_dict=False)[0]
+        else:
+            image = latents
+
+        image = self.image_processor.postprocess(image, output_type=output_type)
+
+        # Offload last model to CPU
+        # if hasattr(self, "final_offload_hook") and self.final_offload_hook is not None:
+        #     self.final_offload_hook.offload()
+        if not return_dict:
+            return (image, )
+        return ImagePipelineOutput(images=image)

requirements.txt

@@ -0,0 +1,36 @@
+# Core dependencies
+torch>=2.0.0
+torchvision>=0.15.0
+numpy>=1.24.0
+pillow>=9.5.0
+
+# Deep learning frameworks
+diffusers>=0.27.0
+transformers>=4.30.0
+accelerate>=0.20.0
+
+# Image processing
+opencv-python>=4.8.0
+rembg>=2.0.50
+facenet-pytorch>=2.5.3
+
+# 3D and rendering
+diff-gaussian-rasterization
+einops>=0.7.0
+plyfile>=0.9
+
+# Utilities
+easydict>=1.10
+pyyaml>=6.0
+lpips>=0.1.4
+huggingface-hub>=0.19.0
+
+# Video processing
+videoio>=0.2.0
+
+# Gradio for UI
+gradio>=5.0.0
+
+# Optional performance
+xformers>=0.0.20
+

utils_folder/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+

utils_folder/face_utils.py

@@ -0,0 +1,240 @@
+# Copyright (C) 2025, FaceLift Research Group
+# https://github.com/weijielyu/FaceLift
+#
+# This software is free for non-commercial, research and evaluation use 
+# under the terms of the LICENSE.md file.
+#
+# For inquiries contact: wlyu3@ucmerced.edu
+
+"""
+Face detection and cropping utilities for 3D face reconstruction.
+
+This module provides functions for face detection, cropping, and preprocessing
+to align faces with training data specifications.
+"""
+
+from typing import Tuple, Optional, Dict, Any
+import numpy as np
+import torch
+from PIL import Image
+from facenet_pytorch import MTCNN
+from rembg import remove
+
+# Training set face parameters (derived from training data statistics)
+TRAINING_SET_FACE_SIZE = 194.2749650813705
+TRAINING_SET_FACE_CENTER = [251.83270369057132, 280.0133630862363]
+
+# Public constants for external use
+FACE_SIZE = TRAINING_SET_FACE_SIZE
+FACE_CENTER = TRAINING_SET_FACE_CENTER
+DEFAULT_BACKGROUND_COLOR = (255, 255, 255)
+DEFAULT_IMG_SIZE = 512
+
+# Device setup
+DEVICE = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+
+# Default face detector instance
+FACE_DETECTOR = MTCNN(
+    image_size=512, 
+    margin=0, 
+    min_face_size=20, 
+    thresholds=[0.6, 0.7, 0.7], 
+    factor=0.709, 
+    post_process=True, 
+    device=DEVICE
+)
+
+def select_face(detected_bounding_boxes: Optional[np.ndarray], confidence_scores: Optional[np.ndarray]) -> Optional[np.ndarray]:
+    """
+    Select the largest face from detected faces with confidence above threshold.
+    
+    Args:
+        detected_bounding_boxes: Detected bounding boxes in xyxy format
+        confidence_scores: Detection confidence probabilities
+        
+    Returns:
+        Selected bounding box or None if no suitable face found
+    """
+    if detected_bounding_boxes is None or confidence_scores is None:
+        return None
+        
+    # Filter faces with confidence > 0.8
+    high_confidence_faces = [
+        detected_bounding_boxes[i] for i in range(len(detected_bounding_boxes)) 
+        if confidence_scores[i] > 0.8
+    ]
+    
+    if not high_confidence_faces:
+        return None
+
+    # Return the largest face (by area)
+    return max(high_confidence_faces, key=lambda bbox: (bbox[3] - bbox[1]) * (bbox[2] - bbox[0]))
+
+def crop_face(
+    input_image_array: np.ndarray, 
+    face_detector: MTCNN = FACE_DETECTOR, 
+    target_face_size: float = FACE_SIZE, 
+    target_face_center: list = FACE_CENTER, 
+    output_image_size: int = 512, 
+    background_color: Tuple[int, int, int] = (255, 255, 255)
+) -> Tuple[Image.Image, Dict[str, Any]]:
+    """
+    Crop and align face in image to match training data specifications.
+    
+    Args:
+        input_image_array: Input image as numpy array (H, W, C)
+        face_detector: MTCNN face detector instance
+        target_face_size: Target face size from training data
+        target_face_center: Target face center from training data
+        output_image_size: Output image size
+        background_color: Background color for padding
+        
+    Returns:
+        Tuple of (cropped_image, crop_parameters)
+        
+    Raises:
+        ValueError: If no face is detected in the image
+    """
+    image_height, image_width, _ = input_image_array.shape
+    
+    # Handle RGBA images by compositing with background color
+    if input_image_array.shape[2] == 4:
+        rgba_pil_image = Image.fromarray(input_image_array)
+        background_image = Image.new("RGB", rgba_pil_image.size, background_color)
+        rgb_composite_image = Image.alpha_composite(background_image.convert("RGBA"), rgba_pil_image).convert("RGB")
+        processed_image_array = np.array(rgb_composite_image)
+    else:
+        processed_image_array = input_image_array[:, :, :3]  # Ensure RGB format
+
+    # Detect and select face
+    detected_bounding_boxes, confidence_scores = face_detector.detect(processed_image_array)
+    selected_face_bbox = select_face(detected_bounding_boxes, confidence_scores)
+    if selected_face_bbox is None:
+        raise ValueError("No face detected in the image")
+
+    # Calculate detected face properties
+    detected_face_size = 0.5 * (selected_face_bbox[2] - selected_face_bbox[0] + selected_face_bbox[3] - selected_face_bbox[1])
+    detected_face_center = (
+        0.5 * (selected_face_bbox[0] + selected_face_bbox[2]), 
+        0.5 * (selected_face_bbox[1] + selected_face_bbox[3])
+    )
+
+    # Scale image to match training face size
+    scale_ratio = target_face_size / detected_face_size
+    scaled_width, scaled_height = int(image_width * scale_ratio), int(image_height * scale_ratio)
+    scaled_pil_image = Image.fromarray(processed_image_array).resize((scaled_width, scaled_height))
+    scaled_face_center = (
+        int(detected_face_center[0] * scale_ratio), 
+        int(detected_face_center[1] * scale_ratio)
+    )
+
+    # Create output image with background
+    output_image = Image.new("RGB", (output_image_size, output_image_size), color=background_color)
+
+    # Calculate alignment offsets
+    horizontal_offset = target_face_center[0] - scaled_face_center[0]
+    vertical_offset = target_face_center[1] - scaled_face_center[1]
+
+    # Calculate crop boundaries
+    crop_left_boundary = int(max(0, -horizontal_offset))
+    crop_top_boundary = int(max(0, -vertical_offset))
+    crop_right_boundary = int(min(scaled_width, output_image_size - horizontal_offset))
+    crop_bottom_boundary = int(min(scaled_height, output_image_size - vertical_offset))
+
+    # Crop and paste
+    cropped_face_image = scaled_pil_image.crop((crop_left_boundary, crop_top_boundary, crop_right_boundary, crop_bottom_boundary))
+    paste_coordinates = (int(max(0, horizontal_offset)), int(max(0, vertical_offset)))
+    output_image.paste(cropped_face_image, paste_coordinates)
+
+    crop_parameters = {
+        'resize_ratio': scale_ratio,
+        'x_offset_left': horizontal_offset,
+        'y_offset_top': vertical_offset,
+    }
+
+    return output_image, crop_parameters
+
+def prepare_foreground_with_rembg(input_image_array: np.ndarray) -> np.ndarray:
+    """
+    Prepare foreground image using rembg for background removal.
+    
+    Args:
+        input_image_array: Input image as numpy array (H, W, C)
+        
+    Returns:
+        RGBA image as numpy array with background removed
+    """
+    pil_image = Image.fromarray(input_image_array)
+    background_removed_image = remove(pil_image)
+    processed_image_array = np.array(background_removed_image)
+    
+    # Ensure RGBA format
+    if processed_image_array.shape[2] == 4:
+        return processed_image_array
+    elif processed_image_array.shape[2] == 3:
+        height, width = processed_image_array.shape[:2]
+        alpha_channel = np.full((height, width), 255, dtype=np.uint8)
+        rgba_image = np.zeros((height, width, 4), dtype=np.uint8)
+        rgba_image[:, :, :3] = processed_image_array
+        rgba_image[:, :, 3] = alpha_channel
+        return rgba_image
+    
+    return processed_image_array
+
+def preprocess_image(
+    original_image_array: np.ndarray, 
+    target_image_size: int = DEFAULT_IMG_SIZE, 
+    background_color: Tuple[int, int, int] = DEFAULT_BACKGROUND_COLOR
+) -> Image.Image:
+    """
+    Preprocess image with background removal and face cropping.
+    
+    Args:
+        original_image_array: Input image as numpy array
+        target_image_size: Target image size
+        background_color: Background color for compositing
+        
+    Returns:
+        Processed PIL Image
+    """
+    processed_image_array = prepare_foreground_with_rembg(original_image_array)
+    
+    # Convert RGBA to RGB with specified background
+    if processed_image_array.shape[2] == 4:
+        rgba_pil_image = Image.fromarray(processed_image_array)
+        background_image = Image.new("RGB", rgba_pil_image.size, background_color)
+        rgb_composite_image = Image.alpha_composite(background_image.convert("RGBA"), rgba_pil_image).convert("RGB")
+        processed_image_array = np.array(rgb_composite_image)
+    
+    cropped_image, crop_parameters = crop_face(
+        processed_image_array,
+        FACE_DETECTOR,
+        FACE_SIZE, 
+        FACE_CENTER,
+        target_image_size, 
+        background_color
+    )
+    return cropped_image
+
+def preprocess_image_without_cropping(
+    original_image_array: np.ndarray, 
+    target_image_size: int = DEFAULT_IMG_SIZE, 
+    background_color: Tuple[int, int, int] = DEFAULT_BACKGROUND_COLOR
+) -> Image.Image:
+    """
+    Preprocess image with background removal, without face cropping.
+    
+    Args:
+        original_image_array: Input image as numpy array
+        target_image_size: Target image size
+        background_color: Background color for compositing
+        
+    Returns:
+        Processed PIL Image
+    """
+    processed_image_array = prepare_foreground_with_rembg(original_image_array)
+    
+    resized_image = Image.fromarray(processed_image_array).resize((target_image_size, target_image_size))
+    background_image = Image.new("RGBA", (target_image_size, target_image_size), background_color)
+    composite_image = Image.alpha_composite(background_image, resized_image).convert("RGB")
+    return composite_image

utils_folder/opencv_cameras.json

@@ -0,0 +1,245 @@
+{
+    "id": "sample_000",
+    "frames": [
+        {
+            "w": 512,
+            "h": 512,
+            "fx": 548.9937744140625,
+            "fy": 548.9937744140625,
+            "cx": 256.0,
+            "cy": 256.0,
+            "w2c": [
+                [
+                    7.549789865864094e-08,
+                    -0.9999999999999908,
+                    5.960464618088506e-08,
+                    2.0384433030900552e-07
+                ],
+                [
+                    -7.549789676401702e-08,
+                    -5.960465047532283e-08,
+                    -0.9999999999999908,
+                    -2.0384432486286618e-07
+                ],
+                [
+                    0.9999999999999885,
+                    7.549789676401702e-08,
+                    -7.549789865864095e-08,
+                    2.7000000476836847
+                ],
+                [
+                    0.0,
+                    0.0,
+                    0.0,
+                    1.0
+                ]
+            ],
+            "blender_camera_name": "lrm_cam.000",
+            "blender_camera_location": [
+                -2.7,
+                3.3065463576978537e-16,
+                0.0
+            ]
+        },
+        {
+            "w": 512,
+            "h": 512,
+            "fx": 548.9937744140625,
+            "fy": 548.9937744140625,
+            "cx": 256.0,
+            "cy": 256.0,
+            "w2c": [
+                [
+                    0.7071067932881387,
+                    -0.7071067336835127,
+                    -1.4907362623459278e-07,
+                    1.137964524414734e-07
+                ],
+                [
+                    -1.5879604949837492e-07,
+                    5.202588738731513e-08,
+                    -0.999999999999972,
+                    -2.0384434114916973e-07
+                ],
+                [
+                    0.7071067336835085,
+                    0.7071067932881663,
+                    -7.549790026365632e-08,
+                    2.6999998777741223
+                ],
+                [
+                    0.0,
+                    0.0,
+                    0.0,
+                    1.0
+                ]
+            ],
+            "blender_camera_name": "lrm_cam.001",
+            "blender_camera_location": [
+                -1.9091883092036788,
+                -1.9091883092036783,
+                0.0
+            ]
+        },
+        {
+            "w": 512,
+            "h": 512,
+            "fx": 548.9937744140625,
+            "fy": 548.9937744140625,
+            "cx": 256.0,
+            "cy": 256.0,
+            "w2c": [
+                [
+                    1.0,
+                    -1.8369704112266414e-16,
+                    -1.8716961953007326e-23,
+                    -7.758078222293693e-23
+                ],
+                [
+                    -1.0687309218630199e-23,
+                    4.371138828673784e-08,
+                    -0.9999999999999981,
+                    1.1802075045851359e-07
+                ],
+                [
+                    1.8369704112266542e-16,
+                    0.999999999999998,
+                    4.371138828673784e-08,
+                    2.7000000476837105
+                ],
+                [
+                    0.0,
+                    0.0,
+                    0.0,
+                    1.0
+                ]
+            ],
+            "blender_camera_name": "lrm_cam.002",
+            "blender_camera_location": [
+                -4.959819536546781e-16,
+                -2.7,
+                0.0
+            ]
+        },
+        {
+            "w": 512,
+            "h": 512,
+            "fx": 548.9937744140625,
+            "fy": 548.9937744140625,
+            "cx": 256.0,
+            "cy": 256.0,
+            "w2c": [
+                [
+                    0.7071067932881387,
+                    0.7071067336835127,
+                    1.4907362623459278e-07,
+                    -1.137964524414734e-07
+                ],
+                [
+                    1.5879604949837492e-07,
+                    5.202588738731513e-08,
+                    -0.999999999999972,
+                    -2.0384434114916973e-07
+                ],
+                [
+                    -0.7071067336835085,
+                    0.7071067932881663,
+                    -7.549790026365632e-08,
+                    2.6999998777741223
+                ],
+                [
+                    0.0,
+                    0.0,
+                    0.0,
+                    1.0
+                ]
+            ],
+            "blender_camera_name": "lrm_cam.003",
+            "blender_camera_location": [
+                1.9091883092036779,
+                -1.9091883092036788,
+                0.0
+            ]
+        },
+        {
+            "w": 512,
+            "h": 512,
+            "fx": 548.9937744140625,
+            "fy": 548.9937744140625,
+            "cx": 256.0,
+            "cy": 256.0,
+            "w2c": [
+                [
+                    7.549790126404288e-08,
+                    0.9999999999999943,
+                    2.1254750082671866e-22,
+                    -2.0384433701293624e-07
+                ],
+                [
+                    7.549790126404245e-08,
+                    -5.699933095275168e-15,
+                    -0.9999999999999943,
+                    -2.0384433701293508e-07
+                ],
+                [
+                    -0.9999999999999885,
+                    7.549790126404245e-08,
+                    -7.549790126404288e-08,
+                    2.7000000476836847
+                ],
+                [
+                    0.0,
+                    0.0,
+                    0.0,
+                    1.0
+                ]
+            ],
+            "blender_camera_name": "lrm_cam.004",
+            "blender_camera_location": [
+                2.7,
+                0.0,
+                0.0
+            ]
+        },
+        {
+            "w": 512,
+            "h": 512,
+            "fx": 548.9937744140625,
+            "fy": 548.9937744140625,
+            "cx": 256.0,
+            "cy": 256.0,
+            "w2c": [
+                [
+                    -0.9999999999999847,
+                    -8.74227798575314e-08,
+                    8.742276618399183e-08,
+                    2.360415099493051e-07
+                ],
+                [
+                    -8.742276564667607e-08,
+                    -4.371139592947904e-08,
+                    -0.9999999999999906,
+                    1.1802077109391521e-07
+                ],
+                [
+                    8.742278039484591e-08,
+                    -0.9999999999999905,
+                    4.3711391302137594e-08,
+                    2.70000004768369
+                ],
+                [
+                    0.0,
+                    0.0,
+                    0.0,
+                    1.0
+                ]
+            ],
+            "blender_camera_name": "lrm_cam.005",
+            "blender_camera_location": [
+                1.6532731788489269e-16,
+                2.7,
+                0.0
+            ]
+        }
+    ]
+}