File Exchange

image thumbnail

Fast Non-Local Means 1D, 2D Color and 3D

version (29.4 KB) by Dirk-Jan Kroon
NL-means image and signal denoising filter based on similarity between pixel patches


Updated 07 Sep 2010

View License

This function NLMF performs Non-Local Means noise filtering of 1D signal, 2D grey/color or 3D image data. The function is partly c-coded for cpu efficient filtering. Suitable for almost every image data type such as MRI, CT and normal photos.

Warning !, Image filtering removes noise, but important (medical) details can also be lost, (see discussion in comments).

Principle NL-Mean filter:
A local pixel region (patch) around a pixel is compared to patches of pixels in the neighbourhood (or in the whole image). The centerpixels of the patches are averaged depending on the quadratic pixel distance between the patches.

J = NLMF( I, Options);
I : 1D signal, 2D grey/color or 3D image data, of type Single or Double in range [0..1]
Options : Struct with options, such as filtering strength
J : The NL-means filtered image or image volume

J = NLMF2Dtree(I, Options);
Same as NLMF but will search for the best matches in the whole 2D images using a kd-tree (is still extremely slow)

- Non local filter proposed for A. Buades, B. Coll and J.M. Morel "A non-local algorithm for image denoising"
- Basic Matlab implementation of Jose Vicente Manjon-Herrera

Cite As

Dirk-Jan Kroon (2020). Fast Non-Local Means 1D, 2D Color and 3D (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (45)

Thanks to Juna Cadena, my problem has been solved. Also the vsize[2]-to-vsize[3] correction mentioned above is also necessary. The program works very well.

Anju Kaimal

Error using image2vectors_single
Requested 215577293488471x71284656 (17179869184.0GB) array exceeds maximum array size preference. Creation of arrays greater than this limit may
take a long time and cause MATLAB to become unresponsive. See array size limit or preference panel for more information.

Error in NLMF (line 145)

How to solve this error?

Hi all. May I know why would the running time increase when increase the kernel ratio and window ratio? Shouldn't it decrease, as less values are being computed? Is it because the block size is decreased when the two ratios increase?

The Solution of Juan Cadena for Error using image2vectors_double, worked for me. Thank you, you save me the implementation

Juan Cadena

Hello, I think I have solved the problem stated in the last three comments. The issue appears to happen due to the version of the third party gcc compiler and the supported gcc compiler version of your current MATLAB version.

Solution 1:
- Update or downgrade your gcc version in order to meet the version supported by your MATLAB.

- Because I wasn't allowed to change any version of the gcc (I was using a private cluster) I had to find another way. This did the trick for me:

mex -v -compatibleArrayDims vectors_nlmeans_single.c
mex -v -compatibleArrayDims image2vectors_single.c
mex -v -compatibleArrayDims vectors_nlmeans_double.c
mex -v -compatibleArrayDims image2vectors_double.c

Dirk-Jan Kroon thank you for your contributions to the field!

Emma Reid

xiaohui qi

Error using image2vectors_double
Requested 86603720556787x71281417 (17179869184.0GB) array exceeds maximum array size
preference. Creation of arrays greater than this limit may take a long time and cause MATLAB to
become unresponsive. See array size limit or preference panel for more information.
Error in NLMF (line 143)


Jiong Zhang

Error using image2vectors_double
Requested 86603720556787x140703886664826 (17179869184.0GB) array exceeds maximum array size
preference. Creation of arrays greater than this limit may take a long time and cause MATLAB to
become unresponsive. See array size limit or preference panel for more information.

Error in NLMF (line 143)

Nathan Zhang

Thanks for sharing.


Error using image2vectors_double
Requested 6532645257265x35374636064 (17179869184.0GB) array exceeds maximum array size preference. Creation of arrays greater than
this limit may take a long time and cause MATLAB to become unresponsive. See array size limit or preference panel for more
kindly help me...

kai li

is it really works with 1D signal ?


This is great, and fast. However, I do have a problem if NaN values exist within the image before de-noising. It causes all neighboring pixels to fail.


is it really works with 1D signal ?

also aggre on comment by Renee Fang. Need to make corrections.

This implementation is much faster than the ones I tried before. Thanks!

dancy wang

Nathan Zhang

Thanks for sharing your submission. Good job.


Can anyone write a MATLAB code for Non-Local Mean Filter for Image Pre-Procesing

Not running in Matlab R2014b..
When I run the code on a 3D matrix in shows:
Undefined function 'image2vectors_single' for input arguments of type

Error in NLMF (line 145)

Does anyone know how to solve this problem?

Renee Fang

More update:
The run the 3D example, the same thing should be done to vectors_nlmeans_single.c and image2vectors_double.c.
Replace Vsize[2] to Vsize[3] in all definitions.

Renee Fang

The toolbox is good and fast. But the reason I gave 4-star is because it crashed when I first ran the toolbox. After reading the reviews and fixed the bugs, it is running well now.
Solution for crashing:
- In vectors_nlmeans_double.c, line 256: change Vsize[2] to Vsize[3]
- In image2vectors_double.c, line 166 & 227: change Vsize[2] to Vsize[3].

Then it works!

For those using MATLAB 2013 or higher, if there is an error "char16_t" is not recognized

#include <stdint.h>
#define char16_t UINT16_T

before #include "mex.h" in every .c file.


将vectors_nlmeans_double.c 256行的vsize[2]改成3,可以运行


Matlab crashes when run the program


Thanks for sharing. It works very well!

Dear Author, Thanx for sharing. But, there is some error in C files as it crashes on Matlab R2010b. Ole Buus & Jancc Chan had also the same problem, but you didn't respond to them.
Please correct the error and upload correct files

Ole Buus

Hi Dirk-Jan,

Is there an error in the .c files? It seems that the mex-compiler gives a warning when compiling. In line 183 in the image2vectors-files and in line 273 in the nlmeans-files. Why is Vsize only defined with dimension 2? You obviously use a third indice in those lines. I corrected the declaration of Vsize and the code compiles and even runs (before I had MATLAB crashing).

Denoised an image of 240x240 px in ~5s (Windows 7, MATLAB r2009b). It seems to work...


Hi, I tried this program on my Matlab R2009a, it either lost response or just exited my MATLAB, what's the problem?

Eric Diaz

Hi SamSam,

I just wanted to say that I have nothing against Dirk-Jan. I applaud him for his work and the contributions he has made to research, programming and the matlab communities, in large. He certainly has produced excellent work in the past and generously contributed to others. I only wanted to make note of a minor or major omission (depending on how you look at it) when this file was first posted, namely a disclaimer and references. If it makes any difference, I am glad to give it another 4 star rating, even though I still haven't even tried it because I know that Dirk-Jan has put a lot of work into it and is contributing to the community.

NLM takes the mean of (the center of) image patches. In situations where the mean is not a good predictor of the real value without noise, this method will fail. It doesn't really depend on the type of noise model.


_Not_ an expert in this, but doesn't NLM assume additive noise? For images with multiplicative noise(e.g. SAR, CT, MRI, PET) this assumption is not valid.


OK, I am sorry for the mistaking. BTW, it there any time-cost experimental result for this implementation, × seconds for 1m image data?
Further, using the fix-point[int short byte] will run much faster(>5X) than the float-point[double float, even using the MMX/SSE1~4 instructions] .

I have never seen the Cuda code or paper.
(also the code may look the same from outside, but some implementation decisions are probably very different)


Nice, but the source code looks very like the C&&matlab version of "Image Denoising " example of CUDA. If so, CUDA community should get a reference at the least.

Sam Sam

The discussion above proves to me that the old cynical joke - "No good deed ever goes unpunished" - is actually very true.

Dirk took the time to publish his very useful submission - one of 43 he's posted on Matlab Exchange - a well documented and optimized implementation of a useful algorithm, and then some jerk comes over and starts giving it one star ratings because there are no caveats for medical imaging users. If you need warnings of this sort when using medical imaging algorithms, then you suffer from some sort of blind faith in "magical software algorithms" that will de-noise everything and tell you where the tumor is 100% of the time, and need no tuning. If you don't understand what you're doing, then don't blindly apply matlab algorithms in clinical practice - you might hurt someone. It is extremely rude, in my opinion, to come here and complain about a sample algorithm implementation that someone posted just to help out fellow researchers.

Again, Dirk, great job!


Eric Diaz

Dear Dirk,

I recommend simply removing the suggestion all together. If someone would like to venture into that territory by their own free will, then they will be liable and subject to peer review.

Alternatively, I would suggest the following amendment,

Warning !!!
Image filtering attempts to remove noise but because will end up removing some real values and replacing them with inaccurate estimates.

If tried on medical images, these artifacts are even more likely due to the different physical principles underlying image intensity at any given pixel. Please BEWARE that important anatomic and pathologic details can be lost with potentially tragic consequences. (see discussion below).

Eric Diaz

Dear Dirk,

Just to let you know, I gave another rating at 1 star because I realized you only had 2 references, neither of which say anything about application to medical imaging (MRI or CT). That is very poor form!

Again, I want to say that I haven't tried your code, but I am willing to re-star your post at higher level, if you amend your opening statement to something less falsely advertising. Indeed, if you have done a good job, then you shouldn't have to sell it as more than it is. I see that you have posted many files before and so I don't doubt that you are able to code well. It is just your reckless propagation of something unscientific in such an important arena as medicine that I have problems with.

Eric Diaz

Dear Dirk,

If we want to make automatic computerized recognition systems we need to use real science and not just translate what has been done in some other field and claim that it works great for medical images. Medical images are not like natural light images, they use completely different physical mechanisms to capture information.

Reconstruction needs to be performed, filtering does not. Furthermore, reconstruction is based on science fundamentally geared toward medical images to reduce bias.

I can tell you for certain that applying NLM to an MR would introduce an unacceptable amount of bias, blur the image, and cover up lesions. So what is the point? There is none. One can't just start posting up files saying they are good for this and that, when in fact they are not. Science needs to be done properly if one wants to make gains for ACRS. And thus, any medical doctor or true scientist would say that your claims and program are pointless and false with respect to medical images, as they would find the raw image better.

If you have not done your research, don't make false claims!
Propagation of unreviewed applications on the FEX to different fields is a danger to science! All you have are 2 literature citations, neither of which have anything to do with MRI or CT or any other medical imaging modality, yet you claim that it works on them!

Dear Eric Diaz,

Indeed, medical doctors are very good in recognizing small important details in raw data, and don't like filtered data.

But if we want to make an automatic computerized recognition system we need image noise filters, for fast and good image segmentation.

The filtering is indeed overdone in the example. But the amount of smoothing versus detail can be set by a simple input value.

For medical doctors is also important to there is no real "raw data". Because reconstruction of CT and MRI already contain many image filtering steps, which also have there problems, such as bias correction causing false MS lesions.

Eric Diaz

Dear Dirk,

If you are not a medical doctor, I don't think you are justified in making that claim. The human eye - brain "filtering algorithm" is far more advanced than any available algorithm and does not suffer from this problem the way all other filtering algorithms do. This is why I see no reason to perform the filtering on the image in the first place, especially in the medical setting where details are important, and even much less so after knowing that it covers up lesions (again look at your image example, it is a disgrace!) . As far as there being 100+ papers on using NL-means on medical data, I can't tell you much about all modalities, but the few that I have seen in MR are awful and written by non-experts in the field. Probably attempted practical translation of some FEX NLM file, like the one you posted claiming to work miracles, by some eager person seeking a publication or fame and yet not having a clue what they are doing are talking about. I hope you can realize that there is no sound nor justified reason to make your claim, much less so knowing that someone could die from NLM covered up pathology. I hope you retract your claims and make them more reasonable.

Dear Eric Diaz,

You are right this noise filter can remove small MS lesions in MRI or other important small structures such as calcification's.

But this is the problem with all filtering algorithms, from simple Gaussian filtering to Anisotropic Diffusion Filtering.

There are 100+ papers using NL-means on Medical Data, thus my claim seems justified.

Eric Diaz

Dear Dirk,

I gave this a 2 - star because it is completely false advertisement to say that this is suitable for almost every type of image, especially medical images. I would hope that a doctor doesn't miss some lesion because your code filtered it out. You should really not try to sell this as more than it is. I know that NLM is a powerful denoising algorithm but it has its limitations. Firstly, I would certainly hope that you know something about medical images, such as MRI and CT, to be making such claims. If you don't then you shouldn't be making them. I can certainly tell you from my first hand knowledge that it can cover up lesions (just look at the example picture you posted...nearly all the anatomic detail is gone!). I haven't tried your code, but I will certainly bump my stars up to at least a 4 (even without trying it, as I'm sure that you've done a decent job coding), if you amend your opening statement to something a bit more reasonable.

Jancc Chan

Hi Dirk, thanks for sharing the code!

I've tried to run the code, however, my Matlab R2008b crashes all the time when I was trying the examples (I have compiled all c-code in Matlab). Can you please advice on how to solve this problem?

Many thanks!!


Added KN-tree based search

Added 1D filtering

added warning

MATLAB Release Compatibility
Created with R2010a
Compatible with any release
Platform Compatibility
Windows macOS Linux