Add [controlnet] extra for annotator dependencies (#1671)

Co-authored-by: Sun Longfei <zhiwuyazhe-z@users.noreply.github.com>

Author: zhiwuyazhe-z

diffsynth/utils/controlnet/annotator.py

@@ -9,31 +9,39 @@
 class Annotator:
     def __init__(self, processor_id: Processor_id, model_path="models/Annotators", detect_resolution=None, device=get_device_type(), skip_processor=False):
         if not skip_processor:
-            if processor_id == "canny":
-                from controlnet_aux.processor import CannyDetector
-                self.processor = CannyDetector()
-            elif processor_id == "depth":
-                from controlnet_aux.processor import MidasDetector
-                self.processor = MidasDetector.from_pretrained(model_path).to(device)
-            elif processor_id == "softedge":
-                from controlnet_aux.processor import HEDdetector
-                self.processor = HEDdetector.from_pretrained(model_path).to(device)
-            elif processor_id == "lineart":
-                from controlnet_aux.processor import LineartDetector
-                self.processor = LineartDetector.from_pretrained(model_path).to(device)
-            elif processor_id == "lineart_anime":
-                from controlnet_aux.processor import LineartAnimeDetector
-                self.processor = LineartAnimeDetector.from_pretrained(model_path).to(device)
-            elif processor_id == "openpose":
-                from controlnet_aux.processor import OpenposeDetector
-                self.processor = OpenposeDetector.from_pretrained(model_path).to(device)
-            elif processor_id == "normal":
-                from controlnet_aux.processor import NormalBaeDetector
-                self.processor = NormalBaeDetector.from_pretrained(model_path).to(device)
-            elif processor_id == "tile" or processor_id == "none" or processor_id == "inpaint":
+            if processor_id == "tile" or processor_id == "none" or processor_id == "inpaint":
                 self.processor = None
             else:
-                raise ValueError(f"Unsupported processor_id: {processor_id}")
+                if processor_id not in ("canny", "depth", "softedge", "lineart", "lineart_anime", "openpose", "normal"):
+                    raise ValueError(f"Unsupported processor_id: {processor_id}")
+                try:
+                    import controlnet_aux  # noqa: F401
+                except ImportError:
+                    raise ImportError(
+                        "The ControlNet annotator detectors require the 'controlnet_aux' package. "
+                        "Install it with `pip install -e .[controlnet]`."
+                    ) from None
+                if processor_id == "canny":
+                    from controlnet_aux.processor import CannyDetector
+                    self.processor = CannyDetector()
+                elif processor_id == "depth":
+                    from controlnet_aux.processor import MidasDetector
+                    self.processor = MidasDetector.from_pretrained(model_path).to(device)
+                elif processor_id == "softedge":
+                    from controlnet_aux.processor import HEDdetector
+                    self.processor = HEDdetector.from_pretrained(model_path).to(device)
+                elif processor_id == "lineart":
+                    from controlnet_aux.processor import LineartDetector
+                    self.processor = LineartDetector.from_pretrained(model_path).to(device)
+                elif processor_id == "lineart_anime":
+                    from controlnet_aux.processor import LineartAnimeDetector
+                    self.processor = LineartAnimeDetector.from_pretrained(model_path).to(device)
+                elif processor_id == "openpose":
+                    from controlnet_aux.processor import OpenposeDetector
+                    self.processor = OpenposeDetector.from_pretrained(model_path).to(device)
+                elif processor_id == "normal":
+                    from controlnet_aux.processor import NormalBaeDetector
+                    self.processor = NormalBaeDetector.from_pretrained(model_path).to(device)
         else:
             self.processor = None
 

docs/en/Pipeline_Usage/Setup.md

@@ -23,6 +23,7 @@ To keep the framework lightweight, the base installation only installs the neces
 * `[npu]`: For Ascend NPU devices with x86 architecture.
 * `[npu_aarch64]`: For Ascend NPU devices with aarch64/ARM architecture.
 * Dependencies of specific models
+   * `[controlnet]`: For the ControlNet annotator detectors (Canny, depth, OpenPose, etc.) used by the ControlNet examples under `examples/flux` and `examples/qwen_image`.
    * `[infiniteyou]`: https://arxiv.org/abs/2503.16418
    * `[ses]`: https://arxiv.org/abs/2602.03208
    * `[nexusgen]`: https://arxiv.org/pdf/2504.21356

docs/zh/Pipeline_Usage/Setup.md

@@ -23,6 +23,7 @@ pip install diffsynth
 * `[npu]`: 用于 x86 架构的 Ascend NPU 设备
 * `[npu_aarch64]`: 用于 aarch64/ARM 架构的 Ascend NPU 设备
 * 特定模型的依赖
+   * `[controlnet]`: 用于 `examples/flux` 和 `examples/qwen_image` 下 ControlNet 示例所需的 ControlNet 注解器（Canny、深度图、OpenPose 等）
    * `[infiniteyou]`: https://arxiv.org/abs/2503.16418
    * `[ses]`: https://arxiv.org/abs/2602.03208
    * `[nexusgen]`: https://arxiv.org/pdf/2504.21356

pyproject.toml

@@ -66,6 +66,9 @@ npu_aarch64 = [
     "torch-npu==2.7.1",
     "torchvision==0.22.1"
 ]
+controlnet = [
+    "controlnet_aux"
+]
 infiniteyou = [
     "insightface",
     "facexlib"