The openip open source image processing library

The openip open source image processing library Gy¨orgy Kov´acs May 26, 2010

Contents I

Install Guide

3

1 Linux 1.1 Required tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4 4 5

2 Windows 2.1 General requirements . . . . . . . . . . . 2.2 Preface to build tools in Windows . . . 2.3 Installing MinGW . . . . . . . . . . . . 2.3.1 MinGW from the Qt SDK . . . . 2.3.2 MinGW from the actual build . . 2.4 Installing MSYS . . . . . . . . . . . . . 2.5 Testing the installed tools . . . . . . . . 2.6 Compiling the openIP sources . . . . . . 2.6.1 Using the NetBeans project files 2.6.2 Compile in the command line . . 2.6.3 Usual problems . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

7 7 7 8 8 8 9 9 11 11 11 11

3 Testing 3.1 Test 3.2 Test 3.3 Test 3.4 Test 3.5 Test 3.6 Test

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

12 12 12 14 14 16 16

01 02 03 04 05 06

-

matched filters . . . . . thinning . . . . . . . . thresholding . . . . . . ROI selection dialog . . 3D visualization dialog OpenCL . . . . . . . .

1

. . . . . .

. . . . . .

. . . . . .

. . . . . .

Introduction The openIP open source image processing library provides tools and environment for development and research in image processing and computer vision. The current 0.0.4 release of the library contains common data structures related to image processing, I/O support, numerical tools, low-level image processing methods, machine learning algorithms and visualization tools. The following libraries are in the openip-0.0.4 release: • openipDS - providing the basic datastructures • openipIO - methods for image I/O operations • openipSC - a very simple wrapper over the GSL - GNU Scientific Library • openipML - machine learning algorithms • openipVS - visualization tools based on Qt • openipLL - using the tools of the previous libraries, this library contains some simple low-level image processing operations Due to the interoperability of the projects and code, currently the open source developer tools (gcc, netbeans, qt) are supported both in windows and linux. In the followings a short tutorial guides you through the steps of the configuration and compilation of the libraries.

2

Part I

Install Guide

3

Chapter 1

Linux 1.1

Required tools

In Linux systems the configuration and compilation is very simple. The library wraps all the libraries required (libjpeg, libpng, libtiff, gsl, ...), except Qt, therefore it is easy to set up the environment, but the packages mentioned before can be installed two times on the system. Once as part of the system (/usr), and once as part of the openIP libraries. This is a compromise we had to made for the easy portability of the whole openIP libraries. (We are planning to release source packages dedicated for Linux systems to reduce redundancy, but currently we are focusing on the functionalities of the libraries). We used cmake system, besides we provide netbeans project files, since it is interoperable, as well. Hence to build the libraries, the following general tools are required: • gcc • cmake The libraries are well-documented in doxygen style, to generate the documentation, you may also need • doxygen installed. Visualization is an optional feature in openIP. If you wanna build graphical user interfaces or use the dialog primitives provided in the openipVS library, you must install • Qt4 • libXmu • libXi • freeglut - for 3D visualization In Debian based Linux systems (Debian, Ubuntu, Kubuntu, Edubuntu, LinuxMint) the installation can be performed with the following command: sudo apt-get install gcc4 cmake doxygen Qt4-* libxmu-dev libxi-dev freeglut-dev 4

In Linux systems not based on Debian, you can use the appropriate software installation tool, the required libraries are present in almost each Linux repositories.

1.2

Guide

Download the tarball, with or without project files, and extract it: tar xvzf openip-0.0.4-src.tar.gz Enter the extracted directory: cd openip-0.0.4-src The directories inside are empty except the src and data directories. Enter the src directory: cd src Here you can find the cmake project file. To compile the libraries Makefiles must be generated using cmake. The libraries can be compiled in debug or release mode, depending on setting the -DCMAKE_BUILD_TYPE=Debug or -DCMAKE_BUILD_TYPE=Release option. If non of the is set, the libraries are compiled in Debug mode. Install prefix can be set through the -DINSTALL_PREFIX= /usr option. If install prefix is not set, the library will be installed into the hierarchy extracted from the tarball. (e.g. you can set both options cmake -DCMAKE_BUILD_TYPE=Release -DINSTALL_PREFIX=/usr .): cmake . This call generates the Makefiles required to compile the libraries. Now the libraries can be compiled calling make: make After the libraries are compiled, it is worth to install them into the appropriate directories: make install Now the shared object files and a test application can be found in the install prefix/ lib and install prefix/ bin directories. In order to make the test application find the shared object libraries, the appropriate environment variables must be set. In Debian based systems this variable is LD_LIBRARY_PATH, that is you must add the path of the lib directory to this variable, using the following command or adding this line to the end of the file .bashrc: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:install_prefix/lib The documentation for each of the libraries can be generated using doxygen, the appropriate doxyfiles can be found in the src directories, so e.g. standing in the src directory enter lib, then openipDS directory: cd lib/openipDS

5

Here you can find the doxyfile, so You can use doxygen in the following way: doxygen doxyfile Repeat this step for all the libraries, in order to generate the documentations you need. The generated HTML documentations get installed into the openip0.0.4-src/docs directory. Now the libraries are compiled. To see how to test some functionalities skip the chapter about Windows Guide.

6

Chapter 2

Windows It is strongly recommended to develop in Linux systems! To work with the open source tools in Windows is tricky a little bit. Since we try to avoid the use of commercial software, more tools have to be installed, than in linux systems.

2.1

General requirements

Since the build system is cmake based, the • cmake (http://www.cmake.org/cmake/resources/software.html) must be installed. To avoid possible problems in the compile process, install cmake to path, which does not contain space characters, instead of installing it into the default c:/Program Files/CMake 2.8 directory. To generate the documentation, install • doxygen (http://www.doxygen.nl/download.html#latestsrc)

2.2

Preface to build tools in Windows

Depending of Your choice, any of the following compiler/make configurations can be used to build the libraries. First of all, shortly about the compilation in Windows: The MinGW abbreviation stands for Minimalist GNU for Windows, therefore it contains the pack of GNU compilers and in contrast with cygwin, MinGW uses the tools of msvcrt.dll provided by Windows. If cygwin would be used to compile the openip stuff in Windows, the cygwin.dll should be present on each system, on which the openip tools are run. Using MinGW this phenomena is avoided, since the msvcrt.dll is basically present in the newer versions of Windows. The MinGW installer available at the official MinGW web page is currently out of date, that is it contains only the version 3.6 gcc compilers, and the tools integrated in the openip package, like openMP based parallelization, can not be handled by the 3.x versions of gcc. This is the reason, why the set up of the 7

MinGW environment is tricky. Do not use the MinGW-5.1.6.exe installer, since it contains an old build of MinGW! Those, who are used to Visual Studio based development, or familiar with Java, can find it strange, that in this development no usual project files are provided. The compilation rules are in the so called Makefiles, generated by cmake software in this case. However, to build the project upon these Makefiles, make program is required. There are several standards/languages for the content of a Makefile, requiring different make software. The easiest is to use MinGW or MSYS Makefiles in Windows. MSYS is a thin linux-like shell environment for Windows, containing the most necessary tools and commands, like rm, cp and make. In the next sections the compile process is presented using MinGW compiler with MSYS Makefiles.

2.3 2.3.1

Installing MinGW MinGW from the Qt SDK

The actual version of the Qt SDK contains the MinGW tools with up-to-date GNU compilers. 2.3.1.1

Required tools

Install the Qt SDK provided by Trolltech: • Qt SDK for Windows (http://qt.nokia.com/downloads) 2.3.1.2

Guide

After installing the tools, do not forget to add the path of the binary cmake.exe, doxygen.exe files and the path of the mingw\\bin directories to the PATH environment variable, namely add the following strings, depending on the installation path: c:\...\cmake2.8\bin;c:\...\doxygen\bin;c:\...\Qt\2010.02.1\mingw\bin If some of the installed software does not work, do not go further, try to solve the problem by checking the PATH variable!

2.3.2

MinGW from the actual build

Although the currently available MinGW installer is an old one, the components of the actual build can be downloaded from the MinGW webpage through the following link: http://www.mingw.org/wiki/Getting_Started

8

2.3.2.1

Required tools

Download each of the following packages: • binutils • mingw-runtime (dev and dll) • w32api • runtime libraries for GCC (gmp, libiconv, MPFR, pthreads) • gcc-core (bin and dll) • gcc-g++ (bin and dll) • mingw32-make 2.3.2.2

Guide

Copy all the downloaded files into an empty directory (e.g.: mingw) and extract each of them. After extraction You got the same small MinGW environment as provided by the Qt SDK. In order to use these tools You must put the binary directory (e.g.: mingw/bin) into the system PATH environment variable as described in section MinGW from the Qt SDK.

2.4

Installing MSYS

In windows we will use MSYS in the build process, so download it from the link http://www.mingw.org/wiki/MSYS and install it into an arbitrary directory. Do not forget to add the MSYS/bin directory to the PATH environment variable.

2.5

Testing the installed tools

In Windows the environment variables are mapped to processes, so after altering the PATH environment variable you must restart each process in which you want to use the values of the altered variable. Therefore you can test the PATH in a new command line (cmd) window. You can check the value of PATH as well as the installed tools, with the following commands in the command line: echo %PATH% You must see something like this: c:\Windows\system32;c:\Windows;c:\Qt\2010.02.0\qt\bin; c:\Qt\2010.02.1\mingw\bin;c:\cmake2.8\bin;z:\msys\1.0\bin ;c:\Program Files\doxygen\bin Testing cmake cmake --version You must get a long list of command line options:

9

cmake version 2.8.1 Calling doxygen doxygen --version You must see another long list of command line options and usages, something like 1.6.3 Trying g++, just call g++ --version The desired output: g++ (GCC) 4.4.0 Copyright (C) 2009 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is no warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Similarly with gcc, call gcc --version The desired output: gcc (GCC) 4.4.0 Copyright (C) 2009 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is no warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Be sure, the version of g++ and gcc is higher or equal to 4.4! Testing make call: make --version The desired output should be something like: GNU make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is no warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program is built for i686-pc-msys

10

2.6 2.6.1

Compiling the openIP sources Using the NetBeans project files

After extraction of the openIP tar ball, you can find the NetBeans 6.8 project files in the src\projs directory. You can compile the projects one-by-one. Do not forget to select the right configuration in NetBeans (DebugWindows/ReleaseWindows). Since the packages are built on each other, compile them in the following order: 1. openipDS 2. openipIO 3. openipSC 4. openipLL 5. openipML 6. openipVS 7. testApp

2.6.2

Compile in the command line

The project is built using the cmake system. On the one hand, each of the source directories contains a CMakeLists.txt configuration file, using them, the libraries can be compiled one-by-one, on the other hand, there is one CMakeLists.txt file in the openip/src directory, using this latter one, all the libraries and the test application can be compiled simultaneously. Use the following command to generate Makefiles: cmake CMakeLists.txt [-DBUILD_TYPE=Debug | -DBUILD_TYPE=Release] -G "MSYS Makefiles" The -DBUILD\_TYPE=Debug and -DBUILD\_TYPE=Release options can be used to set the build mode, if none is set, the libraries are built in Debug mode. Once the Makefiles are generated, You can build and install the libraries using make: make make install

2.6.3

Usual problems

• If cygwin is installed, problems can turn out, since cygwin has also gcc, g++ and make programs. It is worth to remove cygwin\bin from PATH. • cmake must be installed to a path without space characters.

11

Chapter 3

Testing For testing the test application should be used, which is compiled in the openip0.0.4/bin directory both under Windows and Linux operating systems. If you get a command line and type: ./testApp --help or testApp.exe --help you must see the list of switches and options of the test application. The two functionalities which can be tested are the matched filters for linelike structure enhancement (both in image and Fourier-space) and an iterative thinning method. For testing the images of the openip-0.0.4/data directory should be used.

3.1

Test 01 - matched filters

The first test is about matched filtering. The test image for this is the image24 training.jpg, which contains the image of a human retina. The application of matched line segment filters here is to enhance and detect the vascular system on the image. You can use the matched filters on this image in both image space and Fourier-space: ./testApp --mf ../data/image24_training.jpg mf-image-space.jpg ./testApp --mf --ff ../data/image24_training.jpg mf-fourier-space.jpg The matched filters in image space have very huge computing demand, therefore the application can run for several seconds. Doing the same operation in Fourierspace, you can get the same results in shorter time. Compare the results and the run time and check the source for details. On Figure 3.1 you can see the test image and the result.

3.2

Test 02 - thinning

The iterative thinning can by tested on the chipmunk.pgm image: 12

Figure 3.1: The original and the enhanced retina image

Figure 3.2: The original and the thinned image

13

Figure 3.3: The original and the thresholded image ./testApp --th ../data/chipmunk.pgm chipmunk-skeleton.pgm Note, that in the first run, the testApp generates a file called binaryMaskSystem2.lut. This file contains a look up table, which must be generated only at the first run of the CWSI skeletnoization process. In the further runs, on any images, this look up table will be used, which makes the processing much faster. You can try it typing the same command again and compare the run times. On Figure 3.2 the test image and the result can be seen.

3.3

Test 03 - thresholding

In this test the simple thresholding method from Niblack is applied to the input image with its default parameters ./testApp --thres ../data/vessel/01_test.jpg vessel-thresholded.jpg The input and output images can be seen on Figure 3.3.

3.4

Test 04 - ROI selection dialog

This test is available only if the openipVS library depending on Qt is compiled. In this test the dialog primitives are demonstrated, namely the open image, save image, and region of interest selection dialog. The application asks for an image to open, once the image is opened, the region of interest must be selected. The region of intereset will be Gaussian filtered with deviation 8 and kernel size 21. The output image is saved to a file name provided by the save image dialog. .\testApp --vis The input and output images and the screenshot of the dialog can be seen on Figure 3.4.

14

Figure 3.4: The original image, screenshot from the ROI selection dialog, filtered result

15

Figure 3.5: Screenshot of the 3D visualization dialog

3.5

Test 05 - 3D visualization dialog

This test is available only if the openipVS library depending on Qt is compiled. In this test the 3D visualization can be tested. The parameters of the application are a retina image, and the mask of the vessel system in the image. The application extracts 3 dimensional feature vectors from the image using the second derivative Gaussian filters. The feature vectors belonging to points of the vessel system are visualized by green vertices, the vectors belonging to the background are visualized by red vertices. Screenshot of the 3D visualization can be seen on Figure 3.5. ./testApp --vis3 ../data/vessel/01_test.jpg ../data/vessel/01_test_VS.jpg

3.6

Test 06 - OpenCL

This test is available only if the appropriate driver from nVIDIA or ATI is installed. In this test a simple Gaussian filter is applied to the input image, using the OpenCL kernel generated by the GaussianFilter object. ./testApp --openCL ../data/chinese.jpg chinese-filtered.jpg The input and output image can be seen on Figure 3.6. 16

Figure 3.6: Input and output of OpenCL filtering, using the generated kernels

17