cocolib command line tool

Parameter syntax and configuration file(s)

The command line tool takes an image as input, runs the specified algorithm, and writes an output image and maybe additional output to the specified directory. It is configured via a set of parameters. Each parameter has a unique name.

There are two ways to specify the parameters. The first is to write a configuration file. Take a look at the following example configuration file, which solves the TV denoising (ROF) model using the FGP algorithm and contatins a typical set of parameters you might wish to specify.

# Regularizer configuration
regularizer           tv
dataterm              denoising
lambda                0.1

# Input noise configuration
input_noise_type      gaussian
input_noise_sigma     0.1

# Algorithm specification and parameters
algorithm             FGP
iterations            100

# Input image configuration
in                    ./in/burg_eltz.jpg
colorspace            grayscale
W                     640
H                     856

# Output image configuration
out                   ./out/tv/denoising/result_burg_eltz.png



Each parameter is defined in its own line by giving first parameter name, then desired value. Blank lines are ignored, as are lines starting with "#", which may contain comments. Many examples can be found in the subdirectory "examples/example_configs" in the library archive.

You are not required to write configuration files, since the same parameters which can be specified in a config file can be given at the command line, where their names are preceded with a "-". A special parameter is the config parameter, which causes a configuration file to be included. On the command line, this looks like this:

./coco_ip -config myconfig.cfg



Parameters are read in consecutive order, so later specifications of a parameters overwrite the previous one. In particular, afterreading a config file, you can overwrite specific parameters. The following example uses a different value of lambda than specified in the config file:

./coco_ip -config myconfig.cfg -lambda 10.0



The config parameter can also be used in configuration files, which corresponds to including another configuration file. This way, you can specify global parameter settings which you wish to commonly use.

# Include another file
config  include_this.cfg



Command line tool parameters

The following options and parameters can be given to the command line tool coco_ip. Not all models and algorithms require all parameters - if a parameter is unneeded, it will be ignored.

Input/output image configuration

in <filename>

Name (possibly with path) of the input image.

 W <integer>, H <integer>

Desired width and height of the input image (will be scaled when loaded).

colorspace <string>

Color space for the computation. The input image will be transformed into this colorspace and transformed back to RGB when saving the result. Note: If the regularizer only supports single channel (grayscale) images and a multi-channel color space is configured, then the model is solved for each of the color channels separately. Possible values for this parameter are:

grayscaleSingle channel image. Image will be converted to a matrix, and the algorithm run only on a single channel. Supported for regularizers TV and TC.
rgbMulti-channel RGB image. Default setting.
hsvMulti-channel image in HSV color space.
cielabMulti-channel image in CIE-L\*a\*b\* perceptually uniform color space.



out <filename>

Name (possibly with path) to the output image. Note: some algorithms will write additional output to the same directory.

 outdir <directory_name>

Directory for additional output, if it shall be written to a different place than the output image.

  mask <filename>

Inpainting or segmentation mask image. Colors in the image will be interpreted according to the following parameter values.

   ip_mask_r <double>, ip_mask_g <double>, ip_mask_b <double>

Inpainting mask RGB color of the damaged region (default: green 0 1 0). Pixels of this color in the input mask image will be marked as damaged and inpainted.

   bg_mask_r <double>, bg_mask_g <double>, bg_mask_b <double>

Segmentation mask RGB color of the background region (default: blue 0 0 1). Pixels of this color in the input mask image correspond to user-defined background and will be used to build the background statistics.

     fg_mask_r <double>, fg_mask_g <double>, fg_mask_b <double>

Segmentation mask RGB color of the foreground region (default: red 1 0 0). Pixels of this color in the input mask image correspond to user-defined foreground and will be used to build the foreground statistics.


Blur and noise

The values for the blur kernel will be used in deblurring models. If desired, blur can also be applied to the input image. Noise is always applied to the input image.

blur_size <integer>

Size of the blur kernel in pixels. The kernel will be a Gaussian distribution.

 blur_sigma <double>

The standard deviation of the distribution in case of a rotationally symmetric kernel.

blur_sigma_x <double>, blur_sigma_y <double>

Different standard deviations in X and Y direction, if the kernel should be asymmetric. Overrides blur_sigma.

blur_rotate <double>

For asymmetric kernels, rotates the kernel counterclockwise by the given angle.

input_blur <bool>

If set to an integer value different from zero, the configured blur kernel will be
applied to the input image.

input_noise_type <string>

Type of noise added to the input image. Possible values are

gaussianGaussian noise with standard deviation *sigma*.
impulseImpulse noise. A percentage *sigma* of pixels will get a random color value.



input_noise_sigma <double>

Parameter sigma for noise as defined above.



Energy functional

regularizer <string>

Selects the regularizer. Possible values are:

TVTotal variation
VTV_SVectorial total variation where TV is applied to each channel separately
VTV_FVectorial total variation which penalizes the Frobenius norm of the derivative matrix.
VTV_JVectorial total variation which penalizes a Jacobian of the derivative matrix, which is the same as the square root of its largest singular value.
TCTotal curvature
ML_TVMultilabel model (lifting framework), linear regularity penalizer. See configs/multilabel_tv_* for example dataterms.
ML_POTTSMultilabel model (lifting framework), Potts regularity. See configs/multilabel_potts_* for example dataterms.
ML_VECTORIALVectorial multilabel model (lifting framework), various regularizers. See configs/vectorial_multilabel_* for a multitude of options.



dataterm <string>

Selects the data term. Possible values are:

supported regularizersdata term
denoisingall || u-f ||pp
deblurringall || b * u-f ||2
inpaintingall m|| u-f ||2
segmentationTV, TC, ML_POTTS, ML_VECTORIAL a u
optic_flowVTV_x, ML_VECTORIAL || I_1(x)-I_2(x+u) ||

In all the above models, u is the desired minimizer of the model and f is the input image. All data terms are scaled with 1/(2 lambda), where lambda is the user-supplied regularity constant and p a user-defined exponent.

For deblurring, b is the user-configured blur kernel.

For inpainting, m is the user-configured inpainting mask.

For segmentation, a is the log-probability quotient for a pixel to be in the foreground or background. Foreground and background statistics are derived from the user-supplied foreground and background masks according to a very simple histogram model.

p <integer>

Exponent in the data term. Supported only for VTV_x denoising.

lambda <double>

Regularity constant (double). Usually, a higher value means the result will become smoother.


Algorithm selection and configuration

If any of the following parameters is not specified, the tool tries to make optimal selections by itself, according to empiric or theoretical measurements and step size bounds. However, it is possible that a manual selection greatly improves performance.

algorithm

Selects the algorithm. Not every algorithm supports all dataterm/regularizer combinations, usually the choice is fairly limited. Possible parameter values are

algorithmsupported
models
parameters
CHAMBOLLE_SISemi-implicit gradient descentTV denoisingsigma
CHAMBOLLE_PGDProjected gradient descentTV denoisingsigma
BMBermudez-Morenoall denoisingsigma
FGPFast gradient projectionall denoisingsigma
ARROW_HURWICZProjected gradient ascent/descent
for saddle point problems
VTV_x allsigma, tau
CHAMBOLLE_POCK_1Accelerated gradient ascent/descent
for saddle point problems
VTV_x allsigma, tau
CHAMBOLLE_POCK_2Accelerated gradient ascent/descent
for saddle point problems,
adaptive acceleration
VTV_x allsigma, tau
FISTAFast iterative shrinkage
and thresholding
all deblurring
all inpainting
all segmentation
sigma, tau,
inner_iterations



iterations <integer>

Number of (complete) iterations of the algorithm performed, including one set of inner iterations when applicable.

   inner_iterations <integer>

Number of inner iterations for algorithms which solve an interior model in each iteration (e.g. FISTA).

   tau <integer>

Step size for primal (sub-)gradient descent.

 sigma <integer>

Step size for dual (sub-)gradient ascent.



Miscellaneous (not directly related to algorithms)

tracelevel <integer>

Set level of verbosity of output (0-9). For debugging purposes.