H3DAPI Installation

From H3D.org

Revision as of 18:18, 25 June 2012; view current revision
←Older revision | Newer revision→
Jump to: navigation, search

Contents

Requirements

Installation on Windows

Minimum system requirements

Windows 2000/XP, 250MB of disk space

Installation walkthrough

Download the latest binary release from the download section of the H3D community. The installation file will install everything you need to run H3D on your system.

Of course you will need to install drivers for specific haptics devices when you want to use those with H3D.

Check out our installation instruction videos at H3DAPI on Youtube. There are also videos on how to create a simple scene with H3D.

Building from source

To build H3DAPI on Windows follow these steps.

  1. Obtain the source code. Preferrably by installing H3DAPI as in the walkthrough above. If the development source is desired follow the instructions in the Source Repositories section.
  2. Download and install the latest cmake version from http://www.cmake.org/cmake/resources/software.html
  3. Download and install Visual C++ 2010 if you do not have one. An express version is available free of charge at http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express
  4. Start CMake GUI. Put the search path to CMakeLists.txt in the first text box in this GUI. On a standard installation the search path is C:\H3D\H3DAPI\build. Put the search path to where the generate projects will be build in the second text box, for example C:\H3D\H3DAPI\build\win32. Press the Configure button and choose the compiler is Visual Studio 10. If everything went fine then the "Generate" button should be enabled.
  5. After configuration is done, click on the box "show advanced". Search for "GENERATE_UNITY_BUILD" and tick on the box to enable it. After that click on "Configure" again
  6. After the second configuration, click "Generate", all project files will be generated
  7. Browse into where you build the projects file and open the H3DAPI.sln file with Visual Studio.
  8. Change configuration to "Release" instead of debug and build the solution.

Wait for the project to be built.....

  1. After that, right click on INSTALL project and "build"
  2. Close Visual Studio, go back to cmake GUI, search for "H3DAPI_LOADER_PROJECT" and tick the box
  3. Configure and Generate the solution once more
  4. In the latest development version, the path added is different from the previous version. Change the system path from C:\H3D\External\bin to C:\H3D\External\bin32
  5. Open the solution file again and build it.
  6. Testing: set H3DViewer as start up project in H3DAPI, and run it. The H3DViewer window is opened. Drag any of the .x3d files under C:\H3D\H3DAPI\examples\All to that window to check if it works

Installation on GNU/Linux

Currently you need to build H3D API on Linux yourself. To build H3DAPI on Linux follow these steps.

  1. Install version 2.4.7 or later of CMake. (Development version of H3D needs 2.6(?)) To do this on Ubuntu open a terminal and write: 
    sudo apt-get install cmake
  2. Register at http://www.h3d.org and download the source for H3DAPI.
  3. Download the source for HAPI. Build and install HAPI on your system since H3DAPI requires HAPI. See the HAPI Installation guide.
  4. H3DAPI depends on other libraries. The build system used by H3DAPI will detect which libraries are installed on the system and only enable the features that the system can support. If more features are desired the corresponding library has to be installed. Note that some libraries are required for H3DAPI to compile. See the list of external libraries. For linux the library fontconfig is also needed.
    • If using Ubuntu, several of these libraries can be obtained by using the apt-get feature. The first two debian packages are the C++ compilers needed to compile H3DAPI. In a terminal write:
      sudo apt-get update; sudo apt-get install gcc g++ ftgl-dev libxerces-c2-dev libmozjs-dev
libopenal0a libalut0 libalut-dev libopenal-dev libglew-dev libglut libglut3-dev libcurl3-dev
libaudiofile-dev libfontconfig1-dev libfontconfig1 libvorbis-dev python-dev python-all-dev
libfreeimage-dev libxi-dev libxmu-dev python-wxglade libxerces27 libxerces27-dev

      Freeglut can be obtained using the following commands:
      wget http://ovh.dl.sourceforge.net/sourceforge/freeglut/freeglut-2.4.0.tar.gz
      tar -xzvf freeglut-2.4.0.tar.gz
      cd freeglut-2.4.0
      ./configure CFLAGS="-fexceptions" CXXFLAGS="-fexceptions"
      make
      sudo make install
      Depending on which version of the gcc compiler is used two lines in the file freeglut_joystick.c should be removed or uncommented before compiling freeglut, otherwise the build will fail. In this link there is a patch that does this http://bugs.gentoo.org/131856

      To install WxWidgets (version 2.8) write:
      sudo apt-get install libwxgtk2.8-dev
  5. Now it is time to generate the make files. In the terminal change directory to the H3DAPI/build directory and write:
    mkdir linux
    The reason for creating a new directory called 'linux' is to easily remove all the cmake generated files in the future in case this is needed. Now change directory to the new 'linux' directory. Then write:
    cmake ../

    To build H3D API write: (tip: write "make -j3" if you have a core duo, and "make -j5" for quads: faster)
    make

    To install H3DAPI write:
    sudo make install

    H3DAPI libraries are now installed on your system. But there is no application installed that use H3DAPI libraries.
  6. There are two applications provided that can be used to load the example x3d-files provided. These applications are H3DLoad and H3DViewer. To build and install these programs do the following.
    Change folder to H3DAPI/H3DLoad/build.
    mkdir linux
    cd linux
    cmake ../
    sudo make install

    Change folder to H3DAPI/H3DViewer/build
    mkdir linux
    cd linux
    cmake ../
    sudo make install.

    If only one of these applications is desired then only build and install one of them.
  7. To use the SettingGUI.py program located in the H3DAPI/settings folder the H3D_ROOT environment variable needs to be set to the folder H3DAPI. When this is done the program can be started by navigating to the appropiate folder and write (make sure you have wxPython installed):
    python SettingsGUI.py

    Without this program H3DLoad and H3DViewer will not be configured correctly for the examples provided.
  8. Test your installation by changing directory to H3DAPI/example/x3dmodels/berk and write:
    H3DLoad berk.x3d

Setting Up Runtime Environment

The make file will only install the libraries and header files, so to set up a runtime environment for all users on your computers, for example in a University laboratory, you'll have to perform a few steps manually.

  1. Create a folder for H3D API at your preferred location, e.g. under /usr/local/share on the Ubuntu distribution 
    sudo mkdir /usr/local/share/h3dapi
  2. Copy the runtime parts of H3D API to your new h3dapi folder. That would be the "settings" folder and optionally also the "examples" folder. You may also create a "python" folder where you may add miscellaneous Python scripts and an "images" folder for images.
  3. For some Linux platforms you'll need to add to ldconfig the path /usr/local/lib, and for 64 bits platforms sometimes also /usr/local/lib64. This is done by writing 
    echo -e "/usr/local/lib\n/usr/local/lib64" | sudo tee /etc/ld.so.conf.d/locallib.conf
    sudo ldconfig
  4. Make sure that /usr/local/bin is a part of the PATH variable in /etc/environment
  5. Set H3D_ROOT to the H3D API path you created earlier by writing 
    echo export H3D_ROOT=/usr/local/share/h3dapi | sudo tee /etc/profile.d/h3dapi.sh
    sudo chmod 755 /etc/profile.d/h3dapi.sh
  6. You may optionally add an index.urn file to the H3D API root. To this file you should add URN style short cuts to resources in the H3D API folder. A good URN rule to add would be 
    urn:h3dapi: /usr/local/share/h3dapi/
    This way you can access Python scripts and images under the H3D API root using this shorter and more portable URL 
    urn:h3dapi:python/TheScript.py

Installation on Mac OS

Currently you need to build H3DAPI on MacOS X yourself. To build H3DAPI on MacOS X follow these steps.

  1. Install version 2.4.7 or later of CMake.
  2. Install XCode. If gcc is an unrecognized command in the terminal after installing XCode there is a high probability that CMake will not be able to generate build files for gcc and/or XCode. Another version of XCode could be used or fix it in some other way.
  3. Register at http://www.h3d.org and download the source for H3DAPI.
  4. Download the source for HAPI. Build and install HAPI on your system, see the HAPI installation guide. H3DAPI requires HAPI to build.
  5. H3DAPI depends on other libraries. The build system used by H3DAPI will detect which libraries are installed on the system and only enable the features that the system can support. If more features are desired the corresponding library has to be installed. Note that some libraries are required for H3DAPI to compile. See the list of external libraries.
  6. Generate build files for your build system using CMake. Either use the console version as in the installation guide for linux or use the GUI version in which the first textbox should contain the location of the CMakeLists.txt file. This can be located in H3DAPI/build. The second box is the location of where the build files will be created. Use for example H3DAPI/build/OSX. Press configure, choose which system to generate build files for wait and press configure again until the generate button can be used. Press generate and then the build files will be in the choosen folder. If "Unix Makefile" are choosen then proceed from step 4 in the linux installation guide.
  7. Generate build files for H3DLoad and H3DViewer with the CMakeLists.txt located in H3DAPI/H3DLoad/build and H3DAPI/H3DViewer/build. Build these and test your installation by starting H3DViewer and opening a file using the menu. Alternatively you could open a file with H3DLoad from the terminal as in step 6 of the linux installation guide.

Troubleshooting

Upgrading

Source Repositories

Latest development version

Sometimes it is convenient to get the latest source of H3DAPI that is not yet in an official release. To obtain the source an internet connection and a subversion client is needed. Subversion can be obtained from subversion.tigris.org. The following instructions assume that a subversion client is used.

For Windows:

  1. Install H3DAPI 2.1.1 release, this will also install other packages like Python for you to run H3D on your system
  2. Delete c:\h3d\h3dapi, c:\h3d\hapi and c:\h3d\h3dutil
  3. Checkout into c:\h3d the following subversion repository using TurtoiseSVN GUI: https://www.h3dapi.org:8090/H3DAPI/metarepos/H3DCoreWin/trunk/H3D or by the following command 
    svn checkout https://www.h3dapi.org:8090/H3DAPI/metarepos/H3DCoreWin/trunk/H3D
  4. On Windows it makes developing smoother if an official H3DAPI release is installed and the folders created by it are used to check out the source in. The reason for this is to not have to download and install all external libraries needed by H3DAPI, HAPI and H3DUtil. For Windows TortoiseSVN could be used as a subversion client to integrate subversion closely to the Explorer interface.
  5. To build H3DAPI, follow the instruction on the section Building From Source above

For Linux:

  1. Create a directory for the repository 
    mkdir H3D
  2. Check out the latest code from the server 
    svn checkout https://www.h3dapi.org:8090/H3DAPI/metarepos/H3DCore/trunk/H3D

To build it, refer to the part Installation on GNU/Linux above

Bug fix repositories

The repository urls listed below contain bug fixes to official releases of H3DAPI. These differs from the latest development version in the way that no new functionality will be added to the repository. Only fixes to problems discovered in the release will be added.

Release 2.0

https://www.h3dapi.org:8090/H3DAPI/branches/release2.0.1
https://www.h3dapi.org:8090/HAPI/branches/release1.0.1
https://www.h3dapi.org:8090/H3DUtil/branches/release1.0.1

Step by step H3D Trunk compile & install with Visual Studio 8 aka 2005

This step by step assumes console command usage of CMake. It works just as well with CMake GUI.

  1. install H3DAPI 2.0 release
  2. delete c:\h3d\h3dapi, c:\h3d\hapi and c:\h3d\h3dutil
  3. checkout into h3d: https://www.h3dapi.org:8090/H3DAPI/metarepos/H3DCoreWin/trunk/H3D
  4. in c:\h3d\h3dapi\build, run 
 cmake . -G "Visual Studio 8 2005"
  1. Doubleclick on "H3DAPI.sln" to open visual studio 2005.
  2. Now, chose "release" instead of "debug" in solutions configuration dropdown menu, and then build (F7)

make a cup of coffee...

  1. Rightclick on INSTALL project and "build"

To test:

  1. In c:\h3d\h3dapi\examples\manualExamples\c++, run 
 cmake . -G "Visual Studio 8 2005"
  1. doublecklick on "ManualExamples.sln", set "release" and build
  2. run release\sphere_x3d.exe
  • Note:
  1. In some system, the wrong link C:\H3D\External\bin is added to path instead of the correct one, which is C:\H3D\External\bin32
  2. If cmake complains about libraries or include directories missing, add C:\H3D\External\lib32 and C:\H3D\External\include respectively to the system path</code>
Retrieved from "http://www.h3dapi.org/modules/mediawiki/index.php/H3DAPI_Installation"
Personal tools
go to