Rudin-Osher-Fatemi Total Variation Denoising using Split Bregman
Macros | Typedefs | Functions
tvreg.h File Reference

TV-regularized image restoration. More...

#include "basic.h"
#include "num.h"

Go to the source code of this file.

Macros

#define TVREGOPT_DEFAULT_LAMBDA   25
 Default fidelity weight.
 
#define TVREGOPT_DEFAULT_TOL   1e-3
 Default convegence tolerance.
 
#define TVREGOPT_DEFAULT_GAMMA1   5
 Default penalty weight on the d = grad u constraint.
 
#define TVREGOPT_DEFAULT_GAMMA2   8
 Default penalty weight on the z = u constraint.
 
#define TVREGOPT_DEFAULT_MAXITER   100
 Default maximum number of Bregman iterations.
 

Typedefs

typedef struct tag_tvregopt tvregopt
 

Functions

int TvRestore (num *u, const num *f, int Width, int Height, int NumChannels, tvregopt *Opt)
 Total variation based image restoration. More...
 
tvregoptTvRegNewOpt ()
 Create a new tvregopt options object. More...
 
void TvRegFreeOpt (tvregopt *Opt)
 Free tvregopt options object. More...
 
void TvRegSetLambda (tvregopt *Opt, num Lambda)
 Specify fidelity weight lambda. More...
 
void TvRegSetVaryingLambda (tvregopt *Opt, const num *VaryingLambda, int LambdaWidth, int LambdaHeight)
 Specify spatially varying fidelity weight. More...
 
void TvRegSetKernel (tvregopt *Opt, const num *Kernel, int KernelWidth, int KernelHeight)
 Specify kernel for a deconvolution problem. More...
 
void TvRegSetTol (tvregopt *Opt, num Tol)
 Specify convergence tolerance. More...
 
void TvRegSetGamma1 (tvregopt *Opt, num Gamma1)
 Specify d = grad u penalty weight. More...
 
void TvRegSetGamma2 (tvregopt *Opt, num Gamma2)
 Specify z = Ku constraint weight. More...
 
void TvRegSetMaxIter (tvregopt *Opt, int MaxIter)
 Specify the maximum number of iterations. More...
 
int TvRegSetNoiseModel (tvregopt *Opt, const char *NoiseModel)
 Specify noise model. More...
 
void TvRegSetPlotFun (tvregopt *Opt, int(*PlotFun)(int, int, num, const num *, int, int, int, void *), void *PlotParam)
 Specify plotting function. More...
 
void TvRegPrintOpt (const tvregopt *Opt)
 Debugging function that prints the current options. More...
 
const char * TvRegGetAlgorithm (const tvregopt *Opt)
 Get a string description of the selected restoration algorithm. More...
 
int TvRestoreSimplePlot (int State, int Iter, num Delta, ATTRIBUTE_UNUSED const num *u, ATTRIBUTE_UNUSED int Width, ATTRIBUTE_UNUSED int Height, ATTRIBUTE_UNUSED int NumChannels, ATTRIBUTE_UNUSED void *Param)
 

Detailed Description

TV-regularized image restoration.

Author
Pascal Getreuer getre.nosp@m.uer@.nosp@m.gmail.nosp@m..com

Copyright (c) 2010-2012, Pascal Getreuer All rights reserved.

This program is free software: you can use, modify and/or redistribute it under the terms of the simplified BSD License. You should have received a copy of this license along this program. If not, see http://www.opensource.org/licenses/bsd-license.html.

Definition in file tvreg.h.

Function Documentation

void TvRegFreeOpt ( tvregopt Opt)

Free tvregopt options object.

Parameters
Opttvregopt options object

Definition at line 203 of file tvregopt.h.

const char* TvRegGetAlgorithm ( const tvregopt Opt)

Get a string description of the selected restoration algorithm.

Parameters
Opttvregopt options object
Returns
String describing the selected algorithm

This routine calls TvRestoreChooseAlgorithm() and translates the result to a text string. The string is stored in a small buffer within the tvregopt and does not need to be released separately.

Definition at line 484 of file tvregopt.h.

tvregopt* TvRegNewOpt ( )

Create a new tvregopt options object.

Returns
tvregopt pointer, or NULL if out of memory

This routine creates a new tvregopt options object and initializes it to default values. It is the caller's responsibility to call TvRegFreeOpt() to free the tvregopt object when done.

Definition at line 182 of file tvregopt.h.

void TvRegPrintOpt ( const tvregopt Opt)

Debugging function that prints the current options.

Parameters
Opttvregopt options object

Definition at line 420 of file tvregopt.h.

void TvRegSetGamma1 ( tvregopt Opt,
num  Gamma1 
)

Specify d = grad u penalty weight.

Parameters
Opttvregopt options object
Gamma1penalty (positive scalar)

Definition at line 299 of file tvregopt.h.

void TvRegSetGamma2 ( tvregopt Opt,
num  Gamma2 
)

Specify z = Ku constraint weight.

Parameters
Opttvregopt options object
Gamma1penalty (positive scalar)

Definition at line 311 of file tvregopt.h.

void TvRegSetKernel ( tvregopt Opt,
const num *  Kernel,
int  KernelWidth,
int  KernelHeight 
)

Specify kernel for a deconvolution problem.

Parameters
Opttvregopt options object
Kernelpointer to convolution kernel
KernelWidth,KernelHeightdimensions of the kernel

Kernel should be a contiguous array of size KernelWidth by KernelHeight in row-major order, Kernel[x + KernelWidth*y] = K(x,y). If Kernel = NULL, then no deconvolution is performed.

Definition at line 270 of file tvregopt.h.

void TvRegSetLambda ( tvregopt Opt,
num  Lambda 
)

Specify fidelity weight lambda.

Parameters
Opttvregopt options object
Lambdafidelity weight (positive scalar)

Definition at line 219 of file tvregopt.h.

void TvRegSetMaxIter ( tvregopt Opt,
int  MaxIter 
)

Specify the maximum number of iterations.

Parameters
Opttvregopt options object
MaxItermaximum number of iterations

Definition at line 323 of file tvregopt.h.

int TvRegSetNoiseModel ( tvregopt Opt,
const char *  NoiseModel 
)

Specify noise model.

Parameters
Opttvregopt options object
NoiseModelstring

NoiseModel should be a string specifying one of the following:

  • 'Gaussian' or 'L2' (default) Additive white Gaussian noise (AWGN), this is the noise model used in the traditional Rudin-Osher-Fatemi model;
  • 'Laplace' or 'L1' Laplace noise, effective for salt & pepper noise;
  • 'Poisson' Each pixel is an independent Poisson random variable with mean equal to the exact value.

Definition at line 346 of file tvregopt.h.

void TvRegSetPlotFun ( tvregopt Opt,
int(*)(int, int, num, const num *, int, int, int, void *)  PlotFun,
void *  PlotParam 
)

Specify plotting function.

Parameters
Opttvregopt options object
PlotFunplotting function
PlotParamvoid pointer for passing addition parameters

Specifying the plotting function gives control over how TvRestore displays information. Setting PlotFun = NULL disables all normal display (error messages are still displayed).

An example PlotFun is

int ExamplePlotFun(int State, int Iter, num Delta,
const num *u, int Width, int Height, int NumChannels, void *PlotParam)
{
switch(State)
{
case 0:
fprintf(stderr, " RUNNING Iter=%4d, Delta=%7.4f\r", Iter, Delta);
break;
case 1:
fprintf(stderr, " CONVERGED Iter=%4d, Delta=%7.4f\n", Iter, Delta);
break;
case 2:
fprintf(stderr, " Maximum number of iterations exceeded!\n");
break;
}
return 1;
}

The State argument is either 0, 1, or 2, and indicates TvRestore's status. Iter is the number of Bregman iterations completed, Delta is the change in the solution Delta = ||u^cur - u^prev||_2 / ||f||_2. Argument u gives a pointer to the current solution, which can be used to plot an animated display of the solution progress. PlotParam is a void pointer that can be used to pass additional information to PlotFun if needed.

Definition at line 404 of file tvregopt.h.

void TvRegSetTol ( tvregopt Opt,
num  Tol 
)

Specify convergence tolerance.

Parameters
Opttvregopt options object
Tolconvergence tolerance (positive scalar)

Definition at line 287 of file tvregopt.h.

void TvRegSetVaryingLambda ( tvregopt Opt,
const num *  VaryingLambda,
int  LambdaWidth,
int  LambdaHeight 
)

Specify spatially varying fidelity weight.

Parameters
Opttvregopt options object
VaryingLambdapointer to Lambda array
LambdaWidth,LambdaHeightdimensions of the array

VaryingLambda should be a contiguous array of size LambdaWidth by LambdaHeight in row-major order of nonnegative values, VaryingLambda[x + Width*y] = fidelity weight at pixel (x,y). Smaller VaryingLambda at a point implies stronger denoising, and a value of zero specifies that the point should be inpainted.

If VaryingLambda = NULL, the constant Lambda value is used.

For inpainting, set VaryingLambda as VaryingLambda[x + Width*y] = 0 if pixel (x,y) is unknown, VaryingLambda[x + Width*y] = C if pixel (x,y) is known, where C is a positive constant. Unknown pixels are inpainted (interpolated). Known pixels are denoised (and deconvolved, if a kernel is also set). To keep the known pixels (approximately) unchanged, set C to a large value.

Definition at line 247 of file tvregopt.h.

int TvRestore ( num *  u,
const num *  f,
int  Width,
int  Height,
int  NumChannels,
tvregopt Opt 
)

Total variation based image restoration.

Parameters
uinitial guess, overwritten with restored image
finput image
Width,Height,NumChannelsdimensions of the input image
Opttvregopt options object
Returns
0 on failure, 1 on success, 2 on maximum iterations exceeded

This routine implements simultaneous denoising, deconvolution, and inpainting with total variation (TV) regularization, using either the Gaussian (L2), Laplace (L1), or Poisson noise model, such that Kernel*u is approximately f outside of the inpainting domain.

The input image f should be a contiguous array of size Width by Height by NumChannels in planar row-major order, f[x + Width*(y + Height*k)] = kth component of pixel (x,y).

The image intensity values of f should be scaled so that the maximum intensity range of the true clean image is from 0 to 1. It is allowed that f have values outside of [0,1] (as spurious noisy pixels can exceed this range), but it should be scaled so that the restored image is in [0,1]. This scaling is especially important for the Poisson noise model.

Typically, NumChannels is either 1 (grayscale image) or 3 (color image), but NumChannels is allowed to be any positive integer. If NumChannels > 1, then vectorial TV (VTV) regularization is used in place of TV.

Image u is both an input and output of the routine. Image u should be set by the caller to an initial guess, for example a good generic initialization is to set u as a copy of f. Image u is overwritten with the restored image.

Other options are specified through the options object Opt. First use tvregopt Opt = TvRegNewOpt() to create a new options object with default options (denoising with the Gaussian noise model). Then use the following functions to make settings.

When done, call TvRegFreeOpt() to free the options object. Setting Opt = NULL uses the default options (denoising with Gaussian noise model).

The split Bregman method is used to solve the minimization, T. Goldstein and S. Osher, "The Split Bregman Algorithm for L1 Regularized Problems", UCLA CAM Report 08-29.

The routine automatically adapts the algorithm according to the inputs. If no deconvolution is needed, Gauss-Seidel is used to solve the u-subproblem. If the kernel is symmetric, a DCT-based solver is applied and, if not, a (slower) Fourier-based solver. For the Gaussian noise model, the routine uses a simpler splitting of the problem with two auxiliary variables. For non-Gaussian noise models, a splitting with three auxiliary variables is applied.

Definition at line 98 of file tvreg.c.