Repository navigation
NLMeans
Spatio-temporal non-local means denoiser on the CPU, ported from the CUDA NLMeans in vszipcu. Its interface, defaults and algorithm are those of KNLMeansCL. The output agrees closely with the GPU versions but isn't guaranteed bit-identical (see Differences).
Signature (argument order and defaults):
vszip.NLMeans(vnode clip[, int d=1, int a=2, int s=4, float h=1.2, string channels="auto", int wmode=0, float wref=1.0, vnode rclip=None])
It can replace core.knlm.KNLMeansCL with the same keyword arguments, minus the OpenCL device ones (device_type, device_id, ocl_x, ocl_y, ocl_r, info):
# KNLMeansCL
den = clip.knlm.KNLMeansCL(d=1, a=2, s=4, h=1.2)
# vszip
den = clip.vszip.NLMeans(d=1, a=2, s=4, h=1.2)
# chroma of a 4:2:0 clip, then luma
den = clip.vszip.NLMeans(h=1.0, channels="UV").vszip.NLMeans(h=1.2, channels="Y")-
clip:
Input clip: constant-format Gray, YUV or RGB, in 8–16-bit integer, 16-bit float or 32-bit float. -
d (int, default: 1, range: 0..16):
Temporal radius. Framenuses radiusmin(d, n), so frame 0 is spatial-only; past the end of the clip the last frame is repeated.0disables temporal filtering. -
a (int, default: 2, range: 1..64):
Search radius, in pixels of the processed plane. The(2a+1) x (2a+1)window must fit the plane. Work grows with(2a+1)^2 * (2d+1). -
s (int, default: 4, range: 0..8):
Similarity radius: patches of(2s+1) x (2s+1)pixels are compared. -
h (float, default: 1.2):
Filtering strength. Higher denoises more and keeps less detail. It uses the 8-bit scale at every bit depth, so don't rescale it for 16-bit or float clips. -
channels (string, default:
"auto"):
Planes to filter, sharing one patch distance:
"Y": luma only (default for Gray and YUV).
"UV": both chroma planes.
"YUV": all planes, 4:4:4 only.
"RGB": all planes (default for RGB). -
wmode (int, default: 0, range: 0..3):
Weighting function of the patch distancex:
0 =exp(-x)(Welsch)
1 =max(1 - x, 0)
2 =max(1 - x, 0)^2
3 =max(1 - x, 0)^8 -
wref (float, default: 1.0, range: >= 0):
Weight of the center pixel, relative to the best candidate. Smaller values filter more. -
rclip (clip):
Clip used to compute the weights (e.g. a pre-filtered copy); the averaged values still come fromclip. Must matchclip's format, size and length.
- No OpenCL/CUDA device arguments; also accepts 9–15-bit input.
-
wmode1–3 matched vszipcu bit for bit in testing;wmode0 uses a fastexp(about 1e-6 error). - Negative RGB distances (samples outside [0, 1]) are clamped to zero, avoiding an overflow the GPU versions can hit.
- If the total weight is zero, the source pixel is kept instead of NaN.
- With
wmode=0andwref=0, extremely small weights (below ~1e-38) are dropped, so a few pixels may keep the source value where the GPU averages.
nlm_ispc (pip install vapoursynth-nlm-ispc) is another CPU port of KNLMeansCL, with the same arguments.
- Output: vszip matches KNLMeansCL; nlm_ispc doesn't (see the results and bugs below).
-
First frames: with
d > 0, nlm_ispc doesn't filter frame 0 spatially only; it uses frame 0 again in place of the missing earlier frames. vszip and KNLMeansCL use radiusmin(d, n). -
Frame borders: nlm_ispc repeats the edge pixels; vszip and KNLMeansCL count pixels outside the frame as zero. Pixels within
a + sof an edge differ. -
Arguments: nlm_ispc only accepts upper-case
channels("auto", KNLMeansCL's default spelling, is an error), and doesn't check that the search window fits the clip. vszip also accepts 16-bit float.
Difference from KNLMeansCL 1.3 (GPU), in [0, 1] units, on 6 frames of a 400x224 crop of a real 1080p video. nlm_ispc 4.0 and 4.1 give identical output.
| Clip, settings | vszip mean | vszip max | nlm_ispc mean | nlm_ispc max |
|---|---|---|---|---|
| Gray 8-bit | 3.0e-5 | 0.0039 (1 code) | 3.9e-5 | 0.0196 (5 codes) |
| YUV 4:2:0 16-bit | 1.3e-7 | 1.5e-5 (1 code) | 1.0e-5 | 0.0182 |
| Gray float | 4e-8 | < 1e-6 | 1.9e-5 | 0.0235 |
| RGB float | 3e-8 | < 1e-6 | 2.1e-5 | 0.0275 |
Gray float, wmode=1
|
2e-8 | < 1e-6 | 1.2e-5 | 0.0073 |
Gray float, s=0
|
7e-8 | < 1e-6 | 2.7e-4 | 2.69 |
nlm_ispc's errors are concentrated near the frame borders (3 to 70 times the interior, depending on the case), and frame 0 is about 6 times worse than the others (see above).
A synthetic image (gradient, flat shapes, noise 0.04) at h=0.6. Red: NaN, magenta: outside the input range.

The same image at the default settings: the difference from KNLMeansCL, times 50 (red: NaN).

Found in version 4.1 (identical to 4.0):
-
Broken weights with
wmode=0(the default). Where patches differ strongly (edges, smallerh, smallers), the Welsch weight comes out invalid, likely from the fast-mathexpit is built with.- Float clips get NaN pixels and values far outside the input: 1.9% NaN on the synthetic image at the default settings, 4.6% at
h=0.6; on real video already belowh=1.0, or withs0 or 1. - Integer clips get wrong pixels instead: about 8% off by more than 1% of the range, up to 92%.
-
wmode1 to 3 are not affected.
- Float clips get NaN pixels and values far outside the input: 1.9% NaN on the synthetic image at the default settings, 4.6% at
-
channelsis case-sensitive:"auto","y"and so on are errors. -
No search-window check: a window larger than the clip (
a=40on 64x64) is accepted and returns an almost flat frame. - Small clips: a 16x16 clip at the default settings comes out as one constant value.
h=infis accepted.