Add [controlnet] extra and clarify annotator dependency errors

[zhiwuyazhe-z]

What

• Adds a controlnet extra (controlnet_aux) to pyproject.toml, documented in the docs/en and docs/zh Setup guides (listed under "Dependencies of specific models", consistent with [infiniteyou]/[ses]/[nexusgen]).
• Annotator now raises a clear ImportError (with the install command) when controlnet_aux is missing, instead of a ModuleNotFoundError deep inside the first detector import. tile/none/inpaint ids still work without the package, and unknown ids still raise ValueError.

Why

Fixes #1669: the ControlNet examples under examples/flux and examples/qwen_image fail after pip install -e ".[all]" because controlnet_aux is in no install extra.

How it was checked

• python3 -m py_compile on the changed module; tomllib parse of pyproject.toml (the controlnet extra resolves to ["controlnet_aux"]; all is unchanged by design, matching the documented convention).
• Negative path (clean venv without controlnet_aux): Annotator("openpose") raises the new ImportError with the install hint; Annotator("none") constructs with processor=None; Annotator("bogus") still raises ValueError.
• Positive path (venv with controlnet_aux==0.0.10): Annotator("canny") constructs a CannyDetector.

Related issue

• controlnet_aux is required by the Annotator examples but is not in any install extra #1669

[Copilot]

🟡 Changes recommended

The new Annotator import-guard currently masks non-install-related import failures and includes an extras install command that should be quoted to avoid shell globbing.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a dedicated controlnet optional dependency group and improves the runtime error surfaced by Annotator when ControlNet annotator detectors are requested without the needed package installed.

Changes:

• Add a [controlnet] optional-dependencies extra in pyproject.toml for controlnet_aux.
• Document the new [controlnet] extra in both English and Chinese setup guides under “Dependencies of specific models”.
• Update Annotator to raise a clearer ImportError with an install hint when a detector is requested but controlnet_aux is unavailable.

File summaries

File	Description
pyproject.toml	Adds a controlnet optional-dependencies extra for controlnet_aux.
docs/en/Pipeline_Usage/Setup.md	Documents the new [controlnet] extra and its intended use cases.
docs/zh/Pipeline_Usage/Setup.md	Same as English docs, for the Chinese setup guide.
diffsynth/utils/controlnet/annotator.py	Improves missing-dependency behavior for ControlNet annotator detectors while preserving tile/none/inpaint.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.