ControlNet 自动标注实战指南用 gradio_annotator.py 一键生成六大条件控制图【免费下载链接】ControlNetLet us control diffusion models!项目地址: https://gitcode.com/gh_mirrors/co/ControlNet本指南围绕 ControlNet 仓库中的 docs/annotator.md 展开系统讲解如何利用官方提供的 Gradio 标注工具gradio_annotator.py为训练 ControlNet 模型生成与预训练权重严格对齐的六类条件控制图Canny / HED / MLSD / MIDAS / OpenPose / Uniformer。读完本文你将掌握标注工具的启动方式、每个接口的参数语义与源码实现原理以及边缘图黑白底约定、法线与姿态图的RGB/BGR约定等关键细节能够据此改造脚本进行自定义批量标注。一、自动标注让条件控制图与预训练模型严格对齐ControlNet 的核心思想是在扩散模型如 Stable Diffusion的 UNet 主干上注入可控条件而训练与推理效果高度依赖输入条件图annotation与预训练模型训练时看到的数据分布一致。官方因此在仓库中内置了一套自动标注Automatic Annotations工具链其入口文档即 docs/annotator.md。该文档明确说明了两点设计意图提供与生产级模型对齐的标注能力gradio_annotator.py中的每个检测器其输出格式、色彩约定都与仓库配套的预训练 ControlNet 权重严格对齐直接用于后续训练或推理无需二次加工。不硬编码批量处理脚本由于不同开发者组织数据集的习惯千差万别官方刻意没有提供一刀切的批量脚本而是把gradio_annotator.py写得超级可读让使用者通过简单修改即可适配自己的标注流程。因此本工具的定位是标注生成器而非数据集管线理解这一点有助于你在自己的项目中正确地复用这些检测器。二、快速启动一条命令打开标注界面环境就绪后在仓库根目录执行python gradio_annotator.py即可启动 Gradio Web UI默认监听0.0.0.0见 gradio_annotator.py 中的block.launch(server_name0.0.0.0)可通过局域网访问。首次运行时各检测器会自动下载对应的预训练权重到 annotator/ckpts/ 目录下载逻辑统一封装在basicsr.utils.download_util.load_file_from_url中包括检测器权重文件下载来源HEDControlNetHED.pthannotator/hed/init.pyMLSDmlsd_large_512_fp32.pthannotator/mlsd/init.pyMIDASdpt_hybrid-midas-501f0c75.ptannotator/midas/api.pyOpenPosebody_pose_model.pth、hand_pose_model.pthannotator/openpose/init.pyUniformerupernet_global_small.pthannotator/uniformer/init.pyCanny 为纯 OpenCV 实现cv2.Canny无需下载权重见 annotator/canny/init.py。若网络受限无法访问权重地址可在annotator/ckpts/下预置对应文件后重试。UI 中共包含六个标注接口分别对应一个预训练 ControlNet 模型的条件输入类型。下面逐一详解。三、六大标注接口详解所有接口共享同一套交互模式左侧为上传图像 参数滑块 Run 按钮右侧为结果画廊点击 Run 后参数通过run_button.click(fn..., inputs[...], outputs[gallery])绑定到对应的 Python 检测函数见 gradio_annotator.py。输入图像统一以 numpy 数组传入先经过HWC3与resize_image预处理。3.1 Canny EdgeCanny 边缘界面参数gradio_annotator.py参数范围默认值说明low_threshold1–255100Canny 低阈值high_threshold1–255200Canny 高阈值resolution256–1024512步长 64处理分辨率源码实现Canny 检测器极简直接封装 OpenCVclass CannyDetector: def __call__(self, img, low_threshold, high_threshold): return cv2.Canny(img, low_threshold, high_threshold)见 annotator/canny/init.py关键注意事项Canny 输出为二值边缘图务必注意黑边白底与白边黑底两种约定的区别。ControlNet 各训练/推理脚本对边缘图的极性有明确要求例如与官方示例canny2image对齐时使用的是黑底白线还是白底黑线直接决定控制效果在生成标注后应与目标模型约定保持一致。3.2 HED EdgeHED 软边缘界面参数仅resolution256–1024默认 512。源码实现仓库使用的是改进版 HED 模型ControlNetHED_Apache2Apache-2.0 许可基于 5 个DoubleConvBlock构建每个 block 输出特征图的同时投影出 1 通道边缘响应最终通过多尺度响应取平均 Sigmoid 得到软边缘图见 annotator/hed/init.py。两点与官方 HED 的差异值得注意文件头部注释明确说明该实现生成更平滑的边缘比 Saining Xie 官方实现更适合 ControlNet 及一般 image-to-image 任务这是一个RGB 输入模型而非 BGR因此与 Gradio 的 RGB 图像协议天然兼容。关键注意事项与 Canny 相同HED 输出同样是二值化软边缘需注意黑边白底/白边黑底的极性约定。3.3 MLSD Edge直线段检测界面参数gradio_annotator.py参数范围默认值说明value_threshold0.01–2.00.1线段得分阈值thr_vdistance_threshold0.01–20.00.1线段距离阈值thr_dresolution256–1024384步长 64处理分辨率源码实现MLSD 检测器加载 MobileV2_MLSD_Large 网络见 annotator/mlsd/models/mbv2_mlsd_large.py通过pred_lines提取直线段并在黑色画布上以 1px 白色线条绘制见 annotator/mlsd/init.pyfor line in lines: x_start, y_start, x_end, y_end [int(val) for val in line] cv2.line(img_output, (x_start, y_start), (x_end, y_end), [255, 255, 255], 1)关键注意事项MLSD 专长于几何结构建筑、室内场景的直线边缘对曲线轮廓不敏感输出同为边缘图需注意黑白极性约定。3.4 MIDAS Depth and Normal深度与法线界面参数gradio_annotator.py参数范围默认值说明alpha0.1–20.06.2法线图 z 轴分量缩放系数resolution256–1024384步长 64处理分辨率源码实现MIDAS 检测器使用DPT-Hybrid模型dpt_hybrid-midas-501f0c75.pt见 annotator/midas/api.py一次前向同时产出深度图与法线图因此该接口的 gallery 会返回两张结果图见 annotator/midas/init.py深度图将预测深度归一化到 0–255 的灰度图法线图对深度图做 Sobel 梯度x、y 方向z 分量取常数alpha归一化后按(normal * 127.5 127.5)编码为 RGB即法线图以颜色方向编码表面朝向。关键注意事项法线图以 RGB 颜色编码方向信息务必注意 RGB 与 BGR 通道顺序约定。若后续模型训练时按 BGR 读取而标注按 RGB 生成或反之会导致法线方向整体错乱、控制失效。3.5 Openpose人体姿态界面参数gradio_annotator.py参数范围默认值说明detect hand布尔开关False关闭是否检测手部关键点resolution256–1024512步长 64处理分辨率源码实现OpenPose 检测器集成 CMU OpenPose 思路的 PyTorch 实现包含Body身体关键点与Hand手部关键点两个子网络见 annotator/openpose/init.py。调用时先将 RGB 图像反转为 BGRoriImg[:, :, ::-1]供内部模型推理结果以骨架线条绘制到黑色画布上当handTrue时还会基于身体关键点定位手部区域并追加绘制手部关键点连线。关键注意事项姿态图同样以颜色区分不同关键点/连接属于伪彩色语义图务必注意 RGB 与 BGR 通道顺序约定。另外官方生产级 ControlNet 模型训练时手部姿态选项是关闭的文档原文For our production-ready model, the hand pose option is turned off.界面中detect hand默认值为 False 正是与此对齐——若你想训练自己的含手部姿态控制模型可手动开启该开关重新生成标注。3.6 Uniformer Segmentation语义分割界面参数仅resolution256–1024默认 512。源码实现Uniformer 检测器加载upernet_global_small.pth检查点配合仓库内置的 mmseg 配置 annotator/uniformer/exp/upernet_global_small/config.py 完成推理输出为 ADE20K 数据集的彩色分割结果get_palette(ade)见 annotator/uniformer/init.py。分割图中每个颜色区域对应一个语义类别天空、建筑、草地等。关键注意事项分割图同样是按调色板编码类别的彩色图务必注意 RGB 与 BGR 通道顺序约定避免类别颜色被错误置换。四、贯穿全部接口的两条色彩约定综合文档与源码六个接口背后有两条全局性约定是生成可用标注的关键边缘类Canny / HED / MLSD黑白极性约定黑边白底与白边黑底在视觉上互为反色但对 ControlNet 而言是完全不同的输入分布。使用时需对照目标模型的训练约定例如官方canny2image、scribble2image等脚本的预处理选择或翻转极性。语义/几何类MIDAS 法线 / OpenPose / Uniformer 分割RGB 与 BGR 约定这三类输出都以 RGB 通道编码信息法线方向、关键点颜色、类别颜色。OpenCV 默认以 BGR 读取图像、Gradio 以 RGB 传输图像两者的混用是这类标注最常见的错误来源。仓库在 annotator/openpose/init.py 中专门做了oriImg[:, :, ::-1]的通道翻转正是为了在内部推理与外部 RGB 协议之间保持一致。五、进阶把 Gradio 标注器改造成你自己的批量管线文档明确建议不提供批量脚本但gradio_annotator.py可读性极高改造即可用于批量标注。理解以下三个机制改造会非常顺畅5.1 检测器采用懒加载Lazy Loading单例模式每个接口函数都维护一个全局模型变量首次调用时才导入并实例化检测器后续复用见 gradio_annotator.pymodel_canny None def canny(img, res, l, h): img resize_image(HWC3(img), res) global model_canny if model_canny is None: from annotator.canny import CannyDetector model_canny CannyDetector() result model_canny(img, l, h) return [result]这意味着六个检测器可以直接 import 到你的脚本中复用from annotator.canny import CannyDetector等无需启动 Gradio。模型只加载一次适合循环处理整批图像。5.2 统一的图像预处理所有标注函数进入检测器前都经过 annotator/util.py 的两个工具HWC3(x)将输入统一为H x W x 3的 uint8 数组——灰度图复制为三通道、RGBA 图按 alpha 通道合成到白底resize_image(input_image, resolution)以短边为基准等比缩放并把宽高取整到 64 的倍数int(np.round(H / 64.0)) * 64放大用INTER_LANCZOS4、缩小用INTER_AREA。64 对齐是扩散模型含 ControlNetU-Net 下采样结构的硬性要求批量标注时务必沿用这一约束。5.3 批量改造的最小模式以 Canny 为例批量标注只需剥离 Gradio 外壳、直接循环from annotator.util import HWC3, resize_image from annotator.canny import CannyDetector detector CannyDetector() # 只加载一次 for path in image_list: img HWC3(load_image(path)) # 你的图像读取逻辑 img resize_image(img, 512) # 短边对齐 512宽高 64 对齐 edge detector(img, 100, 200) # low100, high200 save(edge, output_path) # 你的图像写出逻辑其余五个检测器的调用签名与上述对应HEDdetector()(img)、MLSDdetector()(img, thr_v, thr_d)、MidasDetector()(img, alpha)返回深度图与法线图二元组、OpenposeDetector()(img, hand)返回画布与关键点数据、UniformerDetector()(img)。通过这种方式你可以自由组织目录结构、文件名与格式约定构建属于自己的标注流水线。六、常见问题速查模型下载失败怎么办六个检测器均从 HuggingFace 拉取权重到 annotator/ckpts/可手动下载对应权重放入该目录检测器检测到文件存在后会跳过下载。为什么 OpenPose 没有手部关键点生产级模型默认关闭手部检测detect hand默认 False需要手部姿态数据时请手动开启。生成结果颜色/边缘看起来不对先检查两类约定边缘图的黑白极性法线/姿态/分割图的 RGB/BGR 通道顺序。批量处理该用哪个入口直接 importannotator下的检测器类见 5.1 节Gradio 仅作可视化调试入口。通过以上六个接口与两条约定你已可以复现官方训练数据的标注流程并为自己的 ControlNet 微调任务生成风格一致、可直接对齐预训练模型的条件控制图。【免费下载链接】ControlNetLet us control diffusion models!项目地址: https://gitcode.com/gh_mirrors/co/ControlNet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ControlNet 自动标注实战指南：用 gradio_annotator.py 一键生成六大条件控制图
ControlNet 自动标注实战指南用 gradio_annotator.py 一键生成六大条件控制图【免费下载链接】ControlNetLet us control diffusion models!项目地址: https://gitcode.com/gh_mirrors/co/ControlNet本指南围绕 ControlNet 仓库中的 docs/annotator.md 展开系统讲解如何利用官方提供的 Gradio 标注工具gradio_annotator.py为训练 ControlNet 模型生成与预训练权重严格对齐的六类条件控制图Canny / HED / MLSD / MIDAS / OpenPose / Uniformer。读完本文你将掌握标注工具的启动方式、每个接口的参数语义与源码实现原理以及边缘图黑白底约定、法线与姿态图的RGB/BGR约定等关键细节能够据此改造脚本进行自定义批量标注。一、自动标注让条件控制图与预训练模型严格对齐ControlNet 的核心思想是在扩散模型如 Stable Diffusion的 UNet 主干上注入可控条件而训练与推理效果高度依赖输入条件图annotation与预训练模型训练时看到的数据分布一致。官方因此在仓库中内置了一套自动标注Automatic Annotations工具链其入口文档即 docs/annotator.md。该文档明确说明了两点设计意图提供与生产级模型对齐的标注能力gradio_annotator.py中的每个检测器其输出格式、色彩约定都与仓库配套的预训练 ControlNet 权重严格对齐直接用于后续训练或推理无需二次加工。不硬编码批量处理脚本由于不同开发者组织数据集的习惯千差万别官方刻意没有提供一刀切的批量脚本而是把gradio_annotator.py写得超级可读让使用者通过简单修改即可适配自己的标注流程。因此本工具的定位是标注生成器而非数据集管线理解这一点有助于你在自己的项目中正确地复用这些检测器。二、快速启动一条命令打开标注界面环境就绪后在仓库根目录执行python gradio_annotator.py即可启动 Gradio Web UI默认监听0.0.0.0见 gradio_annotator.py 中的block.launch(server_name0.0.0.0)可通过局域网访问。首次运行时各检测器会自动下载对应的预训练权重到 annotator/ckpts/ 目录下载逻辑统一封装在basicsr.utils.download_util.load_file_from_url中包括检测器权重文件下载来源HEDControlNetHED.pthannotator/hed/init.pyMLSDmlsd_large_512_fp32.pthannotator/mlsd/init.pyMIDASdpt_hybrid-midas-501f0c75.ptannotator/midas/api.pyOpenPosebody_pose_model.pth、hand_pose_model.pthannotator/openpose/init.pyUniformerupernet_global_small.pthannotator/uniformer/init.pyCanny 为纯 OpenCV 实现cv2.Canny无需下载权重见 annotator/canny/init.py。若网络受限无法访问权重地址可在annotator/ckpts/下预置对应文件后重试。UI 中共包含六个标注接口分别对应一个预训练 ControlNet 模型的条件输入类型。下面逐一详解。三、六大标注接口详解所有接口共享同一套交互模式左侧为上传图像 参数滑块 Run 按钮右侧为结果画廊点击 Run 后参数通过run_button.click(fn..., inputs[...], outputs[gallery])绑定到对应的 Python 检测函数见 gradio_annotator.py。输入图像统一以 numpy 数组传入先经过HWC3与resize_image预处理。3.1 Canny EdgeCanny 边缘界面参数gradio_annotator.py参数范围默认值说明low_threshold1–255100Canny 低阈值high_threshold1–255200Canny 高阈值resolution256–1024512步长 64处理分辨率源码实现Canny 检测器极简直接封装 OpenCVclass CannyDetector: def __call__(self, img, low_threshold, high_threshold): return cv2.Canny(img, low_threshold, high_threshold)见 annotator/canny/init.py关键注意事项Canny 输出为二值边缘图务必注意黑边白底与白边黑底两种约定的区别。ControlNet 各训练/推理脚本对边缘图的极性有明确要求例如与官方示例canny2image对齐时使用的是黑底白线还是白底黑线直接决定控制效果在生成标注后应与目标模型约定保持一致。3.2 HED EdgeHED 软边缘界面参数仅resolution256–1024默认 512。源码实现仓库使用的是改进版 HED 模型ControlNetHED_Apache2Apache-2.0 许可基于 5 个DoubleConvBlock构建每个 block 输出特征图的同时投影出 1 通道边缘响应最终通过多尺度响应取平均 Sigmoid 得到软边缘图见 annotator/hed/init.py。两点与官方 HED 的差异值得注意文件头部注释明确说明该实现生成更平滑的边缘比 Saining Xie 官方实现更适合 ControlNet 及一般 image-to-image 任务这是一个RGB 输入模型而非 BGR因此与 Gradio 的 RGB 图像协议天然兼容。关键注意事项与 Canny 相同HED 输出同样是二值化软边缘需注意黑边白底/白边黑底的极性约定。3.3 MLSD Edge直线段检测界面参数gradio_annotator.py参数范围默认值说明value_threshold0.01–2.00.1线段得分阈值thr_vdistance_threshold0.01–20.00.1线段距离阈值thr_dresolution256–1024384步长 64处理分辨率源码实现MLSD 检测器加载 MobileV2_MLSD_Large 网络见 annotator/mlsd/models/mbv2_mlsd_large.py通过pred_lines提取直线段并在黑色画布上以 1px 白色线条绘制见 annotator/mlsd/init.pyfor line in lines: x_start, y_start, x_end, y_end [int(val) for val in line] cv2.line(img_output, (x_start, y_start), (x_end, y_end), [255, 255, 255], 1)关键注意事项MLSD 专长于几何结构建筑、室内场景的直线边缘对曲线轮廓不敏感输出同为边缘图需注意黑白极性约定。3.4 MIDAS Depth and Normal深度与法线界面参数gradio_annotator.py参数范围默认值说明alpha0.1–20.06.2法线图 z 轴分量缩放系数resolution256–1024384步长 64处理分辨率源码实现MIDAS 检测器使用DPT-Hybrid模型dpt_hybrid-midas-501f0c75.pt见 annotator/midas/api.py一次前向同时产出深度图与法线图因此该接口的 gallery 会返回两张结果图见 annotator/midas/init.py深度图将预测深度归一化到 0–255 的灰度图法线图对深度图做 Sobel 梯度x、y 方向z 分量取常数alpha归一化后按(normal * 127.5 127.5)编码为 RGB即法线图以颜色方向编码表面朝向。关键注意事项法线图以 RGB 颜色编码方向信息务必注意 RGB 与 BGR 通道顺序约定。若后续模型训练时按 BGR 读取而标注按 RGB 生成或反之会导致法线方向整体错乱、控制失效。3.5 Openpose人体姿态界面参数gradio_annotator.py参数范围默认值说明detect hand布尔开关False关闭是否检测手部关键点resolution256–1024512步长 64处理分辨率源码实现OpenPose 检测器集成 CMU OpenPose 思路的 PyTorch 实现包含Body身体关键点与Hand手部关键点两个子网络见 annotator/openpose/init.py。调用时先将 RGB 图像反转为 BGRoriImg[:, :, ::-1]供内部模型推理结果以骨架线条绘制到黑色画布上当handTrue时还会基于身体关键点定位手部区域并追加绘制手部关键点连线。关键注意事项姿态图同样以颜色区分不同关键点/连接属于伪彩色语义图务必注意 RGB 与 BGR 通道顺序约定。另外官方生产级 ControlNet 模型训练时手部姿态选项是关闭的文档原文For our production-ready model, the hand pose option is turned off.界面中detect hand默认值为 False 正是与此对齐——若你想训练自己的含手部姿态控制模型可手动开启该开关重新生成标注。3.6 Uniformer Segmentation语义分割界面参数仅resolution256–1024默认 512。源码实现Uniformer 检测器加载upernet_global_small.pth检查点配合仓库内置的 mmseg 配置 annotator/uniformer/exp/upernet_global_small/config.py 完成推理输出为 ADE20K 数据集的彩色分割结果get_palette(ade)见 annotator/uniformer/init.py。分割图中每个颜色区域对应一个语义类别天空、建筑、草地等。关键注意事项分割图同样是按调色板编码类别的彩色图务必注意 RGB 与 BGR 通道顺序约定避免类别颜色被错误置换。四、贯穿全部接口的两条色彩约定综合文档与源码六个接口背后有两条全局性约定是生成可用标注的关键边缘类Canny / HED / MLSD黑白极性约定黑边白底与白边黑底在视觉上互为反色但对 ControlNet 而言是完全不同的输入分布。使用时需对照目标模型的训练约定例如官方canny2image、scribble2image等脚本的预处理选择或翻转极性。语义/几何类MIDAS 法线 / OpenPose / Uniformer 分割RGB 与 BGR 约定这三类输出都以 RGB 通道编码信息法线方向、关键点颜色、类别颜色。OpenCV 默认以 BGR 读取图像、Gradio 以 RGB 传输图像两者的混用是这类标注最常见的错误来源。仓库在 annotator/openpose/init.py 中专门做了oriImg[:, :, ::-1]的通道翻转正是为了在内部推理与外部 RGB 协议之间保持一致。五、进阶把 Gradio 标注器改造成你自己的批量管线文档明确建议不提供批量脚本但gradio_annotator.py可读性极高改造即可用于批量标注。理解以下三个机制改造会非常顺畅5.1 检测器采用懒加载Lazy Loading单例模式每个接口函数都维护一个全局模型变量首次调用时才导入并实例化检测器后续复用见 gradio_annotator.pymodel_canny None def canny(img, res, l, h): img resize_image(HWC3(img), res) global model_canny if model_canny is None: from annotator.canny import CannyDetector model_canny CannyDetector() result model_canny(img, l, h) return [result]这意味着六个检测器可以直接 import 到你的脚本中复用from annotator.canny import CannyDetector等无需启动 Gradio。模型只加载一次适合循环处理整批图像。5.2 统一的图像预处理所有标注函数进入检测器前都经过 annotator/util.py 的两个工具HWC3(x)将输入统一为H x W x 3的 uint8 数组——灰度图复制为三通道、RGBA 图按 alpha 通道合成到白底resize_image(input_image, resolution)以短边为基准等比缩放并把宽高取整到 64 的倍数int(np.round(H / 64.0)) * 64放大用INTER_LANCZOS4、缩小用INTER_AREA。64 对齐是扩散模型含 ControlNetU-Net 下采样结构的硬性要求批量标注时务必沿用这一约束。5.3 批量改造的最小模式以 Canny 为例批量标注只需剥离 Gradio 外壳、直接循环from annotator.util import HWC3, resize_image from annotator.canny import CannyDetector detector CannyDetector() # 只加载一次 for path in image_list: img HWC3(load_image(path)) # 你的图像读取逻辑 img resize_image(img, 512) # 短边对齐 512宽高 64 对齐 edge detector(img, 100, 200) # low100, high200 save(edge, output_path) # 你的图像写出逻辑其余五个检测器的调用签名与上述对应HEDdetector()(img)、MLSDdetector()(img, thr_v, thr_d)、MidasDetector()(img, alpha)返回深度图与法线图二元组、OpenposeDetector()(img, hand)返回画布与关键点数据、UniformerDetector()(img)。通过这种方式你可以自由组织目录结构、文件名与格式约定构建属于自己的标注流水线。六、常见问题速查模型下载失败怎么办六个检测器均从 HuggingFace 拉取权重到 annotator/ckpts/可手动下载对应权重放入该目录检测器检测到文件存在后会跳过下载。为什么 OpenPose 没有手部关键点生产级模型默认关闭手部检测detect hand默认 False需要手部姿态数据时请手动开启。生成结果颜色/边缘看起来不对先检查两类约定边缘图的黑白极性法线/姿态/分割图的 RGB/BGR 通道顺序。批量处理该用哪个入口直接 importannotator下的检测器类见 5.1 节Gradio 仅作可视化调试入口。通过以上六个接口与两条约定你已可以复现官方训练数据的标注流程并为自己的 ControlNet 微调任务生成风格一致、可直接对齐预训练模型的条件控制图。【免费下载链接】ControlNetLet us control diffusion models!项目地址: https://gitcode.com/gh_mirrors/co/ControlNet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考