ZImage SDNQ Control Sampler

ZImageSDNQSamplerControl is where the pack's control side actually pays off. It takes a ZIMAGE_CONTROL_PIPELINE from ZImageSDNQControlPipelineLoader, a control_image - the Canny edge map, depth map, or whatever condition you've prepared - and a prompt, then generates an image whose structure follows the control. This is Z-Image doing ControlNet, and it's the node that separates "I hope the model feels like doing what I asked" from "the composition is decided, go fill it in."

The mechanism is the Fun ControlNet Union pipeline: the control image is encoded into the control transformer's channels, and during denoising the model's attention layers are steered toward reproducing that structure. The prompt still controls what gets drawn; the control decides where it goes.

Inputs that matter

• control_image - the required condition. What you feed it decides what kind of control you get. Canny map → hard structure. Depth map → spatial layout. This comes straight from the pack's preprocessors (ZImageSDNQCannyPreprocess, ZImageSDNQDepthPreprocess) or from anywhere else that produces the right kind of map.
• control_context_scale (default 0.8, 0–2) - your control-strength dial, and the most important input on this node. Because the union ControlNet was trained on the distilled Turbo by a team that didn't have the base checkpoint, cranking it to 1.0+ across all steps costs quality. The community's canonical workaround is the step cutoff - strong control early, released for the last steps. This pack doesn't expose step ranges, so control_context_scale is doing all that work by itself. Start at 0.8, and if output looks slavish or overcooked, drop it to 0.6–0.7 before you change anything else.
• prompt / negative_prompt - the usual distilled-model caveat: at guidance_scale 0 the negative does nothing. The prompt should describe the content you want inside the structure.
• steps (default 8) and guidance_scale (default 0) - the standard Turbo contract.
• seed / num_images - standard; multiple images per run all follow the same control.
• image + mask (both optional) - provide both and this node becomes control-inpainting: the mask region gets regenerated while the rest is preserved. The mask requires the image - the node will error if you give it a mask without one.

Output is an images tensor of IMAGE type, straight into SaveImage or PreviewImage. No VAE decode needed - the pipeline handles it.

The classic workflow

The pack's example (zimage_sdnq_control_canny.json) wires it exactly as expected:

LoadImage → ZImageSDNQCannyPreprocess → ZImageSDNQSamplerControl → SaveImage
ZImageSDNQControlPipelineLoader → (pipeline) ────────────────────┘

Swap the preprocessor for depth and you've got the other example. That's the whole shape of controlled Z-Image generation in this pack.

Gotchas

Two things. First, remember the cache rule: loading a control pipeline evicts the base pipeline and vice versa, so don't mix a base T2I sampler and this node in one graph expecting both to stay resident - you'll eat reloads on every queue. Second, the control_image and the pipeline's expected resolution should roughly agree. The sampler runs at the control image's resolution, and Z-Image's ~2MP ceiling still applies - control a 1024x1024 or 1216x832 canvas, not 4K.

Install: Manager (search "Z-Image SDNQ") or git clone https://github.com/GeneralShan/comfyui-zimage-sdnq into custom_nodes, restart, and for the control path pip install sdnq diffusers timm opencv-python-headless.