TV-regularized image restoration. More...

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

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...

tvregopt *	TvRegNewOpt ()
	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

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

Opt	tvregopt 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

Opt	tvregopt 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

Opt	tvregopt options object

Definition at line 420 of file tvregopt.h.

void TvRegSetGamma1	(	tvregopt *	Opt,
		num	Gamma1
	)

Specify d = grad u penalty weight.

Parameters

Opt	tvregopt options object
Gamma1	penalty (positive scalar)

Definition at line 299 of file tvregopt.h.

void TvRegSetGamma2	(	tvregopt *	Opt,
		num	Gamma2
	)

Specify z = Ku constraint weight.

Parameters

Opt	tvregopt options object
Gamma1	penalty (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

Opt	tvregopt options object
Kernel	pointer to convolution kernel
KernelWidth,KernelHeight	dimensions 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

Opt	tvregopt options object
Lambda	fidelity weight (positive scalar)

Definition at line 219 of file tvregopt.h.

void TvRegSetMaxIter	(	tvregopt *	Opt,
		int	MaxIter
	)

Specify the maximum number of iterations.

Parameters

Opt	tvregopt options object
MaxIter	maximum number of iterations

Definition at line 323 of file tvregopt.h.

int TvRegSetNoiseModel	(	tvregopt *	Opt,
		const char *	NoiseModel
	)

Specify noise model.

Parameters

Opt	tvregopt options object
NoiseModel	string

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

Opt	tvregopt options object
PlotFun	plotting function
PlotParam	void 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

Opt	tvregopt options object
Tol	convergence 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

Opt	tvregopt options object
VaryingLambda	pointer to Lambda array
LambdaWidth,LambdaHeight	dimensions 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

u	initial guess, overwritten with restored image
f	input image
Width,Height,NumChannels	dimensions of the input image
Opt	tvregopt 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.

TvRegSetLambda(): set fidelity weight
TvRegSetVaryingLambda(): set spatially varying fidelity weight
TvRegSetKernel(): Kernel for deconvolution problems
TvRegSetTol(): convergence tolerance
TvRegSetMaxIter(): maximum number of iterations
TvRegSetNoiseModel(): noise model
TvRegSetGamma1(): constraint weight on d = grad u
TvRegSetGamma2(): constraint weight on z = Ku
TvRegSetPlotFun(): custom plotting function

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.

Macros

Typedefs

Functions

Detailed Description

Function Documentation