Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

Building & Installing Phission in Linux and Cygwin

Table of Contents


The Quick and Dirty Installation Guide


Detailed Installation

Here is a more detailed discussion for downloading, configuring and installing Phission.

Download Phission

After installing as many of the optional packages from above, you should now be ready to install Phission. If you have any difficulties installing or compiling Phission, please subscribe to and/or email the phission-help@lists.sourceforge.net mailing list. There are two places you can obtain Phission: From CVS. CVS requires a couple extra initial steps and the autotools ( automake / autoconf ) development support. After these initial steps, configuring and building the source is very similar (in fact, identical) to the distributed release.

From CVS

First one needs to checkout the code base from CVS. This is equivalent to downloading the code that currently resides in the CVS repository. You'll want to login to the anonymous sourceforge.net account in order to set up the CVS session. When prompted for a password after the login command, just press enter/return.

$ cvs -d :pserver:anonymous@phission.cvs.sourceforge.net:/cvsroot/phission login 

After a successful login, the Phission code base can be checked out from CVS:


$ cvs -z3 -d :pserver:anonymous@phission.cvs.sourceforge.net:/cvsroot/phission checkout -d <phissiondir> phission

The -d <phissiondir> parameter is a checkout command parameter and is optional. It merely specifies the name of the directory where the Phission code base is stored. Use cvs –help checkout for more checkout command options. Don't confuse the checkout command's -d switch with the cvs program's -d switch which overrides the default environmental variable for $CVSROOT (if it's defined).

If you're subscribed to the CVS mailing list , saw some important fix and want to update code that was checked out a while ago:


$ cd phission 
$ make clean 
$ cvs -z3 update -dR 

Building Phission

After getting the Phission code from either a release package or CVS, you'll need to generate the Makefiles and configure related files. This assumes that the release package isn't preconfigured (look for configure for your specific platform. Generating the Makefiles and configure need the latest autotools: automake, autoconf, and libtool. If you're getting packaged releases such as SRPMs or using Cygwin, you'll want to install the development packages for each autotool package, too.

Autogen.sh : Generating configure and the Makefiles

A script is supplied to automate the series of commands for generating the files. Run the following from the phission directory, i.e. not in the scripts directory:

$ ./scripts/autogen.sh

You should now be able to run configure and make, make install as you would an ordinary packaged release.

Configure script

The configure script will allow you to disable/enable or compile with/without some feature that is available. Run with the --help switch to get a list of the options available to you:

$ ./configure --help 

This can be useful if, for example, some optional feature isn't compiling properly. You can disable it and then re-run make to allow you to get some minimum of Phission built. Any problems should be emailed to the author or the phission-help@lists.sourceforge.net mailing list.

If you don't have root access or just want to test out Phission. You can install to your home directory by using the --prefix configure switch. Suppose you have a directory called local in your home directory. (Make sure that you have created the local directory in your home directory before running the configure script.) The following will set up the Makefiles so they will install to /home/myusername/local:


$ ./configure --prefix=/home/myusername/local

If you're interested in specific features, like Python support, you'll want to pay careful attention to the final report printed when configure finishes successfully. It lists the supported packages and whether the relevant Phission code will be compiled for those packages. If a capability has no after it, this may be the default setting or there may have been an error when the configure script tested for that package support. Looking at config.log can be useful in determining what could have potentially gone wrong if the default is yes or the configure switch was supplied to enable the package support. The following is an example print out from configure when it finishes:

        
configure: --------------------------------------------------
configure:     Using Network capabilities: yes
configure:     Using ZLib:                 yes
configure:     Using libjpeg:              yes
configure:     Using JRTPLIB:              no
configure:     Using JTHREAD:              no
configure:     Using AVCODEC:              yes
configure:     Using OpenCV:               yes
configure:     Using VideoForWindows:      no
configure:     Using Video4Linux:          yes
configure:     Using GDI:                  no
configure:     Using X11:                  yes
configure:         Using XShm:             yes
configure:         Using Xdbe:             yes
configure:         Using XF86DGA:          yes
configure:         Using XVlib:            yes
configure:         Using XF86VMode:        yes
configure:     Using SDL:                  yes
configure:     Using FLTK:                 no
configure:     Using SWIG:                 yes
configure:          Using Python:          no
configure:          Using Java:            no
configure:              Why? Java option not enabled
configure:     Building Vision Classes:    yes
configure: --------------------------------------------------

Building and Installing Phission

After you've configured your build you simply run "make" and then "make install" assuming nothing failed to compile.

If you aren't the super user you'll need to install to your own directory.

Building and Installing the RPM

The ./scripts/makerpm.sh script is used to automate the RPM creation process. If you are running on a Linux system, you will have to have superuser privileges so you can build in the temporary RPM source directories (/usr/src/redhat/). The script will run scripts/autogen.sh and then ./configure. If necessary, these commands can be changed by editing the ./scripts/makerpm.sh script. The config/phission.spec file is output by running configure. The input file config/phission.spec.in is the input for that .spec file and if it needs to be edited, configure will have to be run again. Next, the version is grepped from the .spec file and a tarball is created. The tarball is passed to rpmbuild which will output a Source RPM. The Source RPM is then passed back to rpmbuild to create the Binary RPM file output. The location of the Binary RPM will be printed towards the end of the rpmbuild process should everything execute successfully to this point. You can then install the Binary RPM using rpm -iUvh <pathtorpm> .

Configuring Phission on a 64-bit machine for 32-bit

Use the script ./scripts/32bit_config.sh if you want to configure your Phission build to be a 32-bit build on a 64-bit machine. If you decide you want to build in 32-bit mode, you'll need the 32-bit libraries for the optional packages above as well as the system dependent support libraries. Otherwise, you'll get relocation errors because the 32-bit compiled output can't be linked with the 64-bit libraries.

Post installation

In order to use phission-config (the Phission examples depend on it) you'll need to add an export command to your ~/.bashrc:


$ export PATH=/home/username/installs/:$PATH

This will allow phission/examples/cpp/Makefile.example (which is sourced from all the subdirectory Makefiles) to find phission-config and retreive the required compilation and linking flags/arguments.

Uninstalling

If you haven't done a make distclean in your Phission source directory and you have up-to-date autotools, you'll also be able to uninstall Phission after you install if you need:

$ make uninstall


Optional Packages

All the packages listed below are optional and none are required for the most basic capabilities of Phission. For example, if you don't install the libjpeg package, then you won't be able to save images as jpegs or compress the data to a jpeg. The version numbers you'll find up to date may be different than the version numbers in the documentation below. If a newer version doesn't work with Phission, please send an email so the code base can be updated if it's necessary. If you want to build with support for one of the optional packages, you'll likely need all the libraries and headers required for development. The web sites where the projects are hosted and where downloads can be obtained are included for each package. Since Phission has been developed on the Redhat distribution, instructions are given for building Redhat packages as opposed to Debian or another package type.

SDL

http://www.libsdl.org/

SDL ( Simple Direct Media Layer ) is a fast portable media library that is being used here for it's high performance capabilities and is required by the SDLDisplay class. See the documentation below on Display classes for more information. on using a display class. It is possible to only have one 1.2.x SDL version window open in any instance of an application. For this reason, the X11Display and GDIDisplay displays were written for Linux/Cygwin and Windows respectively. Even with this limitation, the SDLDisplay is likely to provide way better performance than the X11 or GDI displays. SDL can be used in conjunction with the X11 and GDI displays if more than one window is necessary.

Install SDL

Check to see if you have SDL installed:

$ rpm -q SDL 
$ rpm -q SDL-devel
$ which sdl-config 
$ locate sdl-config | grep bin 

I'd suggest use of the source RPM (src.rpm) and that one build a binary version using the following command (must have root access):


$ rpmbuild --rebuild SDL-1.2.6.src.rpm 

rpmbuild will proceed to compile and assemble a binary RPM file and will display the full path to that file at the end of the build.

Install the rpm using the following command(as root or using sudo):


$ rpm -iUh /path/to/binary/package.i386.rpm 

FLTK

http://www.fltk.org/

FLTK is a GUI library and is required for the FLDisplay class. The FLTK library is also used for some of the OpenCV library routines internal to the OpenCV package which aren't used by Phission but are useful when exploring OpenCV examples. The inclusion of a display class that uses a GUI package like FLTK is to provide the basis for a C/C++ program with menus and buttons to allow manipulation of the Phission classes during runtime. The phFLImageWindow class contains the GUI specific code and could be contained in a full blown FLTK application that connects it to any of the constantly updating phImage sources internal to a capture class or a pipeline.

Install FLTK

Check to see if you have FLTK installed:

$ rpm -q fltk
$ rpm -q fltk-devel 
$ which fltk-config 
$ locate fltk-config | grep bin 

Version 1.1.x should be downloaded and installed. Newer versions have not been tested with Phission. I used the SourceForge servers and downloaded the tarball (tar.gz).

The FLTK tarball has an RPM .spec file (fltk.spec) file packaged with it and can potentially be built into a binary RPM package using the following command:


$ rpmbuild -ta fltk-1.x.x.tar.gz 

If that fails, you can still untar ( tar -xvzf fltk-1.x.x.tar.gz ) the tarball and build it manually:


$ cd fltk-1.x.x 
$ ./configure 
$ make
$ make install 

OpenCV

http://sourceforge.net/projects/opencvlibrary/

OpenCV is going to be required for most the filters in furture releases of Phission, but is currently only required for one filter (which resides in the phission/filter/video/ directory): cv_canny_Filter. OpenCV provides many image processing filters and has a long detailed and thorough manual documenting their use. I suggest learning and using OpenCV if you really want top quality high performance image filters. The Phission filters have been C/C++ optimized only to a certain extent in order to provide as decent performance as possible using C/C++. If you write a phFilter that uses an OpenCV filter, please submit it one of the mailing lists or myself so it can be included in the Phission distribution.

Install OpenCV

Check to see if you already have OpenCV installed:
$ rpm -q OpenCV
$ which opencv-config
$ locate opencv-config | grep bin (v0.9.5)
$ locate opencv.pc (v0.9.6)

Downloading version 0.9.5 is recommended. There is an RPM .spec file within the tarball (tar.gz) but may need to be edited. To try and build the binary RPM package:


$ rpmbuild -ta OpenCV-0.9.5.tar.gz

If this doesn't work, you can untar the tarball:


$ tar -xvzf OpenCV-0.9.5.tar.gz 

edit the .spec file or create it if necessary:


$ ./configure

(will use OpenCV.spec.in to create OpenCV.spec) 

Save the old tarball and repackage the tarball:


$ mkdir backup 
$ mv OpenCV-0.9.5.tar.gz backup/ 
$ tar -cvzf OpenCV-0.9.5.tar.gz OpenCV-0.9.5 

Build the RPM binary package:


$ rpmbuild -ta OpenCV-0.9.5.tar.gz 

Finally, install the RPM package rpmbuild created:


$ rpm -iUh /path/to/OpenCV-0.9.5.i386.rpm 

If you've gone through all that with no luck, you can still untar ( tar -xvzf OpenCV-0.9.5.tar.gz ) the tarball and build it manually:


$ cd OpenCV-0.9.5 
$ ./configure 
$ make 
$ make install 

SWIG

http://www.swig.org/

SWIG supplies the facilities to bind/wrap Phission's API into any of the supported SWIG langauges. Each language being bound to usually has some amount of differences from C/C++ syntax and capabilities. This requires changes to the Phission code base to support those differences. Python and Java are currently the only alternative supported languages.

Install SWIG

Check to see if you already have Swig installed:

$ rpm -q swig 
$ which swig 
$ locate swig | grep bin
$ swig -version 

I suggest getting the latest version (1.3.24) of SWIG.

You may be able to create an RPM binary package using the tarball:


$ rpmbuild -ta swig-1.x.x.tar.gz 

After building the RPM, install it:


$ rpm -iUh /path/to/swig-1.x.x.i386.rpm 

Otherwise, follow the SWIG directions for installing this package.

Python

http://www.python.org/

Python is the language in which Pyro (Python for Robots) is written. Support for Python wrapping is supplied by the SWIG package and without it Python will not be supported.

Java

http://java.sun.com/

You'll want to download the SDK so the Java classes and modules can be built correctly. Phission uses J2SE 1.4.2 for Java development and other versions have not yet been tested. SWIG 1.3.24 is required for correct Java support and without it the Java language bindings won't be supported.

zlib

http://www.zlib.net/

libjpeg

http://www.ijg.org/

libjpeg is usually installed in most distributions. Instructions on building and installing libjpeg are similar to instructions for building and installing other packages above.

FFMpeg

http://ffmpeg.sourceforge.net/

FFmpeg is a group of tools and libraries that allow reading, converting and playing of supported audio and video files. Even raw device reading and writing are supported by the FFmpeg project. The libavcodec and libavformat libraries supplied by the FFmpeg project allow Phission to read (and potentially write) video files. There are a large number of audio and video formats that are supported as outlined by the documentation: Supported File Formats and Codecs. Phission's ability to read video files allows researchers to capture videos, in any way that is convenient for them, and have Phission play the video as a regular source. The difference of any code written to use a Video4Linux device and input from a video file are very minimal and lie only in the particular configuration differences between the V4LCapture class and the phAvcodecSource class. (Capture and Source terms are interchangeable as in a Capture device is a Source of video data and a Source uses Captured data. The names are still in a bit of flux. ) While Phission tries to keep up with the CVS changes of FFmpeg, version 0.4.9-pre1 is the package that is recommended if you want stability. The CVS version has newer codec support which can come in handy.

Install libavcodec and libavformat

You have two choices for installing FFmpeg (which supplies libavcodec and libavformat): install from CVS or install from a tarball. Either way, if one choice doesn't work it's likely the other may work.

Check to see if you have ffmpeg installed:


$ locate ffmpeg | grep bin
$ which ffmpeg
$ rpm -q ffmpeg
$ rpm -q ffmpeg-devel

Check to see if you have the libraries installed:


$ locate libavcodec.so
$ locate libavcodec.a
$ locate avcodec.h | grep include
$ locate libavformat.so
$ locate libavformat.a
$ locate avformat.h | grep include

Shared libraries usually end in '.so' and static libraries end in '.a'; you'll need one of the two. If you're using the RPMs, you'll need the -devel library.

If you don't have ffmpeg installed, go to the FFmpeg web site and follow the download instructions for CVS or downloading from their file release page. Once you have the source you can run ./configure --enable-shared and make. to build the source. You can then make install the FFmpeg binaries along with the libavcodec and libavformat libraries. Without configuring to build with the --enable-shared, the shared libraries are not installed and neither are the header files required to build with the libraries.

Pyro

http://pyrorobotics.org/

“Pyro supplies a programming environment for ... artificial intelligence and robotics...”. See the http://pythonrobotics.org website for installation instructions. The current version as of this writing is 1.4.2. However, the last tested version is 1.3.x and there are significant differences between the two versions. The examples provided should work in 1.3.x and modifications to run in 1.4.x are left to the reader until such time as the examples can be updated.

Pyrobot has it's own vision system that is extremely simplistic and quite slow. It runs serially with all the control code so any large amount of vision processing could potentially hold up the processing of sonar or laser information and may cause a robot to collide with objects. Phission was originally written to allow a separate vision processing sub-system to prevent the control loop from being blocked by any slow vision algorithms. While it isn't integrated with Pyrobot yet, it can still provide the Pyrobot system with a vision processing sub-system capable of better performance and robustness than the integrated system. Phission's phSimpleVision class is used as a container for the usual setup of the Phission system: one capture card, histogramming & blobbing and debug displays for local computers or network computers ( JPEG compressed images ).



Copyright (C) 2002 - 2007 Philip D.S. Thoren ( pthoren@users.sourceforge.net )
University Of Massachusetts at Lowell
Robotics Lab
SourceForge.net Logo


Generated on Sat Jun 16 02:45:25 2007 for phission by  doxygen 1.4.4