cocolib / light field suite Wiki
CUDA library for continuous optimization and light field analysis
Status: Beta
Brought to you by:
goldluecke
Menu
▾
▴
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:
| grayscale | Single channel image. Image will be converted to a matrix, and the algorithm run only on a single channel. Supported for regularizers TV and TC. |
| rgb | Multi-channel RGB image. Default setting. |
| hsv | Multi-channel image in HSV color space. |
| cielab | Multi-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
| gaussian | Gaussian noise with standard deviation *sigma*. |
| impulse | Impulse 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:
| TV | Total variation |
| VTV_S | Vectorial total variation where TV is applied to each channel separately |
| VTV_F | Vectorial total variation which penalizes the Frobenius norm of the derivative matrix. |
| VTV_J | Vectorial total variation which penalizes a Jacobian of the derivative matrix, which is the same as the square root of its largest singular value. |
| TC | Total curvature |
| ML_TV | Multilabel model (lifting framework), linear regularity penalizer. See configs/multilabel_tv_* for example dataterms. |
| ML_POTTS | Multilabel model (lifting framework), Potts regularity. See configs/multilabel_potts_* for example dataterms. |
| ML_VECTORIAL | Vectorial 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 regularizers | data term | |
| denoising | all | || u-f ||pp |
| deblurring | all | || b * u-f ||2 |
| inpainting | all | m|| u-f ||2 |
| segmentation | TV, TC, ML_POTTS, ML_VECTORIAL | a u |
| optic_flow | VTV_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 <string>
Selects the algorithm. Not every algorithm supports all dataterm/regularizer combinations, usually the choice is fairly limited. Possible parameter values are
| algorithm | supported models | parameters | |
| CHAMBOLLE_SI | Semi-implicit gradient descent | TV denoising | sigma |
| CHAMBOLLE_PGD | Projected gradient descent | TV denoising | sigma |
| BM | Bermudez-Moreno | all denoising | sigma |
| FGP | Fast gradient projection | all denoising | sigma |
| ARROW_HURWICZ | Projected gradient ascent/descent for saddle point problems | VTV_x all | sigma, tau |
| CHAMBOLLE_POCK_1 | Accelerated gradient ascent/descent for saddle point problems | VTV_x all | sigma, tau |
| CHAMBOLLE_POCK_2 | Accelerated gradient ascent/descent for saddle point problems, adaptive acceleration | VTV_x all | sigma, tau |
| FISTA | Fast 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.
