OpenCV spatialGradient_0

spatialGradient_0 is the node in this pack that actually feels like it belongs. It wraps cv2.spatialGradient, which computes the first-order image derivative in both the x and y directions at once, using a Scharr kernel - the sharp, rotation-aware edge operator that's a step up from a plain Sobel. You feed it a grayscale image, and it hands you two derivative maps: dx (horizontal changes) and dy (vertical changes).

That's a genuinely useful primitive for ComfyUI post-processing: build an edge map for masking, find where the image changes fastest, compute gradient magnitude or orientation downstream, or feed a derivative-based detail pass. It's the kind of deterministic, millisecond operation the post-processing layer is all about - no model, no sampling, just math you can see.

The inputs

• src (NPARRAY) - the image, and it must be single-channel. This is the one input in this pack that reliably trips people: OpenCV asserts on it, so you'll see error: (-215:Assertion failed) img.type() == CV_8UC1 in function if you feed it the BGR output of Image2Nparray directly. Fix it with a cvtColor conversion - README's code 6 is BGR2GRAY.
• ksize (INT) - the aperture size. OpenCV's spatialGradient uses Scharr, and for Scharr the only meaningful value is 3. Set it and forget it.
• borderType (INT) - how the kernel handles image borders. 0 = constant, 1 = replicate (repeat edge pixels), 4 = the default reflect-101. 4 is the safe starting point; 1 if you're getting weird edge artifacts.
• dx / dy (NPARRAY, optional) - out-parameters; leave them unwired, the outputs carry the result.

Outputs: nparray_0 (the x-derivative) and nparray_1 (the y-derivative), each the same shape as src.

How to use it

Image2Nparray → cvtColor (code 6, BGR2GRAY) → spatialGradient_0 → then either convert one derivative back to an image for preview, or combine them - gradient magnitude is sqrt(dx² + dy²), which you can do in a Python node or another OpenCV op. Derivative maps are float data with negative values, so rendering one directly through Nparrays2Image will look like noise until you normalize it; that's expected, not a bug.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/geroldmeisinger/opencv-comfyui
pip install opencv-contrib-python

or ComfyUI Manager → "opencv-comfyui". Restart. Deps: opencv-contrib-python, numpy, torch - no downloads.

Troubleshooting

• error: (-215:Assertion failed) img.type() == CV_8UC1 - src isn't single-channel. This is the README's exact example: convert with cvtColor code 6 first.
• Edges blown out at the frame border - try borderType 1 (replicate) instead of the default.
• Output looks like static - it's a signed float derivative, not a display image; normalize before previewing.
• Cannot import name 'guidedFilter' at startup - conflicting OpenCV packages; README links the fix.

If you're doing anything gradient-based - edges, structure, detail - this is the workhorse. And it's the reminder that a properly-grayscaled pipeline is the pack's real onboarding test.