H3DAPI Installation

From H3D.org

Jump to: navigation, search

Contents

Requirements

Installation on Windows

Minimum system requirements

Windows 7

Disk space

  • Full Installation (Default configuration) - 1.5GB
  • H3DViewer package - 70 MB

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.

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

Check out our (quite old) 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 Visual Studio if you do not have one. There is usually a free version to obtain from microsoft at https://visualstudio.microsoft.com/downloads/
  3. Start CMake GUI, CMake should have been installed with the full installer, if not then download it from http://www.cmake.org/cmake/resources/software.html. 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 that is used (called generator in cmake). Note that H3D 2.3.0 has prebuilt libraries for visual studio 2010 so if a later compiler is used then choose the visual studio 2010 toolset by giving the flag v100 to the "Optional toolset" textbox on the cmake generator choosing screen. If everything went fine then the "Generate" button should be enabled.
  4. Browse into where you build the projects file and open the H3DWithToolkitsWin.sln file with Visual Studio.
  5. Change configuration to "Release" instead of debug and right click the INSTALL project and "build".
  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

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 GENERATE_H3DAPI_EXAMPLE_PROJECTS, GENERATE_HAPI_EXAMPLE_PROJECTS and GENERATE_MedX3D_DEMO_PROJECT in the CMake GUI and check their boxes. This assumes that you installed all source code. Note that version 2.3.0 or earlier of H3D omits the GENERATE_ prefix for these cmake variables.
  4. Click "Configure" and then "Generate".
  5. Open the solution file again and build solution again.

Installation on GNU/Linux

Using debian package

It is quite easy to use debian packages to install H3DViewer and obtain the source code of H3DAPI. These steps are tested for Ubuntu 18.04. 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 /etc/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 18.04 this is "bionic".
  3. If you would like to make it easy to download the source, then also add
    deb-src ftp://www.h3dapi.org/pub/releases/linux/debian/ distro sensegraphics
  4. Save the 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". Alternatively you might have to use the [ trusted=yes ] option for the urls you added to sources.list. Note that this is really not a recommended approach by debian, but if you want our debian package you have to trust the package. To use the trusted option do the following
    deb [ trusted=yes ] ftp://www.h3dapi.org/pub/releases/linux/debian/ distro sensegraphics
  7. When installation finished, write H3DViewer and H3DViewer will start.
  8. If any of the H3D toolkits are desired, then write
    sudo apt-get install libh3dmedx3d libh3dphysics libh3dui


Sadly we can not distribute H3DViewer with prebuilt OpenHaptics support for Linux. Therefore, it might be useful to instead get the source of H3DAPI, and if so, do the following.

  1. In terminal cd to a directory in which you want to download the source.
  2. Write
    apt-get source libh3dapi libhapi libh3dutil libh3dmedx3d libh3dui libh3dphysics
  3. The last three libs listed are only required if you need their features.
  4. 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 the source for H3DViewer and H3DLoad, so there is 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.

Installation from source

If you want to build H3DAPI on Linux yourself follow these steps.

  1. Install version 2.8.7 or later of CMake. To do this on Ubuntu open a terminal and write:
    sudo apt-get install cmake
  2. Download the source for H3DAPI at http://www.h3d.org
  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. Note that several of these library packages might look a bit different from when this was originally written and might contains version numbers and such, it all depends on which Ubuntu version is used. We leave it up to the user to figure out the different nuances. In a terminal write:
      sudo apt-get update; sudo apt-get install gcc g++ libftgl-dev libalut-dev
      libopenal-dev libglew-dev libcurl4-openssl-dev libaudiofile-dev libfontconfig1-dev
      libvorbis-dev python2.7-dev libfreeimage-dev libxi-dev libxmu-dev libxerces-c-dev
      zlib1g-dev libdcmtk-dev libteem-dev libtiff5-dev libopenexr-dev libfreetype6-dev
      libavcodec-dev libavformat-dev libswscale-dev libglu1-mesa-dev

      Freeglut can be obtained using the following commands(not sure if the -fexceptions build is still needed. It is to handle H3D exceptions properly but perhaps the default freeglut installations are fine for later versions of Ubuntu. In that case install freeglut3-dev):
      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 3.0) write:
      sudo apt-get install libwxgtk3.0-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 H3DAPI 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.
  6. NOTE: This step is only important if you use H3D 2.3.0 or earlier.
    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 appropriate 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

If you used a debian package to install H3DAPI the libraries are not installed in /usr/local as shown below. This 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 H3DAPI 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 H3DAPI 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 the path /usr/local/lib to ldconfig, 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 H3DAPI 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 H3DAPI root. To this file you should add URN style short cuts to resources in the H3DAPI 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 H3DAPI root using this shorter and more portable URL
    urn:h3dapi:python/TheScript.py

Installation on Mac OS

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.

Building from source

Using Macports

  1. Download and install MacPorts as instructed on http://www.macports.org.
  2. Open a Terminal window and run the command "sudo port install h3dviewer"
  3. An app called H3DViewer will now be installed.

Do everything manually

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

  1. Install version 2.8.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. Download the source for H3DAPI at http://www.h3d.org.
  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"
    3. Yes we know this is not really manually, but it make things easier.
  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 chosen folder. If "Unix Makefile" are chosen then proceed from step 4 in 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. There are two ways to get the latest development version.

Obtain nightly build from ftp

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

Download from SVN

To obtain the source, an internet connection and a subversion client is needed. Subversion can be obtained from subversion.apache.org. The following instructions assume that a subversion client is used.

For Windows:

  1. Install the latest H3D release for windows, this will also install other packages like Python for you to run H3D on your system.
  2. Delete the folders in c:\h3d you want to be tracked by svn. See a list at the end of this section of meta-repositories pointing to various projects (folders) and their corresponding svn URL. For example, delete c:\h3d\h3dapi, c:\h3d\hapi and c:\h3d\h3dutil to use the H3DCore meta-repository.
  3. Checkout the subversion meta-repository that you chose to c:\h3d. For example, for H3DCore, checkout the following subversion repository to c:\h3d using TortoiseSVN GUI: https://svn.h3dapi.org/H3DAPI/metarepos/H3DCoreWin/trunk/H3D or by the following command
    svn checkout https://svn.h3dapi.org/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 checkout 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. Checkout the latest code from the server
    svn checkout https://svn.h3dapi.org/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, URLs and the projects that they include are listed below:

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

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

=Step by step H3D Trunk compile & install with Visual Studio 15 (a.k.a. 2017) This step by step assumes console command usage of CMake. It works just as well with CMake GUI.

  1. Install latest H3D release.
  2. Delete c:\H3D\H3DAPI, c:\H3D\HAPI and c:\H3D\H3DUtil, c:\H3D\External, c:\H3D\build
  3. Checkout H3D to: https://svn.h3dapi.org/H3DAPI/metarepos/H3DCoreWin/trunk/H3D
  4. In c:\H3D\build, run
 cmake . -G "Visual Studio 15 2017"
  1. Double-click on "H3DCoreWin.sln" to open Visual Studio.
  2. Now, choose "Release" instead of "Debug" in the Solutions Configuration dropdown menu and then build (F7).
  3. Make a cup of coffee...
  4. Right-click on INSTALL and choose "build"
Personal tools
go to