sd-webui-depth-lib · 技能与配置

让 AI 绘画精准控制空间结构：sd-webui-depth-lib 深度图姿势库

背景故事

2023 年，随着 Stable Diffusion 与 ControlNet 的结合，AI 绘画正式进入"精确控制"时代。ControlNet 允许用户通过额外条件信号（如骨骼姿态、边缘线、语义分割图）来引导 AI 的生成方向，但每生成一张新的控制图，都意味着用户需要手动绘制或借助专业工具处理。对于想要快速尝试不同人体姿势、物体空间布局的创作者来说，这个环节严重拖慢了创作效率。

jexom 开发了 sd-webui-depth-lib，将深度图（Depth Map）和姿势控制库的便捷管理集成到 SD WebUI 界面中。用户无需离开浏览器界面，就能浏览、组合、叠加多个深度图，预览效果，并一键发送到 ControlNet 模块。2023 年 3 月开源至今，已获得 1398 颗星、143 个 Fork，成为 ControlNet 生态中最受欢迎的辅助扩展之一。

sd-webui-depth-lib 操作界面

图1：sd-webui-depth-lib 的 Gradio 操作界面，左侧为深度图库选择区，右侧为交互式画布预览

核心功能：深度图的"资源管理器"

1. 内置深度图库

插件预置了两个深度图分类目录：

shapes：几何形体深度图（立方体、球体、圆柱体等），适合控制物体在画面中的空间位置和投影关系
hands：手部姿态深度图，专门针对手部复杂结构的控制

每个分类下的图以缩略图形式展示，用户点击即可加载到画布上。

2. 交互式画布编辑器

基于 Fabric.js Canvas 引擎，构建了一个功能完整的 2D 编辑画布：

添加/删除元素：可向画布叠加多张深度图，支持选中单个元素调整
调整不透明度：通过 Opacity 滑块控制各层深度图的权重
背景图支持：可加载背景图作为参考，叠加深度信息层
基础深度调节：Base Depth 滑块控制画布整体亮度，影响深度感知强度
尺寸配置：宽度/高度可在 64px 到 2048px 之间以 64 为步长调整

3. 一键发送到 ControlNet

编辑完成后，点击 "Send to ControlNet" 按钮，通过 JavaScript 调用将当前画布图像直接传递到 ControlNet 扩展的输入端，用户无需手动保存和切换页面。这是最核心的效率提升——所见即所得的工作流闭环。

4. 自定义扩展

用户可将自定义深度图放入 extensions/sd-webui-depth-lib/maps/<category>/ 目录下，以分类名作为文件夹名，插件会自动扫描并显示在对应的 Tab 中。

技术架构

前端交互层（JavaScript + Fabric.js）

javascript/main.js 是核心前端逻辑，实现了以下功能模块：

// Canvas 初始化，绑定 Fabric.js 画布
function depth_initCanvas(elem) {
    window.depth_lib_canvas = new fabric.Canvas(elem, {
        backgroundColor: '#000',
        preserveObjectStacking: true
    });
}

// 计算自适应分辨率（响应式布局）
function depth_calcResolution(resolution) {
    const viewportWidth = window.innerWidth / 2.25;
    const viewportHeight = window.innerHeight * 0.75;
    const ratio = Math.min(viewportWidth / width, viewportHeight / height);
    return { width: width * ratio, height: height * ratio }
}

// 保存为 PNG 并触发下载
function depth_savePNG() {
    depth_lib_elem.toBlob((blob) => {
        const a = document.createElement("a");
        a.href = URL.createObjectURL(blob);
        a.download = "pose.png";
        a.click();
    });
}

// 发送到 ControlNet（通过 Gradio 的 JSON 回调机制）
function depth_sendImage() {
    // 触发 Gradio 组件事件，将 canvas 内容发送到 ControlNet 输入
}

javascript/fabric.js 是 Fabric.js 5.3.0 的完整打包文件（约 50KB），提供了 Canvas 上绘制、变换、选择等底层能力。

后端扩展层（Python + Gradio）

scripts/main.py 实现了 SD WebUI 扩展的标准接口：

class Script(scripts.Script):
    def title(self):
        return "Depth Library"

    def show(self, is_img2img):
        return scripts.AlwaysVisible  # 常驻显示，无需手动启用

    def ui(self, is_img2img):
        # 构建 Gradio UI：图库浏览器 + 画布 + 导出按钮
        # 绑定 JavaScript 回调，实现前端-后端事件联动

Gradio 的 _js 参数是关键机制——它允许 Python 端注册 JavaScript 函数到按钮点击事件中，实现前后端双向通信。按钮 send_output.click() 绑定了 depth_sendImage JS 函数，调用 ControlNet 扩展的内部接口完成跨扩展图像传递。

部署模式

这是一个纯 WebUI 扩展，不是独立部署工具：

无 Dockerfile、无 docker-compose
需配合 Automatic1111/stable-diffusion-webui 主程序运行
需配合 sd-webui-controlnet 扩展
推荐 NVIDIA GPU（6GB+ VRAM）以流畅运行 SD 推理

使用门槛与适用场景

维度	说明
上手难度	低。安装后直接在 WebUI "Depth Library" Tab 中操作，无需代码知识
适用用户	AI 绘画爱好者、概念设计师、游戏美术、内容创作者
不适用	纯命令行用户、无 GPU 硬件、仅需文生图而不需结构控制的用户
深度图来源	预置库 + 用户自定义（需自行生成或下载深度图文件）

局限与争议

仅支持 ControlNet Depth 预处理：该扩展生成的是 ControlNet 专用深度图，不兼容其他控制方法（如 OpenPose、Canny）
依赖主程序：无法独立运行，必须在完整 SD WebUI 环境中使用
自定义深度图门槛：用户需要自己生成高质量深度图（如通过 MiDaS 或其他深度估计模型），预置库有限
Canvas 编辑能力有限：Fabric.js 画布不支持图层顺序精确控制、多选批量操作

行业意义

sd-webui-depth-lib 体现了 SD 生态的一个核心趋势：从"单工具效率"到"工作流集成"。ControlNet 的出现让 AI 绘画有了结构控制能力，但工具链的割裂（生成深度图 → 切换页面 → 上传 → 生成）影响了创作流畅性。这类扩展通过将多个工具整合到统一界面，把"3分钟的操作步骤"压缩到"1次点击"，本质上是在降低 AI 创作的认知负担。

截至目前，该项目在 ControlNet 相关扩展中持续活跃，issue 区用户反馈积极，是 Stable Diffusion 生态中插件化协作的典型案例。

让 AI 绘画精准控制空间结构：sd-webui-depth-lib 深度图姿势库

背景故事

sd-webui-depth-lib 操作界面

图1：sd-webui-depth-lib 的 Gradio 操作界面，左侧为深度图库选择区，右侧为交互式画布预览

核心功能：深度图的"资源管理器"

1. 内置深度图库

插件预置了两个深度图分类目录：

shapes：几何形体深度图（立方体、球体、圆柱体等），适合控制物体在画面中的空间位置和投影关系
hands：手部姿态深度图，专门针对手部复杂结构的控制

每个分类下的图以缩略图形式展示，用户点击即可加载到画布上。

2. 交互式画布编辑器

基于 Fabric.js Canvas 引擎，构建了一个功能完整的 2D 编辑画布：

添加/删除元素：可向画布叠加多张深度图，支持选中单个元素调整
调整不透明度：通过 Opacity 滑块控制各层深度图的权重
背景图支持：可加载背景图作为参考，叠加深度信息层
基础深度调节：Base Depth 滑块控制画布整体亮度，影响深度感知强度
尺寸配置：宽度/高度可在 64px 到 2048px 之间以 64 为步长调整

3. 一键发送到 ControlNet

4. 自定义扩展

用户可将自定义深度图放入 extensions/sd-webui-depth-lib/maps/<category>/ 目录下，以分类名作为文件夹名，插件会自动扫描并显示在对应的 Tab 中。

技术架构

前端交互层（JavaScript + Fabric.js）

javascript/main.js 是核心前端逻辑，实现了以下功能模块：

// Canvas 初始化，绑定 Fabric.js 画布
function depth_initCanvas(elem) {
    window.depth_lib_canvas = new fabric.Canvas(elem, {
        backgroundColor: '#000',
        preserveObjectStacking: true
    });
}

// 计算自适应分辨率（响应式布局）
function depth_calcResolution(resolution) {
    const viewportWidth = window.innerWidth / 2.25;
    const viewportHeight = window.innerHeight * 0.75;
    const ratio = Math.min(viewportWidth / width, viewportHeight / height);
    return { width: width * ratio, height: height * ratio }
}

// 保存为 PNG 并触发下载
function depth_savePNG() {
    depth_lib_elem.toBlob((blob) => {
        const a = document.createElement("a");
        a.href = URL.createObjectURL(blob);
        a.download = "pose.png";
        a.click();
    });
}

// 发送到 ControlNet（通过 Gradio 的 JSON 回调机制）
function depth_sendImage() {
    // 触发 Gradio 组件事件，将 canvas 内容发送到 ControlNet 输入
}

javascript/fabric.js 是 Fabric.js 5.3.0 的完整打包文件（约 50KB），提供了 Canvas 上绘制、变换、选择等底层能力。

后端扩展层（Python + Gradio）

scripts/main.py 实现了 SD WebUI 扩展的标准接口：

class Script(scripts.Script):
    def title(self):
        return "Depth Library"

    def show(self, is_img2img):
        return scripts.AlwaysVisible  # 常驻显示，无需手动启用

    def ui(self, is_img2img):
        # 构建 Gradio UI：图库浏览器 + 画布 + 导出按钮
        # 绑定 JavaScript 回调，实现前端-后端事件联动

部署模式

这是一个纯 WebUI 扩展，不是独立部署工具：

无 Dockerfile、无 docker-compose
需配合 Automatic1111/stable-diffusion-webui 主程序运行
需配合 sd-webui-controlnet 扩展
推荐 NVIDIA GPU（6GB+ VRAM）以流畅运行 SD 推理

使用门槛与适用场景

维度	说明
上手难度	低。安装后直接在 WebUI "Depth Library" Tab 中操作，无需代码知识
适用用户	AI 绘画爱好者、概念设计师、游戏美术、内容创作者
不适用	纯命令行用户、无 GPU 硬件、仅需文生图而不需结构控制的用户
深度图来源	预置库 + 用户自定义（需自行生成或下载深度图文件）

局限与争议

仅支持 ControlNet Depth 预处理：该扩展生成的是 ControlNet 专用深度图，不兼容其他控制方法（如 OpenPose、Canny）
依赖主程序：无法独立运行，必须在完整 SD WebUI 环境中使用
自定义深度图门槛：用户需要自己生成高质量深度图（如通过 MiDaS 或其他深度估计模型），预置库有限
Canvas 编辑能力有限：Fabric.js 画布不支持图层顺序精确控制、多选批量操作

行业意义

截至目前，该项目在 ControlNet 相关扩展中持续活跃，issue 区用户反馈积极，是 Stable Diffusion 生态中插件化协作的典型案例。