扩散模型作为着色器：用于多功能视频生成控制的3D感知视频扩散模型

       

最新消息：

• 2025年6月5日：我们发布了用于创建合成数据集的脚本和Blender项目。

• 2025年6月2日：我们在Wanfun分支中添加了基于Wan2.1Fun 1.3B微调的推理代码。

• 2025年4月2日：基于VGGT新增了对视频复杂且精确的相机控制功能。可通过调整--override_extrinsics超参数来追加或覆盖视频中的相机运动。

• 2025年4月1日：增加了对cotracker的支持。

• 2025年2月17日：我们已将验证数据集上传至Google Drive，其中包含4个任务。

快速入门

创建环境

1. 克隆仓库并创建conda环境：

   git clone https://github.com/IGL-HKUST/DiffusionAsShader.git
   conda create -n das python=3.10
   conda activate das
   

2. 安装PyTorch，推荐使用PyTorch 2.5.1与CUDA 11.8：

   pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu118
   

3. 确保子模块和依赖项已安装：

   mkdir -p submodules
   git submodule update --init --recursive
   pip install -r requirements.txt
   

   如果子模块未安装，需手动下载并将它们移动到submodules/目录下。运行以下命令以安装子模块：

   # MoGe
   git clone https://github.com/microsoft/MoGe.git submodules/MoGe
   # VGGT
   git clone https://github.com/facebookresearch/vggt.git submodules/vggt
   

4. 手动将以下检查点下载至checkpoints/目录：

   • SpatialTracker检查点：Google Drive。
   • 我们的扩散模型作为着色器检查点：https://huggingface.co/EXCAI/Diffusion-As-Shader

推理

推理代码已在以下环境中测试通过：

• Ubuntu 20.04
• Python 3.10
• PyTorch 2.5.1
• 1块配备CUDA 11.8的NVIDIA H800显卡。（32GB显存足以使用我们的代码生成视频。）

我们提供了针对各项任务的推理脚本。您可以直接运行demo.py脚本，如下所示。 我们还在Google Drive上提供了一个验证数据集，用于我们的4个任务。您可以通过运行scripts/evaluate_DaS.sh来评估模型性能。

我们还发布了针对各项任务的Gradio界面。您可以直接运行webui.py脚本，如下所示。

python webui.py --gpu <gpu_id>

或者您也可以逐个运行这些任务，如下所示。

1. 运动迁移

原始	物体替换	风格迁移
原始	角色替换1	角色替换2

（以上结果必须在FLUX.1 Kontext的协助下生成。）

---

python demo.py \
    --prompt <"prompt text"> \ # 提示词
    --checkpoint_path <model_path> \ # 检查点路径（例如 checkpoints/Diffusion-As-Shader）
    --output_dir <output_dir> \ # 输出目录
    --input_path <input_path> \ # 参考视频路径
    --repaint < True/repaint_path > \ # 输入源视频的第一帧重绘图像路径，或使用FLUX重绘第一帧
    --gpu <gpu_id> \ # GPU ID

2. 相机控制

弧形右移 + 缩放出	弧形左移 + 缩放出	弧形上移 + 缩放出
左移 + 左偏航	静止	缩放出

我们提供了几种模板化的相机运动类型，您可以从中选择一种。实践中发现，在提示词中详细描述相机运动可以获得更好的效果。

python demo.py \
    --prompt <"prompt text"> \ # 提示词
    --checkpoint_path <model_path> \ # 检查点路径（例如 checkpoints/Diffusion-As-Shader）
    --output_dir <output_dir> \ # 输出目录
    --input_path <input_path> \ # 参考图像或视频路径
    --camera_motion <camera_motion> \ # 相机运动类型，见下方示例
    --tracking_method <tracking_method> \ # 跟踪方法（moge、spatracker、cotracker）。对于图像输入，'moge'是必需的。
    --override_extrinsics <override/append> \ # 如何应用相机运动："override"表示替换原有相机运动，"append"表示在其基础上叠加
    --gpu <gpu_id> \ # GPU ID

以下是关于摄像机动画的一些提示：

• trans：平移动画，摄像机会沿着向量（dx, dy, dz）的方向移动，范围为[-1, 1]。
  • X轴正方向：向左移动；X轴负方向：向右移动。
  • Y轴正方向：向下移动；Y轴负方向：向上移动。
  • Z轴正方向：拉近镜头；Z轴负方向：推远镜头。
  • 例如，“trans -0.1 -0.1 -0.1”表示从当前帧开始向右、向下并拉近镜头。
  • 例如，“trans -0.1 0.0 0.0 5 45”表示从第5帧到第45帧，摄像机沿X轴负方向移动0.1个单位。
• rot：旋转动画，摄像机会绕着（x, y, z）轴旋转指定的角度。
  • X轴旋转：X轴正方向：俯仰向下；X轴负方向：俯仰向上。
  • Y轴旋转：Y轴正方向：偏航向左；Y轴负方向：偏航向右。
  • Z轴旋转：Z轴正方向：逆时针滚转；Z轴负方向：顺时针滚转。
  • 例如，“rot y 25”表示绕Y轴旋转25度（即向左偏航）。
  • 例如，“rot x -30 10 40”表示从第10帧到第40帧，摄像机绕X轴旋转-30度（即向上俯仰）。
• spiral：螺旋动画，摄像机会沿着给定半径的螺旋路径移动。
  • 例如，“spiral 2”表示半径为2的螺旋运动。
  • 例如，“spiral 2 15 35”表示从第15帧到第35帧，摄像机以半径2进行螺旋运动。

多个变换可以通过分号（;）分隔来组合使用：

• 例如，“trans 0 0 -0.5 0 30; rot x -25 0 30; trans -0.1 0 0 30 48” 这将：
  1. 从第0帧到第30帧拉近镜头（z=-0.5）；
  2. 从第0帧到第30帧绕X轴旋转-25度（即向上俯仰）；
  3. 从第30帧到第48帧沿X轴负方向移动0.1个单位。

注意事项：

• 帧数范围为0至48（共49帧）。
• 如果未指定起始帧和结束帧，则动画将应用于所有帧（0至48）。
• 结束帧之后的帧将保持最后的变换状态。
• 对于组合变换，它们会按顺序依次应用。

3. 物体操控

向左移动	向上移动	旋转

我们提供了几种模板化的物体操控类型，您可以从中选择一种。在实践中，我们发现，在提示词中详细描述物体的运动效果会更好。

python demo.py \
    --prompt <"prompt text"> \ # 提示词文本
    --checkpoint_path <model_path> \ # 模型检查点路径（例如 checkpoints/Diffusion-As-Shader）
    --output_dir <output_dir> \ # 输出目录
    --input_path <input_path> \ # 参考图像路径
    --object_motion <object_motion> \ # 物体运动类型（上、下、左、右）
    --object_mask <object_mask_path> \ # 物体掩码路径
    --tracking_method <tracking_method> \ # 跟踪方法（moge、spatracker）。对于图像输入，必须使用“moge”。
    --gpu <gpu_id> \ # GPU编号

或者，您也可以按照以下方式自定义物体运动和摄像机动画，并替换demo.py中的相关代码：

1. 物体运动

   dict: 包含以下内容的运动字典：
     - mask (torch.Tensor): 用于选定物体的二值掩码
     - motions (torch.Tensor): 每帧的运动向量 [49, 4, 4]（49帧，每帧4×4齐次变换矩阵）
   

2. 摄像机动画

   list: 包含以下内容的CameraMotion列表：
     - camera_motion (list): 每帧的摄像机位姿矩阵 [49, 4, 4]（49帧，每帧4×4齐次变换矩阵）
   

需要注意的是，根据您选择的跟踪器，可能需要调整平移的缩放比例。

4. 将网格动画转换为视频

目前我们仅支持使用Blender（版本>4.0）生成跟踪视频。在运行以下命令之前，您需要安装Blender，并在您的Blender项目中运行脚本scripts/blender.py，为您的项目生成跟踪视频。然后，您需要将跟踪视频路径提供给tracking_path参数：

python demo.py \
    --prompt <"prompt text"> \ # 提示词文本
    --checkpoint_path <model_path> \ # 检查点路径（例如 checkpoints/Diffusion-As-Shader）
    --output_dir <output_dir> \ # 输出目录
    --input_path <input_path> \ # 参考视频路径
    --tracking_path <tracking_path> \ # 跟踪视频路径（需由Blender生成）
    --repaint < True/repaint_path > \ # 输入网格视频的第一帧渲染图像，或使用FLUX重新绘制第一帧
    --gpu <gpu_id> \ # GPU编号

微调Diffusion作为着色器

准备数据集

在开始训练之前，请检查数据集是否已按照数据集规范准备妥当。

简而言之，您的数据集结构应如下所示。运行tree命令后，您应该看到：

dataset
├── prompt.txt
├── videos.txt
├── trackings.txt

├── tracking
    ├── tracking/00000_tracking.mp4
    ├── tracking/00001_tracking.mp4
    ├── ...

├── videos
    ├── videos/00000.mp4
    ├── videos/00001.mp4
    ├── ...

训练

可以使用 scripts/train_image_to_video_sft.sh 脚本开始训练。

• 根据需要配置环境变量：

  export TORCH_LOGS="+dynamo,recompiles,graph_breaks"
  export TORCHDYNAMO_VERBOSE=1
  export WANDB_MODE="offline"
  export NCCL_P2P_DISABLE=1
  export TORCH_NCCL_ENABLE_MONITORING=0
  

• 配置用于训练的 GPU：GPU_IDS="0,1"

• 选择训练的超参数。以下以学习率和优化器类型为例进行网格搜索：

  LEARNING_RATES=("1e-4" "1e-3")
  LR_SCHEDULES=("cosine_with_restarts")
  OPTIMIZERS=("adamw" "adam")
  MAX_TRAIN_STEPS=("2000")
  

• 选择要使用的 Accelerate 配置文件：ACCELERATE_CONFIG_FILE="accelerate_configs/uncompiled_1.yaml"。我们在 accelerate_configs/ 目录中提供了一些默认配置，包括单 GPU 的未编译/已编译版本、2x GPU DDP、DeepSpeed 等。您也可以使用 accelerate config --config_file my_config.yaml 创建自定义配置文件。

• 指定字幕和视频的绝对路径及对应的列或文件。

  DATA_ROOT="../datasets/cogshader"
  CAPTION_COLUMN="prompt.txt"
  VIDEO_COLUMN="videos.txt"
  TRACKING_COLUMN="trackings.txt"
  

• 启动不同超参数组合的实验：

  # 训练数据集参数
  DATA_ROOT="../datasets/cogshader"
  MODEL_PATH="../ckpts/CogVideoX-5b-I2V"
  CAPTION_COLUMN="prompt.txt"
  VIDEO_COLUMN="videos.txt"
  TRACKING_COLUMN="trackings.txt"
  
  # 验证参数
  TRACKING_MAP_PATH="../eval/3d/tracking/dance_tracking.mp4"
  VALIDATION_PROMPT="text"
  VALIDATION_IMAGES="../000000046_0.png"
  
  for learning_rate in "${LEARNING_RATES[@]}"; do
    for lr_schedule in "${LR_SCHEDULES[@]}"; do
      for optimizer in "${OPTIMIZERS[@]}"; do
        for steps in "${MAX_TRAIN_STEPS[@]}"; do
          output_dir="/aifs4su/mmcode/lipeng/cogvideo/ckpts/cogshader_inv-avatar-physics_steps_${steps}__optimizer_${optimizer}__lr-schedule_${lr_schedule}__learning-rate_${learning_rate}/"
  
          cmd="accelerate launch --config_file $ACCELERATE_CONFIG_FILE --gpu_ids $GPU_IDS --num_processes $NUM_PROCESSES --main_process_port $PORT training/cogvideox_image_to_video_sft.py \
            --pretrained_model_name_or_path $MODEL_PATH \
            --data_root $DATA_ROOT \
            --caption_column $CAPTION_COLUMN \
            --video_column $VIDEO_COLUMN \
            --tracking_column $TRACKING_COLUMN \
            --tracking_map_path $TRACKING_MAP_PATH \
            --num_tracking_blocks 18 \
            --height_buckets 480 \
            --width_buckets 720 \
            --frame_buckets 49 \
            --dataloader_num_workers 8 \
            --pin_memory \
            --validation_prompt $VALIDATION_PROMPT \
            --validation_images $VALIDATION_IMAGES \
            --validation_prompt_separator ::: \
            --num_validation_videos 1 \
            --validation_epochs 1 \
            --seed 42 \
            --mixed_precision bf16 \
            --output_dir $output_dir \
            --max_num_frames 49 \
            --train_batch_size $TRAIN_BATCH_SIZE \
            --max_train_steps $steps \
            --checkpointing_steps $CHECKPOINT_STEPS \
            --gradient_accumulation_steps 4 \
            --gradient_checkpointing \
            --learning_rate $learning_rate \
            --lr_scheduler $lr_schedule \
            --lr_warmup_steps $WARMUP_STEPS \
            --lr_num_cycles 1 \
            --enable_slicing \
            --enable_tiling \
            --optimizer $optimizer \
            --beta1 0.9 \
            --beta2 0.95 \
            --weight_decay 0.001 \
            --noised_image_dropout 0.05 \
            --max_grad_norm 1.0 \
            --allow_tf32 \
            --report_to wandb \
            --resume_from_checkpoint \"latest\" \
            --nccl_timeout 1800"
          
          echo "正在运行命令: $cmd"
          eval $cmd
          echo -ne "-------------------- 脚本执行完毕 --------------------\n\n"
        done
      done
    done
  done
  

  要了解各个参数的具体含义，您可以查看 args 文件，或者在运行训练脚本时添加 --help 参数。

致谢

本项目基于多个优秀的开源项目：

• CogVideo - 清华大学开发的大规模视频生成模型，为本项目提供了基础架构。

• finetrainers - 提供高效的视频模型训练脚本，帮助我们优化了训练流程。

• SpaTracker - 提供出色的 2D 像素到 3D 空间跟踪能力，支持我们的运动控制功能。

• MoGe - 微软的单目几何估计模型，有助于实现更精确的 3D 重建。

• vggt - Facebook 的视频生成模型，为本项目提供了基础架构。

我们感谢这些项目的作者和贡献者对开源社区所做的宝贵贡献！

引用

如果您觉得这项工作对您的研究有帮助，请考虑引用：

@article{gu2025das,
    title={Diffusion as Shader: 3D-aware Video Diffusion for Versatile Video Generation Control}, 
    author={Zekai Gu and Rui Yan and Jiahao Lu and Peng Li and Zhiyang Dou and Chenyang Si and Zhen Dong and Qifeng Liu and Cheng Lin and Ziwei Liu and Wenping Wang and Yuan Liu},
    year={2025},
    journal={arXiv preprint arXiv:2501.03847}
}

DiffusionAsShader 快速上手指南

DiffusionAsShader 是一个具备 3D 感知能力的视频扩散模型，支持运动迁移、精确相机控制、物体操控以及网格动画生成等多种任务。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Ubuntu 20.04 (推荐)
• Python 版本: 3.10
• GPU: NVIDIA 显卡 (推荐 H800 或同等算力)，显存至少 32GB
• CUDA 版本: 11.8
• PyTorch 版本: 2.5.1
• 其他软件: Blender 4.0+ (仅用于“网格转视频”任务)

2. 安装步骤

2.1 克隆仓库与创建环境

git clone https://github.com/IGL-HKUST/DiffusionAsShader.git
cd DiffusionAsShader
conda create -n das python=3.10
conda activate das

2.2 安装 PyTorch

推荐使用官方源安装适配 CUDA 11.8 的 PyTorch 2.5.1：

pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu118

(注：国内用户若下载缓慢，可尝试使用清华源或阿里源镜像，但需确保版本严格匹配)

2.3 安装子模块与依赖

初始化子模块并安装 Python 依赖：

mkdir -p submodules
git submodule update --init --recursive
pip install -r requirements.txt

注意：如果自动拉取子模块失败，请手动执行以下命令下载并放入 submodules/ 目录：

# MoGe
git clone https://github.com/microsoft/MoGe.git submodules/MoGe
# VGGT
git clone https://github.com/facebookresearch/vggt.git submodules/vggt

2.4 下载模型权重

请手动下载以下检查点文件并放置于项目根目录的 checkpoints/ 文件夹中：

1. SpatialTracker 检查点: Google Drive 下载链接
2. Diffusion as Shader 主模型: HuggingFace 下载链接

目录结构应如下所示：

checkpoints/
├── Diffusion-As-Shader/
└── [SpatialTracker 相关文件]

3. 基本使用

本项目提供了 WebUI 界面和命令行脚本两种使用方式。

3.1 启动 WebUI (推荐)

最快捷的方式是启动 Gradio 界面进行交互式操作：

python webui.py --gpu <gpu_id>

将 <gpu_id> 替换为您的显卡编号（例如 0）。启动后在浏览器访问显示的本地地址即可。

3.2 命令行推理示例

您也可以通过 demo.py 直接运行特定任务。以下是运动迁移 (Motion Transfer) 的最简示例：

python demo.py \
    --prompt "a rocket flying in the sky" \
    --checkpoint_path checkpoints/Diffusion-As-Shader \
    --output_dir outputs \
    --input_path assets/videos/rocket1.mp4 \
    --repaint True \
    --gpu 0

参数说明：

• --prompt: 生成视频的描述提示词。
• --input_path: 参考视频或图片的路径。
• --repaint: 设置为 True 使用 FLUX 重绘首帧，或指定重绘图片的路径。
• --camera_motion: (可选) 用于相机控制任务，如 "trans -0.1 -0.1 -0.1"。
• --tracking_method: 跟踪方法，图片输入建议使用 moge，视频可用 spatracker 或 cotracker。

3.3 高级功能简述

• 相机控制: 通过 --camera_motion 参数定义平移 (trans)、旋转 (rot) 或螺旋 (spiral) 运动。支持组合指令，例如 "trans 0 0 -0.5 0 30; rot x -25 0 30"。
• 物体操控: 需提供物体掩码 (--object_mask) 和运动方向 (--object_motion)。
• 网格动画: 需先使用 Blender 运行 scripts/blender.py 生成跟踪视频，并通过 --tracking_path 传入。

更多详细参数配置请参考项目源码中的 demo.py 或官方文档。