sigseg - manual
The sigseg program is a Command Line Interface (CLI) program which makes use of a library implementing the Blake and Zisserman model in 1D. The sigseg program and the libseg_1d library are written in C language and have been developed and tested on a GNU/Linux OS.

Instruction on how to compile, install and run the sigseg program can be found in the "README.txt" file shipped with the program source code.

The Blake-Zisserman model is an extension of the Mumford-Shah model. These two models solve the problem of data segmentation following a variational approach, i.e,. solving a minimum problem involving energy functionals. The variational segmentation models produce a smooth approximation of the data. The data domain results in being partitioned in to disjoint and homogeneous regions which boundaries are explicitly handled by the model. i.e., data discontinuities cat be detected.
The approximation based on the Mumford-Shah model "respects" the discontinuities of the data by preserving them from being smoothed. The approximation based on the Blake-Zisserman model can "respect" also the discontinuities of the first derivative of the data.

In this page, only a brief and rough overview of the variational approach is given with the aim to clarify the set up and the use of the program sigseg.

The weak formulation of the Blake-Zisserman variational model produces the data segmentation by finding the function u that minimizes the functional:
 BZ(u) = ⌠⌡ b a (u − g)2 dx + γ ⌠⌡ b a |u"|2 dx + α#(Su) + β #(Su')
where:

g is the data;
[a,b] is the domain of g;
u is a smooth approximation of the data g;
u" is the second derivative of u;
Su is the set of the discontinuities of u;
Su' is the set of the discontinuities of the first derivative of u;
# is the counting measure of a set, i.e., the number of elements of a given set;
α, β and γ are null or positive parameters.

The first term of BZ(u) controls the "distance" between the solution u and the data.
The second term controls the smoothness of the solution.
The third and the fourth terms control the "size" of the discontinuity sets.
The parameters α, β and γ act as weights to balance the different effects of the terms in BZ(u).

Minimizing BZ(u) means that:
- the solution u is required to be as close as possible to the data;
- the solution u is required to be as smooth as possible;
- the set Su of the discontinuity of u (and the set Su') can not become too large. This to avoid an over-segmented solution that is, at the limit, the trivial solution where each single data point is considered as a single homogeneous region.

A numerical solution of BZ(u) can be found by the discretization of the following functional:
 BZε(u) = ⌠⌡ b a (u − g)2 dx + γ ⌠⌡ b a (s2 + λε) |u"|2 dx + β Mε(s) + (α− β) Mε(σ) + με ⌠⌡ b a σ|u'|2 dx
under the condition:

β ≤ α ≤ 2 β

with:
 Mε(t) = ⌠⌡ b a [ ε(t′) + 1/(4ε) (1−t)2 ] dx
and where:

σ is a "discontinuity function" that "sees" the discontinuities of u;
s is a "discontinuity function" that "sees" the discontinuities of the first derivative of u;
με and λε are null or positive parameter;
ε is a convergence parameter.

The two discontinuity functions σ and s replace the counting measures of the discontinuity set Su and Su' respectively.

The parameter λε should be set to zero in any applications (unless you know what you are doing).

The parameter ε has to be just greater than 1/n, where n is the number of points of the data. E.g., if n=200 then set epsilon to 1/199.9

If the parameters β and γ are set to zero the above functional becomes:
 MSε(u) = ⌠⌡ b a (u − g)2 dx + αMε(σ) + με ⌠⌡ b a σ|u'|2 dx
that is the functional that permits to implement numerically the weak form of the Mumford-Shah model:
 MS(u) = ⌠⌡ b a (u − g)2 dx + με ⌠⌡ b a |u'|2 dx + α#(Su)
where the smoothness of the solution is controlled by the first derivative of u, and only the set Su of the discontinuities of u is controlled.

Introductory elements on the Blake-Zisserman and Mumford-Shah variational models, and details on the numerical implementation of the Blake-Zisserman model in 1D can be found here (my PhD thesis in pdf).

The CLI sigseg program requires the name of the file containing the data and the name of the file containing the values of the functional parameters to be specified as input parameter.

The input file containing the data is a single column text file with the values of the data. The input file containing the functional parameters is a text file of the form:
 alpha float beta float epsilon float gamma float mu_epsilon float lambda_epsilon 0. tol float mx_iter int
Replace the word "float" with the real value (>= 0) of the respective functional parameters.
Remember the condition: β ≤ α ≤ 2 β if you want to use the Blake-Zisserman model.
Remember to set the parameter beta and gamma to zero if you want to use the Mumford-Shah model.

The parameter "tol" is the convergence threshold of the iterative procedure implemented in the code to minimize the variational model in use. The sigseg program stops when the difference between the current solution and the solution computed at the previous iterative step is smaller than the "tol" value.
Replace the word "float" with the real value (>= 0) for tol.

The parameter "mx_iter" is the maximum number of iterative steps performed before the sigseg program stops.
Replace the word "int" with the integer value (>= 0) for the "mx_iter" parameter.

When a parameter is set to a value greater than zero, the other parameter should be set to zero.
If both the parameters are set to a value greater than zero, the more restrictive of the two is used to stop the iterative procedure.
If both the parameters are set to zero the sigseg program exits with an error.

For instruction on how to run the sigseg program, see the "README.txt" file shipped with the program source code.

See the folder "sample_data" shipped with the source code of the program for examples of input data and input parameters files.

Notes

a) The current version of the sigseg program prints the result of the segmentation on the standard output, i.e., on the terminal window from where the program has been executed.

The folder "script" contains a bash script that can be used to run the sigseg program from the folder where the program has been complied. The script name is: "localrun.sh".
The folder "script" contains also another bash script that uses gnuplot to display on your monitor a plot of the result produced by the "localrun.sh" bash script.
The "script" folder is shipped with the program source code.

Example of the use of the bash scripts.

Open a terminal window and move to the folder where the sigseg program has been compiled:
$cd PATH_TO_FOLDER_sigseg_0.9 Set the following bash variables:$ D=PATH_TO_FILE_inputdatafile
$P=PATH_TO_FILE_inputparametersfile$ K=A
Execute the localrun.sh script:
$sh scripts/localrun.sh$D $P$K
Execute the gplot.sh script:
$sh scripts/gplot.sh$D \$K

The variable K is useful when different input data files and/or input parameters files are used, and you want to be able to compare different (plots of the) results.

b) The result of the variational segmentation depends on the values of the parameters.
The choice of good parameters is not straightforward. However, preliminary results can be obtained with a small number of iterations. This can keep the last of an empirical search reasonably short.
When the parameters are being set up, it seams convenient to fix the "mx_iter" parameter to a value ranging from 100 to 500 while leaving the "tol" parameter to zero. The parameter "tol" could be used more effectively to refine preliminary results. A first attempt to find a relation between the parameters and the properties of the data was carried out already by A. Blake and A. Zisserman in their work: "Visual Reconstruction" (The MIT Press, Cambridge, 1987).

c) The sigseg program can handle only equi-spaced data.

d) The notation used in the PhD thesis is not entirely consistent with the notation used in this page.

Home | SW page

..: 2009 :: Alfonso Vitti :..