Installation

Note about graphics hardware:

Some basic GUI parts of the software, if used, require some libraries (OpenGL and such) that do not work well with Radeon graphics adapters. For example, while trying to run MuRO using Radeon 7000 in Ubuntu 10.04, it crashed with error message "Kernel failed to parse or rejected command stream". The recommendation is to use a Nvidia graphics adapter. Rumour has it that Radeon cards can be made to work, but it requires extensive fiddling. If you have details to share, please do it here.

Getting the source:

The following guide is for the GIM-staff. There is an Open source release, which can be downloaded here.

Use subversion. In Ubuntu you can install it from command line

sudo apt-get install subversion

or in GUI use Ubuntu Software Center (found under Applications menu). You will need access to jemma.hut.fi svn repository, administered by Matthieu Myrsky. After you have got the source you can start your browsing from example codes and docs at GIM/MaCI/doc or GIM/MaCI/example.

Currently access to the MaCI source tree is restricted to members of the Finnish Centre of Excellence in Generic Intelligent Machines Research, but we are planning to publish the MaCI framework in the near future.

Command line usage:

Decide where you want to put the code and "cd" to there. Run command:

svn checkout --username=your_user_name https://jemma.hut.fi/svn/GIM/trunk/src GIM/src

and enjoy the code. (The GIM/src sourcetree is checked out on the directory speficied at the end , in this case GIM/src. The checkout includes a large number of files and folders (GIM/trunk/src has 55 items as of 2.3.2011). Seemingly successful checkout can sometimes lack some items (possibly caused by network problems), so it is a good idea to run update if you suspect that items are missing.

Updating from the head (the "official" source at the server) is done by running:

svn up

committing changes to the SVN is done through command:

svn commit -m"Comment about your commit" [optional filename / filenames ]

although, if you are new user to GIM/src and also if you are new user to SVN, you should be very sure about what you are about to commit. All changes you have made to your local copy will be merged to the global project. If your changes are somehow broken, you may cripple the whole main branch of the project. Instead of blindly committing whatever you have done, please see GIM project Commit Guidelines before doing anything. If you know that you are doing big changes which may affect others, please use branches and review your changes on other developers before committing anything to HEAD.

Compiling

To compile the programs, run make in appropriate MaCI subdirectory. For example; in MaCI/examples to compile all client side example applications, or in MaCI/modules to compile all server side modules at once. Usually modules are compiled when required on interface type basis. When compiling, you will probably see number of error from missing libraries and stuff. Install any missing libraries and try again :)

Now for example you want to play around with laser range finder. You would be using Ranging interface. The code for packaging, sending, receiving and reading ranging data is in MaCI/interface/Ranging folder. You can see how Ranging interface works by starting example module producing pseudo data from MaCI/examples/Ranging/server by command "./Ranging_Dummy -n dumRang" and read it at an other terminal in MaCI/examples/Ranging/client by command "./RangingClientExample -s dumRang" Now if you have an actual LRF you can plug it in and run module for it in MaCI/modules/Ranging/. If your LRF is not there (SICK or URG) copy the dummy module source to write a new module. Then it would be likely that there is no driver for your LRF that module could use. Now you have to go to MaCI/drivers/ and copy one of the folders for your base and write the driver there.

Required library packages:

To install a package, use command: 'sudo apt-get install <packagename>'

build-essential
libxml2
libxml2-dev
libncurses5
libncurses5-dev
libjpeg-dev
libssl-dev
doxygen
freeglut3
freeglut3-dev
libsdl-dev
libsdl-gfx1.2-dev
libsdl-image1.2-dev
libpnglite-dev
libwxgtk2.8-dev wx-common libode-sp-dev libode1sp
libusb++-dev

or all in a one-liner:

sudo apt-get install build-essential libxml2 libxml2-dev libncurses5 libncurses5-dev libjpeg-dev  libssl-dev doxygen freeglut3 freeglut3-dev libsdl-dev libsdl-gfx1.2-dev libsdl-image1.2-dev libwxgtk2.8-dev wx-common libode-sp-dev libode1sp libusb++-dev

Using Python

There exists wrappers for the most common MaCI interfaces. This means that the C++ libraries can be called from Python code. For Python parts of MaCI you would need following libraries:

python
python-dev
swig

Sometimes the previously compiled objects have conflicts and it is recommended to run './rm_all_objects' script under the src/ path before compiling. To compile the wrappers you would need to run 'make' in:
* src/GIMI/wrap/Python/
* src/MaCI/interfaces/wrap/Python/
Commonly Python.h is not in same place on different systems and needs to be corrected in the "Makefile" in the paths above if problems arise.
The majority of the python based GUIs utilize qt4 and opencv:
python-qt4
pyqt4-dev-tools
python-opencv
python-mysqldb

Using VirtualBox virtual machine

If you can't or don't want to install linux, you can use VirtualBox virtual machine instead. We provide you an virtual machine-image of an Ubuntu 10.04 with all the needed library installed here. You have to remember that it is a virtual machine, so it is slower than a native Linux installation.

After downloading and installing VirtualBox and the "Ubuntu for GIMnet"-image start VirtualBox.

  1. Select File->Import Appliance...
  2. Click choose... and Select the downloaded VirtualBox image "Ubuntu For Gimnet.ova" click next
  3. Click import/Finish dependig on the version of the VirtualBox
  4. Wait for VirtualBox to import the image
  5. Select from the list Ubuntu For GIMnet and press Start.

After a while your Virtual machine should be started. Then download the newest MaCI-distribution package and start playing (You can start from the tutorial)

Installing the Stage simulator:

Stage version 4.0.0 is used, and it can be downloaded here: stage_4.0.0.tar.gz Other versions of Stage are not supported!

Install the required packages:

sudo apt-get install cmake-curses-gui libfltk1.1-dev libltdl-dev checkinstall
  1. Extract the archive to any location, for example /home/userName/
  2. Enter the folder "stage_4.0.0", which contains "README.txt" and other files
  3. Type "mkdir build" and "cd build"
  4. Type "ccmake .."
  5. Press 'c' to configure
  6. If the cmake screen warns about a missing library, use "sudo apt-cache search libraryName" to find it, and then install the missing library using "sudo apt-get install libraryName"
  7. When the configuration completes without errors, you should see this screen
  8. Press the down key once to navigate to "BUILD_PLAYER_PLUGIN", press 'enter' to turn it to 'OFF'
  9. At least In Ubuntu 12.04: In addition, Press t (to enter advanced mode) then set CMAKE_CXX_FLAGS to "-Wl,--no-as-needed" (without quotes).
  10. Press 'c' to configure and 'g' to generate and exit
  11. Type "sudo checkinstall make install" to make and install Stage. Checkinstall makes it easier to remove the package later.

To use Stage and compile programs that use libstage, LD_LIBRARY_PATH and PKG_CONFIG_PATH need to be set manually every time. In a 64 bit operating system, this is done using the following commands:

export LD_LIBRARY_PATH=/usr/local/lib64/
export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig/

Or if you are using a 32 bit operating system:

export LD_LIBRARY_PATH=/usr/local/lib/
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/

To test that Stage was installed successfully, run "stage". The terminal should output "Stage 4.0.0 [Stage: done]"