Zoey - 灯光手柄控制

ZoeyLightHandle is the node that lets you place light like you're aiming a real lamp. You drag a colored handle over your image in the node body - around the subject's face, over a product, wherever you want illumination - and out the other side come two things at once: a soft radial mask marking the light's position and reach, and a written light prompt describing the source, color, direction, and intensity. One is for masking-based relight/composite pipelines, the other is for prompt-driven editing. It's the interactive cousin of ZoeyMaskDrawBox: same idea, but instead of deriving a region from a mask, you just... point.

It's part of comfyui-ZoeyTool's image-edit family, and it sits naturally beside IC-Light-style relighting where a light-position mask or a precise light description is half the battle. Rather than hand-drawing a radial gradient with five math nodes, you drop a handle and iterate visually.

How it works

The classic inputs are azimuth, elevation, and ball_size - 3D angles plus reach that the node projects onto a 2D position on the image (azimuth left/right, elevation up/down). intensity (0–10), light_color (hex, default white), handle_shape (circle/square/diamond/triangle), and a light_type dropdown of 16 types (studio, god rays, soft/hard, rim, backlight…) round out the description.

Under the hood the node builds a smooth, distance-falloff mask (a soft-edged radial gradient - the _generate_shape_mask math), and also renders a colored handle onto a preview image so what you see matches what you're describing. The outputs:

• light_mask - the radial MASK at your handle's position. Wire it into a masking/relight pipeline (or union it with a subject mask for targeted lighting).
• light_prompt - an assembled natural-language description, e.g. "hard light, #FFD700-colored light source from upper-left front of the subject, mid-range, moderate intensity (coord…)". Written for a prompt-based relight/edit model.
• preview_image - your image with the handle drawn on, so you can confirm placement.

For precision work there's handles_json, letting you define multiple handles with per-handle position/color/size/type - the mask output becomes a union of all of them and the prompt describes each in turn.

behind_subject + an optional subject_mask flip the light behind the subject (for backlight/rim effects) instead of in front - and as with the mask box, if you don't supply a subject mask it can fall back to rembg to cut the subject out automatically.

Installing it

comfyui-ZoeyTool, standard:

cd ComfyUI/custom_nodes
git clone https://github.com/liangzoey/comfyui-ZoeyTool.git
cd comfyui-ZoeyTool
pip install -r requirements.txt

Restart ComfyUI (or ComfyUI Manager → comfyui-ZoeyTool). No model downloads for the core feature; rembg (installed by the pack's requirements) only kicks in on first use if you enable behind_subject without a subject mask.

Where people get burned

The azimuth/elevation controls are the fiddly bit: they map to 2D position through a projection, so the number in azimuth isn't literally "pixels to the right" - most people ignore the numbers entirely and drag the handle on the preview, which is the intended workflow. Second, light_prompt is Chinese-language output (as with the sibling box node) - fine for the workflow it was built in, but paste it into an English-only prompt model and you'll be translating first. Third, if the mask looks tiny or huge relative to the area you want lit, that's ball_size - it ranges 0.02 (pinpoint) to 1.0 (fills the frame). And remember the handle is drawn into preview_image as a visible colored blob: use the mask output, not the preview, if your downstream step wants clean lighting geometry.