Instructions to use JiayiWuLeo/Real2SAM2Real with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Diffusers
How to use JiayiWuLeo/Real2SAM2Real with Diffusers:
pip install -U diffusers transformers accelerate
import torch from diffusers import DiffusionPipeline from diffusers.utils import load_image, export_to_video # switch to "mps" for apple devices pipe = DiffusionPipeline.from_pretrained("JiayiWuLeo/Real2SAM2Real", torch_dtype=torch.bfloat16, device_map="cuda") pipe.to("cuda") prompt = "A man with short gray hair plays a red electric guitar." image = load_image( "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/guitar-man.png" ) output = pipe(image=image, prompt=prompt).frames[0] export_to_video(output, "output.mp4") - Notebooks
- Google Colab
- Kaggle
Real2SAM2Real: Generative 3D Caches as Complementary Context for Video Diffusion
Jiayi Wu*, Haoming Cai*, Cornelia Fermuller, Christopher Metzler, Yiannis Aloimonos
University of Maryland, College Park Β· *Equal contribution
TL;DR
Real2SAM2Real is a 3D-aware video generation framework that integrates a generative 3D cache to provide video diffusion models (VDMs) with instance-complete geometric guidance. This enables precise, decoupled control over both camera trajectories and multi-entity motions, preventing structural collapse under complex camera shifts and severe occlusions. By fully decoupling geometry and appearance conditions, it remains robust even for non-Lambertian surfaces, fluids, and other complex phenomena.
Overview
Real2SAM2Real is a 3D controllable video generation framework featuring an explicitly editable 3D cache that enables precise control over both cameras and scenes. Existing methods predominantly rely on implicit diffusion priors to generate unobserved regions, which often leads to structural collapse during high-dynamic movements or complex occlusions. Our framework leverages 3D lifting models (e.g., SAM3D) to extract an explicitly editable 3D cache that serves as a robust geometric scaffold for the VDM. By capturing the entire 3D volume of foreground entities rather than just their visible shells, this cache injects holistic spatial priors into the VDM and provides dependable 3D-aware guidance for complex scene dynamics.
To effectively leverage this 3D guidance while preserving pre-trained priors, we design a Soft Spatial-Aligned Injection mechanism together with a minimally invasive fine-tuning strategy tailored for VDMs. We further employ masked normal maps as a cross-modal bridge to construct a 3D-free data curation and perturbation pipeline. Extensive experiments show that Real2SAM2Real enables precise, decoupled control over camera trajectories and multi-entity motions, maintains spatiotemporal consistency under large camera shifts and severe occlusions, and eliminates perspective ambiguities caused by structural holes, erroneous facades, reflections, and refractions.
Model Files
This repository contains the inference checkpoint used to reproduce the results shown on the project page.
checkpoint-infer/
βββ lora_diffusion_pytorch_model.safetensors # LoRA weights (diffusers)
βββ lora_diffusion_pytorch_model_compatible_with_comfyui.safetensors # LoRA weights (ComfyUI-compatible)
βββ pose_patch_embedding.safetensors # Pose patch embedding module
Refer to the code repository for loading and inference instructions.
Citation
@article{wu2025real2sam2real,
title = {Real2SAM2Real: Generative 3D Caches as Complementary Context for Video Diffusion},
author = {Wu, Jiayi and Cai, Haoming and Fermuller, Cornelia and Metzler, Christopher and Aloimonos, Yiannis},
journal = {arXiv preprint arXiv:2606.00299},
year = {2025}
}
- Downloads last month
- -
