OOTDiffusion 官方仓库实战指南Outfitting Fusion 可控虚拟试穿模型的安装、推理与源码解析【免费下载链接】OOTDiffusion[AAAI 2025] Official implementation of OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on项目地址: https://gitcode.com/GitHub_Trending/oo/OOTDiffusionOOTDiffusionOutfitting Fusion based Latent Diffusion for Controllable Virtual Try-onAAAI 2025是基于隐空间扩散模型的虚拟试穿Virtual Try-on开源实现本指南以仓库 README.md 为核心结合源码带你完成环境搭建、权重下载、半身/全身模型的命令行推理与 Gradio Web 演示并深入解析其双 UNet CLIP 融合的底层推理链路。读完本文你将能够独立跑通 VITON-HD 与 Dress Code 两套模型的完整试穿流程并理解掩码生成、姿态引导、图像引导尺度等关键参数的实际作用。一、项目定位与核心思想OOTDiffusion 由 Xiao-i Research 团队Yuhao Xu、Tao Gu、Weifeng Chen、Chengcai Chen于 2024 年提出论文见 arXiv 2403.01779。与早期基于 GAN 的试穿方法不同它将试穿建模为可控的隐空间扩散生成问题给定一张模特全身/半身图、一张平铺服装图以及服装类别模型在 VAE 隐空间内完成换装扩散采样兼顾了服装纹理细节outfitting fusion与人体姿态一致性。仓库已经发布了分别在两个公开数据集上训练的官方权重VITON-HD半身模型hd支持上衣upper-body类别的换装Dress Code全身模型dc支持上衣upperbody、下装lowerbody、连衣裙dress三类换装。从 README.md 的 TODO 列表可以看到论文、Gradio demo、推理代码与模型权重均已发布而训练代码尚未公开因此本仓库的实际用法是开箱即用的推理而非训练复现。二、环境准备与依赖安装官方声明代码与模型仅在LinuxUbuntu 22.04上做过测试这是最稳妥的运行前提。安装过程分为三步# 1. 克隆仓库 git clone https://github.com/levihsu/OOTDiffusion # 2. 创建 conda 环境Python 3.10 conda create -n ootd python3.10 conda activate ootd # 3. 安装 PyTorch 与其余依赖 pip install torch2.0.1 torchvision0.15.2 torchaudio2.0.2 pip install -r requirements.txttorch2.0.1与torchvision0.15.2需按你的 CUDA 版本选择对应的 wheel 源例如在 NVIDIA 官方 PyTorch 索引下安装 CUDA 11.7/11.8 版本。requirements.txt 中锁定了其余核心依赖版本几个值得注意的点依赖版本在项目中的作用diffusers0.24.0提供AutoencoderKL、UniPCMultistepScheduler与 Pipeline 基类transformers4.36.2提供 CLIP 文本/图像编码器CLIPTextModel、CLIPVisionModelWithProjectionaccelerate0.26.1模型设备管理与torch.no_grad加速gradio4.16.0构建 Web 试穿演示界面onnxruntime1.16.2支撑 humanparsing 的 ONNX 推理README 特别提到已支持 ONNX 以解决大部分环境问题opencv-python / pillow / numpy / scipy / scikit-image见文件图像读写、掩码形态学处理、姿态关键点处理三、模型权重下载与 checkpoints 目录结构推理前需要准备三类权重按 checkpoints/README.txt 的说明统一放入checkpoints/目录ootdOOTDiffusion 主模型权重VAE、unet_garm、unet_vton、tokenizer、text_encoder由官方在 Hugging Face 上发布包含hd与dc两套子权重humanparsing人体解析human parsing模型权重README 指出当前已支持 ONNX 格式大幅降低了安装环境依赖的难度openposeOpenPose 姿态检测权重clip-vit-large-patch14OpenAI 的 CLIP ViT-L/14 权重用于提取服装图像的视觉特征必须单独下载并放入checkpoints/文件夹。最终目录结构应形如checkpoints/ ├── clip-vit-large-patch14/ # CLIP 图像/文本编码器 ├── humanparsing/ # 人体解析模型 ├── openpose/ # 姿态检测模型 └── ootd/ ├── vae/ ├── tokenizer/ ├── text_encoder/ ├── ootd_hd/checkpoint-36000/ # 半身模型含 unet_garm、unet_vton └── ootd_dc/checkpoint-36000/ # 全身模型含 unet_garm、unet_vton这一结构与源码中的加载路径一一对应例如 inference_ootd_hd.py 中写死的VIT_PATH ../checkpoints/clip-vit-large-patch14、UNET_PATH ../checkpoints/ootd/ootd_hd/checkpoint-36000以及 inference_ootd_dc.py 中的ootd_dc/checkpoint-36000。因此请勿改动 checkpoints 目录内外的相对位置否则会因路径失效而加载失败。四、命令行推理半身模型进入run/目录执行推理cd OOTDiffusion/run python run_ootd.py --model_path model-image-path --cloth_path cloth-image-path --scale 2.0 --sample 4参数含义--model_path是模特全身/半身图路径--cloth_path是平铺服装图路径--scale 2.0为图像引导尺度image guidance scale--sample 4表示一次生成 4 张候选结果。默认--model_type hd、--category 0上衣。推理结束后run/images_output/目录下会生成mask.jpg预处理阶段生成并保存的换装掩码可视化out_hd_0.png、out_hd_1.png……按--sample数量生成的试穿结果命名规则为out_model_type_序号.png见 run_ootd.py。五、命令行推理全身模型全身模型dc与半身模型的唯一差异在于必须指定服装类别且类别必须与服装图片严格配对Garment category must be paired: 0 upperbody; 1 lowerbody; 2 dresscd OOTDiffusion/run python run_ootd.py --model_path model-image-path --cloth_path cloth-image-path --model_type dc --category 2 --scale 2.0 --sample 4例如--category 2对应连衣裙。若--model_type dc但未显式传--category则使用默认值 0上衣。类别编码会同时影响两个层面详见 run_ootd.py掩码生成category_dict_utils [upper_body, lower_body, dresses]决定get_mask_location使用哪套解析标签组合来划定待换装区域文本提示category_dict [upperbody, lowerbody, dress]作为文本 token 送入 CLIP 文本编码器参与条件生成。六、完整参数表与源码对应run_ootd.py 中的 argparse 定义即官方命令行参数的权威来源整理如下参数缩写类型默认值必填说明--model_path-str是模特图像路径--cloth_path-str是服装图像路径--model_type-strhd否模型类型hd半身VITON-HD或dc全身Dress Code其他值抛出ValueError--category-cint0否服装类别0upperbody1lowerbody2dresshd模型仅允许 0--scale-float2.0否图像引导尺度image_guidance_scaleGradio 中取值范围 1.05.0--step-int20否扩散采样步数对应num_inference_steps--sample-int4否每张输入生成的候选图像数量--seed-int-1否随机种子-1 表示按当前时间自动生成见 inference_ootd_hd.py--gpu_id-gint0否使用的 CUDA 设备编号源码中还内置了两条约束性校验run_ootd.py--model_type取值非法非hd/dc直接报错使用hd模型时category必须为 0hd仅支持上衣否则报错model_type hd requires category 0 (upperbody)!。七、源码级工作流从输入图片到试穿结果run_ootd.py完整展示了端到端推理链路可分为三个阶段阶段一姿态与人体解析run_ootd.py输入图片统一resize((768, 1024))OpenPose(args.gpu_id)在 384×512 尺度上提取 18 个 2D 姿态关键点肩、肘、腕等见 run_openpose.pyParsing(args.gpu_id)输出 18 类标签 017 脖子标签 18的人体解析图ONNX 推理实现见 parsing_api.py其中还包含用 LIP 模型补脖子标签、对上衣区域做孔洞填充的后处理get_mask_location(...)依据类别、解析图与关键点生成二值掩码mask和灰度掩码mask_gray实现位于 utils_ootd.py。阶段二掩码合成run_ootd.pymasked_vton_img Image.composite(mask_gray, model_img, mask)将待换装区域抹灰得到脱掉原衣服的模特图作为扩散模型的输入条件之一。阶段三扩散采样run_ootd.py调用OOTDiffusionHD/DC完成采样核心组件inference_ootd_hd.py包括VAEAutoencoderKLfp16负责图像与隐空间的互转双 UNetunet_garm服装分支与unet_vton试穿分支协同去噪这是Outfitting Fusion的核心——服装信息通过专门分支注入CLIP 双编码CLIPVisionModelWithProjection编码服装图像得到视觉嵌入prompt_imageCLIPTextModel编码文本条件。hd模式将视觉嵌入拼接到空白文本嵌入之后prompt_embeds[:, 1:] prompt_image[:]dc模式则将类别词文本嵌入与视觉嵌入沿序列维拼接torch.cat见 inference_ootd_hd.py调度器UniPCMultistepScheduler完成 20 步默认多步去噪采样自定义OotdPipeline继承DiffusionPipeline承载完整采样流程实现在 pipeline_ootd.py。掩码生成逻辑要点可选进阶get_mask_location中hd与dc使用了不同的手臂线宽arm_width分别为 60 与 45见 utils_ootd.py并根据label_map背景 0、上衣 4、裙 5、裤 6、连衣裙 7、左右腿 12/13、左右臂 14/15 等 18 类标签组合出可更换区域与固定区域再用姿态关键点沿肩-肘-腕连线绘制手臂掩码、对颈部标签 18做膨胀、最后经hole_fill与refine_mask去除孔洞与杂散轮廓。不同类别的标签组合逻辑见 utils_ootd.py。八、Gradio Web 演示仓库同时提供开箱即用的 Web UIgradio_ootd.py启动方式cd OOTDiffusion/run python gradio_ootd.py界面默认监听0.0.0.0:7865见 gradio_ootd.py包含两个独立分区Half-body半身固定类别为上衣提供 14 组官方示例模特与服装图均位于run/examples/下Full-body全身通过下拉框选择Garment categoryUpper-body / Lower-body / Dress官方标注important option!!!必须与服装图片类别配对这与命令行参数--category完全一致见 gradio_ootd.py。界面中的可调参数与命令行一一对应Gradio 控件取值范围默认值对应命令行参数Images141--sampleSteps204020--stepGuidance scale1.05.0步长 0.12.0--scaleSeed-12147483647-1--seed需要注意的是gradio_ootd.py 中hd与dc模型被分别固定加载到 GPU 0 与 GPU 1若你只有单卡需自行调整两个模型实例的gpu_id。九、注意事项与常见问题运行前提官方仅验证过 LinuxUbuntu 22.04Windows/macOS 可能遇到编译或路径兼容问题。权重完整性clip-vit-large-patch14必须与 ootd、humanparsing、openpose 一起放入checkpoints/缺一不可且目录结构需与源码中的硬编码路径保持一致见 inference_ootd_hd.py。类别配对全身模型下服装类别与图片不匹配时掩码区域会错误生成结果出现明显伪影。显存与采样参数默认--sample 4 --step 20会同时解码多张 768×1024 图像显存不足时可调小--sample--scale越高越贴近服装原图过低则服装细节易丢失Gradio 中该参数范围即 1.05.0。seed 固定设--seed为固定非负整数可复现同一种子下的采样结果-1时源码会打印实际使用的随机种子见 inference_ootd_hd.py。十、引用与后续进展若在研究中使用了本项目官方建议引用README.md 中的 Citation 部分article{xu2024ootdiffusion, title{OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on}, author{Xu, Yuhao and Gu, Tao and Chen, Weifeng and Chen, Chengcai}, journal{arXiv preprint arXiv:2403.01779}, year{2024} }截至本仓库当前版本官方 TODO 进度为论文、Gradio demo、推理代码、模型权重均已发布[x]训练代码仍未开放[ ]。若你需要在此仓库基础上二次开发例如替换服装类别、改造掩码生成或接入自有数据可从 run/run_ootd.py、ootd/inference_ootd_hd.py 与 ootd/inference_ootd_dc.py 三个入口开始阅读它们共同构成了完整的推理 API 边界。【免费下载链接】OOTDiffusion[AAAI 2025] Official implementation of OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on项目地址: https://gitcode.com/GitHub_Trending/oo/OOTDiffusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OOTDiffusion 官方仓库实战指南：Outfitting Fusion 可控虚拟试穿模型的安装、推理与源码解析
OOTDiffusion 官方仓库实战指南Outfitting Fusion 可控虚拟试穿模型的安装、推理与源码解析【免费下载链接】OOTDiffusion[AAAI 2025] Official implementation of OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on项目地址: https://gitcode.com/GitHub_Trending/oo/OOTDiffusionOOTDiffusionOutfitting Fusion based Latent Diffusion for Controllable Virtual Try-onAAAI 2025是基于隐空间扩散模型的虚拟试穿Virtual Try-on开源实现本指南以仓库 README.md 为核心结合源码带你完成环境搭建、权重下载、半身/全身模型的命令行推理与 Gradio Web 演示并深入解析其双 UNet CLIP 融合的底层推理链路。读完本文你将能够独立跑通 VITON-HD 与 Dress Code 两套模型的完整试穿流程并理解掩码生成、姿态引导、图像引导尺度等关键参数的实际作用。一、项目定位与核心思想OOTDiffusion 由 Xiao-i Research 团队Yuhao Xu、Tao Gu、Weifeng Chen、Chengcai Chen于 2024 年提出论文见 arXiv 2403.01779。与早期基于 GAN 的试穿方法不同它将试穿建模为可控的隐空间扩散生成问题给定一张模特全身/半身图、一张平铺服装图以及服装类别模型在 VAE 隐空间内完成换装扩散采样兼顾了服装纹理细节outfitting fusion与人体姿态一致性。仓库已经发布了分别在两个公开数据集上训练的官方权重VITON-HD半身模型hd支持上衣upper-body类别的换装Dress Code全身模型dc支持上衣upperbody、下装lowerbody、连衣裙dress三类换装。从 README.md 的 TODO 列表可以看到论文、Gradio demo、推理代码与模型权重均已发布而训练代码尚未公开因此本仓库的实际用法是开箱即用的推理而非训练复现。二、环境准备与依赖安装官方声明代码与模型仅在LinuxUbuntu 22.04上做过测试这是最稳妥的运行前提。安装过程分为三步# 1. 克隆仓库 git clone https://github.com/levihsu/OOTDiffusion # 2. 创建 conda 环境Python 3.10 conda create -n ootd python3.10 conda activate ootd # 3. 安装 PyTorch 与其余依赖 pip install torch2.0.1 torchvision0.15.2 torchaudio2.0.2 pip install -r requirements.txttorch2.0.1与torchvision0.15.2需按你的 CUDA 版本选择对应的 wheel 源例如在 NVIDIA 官方 PyTorch 索引下安装 CUDA 11.7/11.8 版本。requirements.txt 中锁定了其余核心依赖版本几个值得注意的点依赖版本在项目中的作用diffusers0.24.0提供AutoencoderKL、UniPCMultistepScheduler与 Pipeline 基类transformers4.36.2提供 CLIP 文本/图像编码器CLIPTextModel、CLIPVisionModelWithProjectionaccelerate0.26.1模型设备管理与torch.no_grad加速gradio4.16.0构建 Web 试穿演示界面onnxruntime1.16.2支撑 humanparsing 的 ONNX 推理README 特别提到已支持 ONNX 以解决大部分环境问题opencv-python / pillow / numpy / scipy / scikit-image见文件图像读写、掩码形态学处理、姿态关键点处理三、模型权重下载与 checkpoints 目录结构推理前需要准备三类权重按 checkpoints/README.txt 的说明统一放入checkpoints/目录ootdOOTDiffusion 主模型权重VAE、unet_garm、unet_vton、tokenizer、text_encoder由官方在 Hugging Face 上发布包含hd与dc两套子权重humanparsing人体解析human parsing模型权重README 指出当前已支持 ONNX 格式大幅降低了安装环境依赖的难度openposeOpenPose 姿态检测权重clip-vit-large-patch14OpenAI 的 CLIP ViT-L/14 权重用于提取服装图像的视觉特征必须单独下载并放入checkpoints/文件夹。最终目录结构应形如checkpoints/ ├── clip-vit-large-patch14/ # CLIP 图像/文本编码器 ├── humanparsing/ # 人体解析模型 ├── openpose/ # 姿态检测模型 └── ootd/ ├── vae/ ├── tokenizer/ ├── text_encoder/ ├── ootd_hd/checkpoint-36000/ # 半身模型含 unet_garm、unet_vton └── ootd_dc/checkpoint-36000/ # 全身模型含 unet_garm、unet_vton这一结构与源码中的加载路径一一对应例如 inference_ootd_hd.py 中写死的VIT_PATH ../checkpoints/clip-vit-large-patch14、UNET_PATH ../checkpoints/ootd/ootd_hd/checkpoint-36000以及 inference_ootd_dc.py 中的ootd_dc/checkpoint-36000。因此请勿改动 checkpoints 目录内外的相对位置否则会因路径失效而加载失败。四、命令行推理半身模型进入run/目录执行推理cd OOTDiffusion/run python run_ootd.py --model_path model-image-path --cloth_path cloth-image-path --scale 2.0 --sample 4参数含义--model_path是模特全身/半身图路径--cloth_path是平铺服装图路径--scale 2.0为图像引导尺度image guidance scale--sample 4表示一次生成 4 张候选结果。默认--model_type hd、--category 0上衣。推理结束后run/images_output/目录下会生成mask.jpg预处理阶段生成并保存的换装掩码可视化out_hd_0.png、out_hd_1.png……按--sample数量生成的试穿结果命名规则为out_model_type_序号.png见 run_ootd.py。五、命令行推理全身模型全身模型dc与半身模型的唯一差异在于必须指定服装类别且类别必须与服装图片严格配对Garment category must be paired: 0 upperbody; 1 lowerbody; 2 dresscd OOTDiffusion/run python run_ootd.py --model_path model-image-path --cloth_path cloth-image-path --model_type dc --category 2 --scale 2.0 --sample 4例如--category 2对应连衣裙。若--model_type dc但未显式传--category则使用默认值 0上衣。类别编码会同时影响两个层面详见 run_ootd.py掩码生成category_dict_utils [upper_body, lower_body, dresses]决定get_mask_location使用哪套解析标签组合来划定待换装区域文本提示category_dict [upperbody, lowerbody, dress]作为文本 token 送入 CLIP 文本编码器参与条件生成。六、完整参数表与源码对应run_ootd.py 中的 argparse 定义即官方命令行参数的权威来源整理如下参数缩写类型默认值必填说明--model_path-str是模特图像路径--cloth_path-str是服装图像路径--model_type-strhd否模型类型hd半身VITON-HD或dc全身Dress Code其他值抛出ValueError--category-cint0否服装类别0upperbody1lowerbody2dresshd模型仅允许 0--scale-float2.0否图像引导尺度image_guidance_scaleGradio 中取值范围 1.05.0--step-int20否扩散采样步数对应num_inference_steps--sample-int4否每张输入生成的候选图像数量--seed-int-1否随机种子-1 表示按当前时间自动生成见 inference_ootd_hd.py--gpu_id-gint0否使用的 CUDA 设备编号源码中还内置了两条约束性校验run_ootd.py--model_type取值非法非hd/dc直接报错使用hd模型时category必须为 0hd仅支持上衣否则报错model_type hd requires category 0 (upperbody)!。七、源码级工作流从输入图片到试穿结果run_ootd.py完整展示了端到端推理链路可分为三个阶段阶段一姿态与人体解析run_ootd.py输入图片统一resize((768, 1024))OpenPose(args.gpu_id)在 384×512 尺度上提取 18 个 2D 姿态关键点肩、肘、腕等见 run_openpose.pyParsing(args.gpu_id)输出 18 类标签 017 脖子标签 18的人体解析图ONNX 推理实现见 parsing_api.py其中还包含用 LIP 模型补脖子标签、对上衣区域做孔洞填充的后处理get_mask_location(...)依据类别、解析图与关键点生成二值掩码mask和灰度掩码mask_gray实现位于 utils_ootd.py。阶段二掩码合成run_ootd.pymasked_vton_img Image.composite(mask_gray, model_img, mask)将待换装区域抹灰得到脱掉原衣服的模特图作为扩散模型的输入条件之一。阶段三扩散采样run_ootd.py调用OOTDiffusionHD/DC完成采样核心组件inference_ootd_hd.py包括VAEAutoencoderKLfp16负责图像与隐空间的互转双 UNetunet_garm服装分支与unet_vton试穿分支协同去噪这是Outfitting Fusion的核心——服装信息通过专门分支注入CLIP 双编码CLIPVisionModelWithProjection编码服装图像得到视觉嵌入prompt_imageCLIPTextModel编码文本条件。hd模式将视觉嵌入拼接到空白文本嵌入之后prompt_embeds[:, 1:] prompt_image[:]dc模式则将类别词文本嵌入与视觉嵌入沿序列维拼接torch.cat见 inference_ootd_hd.py调度器UniPCMultistepScheduler完成 20 步默认多步去噪采样自定义OotdPipeline继承DiffusionPipeline承载完整采样流程实现在 pipeline_ootd.py。掩码生成逻辑要点可选进阶get_mask_location中hd与dc使用了不同的手臂线宽arm_width分别为 60 与 45见 utils_ootd.py并根据label_map背景 0、上衣 4、裙 5、裤 6、连衣裙 7、左右腿 12/13、左右臂 14/15 等 18 类标签组合出可更换区域与固定区域再用姿态关键点沿肩-肘-腕连线绘制手臂掩码、对颈部标签 18做膨胀、最后经hole_fill与refine_mask去除孔洞与杂散轮廓。不同类别的标签组合逻辑见 utils_ootd.py。八、Gradio Web 演示仓库同时提供开箱即用的 Web UIgradio_ootd.py启动方式cd OOTDiffusion/run python gradio_ootd.py界面默认监听0.0.0.0:7865见 gradio_ootd.py包含两个独立分区Half-body半身固定类别为上衣提供 14 组官方示例模特与服装图均位于run/examples/下Full-body全身通过下拉框选择Garment categoryUpper-body / Lower-body / Dress官方标注important option!!!必须与服装图片类别配对这与命令行参数--category完全一致见 gradio_ootd.py。界面中的可调参数与命令行一一对应Gradio 控件取值范围默认值对应命令行参数Images141--sampleSteps204020--stepGuidance scale1.05.0步长 0.12.0--scaleSeed-12147483647-1--seed需要注意的是gradio_ootd.py 中hd与dc模型被分别固定加载到 GPU 0 与 GPU 1若你只有单卡需自行调整两个模型实例的gpu_id。九、注意事项与常见问题运行前提官方仅验证过 LinuxUbuntu 22.04Windows/macOS 可能遇到编译或路径兼容问题。权重完整性clip-vit-large-patch14必须与 ootd、humanparsing、openpose 一起放入checkpoints/缺一不可且目录结构需与源码中的硬编码路径保持一致见 inference_ootd_hd.py。类别配对全身模型下服装类别与图片不匹配时掩码区域会错误生成结果出现明显伪影。显存与采样参数默认--sample 4 --step 20会同时解码多张 768×1024 图像显存不足时可调小--sample--scale越高越贴近服装原图过低则服装细节易丢失Gradio 中该参数范围即 1.05.0。seed 固定设--seed为固定非负整数可复现同一种子下的采样结果-1时源码会打印实际使用的随机种子见 inference_ootd_hd.py。十、引用与后续进展若在研究中使用了本项目官方建议引用README.md 中的 Citation 部分article{xu2024ootdiffusion, title{OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on}, author{Xu, Yuhao and Gu, Tao and Chen, Weifeng and Chen, Chengcai}, journal{arXiv preprint arXiv:2403.01779}, year{2024} }截至本仓库当前版本官方 TODO 进度为论文、Gradio demo、推理代码、模型权重均已发布[x]训练代码仍未开放[ ]。若你需要在此仓库基础上二次开发例如替换服装类别、改造掩码生成或接入自有数据可从 run/run_ootd.py、ootd/inference_ootd_hd.py 与 ootd/inference_ootd_dc.py 三个入口开始阅读它们共同构成了完整的推理 API 边界。【免费下载链接】OOTDiffusion[AAAI 2025] Official implementation of OOTDiffusion: Outfitting Fusion based Latent Diffusion for Controllable Virtual Try-on项目地址: https://gitcode.com/GitHub_Trending/oo/OOTDiffusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考