Layer Effect: Gradient Overlay (MEC)

What it's for

The colour-overlay node with a ramp instead of a flat fill. Two stops, two alphas, one angle, and a blend mode - which between them cover an unreasonable amount of retouching: sunset casts, ambient occlusion fake-outs, sky-glow on a silhouette, product-photography falloff down a backdrop, the warm-to-cool split that makes a flat render look lit.

The per-stop alpha is the part worth understanding. A gradient overlay with both alphas at 255 is a pure wash, and it will look like a wash. Drop the far stop's alpha and the ramp dissolves into the original layer toward that end instead of tinting it - so you get a gradient that fades to untouched pixels inside the subject, which is how you do a believable light falloff without inventing a new mask.

How it works

The node builds a linear ramp across the layer: t runs 0 at one side to 1 at the other along angle, and both the colour and the alpha interpolate from the start pair to the end pair across it. That gradient is blended against a copy of the layer with blend_mode at opacity, and where the alpha ramp is below full, the result is crossfaded back toward the original layer proportionally. Then the composited layer is pasted onto the plate through the layer matte.

effect_mask is the resolved layer mask - after the invert and after any resize - the same contract as Color Overlay, not a coverage map of the ramp. If you need the ramp itself as a matte, that's Mask Gradient (MEC) in the same pack, and the two are worth pairing: same linear ramp maths, one producing colour, the other producing a mask.

The node also writes a description of the ramp (colours, alphas, angle) into the report string, which is mostly for the frontend preview but is a perfectly good way to check what you actually set on a node you duplicated three times and edited by accident.

Inputs

• layer_image, layer_mask (optional) - one of the two defines the layer; needs a layer mask is the error if you connect neither on an RGB image.
• invert_mask - defaults to true and inverts. With a standard ComfyUI mask (white = subject) leaving it on means your gradient lands on the background. Flip it and re-render.
• start_color, start_alpha (0–255) - the 0-end of the ramp.
• end_color, end_alpha - the 1-end.
• angle - −180 to 180. 0 runs the ramp horizontally (start on the left); 90 runs it top to bottom. The whole ramp spans the frame, so you can't make it shorter without changing the alphas or masking.
• blend_mode (30 modes), opacity, dissolve_seed - fixed seed on the dissolve mode so it doesn't crawl frame-to-frame, unlike upstream's per-frame reseed.
• background_image (optional) - the plate; empty means a transparent canvas, i.e. black in the RGB output.

Outputs: image, effect_mask, report.

Recipes worth stealing

• Light from above: start #FFD9A0 at alpha 200, end #1A2233 at alpha 90, angle 90, soft light, opacity 50. Instant lighting direction on a flat subject.
• Background falloff: start the plate's own colour at alpha 0, end near-black at alpha 160, angle 90, multiply, opacity 70. Reads as light falling off the backdrop, which is the cheapest way to make a flat product shot look photographed.
• Two-tone graphic: start and end fully opaque, normal, opacity 100, alphas 255 - a pure gradient fill over the subject. Great for posters, terrible for realism.

Because the alpha ramp mixes toward the original layer rather than toward transparency, this always stays inside the subject. Nothing bleeds onto the plate, which is why it's usually a better tool than a masked colour grade for shading.

Install

ComfyUI Manager → search "CustomNodePacks", or:

cd ComfyUI/custom_nodes
git clone https://github.com/Code2Collapse/ComfyUI-CustomNodePacks

Restart ComfyUI. Required pack dependencies are opencv-python, scipy, safetensors; the effect nodes themselves are tier 1 - pure tensor work under torch.no_grad(), no model, no VRAM, and no dependency on the upstream ComfyUI_LayerStyle pack this was ported from. As the README insists: check pip list before installing the pack's requirements, or you may replace ComfyUI's own torch.

Common issues

• The gradient is on the wrong side of the subject. invert_mask.
• The gradient looks like a flat wash. Both alphas at 255. Pull one of them down - that's the whole feature.
• You wanted a gradient mask, not a colour. Different node: Mask Gradient (MEC). This one outputs pixels plus the layer mask; it doesn't hand you the ramp.
• The ramp doesn't fade out where you need it to. The ramp always spans the full frame, so a fade that occupies a quarter of the image isn't expressible with angle alone. Mask the fade off with Mask Gradient's multiply input or accept the full-frame span.