A toolbox for the non-local means algorithm.
by Gabriel Peyré, 2007.
The non-local means is an algorithm introduced by A. Buades, B. Coll, J.M Morel.
The main reference for the algorithm is
A. Buades, B. Coll, J.M Morel,
"A review of image denoising algorithms, with a new one" ,
Multiscale Modeling and Simulation (SIAM interdisciplinary journal), Vol 4 (2), pp: 490-530, 2005.
This toolbox implements the algorithm in a fairly general way in a C file that can be called from Matlab. It allows to perform the traditional NL-means for denoising (for both B&W and color images) but also to use an arbitrary set of patches to perform the denoising.
Un-zip the file in your directory and start matlab from the unzipped directory. First compile the main mex file using
If this is not working, you should select your compiler using
> mex -setup
Before writing your own code, be sure to add the following line
so that the additional helper functions (such as image loading and resizing) are available. This is done automatically at the beginning of the test files "test_xxx.m".
I recommend that you run the file "test_nlmeans" (the best would be to run each line one by one to see the effect) to perform a traditional denoising. Then you can start to play with the parameters.
ADVANCED USES OF THE TOOLBOX:
You can denoise an image using the patch of another image. This is useful for funny renderings or for textures synthesis. My recommendation is then to use a small variance for the averaging, but to iterate the NL-means processing. This way, at each iteration, the algorithm will automatically initialize its search around the previous best match (and not from the original pixel). I recommend that you run test_nlmeans_duo.m to see this method.
You can perform very nice texture synthesis by denoising with NL-means a white noise. To that end, you can use the patch from another image. The file text_nl_synthesis.m does exactly that. For synthesis, you can even set the variance options.T to a very small number (like 1e-9) so that no averaging is performed and pixel recopy is simply performed. Once again this should be iterated so that the synthesis improves through iterations. This process is equivalent to traditional texture synthesis as explained in
Alexei A. Efros and Thomas K. Leung
"Texture Synthesis by Non-parametric Sampling"
IEEE International Conference on Computer Vision (ICCV'99),
You can also perform denoising (or synthesis) using patches from a synthetic dictionary. I have implemented a dictionary of binary step edges, and you can see the effect of tynehis in test_edge_synthesis.m.
Copyright (c) 2007 Gabriel Peyré
Hi, Gabriel Peyré. Thanks for your great program. It works very well.
I have a question about the parameter 'ndims' used in options. Is a PCA postprocessing used after NLM? How can I disable this option? Thanks.
I am running test_nl_inpainting which requires 'grab_inpainting_mask'. But I cannot find it in the project folder. Could you please advise?
error in perform_atrou_transform?
Hi, Good Code! But, where's the orignial C code? Thanks.
I can't find some function such as load_image and
that's why? please help me
I downloaded, installed and ran without any problems on Matlab 7 on Linux. This is a great program. Unfortunally, some files such as the ones used in test_denoising.m are missing. As an example, the files psnr.m, compute_best_threshold.m are missing (this is not an exhaustive list). This is however a great work.
Thanks a lot.
C:\PROGRA~1\MATLAB\R2009A\BIN\MEX.PL: Error: Compile of 'MEX\perform_nlmeans_mex - copie.cpp' failed.
??? Error using ==> mex at 218
Unable to complete successfully.
I tried to use the tool box. However I couldn't compile the mex file although I selected the compiler in my computer. Error message is:
C:\PROGRA~1\MATLAB\R2009A\BIN\MEX.PL: Error: Compile of 'MEX\perform_nlmeans_mex.cpp' failed.
??? Error using ==> mex at 218
Unable to complete successfully.
Error in ==> compile_mex at 4
perform_image_extension(M,m) is used in the function [M1,MW,MW1] = perform_wavelet_matching(M1,M,options),but my running error is "Synthesizing corral, ave=1, T=inf.
??? Undefined function or method 'perform_image_extension' for input arguments of type
Error in ==> perform_wavelet_matching at 80
M = perform_image_extension(M,m);
Error in ==> test_nl_synthesis at 216
M = perform_wavelet_matching(M,Ma,options);"
How can I get the function missed here? Please help me ,thank you!
I downloaded, installed and ran without any problems on Matlab 7 on Linux. Thank you for uploading this and for the convenient test programs.
Hi Gabriel Peyré ,
Your program is great. However I encounter a problem: when I run the 'test_nlmeans', Matlab reveals a problem:
??? Undefined command/function 'perform_nlmeans_mex'.
Error in ==> perform_nl_means at 100
[M1,Wx,Wy] = perform_nlmeans_mex(Ma,H,Ha,Vx-1,Vy-1,T,max_dist, do_median, do_patchwise, mask_process, mask_copy, exclude_self);
Error in ==> test_nlmeans at 33
[M1,Wx,Wy] = perform_nl_means(M, options);
How to fix it? Thanks a lot.
This is a good C implementation. The documentation is not perfect but this filter being intuitive it is not important. Great work and thank you to share your code.
For large 3D MR images, the users can test webinterface at:
1. Documentation is not very detailed. Some parameters are not documented in the help.
2. It seems that one function is missing for the demonstration script ('crop').
3. I'm not sure, but it's working very slowly on my PC (dual 3Ghz, 1GB RAM). I wonder if the code can be further optimized.
Bottom line: It does the job and doesn't require any complicated installation or parametrization.
Answers to the questions: 1) options.k is half the size of the windows so that windows width is 2*k+1 (please read 'help perform_nl_means' for details, everything is here). 2) options.max_dist limits the size of the averaging, which is exactly what you are asking for ('help perform_nl_means' says "max_dist: maximum distance to restrict the search"). 3) The h parameter of Buades et al. is called options.T in my code. sigma is the noise variance). If you increase sigma, then T should be increase. As I have already mentionned, the script test_denoising check for various values of T that gives optimal denoising results (with oracle). I think the 'help' command on the functions of the toolbox give some details about all these issues (maybe not enough, but once again, I do not have too much time to spend on it). Your ** rating seems rather unjustified in my opinion.
Thank you for clarifications. Like I said, your toolbox is loosing lots of its value, because it is not documented properly. I understand the working of NLmeans algorithm, however, the main problem is impossibility of matching filter's parameters from the published literature to parameters in your code, without help from your side. As you know, it takes less time to write your own code, then to reverse engineer someone else's.
1) k- is the whole width of the learning window or window width is 2k+1?
2) Do you average a whole image or you use approach by Coupe, Yger, Barillot to limit averaging by a 'search window' centered on the current pixel (bigger than learning windows but smaller that the whole image)
3) What is the relationship between your parameter sigma and parameter 'h' from the Buades' paper?
* concerning the optimization: I did my best to have a fast C code. There might be some fine tuning (e.g. memory access, etc) but this is way beyond the scope of this toolbox (rember that NLmeans is not a static filter, it is a spacially varying filters just like Bilateral Filtering but more complex).
* Concerning the output: do not bother about Wx,Wy for just denoising. It is usefull for iterative texture synthesis (it gives the location of the best windows match).
* Concerning the options: options.k should be set between 2 and 4 (it is the width of the windows). options.sigma should be set around 0.03 (increase if more noise) and is the width of the filter. See test_denoising that test several values for these parameter and keep the best one (obviously this is possible only if you know the original noiseless image, but this is a good benchmark).
* concerning the documentation: I do not have the time to do it know. Obviously, NLmeans is not that simple to use, and one really needs to understand the process to set up correctly the parameters (but test_nlmeans and test_denoising gives simple way to see it in action).
1)the filter' algorithm is not optimized, thus, it is much slower than it could be
2) Help section is very poor. It is quite impossible to guess what is the purpose for some input and output parameters, how to use this function and what is the relation of the function' variables to the variables in the quoted paper. For example, what are Wx, Wy? Which parameter in this function is a filtering parameter 'h' from the quoted paper, What are the uses for option' parameters etc.... The demo included in the toolbox allows to see the results of the filter but in no way helps to understand how to apply this filter to other data or images. IMHO, without a good help section the value of this toolbox is greatly depreciated
Update of Licence
Create scripts with code, output, and formatted text in a single executable document.