fn_registry/python/functions/ml/comfyui_inject_controlnet.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
comfyui_inject_controlnet	function	py	ml	1.0.0	pure	def comfyui_inject_controlnet(workflow: dict, control_image: str, cn_name: str, *, strength: float = 1.0, positive_node: str | None = None) -> dict	Inyecta una rama ControlNet (LoadImage + ControlNetLoader + ControlNetApply) en un workflow ComfyUI ya construido (API format), repuntando el KSampler.positive al condicionamiento condicionado por la imagen de control. Version ENCADENABLE-sobre-dict del builder comfyui_build_controlnet_workflow (que construye desde cero). Pensada para componerse con inject_lora/inject_ipadapter/inject_hires_fix. Pura: no muta el dict de entrada.	comfyui comfyui-skill ml controlnet stable-diffusion workflow				false			name desc workflow dict en API format (ej. salida de comfyui_build_txt2img_workflow). No se muta; se devuelve una copia. name desc control_image Nombre del archivo de la imagen de control en input/ del servidor ComfyUI (mapa preprocesado canny/depth/openpose). No puede estar vacio (raise ValueError). name desc cn_name Nombre del modelo ControlNet en models/controlnet/ (control_net_name de ControlNetLoader). name desc strength Fuerza con la que el ControlNet condiciona la generacion (0.0 nula, 1.0 plena). keyword-only. name desc positive_node node_id cuya salida CONDITIONING (slot 0) sera el positivo de entrada del ControlNetApply. Si None, se detecta la fuente que hoy alimenta el KSampler.positive. keyword-only.	copia del workflow con LoadImage + ControlNetLoader + ControlNetApply insertados y el KSampler.positive repuntado a la salida del ControlNetApply. node_ids = max id numerico + 1/2/3.	true	inyecta los 3 nodos (LoadImage, ControlNetLoader, ControlNetApply) y repunta KSampler.positive ControlNetApply toma el positivo original como conditioning respeta strength y cn_name no muta el dict de entrada (pureza) control_image vacio lanza ValueError workflow sin KSampler lanza ValueError api format valido	python/functions/ml/tests/test_comfyui_inject_controlnet.py	python/functions/ml/comfyui_inject_controlnet.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from ml.comfyui_build_txt2img_workflow import comfyui_build_txt2img_workflow
from ml.comfyui_inject_controlnet import comfyui_inject_controlnet

base = comfyui_build_txt2img_workflow("IMG_dreamshaper_8.safetensors", "a knight, dramatic light")
wf = comfyui_inject_controlnet(base, "pose_canny.png", "control_v11p_sd15_canny.pth", strength=0.8)
# KSampler.positive ahora viene de ControlNetApply(conditioning=CLIPTextEncode+, image=pose_canny)

Cuando usarla

Cuando quieras guiar la composicion (pose, bordes, profundidad) de un workflow txt2img ya construido con una imagen de control, sin reconstruir el grafo desde cero. Es la pieza ControlNet del mixer comfyui_compose_capabilities: encadena sobre el mismo dict que las LoRAs y el IPAdapter. Para construir un workflow ControlNet aislado desde cero usa comfyui_build_controlnet_workflow.

Gotchas

• Pura: no muta el workflow de entrada y NO valida que cn_name/control_image existan en el servidor. La imagen de control debe estar subida al input/ del servidor ANTES de submit; si no, el LoadImage falla en ejecucion.
• control_image obligatorio: una llamada con control_image="" lanza ValueError (ControlNet sin imagen de control no tiene sentido). Es el error path tipico cuando se activa la capacidad sin proveer el mapa de control.
• Repunta solo KSampler.positive. Si el workflow tiene varios KSampler, opera sobre el primero que encuentra; pasa positive_node para casos no triviales.
• Apila coste de VRAM (carga el modelo ControlNet). En 8GB con SD1.5 cabe junto a 1-2 LoRAs; combinandolo con IPAdapter + hires vigila la memoria.