H3DAPI Installation

From H3D.org

Jump to: navigation, search

Contents

[edit]

Requirements

[edit]

Installation on Windows

[edit]

Minimum system requirements

Windows 2000/XP, 250MB of disk space

[edit]

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.

[edit]

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/eng/products/visual-studio-2010-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\build. Put the search path to where the generate projects will be build in the second text box, for example C:\H3D\build\win32. Press the Configure button and choose the compiler Visual Studio 10. If everything went fine then the "Generate" button should be enabled.
  5. Browse into where you build the projects file and open the H3DWithToolkitsWin.sln file with Visual Studio.
  6. Change configuration to "Release" instead of debug and right click the INSTALL project and "build".
  7. 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

If it is desired to build all the C++ examples that comes with H3D follow these steps.

  1. Close Visual Studio.
  2. Open CMake gui for your configuration (if not already opened).
  3. Find H3DAPI_EXAMPLE_PROJECTS, HAPI_EXAMPLE_PROJECTS and MedX3D_DEMO_PROJECT in the CMake GUI and check their boxes. This assumes that you installed all source code.
  4. Click "Configure" and then "Generate".
  5. Open the solution file again and build solution again.
[edit]

Installation on GNU/Linux

[edit]

Using debian package

It is quite easy to use debian packages to install H3DViewer and obtain source code of H3DAPI. These steps are tested for Ubuntu 12.04 and 12.10. We assume it will work on other systems as well.

  1. Open /etc/apt/sources.list as sudo. Use for example the terminal command 
    sudo gedit /ets/apt/sources.list
  2. At the end of that file add the following 
    deb ftp://www.h3dapi.org/pub/releases/linux/debian/ distro sensegraphics
    Where "distro" is your linux distribution. For Ubuntu 12.04 this is "precise" and for Ubuntu 12.10 this is "quantal".
  3. If you would like to make it easy to download source the also add 
    deb-src ftp://www.h3dapi.org/pub/releases/linux/debian/ distro sensegraphics
  4. Save file and exit.
  5. In terminal write 
    sudo apt-get update
    followed by 
    sudo apt-get install h3dviewer
  6. Select Yes for all questions about "not known debian package".
  7. When installation finished write H3DViewer and H3DViewer will start.
  8. If any of the H3D toolkits is desired then write 
    sudo apt-get install libh3dmedx3d libh3dphysics libh3dui<pre>
Sadly we can not distribute H3DViewer with prebuilt OpenHaptics support for linux. Therefore it might be useful to get source of H3DAPI. Then do the following. # In terminal cd to a directory in which you want to download the source. # Write <pre>apt-get source libh3dapi libhapi libh3dutil libh3dmedx3d libh3dui libh3dphysics
  1. The last three libs listed are only required if you need their features.
  2. After download is finished you will have tar.gz files in your directory which contains all the source code for h3d. The source package for libh3dapi contains source for H3DViewer and H3DLoad so no need to download libh3dviewer separately. Note that if you only want extra OpenHaptics support it should be enough to only custom build hapi and h3dapi. The rest can be installed using debian.
[edit]

Installation from source

If you want to build H3D API on Linux yourself 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
[edit]

Setting Up Runtime Environment

If you used a debian package to install H3DAPI then libraries are not installed in /usr/local as shown below. This therefore is only important when building H3DAPI from source. 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
[edit]

Installation on Mac OS

[edit]

H3DViewer installation only

If you want to install only H3DViewer then check out the download section of H3DAPI and hope that your version of OSX is supported.

[edit]

Building from source

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

  1. Install version 2.8.0 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. One option would be to use the macports project which will automatically download, compile and install most of the required libraries. To use it:
    1. Download and install MacPorts as instructed on http://www.macports.org.
    2. Open a Terminal window and run the command "sudo port install glew xercesc dcmtk wxWidgets-devel freeimage ftgl libvorbis audiofile spidermonkey fontconfig"
  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.
[edit]

Troubleshooting

[edit]

Upgrading

[edit]

Source Repositories

[edit]

Latest development version

Sometimes it is convenient to get the latest source of H3DAPI that is not yet in an official release. There are two ways to get the latest development version.

[edit]

Obtain nightly build from ftp

Everyday a build of the latest trunk is generated and uploaded to this public ftp. Download H3D for your operating system from there.

[edit]

Download from SVN

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.

For convenience, meta-repositories that contain several projects have been created. Their names, URL and the projects that they include are listed below:

  1. H3DCore (H3DAPI, H3DUtil, HAPI) https://h3dapi.org:8090/H3DAPI/metarepos/H3DCore/trunk/H3D
  2. H3DCoreWin (H3DAPI, H3DUtil, HAPI and External) https://h3dapi.org:8090/H3DAPI/metarepos/H3DCoreWin/trunk/H3D
  3. H3DWithToolkits (H3DAPI, H3DUtil, HAPI, MedX3D, UI and H3DPhysics) https://h3dapi.org:8090/H3DAPI/metarepos/H3DWithToolkits/trunk/H3D
  4. H3DWithToolkitsWin (H3DAPI, H3DUtil, HAPI, MedX3D, UI, H3DPhysics and External) https://h3dapi.org:8090/H3DAPI/metarepos/H3DWithToolkitsWin/trunk/H3D

Note that H3DPhysics used to be named RigidBodyPhysics. All the RigidBodyPhysics nodes are still there, in the new library.

[edit]

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.

[edit]

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
[edit]

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

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, c:\H3D\External
  3. checkout into h3d: https://www.h3dapi.org:8090/H3DAPI/metarepos/H3DCoreWin/trunk/H3D
  4. in c:\H3D\build, run 
 cmake . -G "Visual Studio 10"
  1. Doubleclick on "H3DCoreWin.sln" to open visual studio 2010.
  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"
  • 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
Retrieved from "http://www.h3dapi.org/modules/mediawiki/index.php/H3DAPI_Installation"
Personal tools
go to