首页/资讯中心/详情

Cosmos-Transfer1-DiffusionRenderer API参考：核心模块与函数详细文档

Cosmos-Transfer1-DiffusionRenderer API参考：核心模块与函数详细文档
📅 发布时间：2026/7/4 21:40:31

Cosmos-Transfer1-DiffusionRenderer API参考：核心模块与函数详细文档

【免费下载链接】cosmos-transfer1-diffusion-rendererCosmos-Transfer1-DiffusionRenderer: High-quality video de-lighting and re-lighting based on Cosmos video diffusion framework项目地址: https://gitcode.com/gh_mirrors/co/cosmos-transfer1-diffusion-renderer

Cosmos-Transfer1-DiffusionRenderer是一个基于NVIDIA Cosmos世界基础模型的高质量视频去光照和重光照框架。这个强大的AI工具能够对输入图像或视频进行可控的照明操作、编辑和合成数据增强，为物理AI系统提供在不同光照条件下训练感知和策略模型的鲁棒性。🚀

在这份完整的API参考指南中，我将详细介绍核心模块、关键函数以及如何使用这个强大的扩散渲染器框架。无论你是初学者还是经验丰富的开发者，这份文档都将帮助你快速上手并充分利用Cosmos-Transfer1-DiffusionRenderer的功能。

🎯 核心架构概览

Cosmos-Transfer1-DiffusionRenderer采用模块化设计，主要分为两个核心组件：

  1. 逆渲染器（Inverse Renderer）- 从RGB图像/视频中提取G-buffer（几何缓冲区）
  2. 前向渲染器（Forward Renderer）- 使用G-buffer和环境光照生成重光照结果

图：扩散渲染器的完整工作流程，从输入图像到G-buffer提取再到重光照输出

📦 主要模块API参考

DiffusionRendererPipeline 类

这是整个框架的入口点，位于cosmos_predict1/diffusion/inference/diffusion_renderer_pipeline.py。

构造函数参数
def __init__( checkpoint_dir: str, checkpoint_name: str, prompt_upsampler_dir: Optional[str] = None, enable_prompt_upsampler: bool = False, has_text_input: bool = False, offload_network: bool = False, offload_tokenizer: bool = False, offload_text_encoder_model: bool = False, offload_prompt_upsampler: bool = False, offload_guardrail_models: bool = False, disable_guardrail: bool = True, guidance: float = 0.0, num_steps: int = 15, height: int = 704, width: int = 1280, fps: int = 24, num_video_frames: int = 57, seed: int = 1000, ):

关键参数说明：

  • checkpoint_dir：模型检查点目录路径
  • checkpoint_name：模型变体名称（如"Diffusion_Renderer_Inverse_Cosmos_7B"）
  • offload_network：是否卸载网络以减少GPU内存使用
  • num_steps：扩散采样步数（默认15步）
  • height/width：输出分辨率（默认1280x704）
generate_video 方法
def generate_video( self, data_batch: Dict[str, torch.Tensor], normalize_normal: bool = False, seed: int = None, ) -> np.ndarray:

功能：从输入视频/图像生成G-buffer映射

参数：

  • data_batch：包含输入数据的字典
  • normalize_normal：是否对法线图进行归一化处理
  • seed：随机种子

返回值：形状为[T, H, W, C]的uint8 numpy数组

图：逆渲染器生成的G-buffer输出，包括基础颜色、法线、深度等

DiffusionRendererModel 类

核心模型类位于cosmos_predict1/diffusion/model/model_diffusion_renderer.py。

prepare_diffusion_renderer_latent_conditions 方法
def prepare_diffusion_renderer_latent_conditions( self, data_batch: dict[str, Tensor], condition_keys: list[str] = ["rgb"], condition_drop_rate: float = 0, append_condition_mask: bool = True, dtype: torch.dtype = None, device: torch.device = None, latent_shape: Union[Tuple[int, int, int, int, int], torch.Size] = None, mode="train", ) -> Tensor:

功能：准备扩散渲染器的潜在条件张量

参数：

  • condition_keys：条件键列表，如["rgb", "normal", "depth"]
  • condition_drop_rate：条件丢弃率，用于训练时的数据增强
  • append_condition_mask：是否附加条件掩码

🔧 推理脚本API

inference_inverse_renderer.py

逆渲染推理脚本位于cosmos_predict1/diffusion/inference/inference_inverse_renderer.py。

主要命令行参数
python cosmos_predict1/diffusion/inference/inference_inverse_renderer.py \ --checkpoint_dir checkpoints \ --diffusion_transformer_dir Diffusion_Renderer_Inverse_Cosmos_7B \ --dataset_path=asset/examples/image_examples/ \ --num_video_frames 1 \ --group_mode webdataset \ --video_save_folder=asset/example_results/image_delighting/ \ --save_video=False

关键参数：

  • --inference_passes：要推断的G-buffer通道（默认：basecolor normal depth roughness metallic）
  • --normalize_normal：是否对法线图进行归一化
  • --save_image/save_video：输出格式控制

inference_forward_renderer.py

前向渲染推理脚本位于cosmos_predict1/diffusion/inference/inference_forward_renderer.py。

主要命令行参数
python cosmos_predict1/diffusion/inference/inference_forward_renderer.py \ --checkpoint_dir checkpoints \ --diffusion_transformer_dir Diffusion_Renderer_Forward_Cosmos_7B \ --dataset_path=asset/example_results/image_delighting/gbuffer_frames \ --num_video_frames 1 \ --envlight_ind 0 1 2 3 \ --use_custom_envmap=True \ --video_save_folder=asset/example_results/image_relighting/

关键参数：

  • --envlight_ind：环境光照索引（支持多个环境贴图）
  • --use_custom_envmap：是否使用自定义环境贴图
  • --rotate_light：是否旋转光照
  • --use_fixed_frame_ind：是否使用固定帧索引

图：使用不同环境光照进行重光照的效果对比

📊 数据格式与配置

G-buffer通道映射

在cosmos_predict1/diffusion/inference/diffusion_renderer_utils/rendering_utils.py中定义了G-buffer索引映射：

GBUFFER_INDEX_MAPPING = { "basecolor": 0, # 基础颜色 "normal": 1, # 表面法线 "depth": 2, # 深度图 "roughness": 3, # 粗糙度 "metallic": 4, # 金属度 }

环境光照配置

预定义的环境光照位于asset/examples/hdri_examples/目录：

  1. pink_sunrise_2k.hdr- 粉色日出环境
  2. rosendal_plains_1_2k.hdr- 罗斯代尔平原环境
  3. street_lamp_2k.hdr- 街灯环境
  4. sunny_vondelpark_2k.hdr- 阳光明媚的冯德尔公园环境

图：不同的HDR环境贴图用于重光照效果

🎨 实用工具函数

视频帧提取工具

位于scripts/dataproc_extract_frames_from_video.py：

def extract_frames_from_video( input_path: str, output_folder: str, frame_rate: int = 24, resize: Tuple[int, int] = (1280, 704), max_frames: int = 57, ) -> List[str]:

功能：从视频文件中提取帧并调整大小

参数：

  • frame_rate：提取帧率
  • resize：调整输出分辨率
  • max_frames：最大帧数限制

数据加载器工具

在cosmos_predict1/diffusion/inference/diffusion_renderer_utils/dataloader_utils.py中提供了数据加载辅助函数：

def dict_collation_fn(batch: List[Dict]) -> Dict: def dict_collation_fn_concat(batch: List[Dict]) -> Dict: def sample_continuous_keys(batch: Dict, keys: List[str]) -> Dict:

⚡ 性能优化参数

内存优化选项

# 减少GPU内存使用的参数 offload_network=True # 卸载网络到CPU offload_tokenizer=True # 卸载分词器到CPU offload_text_encoder_model=True # 卸载文本编码器

推理速度优化

num_steps=15 # 扩散步数（平衡质量与速度） guidance=0.0 # 引导强度（0.0-1.0） seed=1000 # 随机种子（确保可重复性）

🚀 快速开始示例

图像处理流程

# 1. 初始化逆渲染器 inverse_pipeline = DiffusionRendererPipeline( checkpoint_dir="checkpoints", checkpoint_name="Diffusion_Renderer_Inverse_Cosmos_7B", offload_network=True, num_steps=15 ) # 2. 准备输入数据 data_batch = { "rgb": torch.randn(1, 3, 1, 704, 1280), # 单帧图像 "context_index": torch.tensor([0]) # 基础颜色通道 } # 3. 生成G-buffer g_buffer = inverse_pipeline.generate_video(data_batch) # 4. 初始化前向渲染器 forward_pipeline = DiffusionRendererPipeline( checkpoint_dir="checkpoints", checkpoint_name="Diffusion_Renderer_Forward_Cosmos_7B" ) # 5. 应用重光照 relit_image = forward_pipeline.generate_video(g_buffer_data)

图：从原始图像到重光照结果的完整处理流程

视频处理流程

# 1. 提取视频帧 extract_frames_from_video( input_path="input_video.mp4", output_folder="frames/", frame_rate=24, resize=(1280, 704), max_frames=57 ) # 2. 批量处理视频帧 for frame_batch in video_frames: g_buffer_batch = inverse_pipeline.generate_video(frame_batch) relit_batch = forward_pipeline.generate_video(g_buffer_batch) # 3. 合成输出视频 save_video(relit_frames, "output_video.mp4", fps=24)

🔍 故障排除与调试

常见问题解决

  1. 内存不足错误：添加--offload_diffusion_transformer --offload_tokenizer参数
  2. 模型加载失败：检查checkpoints目录和模型名称
  3. 输出质量不佳：调整num_steps参数（增加步数提高质量）

调试工具

# 检查模型配置 print(pipeline.model.config) # 验证输入数据格式 print(f"Input shape: {data_batch['rgb'].shape}") print(f"Data type: {data_batch['rgb'].dtype}") # 监控GPU使用 torch.cuda.memory_summary()

📈 高级配置选项

自定义环境贴图

# 使用自定义HDR环境贴图 custom_envmap = load_hdr_image("custom_environment.hdr") forward_pipeline.set_environment_map(custom_envmap)

多视图渲染

在cosmos_predict1/diffusion/inference/text2world_multiview.py中支持多视图渲染：

# 多视图配置 multi_view_config = { "num_views": 4, "view_angles": [0, 90, 180, 270], "interpolate_views": True }

图：多视图渲染生成的多个视角结果

🎯 最佳实践建议

1. 分辨率选择

  • 图像处理：1280x704（默认最佳分辨率）
  • 视频处理：保持原始宽高比，最大帧数57帧

2. 内存管理

  • 16GB VRAM：适合单图像处理
  • 48GB VRAM：适合视频批量处理
  • 使用offload参数优化大模型内存使用

3. 质量与速度平衡

  • 快速预览：num_steps=8
  • 标准质量：num_steps=15（默认）
  • 最高质量：num_steps=25

4. 环境光照选择

  • 室内场景：street_lamp_2k.hdr
  • 室外场景：sunny_vondelpark_2k.hdr
  • 创意效果：pink_sunrise_2k.hdr

📚 扩展与定制

自定义G-buffer通道

# 自定义推理通道 custom_passes = ["basecolor", "normal", "depth"] inverse_pipeline.set_inference_passes(custom_passes)

集成到现有管道

class CustomRenderingPipeline: def __init__(self): self.inverse_renderer = DiffusionRendererPipeline(...) self.forward_renderer = DiffusionRendererPipeline(...) def process(self, input_data): # 自定义预处理 preprocessed = self.preprocess(input_data) # 逆渲染 g_buffer = self.inverse_renderer.generate_video(preprocessed) # 自定义后处理 processed = self.custom_processing(g_buffer) # 前向渲染 output = self.forward_renderer.generate_video(processed) return output

🏁 总结

Cosmos-Transfer1-DiffusionRenderer提供了强大而灵活的API，支持从简单的图像处理到复杂的视频重光照工作流。通过这份详细的API参考文档，你应该能够：

  1. 快速上手：使用预配置的推理脚本处理图像和视频
  2. 深度定制：通过Python API集成到自定义工作流
  3. 性能优化：根据硬件配置调整参数以获得最佳性能
  4. 扩展功能：添加自定义处理逻辑和环境光照

记住，这个框架的核心优势在于其基于扩散模型的渲染能力，能够在保持高质量的同时提供实时的照明编辑功能。🎨

图：使用Cosmos-Transfer1-DiffusionRenderer处理的各种场景效果展示

无论你是进行学术研究、产品开发还是创意项目，这个API参考都将帮助你充分利用Cosmos-Transfer1-DiffusionRenderer的强大功能。开始探索吧，创造出令人惊叹的视觉内容！✨

【免费下载链接】cosmos-transfer1-diffusion-rendererCosmos-Transfer1-DiffusionRenderer: High-quality video de-lighting and re-lighting based on Cosmos video diffusion framework项目地址: https://gitcode.com/gh_mirrors/co/cosmos-transfer1-diffusion-renderer

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考