Command Line Interface
Gerbil comes in two parts, a command-line interface (CLI) called gerbil (or gerbil.exe) and a graphical user interface (GUI) called qgerbil (or qgerbil.exe). On this page we explain how to use the CLI for batch-processing of images or for algorithms that are not accessible via the GUI.
General usage
Within Windows you can fire up cmd in the Run dialog to obtain a command shell. On OS X you find the Terminal application under Applications/Utilities in Finder. If you use Linux, you should know how to open a terminal already. Then navigate to the directory (using the cd command) where Gerbil is installed and run bin/gerbil or bin\gerbil. It should look like this:
# bin/gerbil
.s_, ._ssaoXXXZqaa,.
_mmZmaoZXSnooooXXZmWWma.
_mQWmZZoo2ooonnnnnXZ#mWWBma.
<QWQB#ZXnnoo2onvnnnXX#mBmWWWm,.
=WWmW#ZenvnoonI|+|+{nX##WBWBWBWWga,
???Y?"---<vIl|i=====I3X#mWmBm###:?Wc
)nnii"---- ---*YX##!~- .mk
- :iiv?!~- . .j#~
_saZ!`
G E R B I L -{I;_asssas%IY!!^
Usage: code/trunk/build/bin/gerbil [--help] command [configfile] [options ...]
All options can also be given in the specified config file.
Options given in the command line will overwrite options from the file.
Available commands:
edge_detect: Edge detection in multispectral images using SOM.
felzenszwalb: Superpixel Segmentation by Felzenszwalb, Huttenlocher on multispectral images
graphseg: Graph Cut / Power Watershed segmentation by Grady
meanshift: Fast adaptive mean shift segmentation by Georgescu
meanshiftsp: Fast adaptive mean shift segmentation on superpixels
rgb: RGB image creation (true-color or false-color)
Note: We denote user input with a hashtag here, don’t enter the hashtag.
The command line contains three parts: A command, optionally a configuration file, and options to the command. With the --help or -H option you can obtain an explanation of available options.
Example: False-color image generation
First we ask for help on the command:
# bin/gerbil -H rgb
-------------------------------------------------------------------------------
RGB image creation (true-color or false-color)
XYZ does a true-color image creation using a standard white balancing.
PCA and SOM do false-coloring."
-------------------------------------------------------------------------------
Options for rgb:
-V [ --verbose ] arg (=1) Verbosity Level: 0 = silent, 1 =
normal, 2 = much output, 3 = insane
--algo arg (=XYZ) Algorithm to employ: XYZ true color,
PCA or SOM false-color
--pca_stretch In PCA case: Maximize contrast in each
channel individually
--somDepth arg (=5) In SOM case: number of best matching
neurons to incorporate
--somLinear In SOM case: Use linear BMU mixing
instead of weighting scheme
-O [ --output ] arg (=output_rgb.png) Output file name
--som.verbose arg (=1) Verbosity Level: 0 = silent, 1 =
normal, 2 = much output, 3 = insane
--som.som_input arg When set, read given multispectral
image file to initialize SOM instead of
training
--som.type arg (=square) Layout of the neurons in the SOM: line,
square, cube
--som.sidelength arg (=32) Sidelength of line / square / cube of
the SOM
--som.maxIter arg (=40000) Number of training iterations for the
SOM
--som.learnStart arg (=0.75) Learning rate at the beginning
--som.learnEnd arg (=0.01) Learning rate at the end of the
training process
--som.sigmaStart arg (=12) Initial neighborhood radius
--som.sigmaEnd arg (=2) Neighborhood radius at the end of the
training process
--som.seed arg (=1399555502) Seed value of random number generators
--som.similarity.verbose arg (=1) Verbosity Level: 0 = silent, 1 =
normal, 2 = much output, 3 = insane
--som.similarity.measure arg (=EUCLIDEAN)
Similarity measurement function.
Available are: MANHATTAN, EUCLIDEAN,
CHEBYSHEV, MOD_SPEC_ANGLE,
SPEC_INF_DIV, SIDSAM1, SIDSAM2, NORM_L2
--input.verbose arg (=1) Verbosity Level: 0 = silent, 1 = normal, 2 = much
output, 3 = insane
--input.file arg Image to process
--input.roi arg apply ROI (x:y:w:h)
--input.normalize normalize vector magnitudes
--input.gradient compute spectral gradient
--input.bands arg (=0) reduce number of bands by linear interpolation (0
means disabled)
--input.bandlow arg (=0) apply lower bound of band ROI
--input.bandhigh arg (=0) apply upper bound of band ROI
As you can see, the interface is quite self-explanatory. If you are happy with the default values, you don’t need to specify them. To compute a false-color image on the spectral gradient with a 2d SOM, we can just run:
# bin/gerbil rgb --input.file data/fake_and_real_peppers_ms.txt --input.gradient --algo SOM -O output_som.png
In this example, the input is an image from the CAVE database and was put into the data folder before. To compare with PCA false coloring, we can then run:
# bin/gerbil rgb --input.file data/fake_and_real_peppers_ms.txt --input.gradient --algo PCA --pca_stretch -O output_pca.png
We are now able to compare the result images. However, the 2d SOM only uses red and green. Let’s write a small config file that expresses a 3d SOM. The file is called cube.conf and has this content:
algo = SOM
[som]
type = cube
sidelength = 10
sigmaStart = 4
sigmaEnd = 1
learnStart = 0.75
learnEnd = 0.01
maxIter = 100000
As you can see, the syntax is the same as on the command line, however, subsections that are separated by a dot on the command line are given as a header here ([som] instead of som.) to make the file easier to read. To produce the 3d SOM output we can now call:
# bin/gerbil rgb --input.file data/fake_and_real_peppers_ms.txt --input.gradient cube.conf -O output_som3d.png
In this example, we combined a configuration file with command line options. Note that command line options always take precedence over a config file. E.g. if the config file states input.gradient=false, we would still operate on the gradient with the command above.
We finally run the program again to compute a true-color image:
# bin/gerbil rgb --input.file data/fake_and_real_peppers_ms.txt -O output_cmf.png
And here are the outputs:
Example: Edge detection
In the edge detection module, we can create fake Sobel maps from the manifold learned by a SOM. Let’s ask first:
# bin/gerbil -H edge_detect
-------------------------------------------------------------------------------
Edge detection in multispectral images using SOM.
Please read "Jordan, J., Angelopoulou E.: Edge Detection in Multispectral
Images Using the N-Dimensional Self-Organizing Map." (ICIP 2011)
-------------------------------------------------------------------------------
Options for edge_detect:
-V [ --verbose ] arg (=1) Verbosity Level: 0 = silent, 1 =
normal, 2 = much output, 3 = insane
--som_input arg When set, read given multispectral
image file to initialize SOM instead of
training
--type arg (=square) Layout of the neurons in the SOM: line,
square, cube
--sidelength arg (=32) Sidelength of line / square / cube of
the SOM
--maxIter arg (=40000) Number of training iterations for the
SOM
--learnStart arg (=0.75) Learning rate at the beginning
--learnEnd arg (=0.01) Learning rate at the end of the
training process
--sigmaStart arg (=12) Initial neighborhood radius
--sigmaEnd arg (=2) Neighborhood radius at the end of the
training process
--seed arg (=1399557469) Seed value of random number generators
-I [ --input ] arg (=input.png) Image file to process
-O [ --output ] arg (=/tmp/) Output directory
--output_som Output trained SOM as a multispectral
image
--similarity.verbose arg (=1) Verbosity Level: 0 = silent, 1 =
normal, 2 = much output, 3 = insane
--similarity.measure arg (=EUCLIDEAN) Similarity measurement function.
Available are: MANHATTAN, EUCLIDEAN,
CHEBYSHEV, MOD_SPEC_ANGLE,
SPEC_INF_DIV, SIDSAM1, SIDSAM2, NORM_L2
As you can see, here the SOM learning parameters are given directly. Also, the input and output parameters are different. Let’s just try it!
# bin/gerbil edge_detect -I data/fake_and_real_peppers_ms.txt -O .
This tells the command to use default parameters and store the results in the current folder. The resulting images are called dx.png and dy.png (However, there is a small glitch: dx.png shows the derivation in y, dy.png accordingly in x.). They can be used for further processing, e.g. by Canny (not included in the software). Here is how they look like:
