Manta project

From Manta Wiki
Jump to: navigation, search

Getting Started with Manta

This page contains instructions for using a skeleton Manta "project" to implement new components in a shared library that is linked to the Manta core shared libraries and invoked via a python script. Using the python/wxwidgets interface is really easy if all of the necessary dependencies are available as packages on your platform (and not so easy if they aren't).

The skeleton project uses some of the .cmake, swig, and header files in the Manta source tree but can be compiled completely outside the Manta source tree. If you want to link your own application gui to Manta libraries, instead of using the python or X11 user interface, this project template provides a good starting place too--just ignore the swig/python side of things.

Obtaining the Skeleton Project

Check out the project from my repository:

svn co https://code.sci.utah.edu/svn/people/abe/code/Manta-project/ Manta-project

Contents

src/ExampleTexture.h
src/ExampleTexture.cc

This directory contains the example C++ source code that will be compiled into a shared library. Currently the example is a texture which changes color based on the t value of each ray.

swig/example.i
swig/CMakeLists.txt

This directory contains the swig file which creates wrappers for the ExampleTexture class.

CMake/FindManta.cmake
CMake/make2cmake.py
CMake/empty.depend.in
CMakeLists.txt

The CMake directory contains a script for locating a Manta source tree and build. make2cmake.py and empty.depend.in are used by Manta's swig dependency checking mechanism. This mechanism causes the swig wrappers to be regenerated whenever one of the headers they include changes (functionality not present in the default CMake swig scripts).

python/test.py

This directory includes a simple test script which loads the example texture into a copy of the Manta default scene.


Modifying the Skeleton

The Manta-project skeleton files may be copied and used as templates for your own Manta development. The advantage of using this template is that it creates a separate shared library and interacts with Manta through public interfaces. This allows for development outside of the Manta repository. In addition to writting your own component implementations, there are four steps to integrate a component, these are described in the CMakeLists.txt file in the Manta-project root directory.

Use the following steps to add a new component (for example a Material implementation) to the Manta-project:

Adding a new class

Add the C++ code to the build:

  • Place the implementation code in the src/ directory (for example src/MyMaterial.h src/MyMaterial.cc).
  • Add both files to the ADD_LIBRARY command in the root directory's CMakeLists.txt file.
  • Add the header file to the swig/example.i file. Note that if your class' interface or parent class contains a templated Manta interface, the template must be explicitly templated for swig using the %template directive (see swig/CMakeLists.txt).
  • If the new code has any additional library dependencies add these both to the TARGET_LINK_LIBRARIES command in the root CMakeLists.txt file and the SWIG_LINK_LIBRARIES command in swig/CMakeLists.txt
  • Modify python/test.py to use the new class.

Rebuild the project.

Modifying python/test.py

python/test.py is a very simple test script which uses Manta's wxPython gui (called wxManta) to create a simple scene and exhibit the example texture component. wxManta is a python class that creates a gui window with a Manta image display and several menu options.

Since the gui is implemented in python the menu options may be modified by a calling script. The frame object passed to initialize_scene is a MantaFrame (see Manta/SwigInterface/wxManta.py) the engine object is a wrapped instance of MantaInterface. Unlike the make_scene function in statically compiled C++ manta modules initialize_scene may modifiy the MantaInterface and the gui, in addition to creating the scene.

Building

First build a copy of Manta with the BUILD_SWIG_INTERFACE cmake option enabled. See the swig-python build instructions. Make sure that wxPython is available also.

Next create a build directory for the Manta-project. Run ccmake from this directory and pass the location of the Manta-project directory as an argument. For example:

cd Manta-project
mkdir build
cd build
ccmake ..

Press 'c' once. ccmake will produce an error telling you to "Manually set the paths MANTA_SOURCE_DIR and MANTA_BUILD_PREFIX". Press 'e' and use the cursor to set these variables. If you followed the build directions on this wiki and started in your home directory, MANTA_SOURCE_DIR would be "~/Manta" and MANTA_BUILD_PREFIX would be "~/Manta/build-demo". Also set the CMAKE_BUILD_TYPE to "Release".

Press 'c' once again. ccmake should find python and swig in your path and set several variables automatically. If it does not set these variables manually or add python and swig to your path. The variables should look something like this: (Your paths might be different, even if you are using a SCI facility machine.)

 CMAKE_BACKWARDS_COMPATIBILITY    2.2
 CMAKE_BUILD_TYPE                 Release
 CMAKE_INSTALL_PREFIX             /usr/local
 MANTA_BUILD_PREFIX               /home/sci/abe/Manta/build-tigger
 MANTA_SOURCE_DIR                 /home/sci/abe/Manta
 PYTHON_EXECUTABLE                /usr/bin/python2.4
 PYTHON_INCLUDE_PATH              /usr/include/python2.4
 PYTHON_LIBRARY                   /usr/lib64/python2.4/config/libpython2.4.a
 SWIG_DIR                         /usr/lib/swig1.3
 SWIG_EXECUTABLE                  /local/abe/build-tigger/bin/swig

Press 'g' to generate build files. Exit ccmake and run make.


Examining the Build Process

Three major events occur during the build process of the Manta-project; first the C++ code implementation is compiled into a shared library, next swig is invoked to generate a wrapper for the classes in the shared library and lastly the swig wrapper is compiled to generate a shared library that will be loaded into python.

gmake -s
-- Configuring done
-- Generating done
-- Build files have been written to: /local/abe/Manta-project/build-tigger
Building CXX object CMakeFiles/Example.dir/src/ExampleTexture.o
Linking CXX shared library lib/libExample.so
Generating examplePYTHON_wrap.cxx.swig-depend
Generating examplePYTHON_wrap.cxx.depend
Generating examplePYTHON_wrap.cxx
... warnings omitted ...
Scanning dependencies of target _example
Building CXX object swig/CMakeFiles/_example.dir/examplePYTHON_wrap.o
Linking CXX shared module ../lib/_example.so

In the above build, libExample.so contains the C++ implementation, examplePYTHON_wrap.cxx is the swig generated wrapper which is placed inside of _example.so.

Run the test script.

Update the PYTHONPATH to contain the libraries in the project as well as the Manta libraries:

source bin/pythonpath.py
python ../python/test.py

Trouble Shooting

Undefined Manta Symbols

Linking project code in external libraries to Manta fails with the following (or similar) in debug mode:

ld: Undefined symbols:
Manta::Mesh::serialInterpolate(std::vector<Manta::Interpolable_keyframe_t, std::allocator<Manta::Interpolable_keyframe_t> > const&)
Manta::Mesh::parallelInterpolate(std::vector<Manta::Interpolable_keyframe_t, std::allocator<Manta::Interpolable_keyframe_t> > const&, int, int)
/usr/bin/libtool: internal link edit command failed

This type of error is likely caused by the presence of -D_GLIBCXX_DEBUG in the Manta CMAKE_CXX_FLAGS_DEBUG cache variable. Even if the external library is built with the flag, linker errors might occur due to different template instantiation between the library and Manta or other problems. Remove the flag from the Manta CMake configuration to resolve the issue.

Merging subsequent changes to the Manta-project template into your local copy.

[Copied from manta@ list: 11/27/2007] I've updated the Manta-project template to reflect the removal of the SCIRun dependency. Since this project is a source code template that users make a copy of (hopefully an "svn cp") it is possible to merge these changes into existing projects. The most relevant file is CMake/FindManta.cmake:

Determine the checkout date in your own copy. Assuming that you didn't modify the file it should be the Last Changed Date. If the file was modified locally then you'll need to look at the svn log in your repository:

svn info CMake/FindManta.cmake 
Path: CMake/FindManta.cmake
Name: FindManta.cmake
URL: https://your_separate_repository/CMake/FindManta.cmake
...
Last Changed Date: 2007-06-29 18:41:11 -0600 (Fri, 29 Jun 2007)
...

Merge changes from after the last changed date from the Manta-project repository into your own repository:


svn merge -r "{2007-06-29 18:41:11 -0600}":HEAD https://code.sci.utah.edu/svn/people/abe/code/Manta-project/CMake/FindManta.cmake CMake/FindManta.cmake

If you checked out the source code but didn't make a copy you should be able to just "svn update", likewise if you made a non-svn copy you should be able to check out a new version and copy it over (and manage any conflicts by hand).