OOPSMP: FAQ

Frequently Asked Questions

  1. When should CMake be rerun to automatically generate makefiles/project files?
  2. What should be done to compile new source files?
  3. For which operating systems/compilers has OOPSMP been compiled and used successfully?
  4. What are the dynamic library extensions for different operating systems?
  5. How is OOPSMP run?
  6. What programs are currently available in OOPSMP?
  7. Where are the XML files located?
  8. Why are syntactically correct XML files not parsed correctly?
  9. How can the entire program setup be stored as a single XML file?
  10. How are single/multiple robot(s) motion-planning problems setup via XML specifications?
  11. What are some common errors when setting up motion-planning problems?
  12. What should be done in case of a plugin error?
  13. Why are there errors related to OpenGL and GLUT?
  14. Why are there compiler errors when using RegisterFnFactory macros?
  15. Why don't collision detection and triangulation work correctly?
  16. Why can't windows find the dlls?

  1. When should CMake be rerun to automatically generate makefiles/project files?

    CMake should be rerun anytime any of the cmake files is modified or if you would like to change the build option from Release (optimized code) to Debug or vice-versa. Furthermore, CMake should be rerun anytime you add/remove/rename header and source files.
    From inside the OOPSMP/ directory it may be necessary to first clean the cmake cache, which is accomplished by removing the file CMakeCache.txt 
        rm CMakeCache.txt
    and then use cmake to generate makefiles/project files: 
        cmake -DCMAKE_BUILD_TYPE="Release" CMakeLists.txt or
    cmake -DCMAKE_BUILD_TYPE="Debug" CMakeLists.txt
    After running cmake, use the makefiles/project files that were created by CMake to build OOPSMP libraries and executable.
    Thus, if cmake created makefiles, then run make
    If cmake created project files, then open the main project file

  2. What should be done to compile new source files?

    If you would like to create a separate library, then create a CMakeLists.txt file in the source code directory for your code. Add this source directory to OOPSMP/src/CMakeLists.txt with the ADD_SUBDIRECTORY command. Look at other CMakeLists.txt files to get an idea of how to write a CMakeLists.txt for your own code. Then, rerun cmake.

  3. For which systems/compilers has OOPSMP been compiled and used successfully?

    One of the reasons why OOPSMP uses CMake to automatically generate makefiles/project files is to make it as easy as possible to compile and use OOPSMP across different operating systems and compilers. So far OOPSMP has been compiled and used successfully for the following systems and compilers:
    • Linux (32-bit, 64-bit): GCC, PGI
    • MS Windows: MinGW/GCC, Microsoft Visual Studio 8.0
    • Mac OS X v10.4 (Tiger) and Mac OS X v10.5 (Leopard): GCC

  4. What are the dynamic library extensions for different operating systems?

    OOPSMP relies on dynamic libraries to provide plug-and-play functionality. The format and extension of dynamic libraries varies from one operating system to another.

    Dynamic libraries in Linux/Unix
    • Dynamic libraries have the .so extension and are created in the lib directory
    • Dynamic libraries are hierarchical, so high-level libraries automatically load the low-level libraries they depend on.

    Dynamic libraries in Mac OS X v10.4 (Tiger) and Mac OS X v10.5 (Leopard)
    • Dynamic libraries have the .dylib extension and are created in the lib directory
    • Dynamic libraries are hierarchical, so high-level libraries automatically load the low-level libraries they depend on.

    Dynamic libraries in MS Windows; compiled with Microsoft Visual Studio
    • Dynamic libraries have the .dll extension and are created in the lib\debug or lib\release directory depending on the particular build.
    • Dynamic libraries are not hierarchical, that is, the high-level library does not automatically load the low-level libraries it depends on, as it is common in Linux/Unix. However, when creating a library in Microsoft Visual Studio all the source files are used. In this way, it is sufficient to load only the appropriate high-level library.
    Make sure to setup the library path so that the system knows where to find the dlls (click here)

    Dynamic libraries in MS Windows; compiled with MinGW/GCC
    • Dynamic libraries have the .dll extension and are created in the lib directory
    • Dynamic libraries created by MinGW/GCC are not hierarchical, that is, the high-level library does not automatically load the low-level libraries it depends on, as it is common in Linux/Unix.
    Make sure to setup the library path so that the system knows where to find the dlls (click here)

  5. How is OOPSMP run?

    OOPSMP uses plug-and-play functionality to run different programs, which are setup using XML files. OOPSMP is using the command: 
        oopsmp program.xml list_of_dll_libraries
    where program.xml is the path of the program XML file the user wants to run, and list_of_dll_libraries is a list of dlls the user wants to load.

    You can get started by running some of the demo programs.

    Running on Linux/Unix
    • Executable is bin/oopsmp
    • Dynamic libraries have the .so extension and are created in the lib/OOPSMP directory
    • A non-graphical program is run from the build or install directory as 
          ./bin/oopsmp nongraphical_program.xml ./lib/OOPSMP/libOOPSMPUserPrograms.so
    • A graphical program is run as 
          ./bin/oopsmp graphical_program.xml ./lib/OOPSMP/libOOPSMPGUserPrograms.so
    • Dynamic libraries are hierarchical, so high-level libraries automatically load the low-level libraries they depend on.

    Running on Mac OS X v10.4 (Tiger) or Mac OS X v10.5 (Leopard)
    • Executable is bin/oopsmp
    • Dynamic libraries have the .dylib extension and are created in the lib directory
    • A non-graphical program is run as 
          ./oopsmp nongraphical_program.xml ./lib/OOPSMP/libOOPSMPUserPrograms.dylib
    • A graphical program is run as 
          ./oopsmp graphical_program.xml ./lib/OOPSMP/libOOPSMPGUserPrograms.dylib
    • Dynamic libraries are hierarchical, so high-level libraries automatically load the low-level libraries they depend on.

    Running on MS Windows; compiled with Microsoft Visual Studio
    Depending on the build (debug or release), then
    • Executable is bin\debug\oopsmp
    • Dynamic libraries have the .dll extension and are created in the lib\debug directory
    • A non-graphical program is run as 
          bin\debug\oopsmp nongraphical_program.xml lib\OOPSMP\OOPSMPUserPrograms.dll
    • A graphical program is run as 
          bin\debug\oopsmp graphical_program.xml lib\OOPSMP\OOPSMPGUserPrograms.dll
    • Dynamic libraries are not hierarchical, that is, the high-level library does not automatically load the low-level libraries it depends on, as it is common in Linux/Unix. However, when creating a library in Microsoft Visual Studio all the source files are used. In this way, it is sufficient to load only the appropriate high-level library.
    Make sure to setup the library path so that the system knows where to find the dlls (click here)

    Running on MS Windows; compiled with MinGW/GCC
    • Executable is bin\oopsmp
    • Dynamic libraries have the .dll extension and are created in the lib directory
    • A non-graphical program is run as 
          bin\oopsmp  nongraphical_program.xml lib\OOPSMP\*.dll
    • A graphical program is run as 
          bin\oopsmp  graphical_program.xml lib\*.dll
    • Dynamic libraries created by MinGW/GCC are not hierarchical, that is, the high-level library does not automatically load the low-level libraries it depends on, as it is common in Linux/Unix. Instead of specifying several DLLs, the easiest way is to just load all the DLLs: lib\*.dll
    Make sure to setup the library path so that the system knows where to find the dlls (click here)

  6. What programs are currently available in OOPSMP?

    OOPSMP programs are divided into two main groups: programs that do not use graphics and programs that use graphics.

    Non-graphical programs
    [browse OOPSMP/src/UserPrograms/ and OOPSMP/input/xml/UserPrograms/]

    Code developers create non-graphical non-interactive programs by extending the class OOPSMP::Program. Currrent non-graphical programs in OOPSMP include the following programs: 
     MotionPlannerQueriesProgram 
 MotionPlannerProgram 
 PrintInputProgram 
 TestPathProgram

    Graphical programs
    [browse OOPSMP/src/Graphics/GUserPrograms/ and OOPSMP/input/xml/Graphics/GUserPrograms/]

    Graphical programs can be non-interactive or interactive, i.e., graphical programs that process events such as mouse movements, keyboard presses, etc. Code developers create graphical non-interactive programs by extending the class OOPSMP::GProgram and create graphical interactive programs by extending the class OOPSMP::GEventProgram. For the graphical programs the user must specify the graphical manager. Currently, the available graphical managers are OOPSMP::GPostscriptManager, OOPSMP::GGLUTManager, and OOPSMP::GGLUTEventManager. Currrent graphical programs in OOPSMP include the following programs: 
     GMotionPlannerProgram
 GMotionPlannerQueriesProgram
 GMotionPlannerDataProgram
 GMotionPlannerSolutionsProgram
 GCoreProgram
 GWorkspaceProgram

  7. Where are the XML files located?

    All XML input files are found in the source directory OOPSMP/input/xml. If you installed OOPSMP, you can find the XML files also in <install_prefix>/share/OOPSMP/xml. The structure of this directory follows as much as possible the code structure. For example, XML specifications for collision detectors are found in OOPSMP/input/xml/Utils/Geometry/Collision and the code for collision detectors is found in OOPSMP/src/Utils/Geometry/Collision.

    In each directory that contains multiple alternatives, there is a file whose name starts with Selected, which indicates the selection made by the user among the several alternatives. For example, in OOPSMP/input/xml/MotionPlanners there is a file called SelectedMotionPlanner.xml which indicates the motion planner selected by the user. Thus, if you would like to change the default selections or solve different problem instances, go to these files and change the selections accordingly.

  8. Why are syntactically correct XML files not parsed correctly?

    The parser that comes with OOPSMP is a simple XML parser and does not fully support everything that XML supports. In particular OOPSMP parser can only support XML files of the following form: 
       XML_file      ::= XML_nodes
   XML_nodes     ::= empty | XML_node XML_nodes
   XML_node      ::= <XML_tag XML_attributes> XML_text XML_nodes XML_text </XML_tag>
   XML_attributes::= empty | XML_attribute XML_attributes
   XML_attribute ::= XML_name="XML_value"
   XML_tag       ::= whatever scanf accepts with %s
   XML_name      ::= whatever scanf accepts with %s
   XML_value     ::= whatever scanf accepts with %s
   XML_text      ::= empty | regular text
    However, OOPSMP also supports libxml2 and if libxml2 is installed in your system, then OOPSMP will use this parser instead. Look at the file OOPSMP/CMakeLists.txt to see how OOPSMP searches for libxml2 and perhaps edit this file to correctly find where the libraries and header files for libxml2 are located.

  9. How can the entire program setup be stored as a single XML file?

    OOPSMP uses the XML directive 
     <readContentFromFile> file.xml </readContentFromFile>
    to inline the content of file.xml, i.e., same effect as copying and pasting the content of file.xml wherever the directive readContentFromFile appears. Anytime this tag is present, the xml parser opens the specified file, reads its content, creates an xml node from the content of the file, and adds it as a child to the parent xml node.

    The use of readContentFromFile directive makes it possible to setup OOPSMP programs and components using different XML files.

    If file.xml is not found in the current directory, then it will try to read OOPSMP/input/xml/file.xml and <install_prefix>/share/OOPSMP/xml/file.xml. In other words, it is not necessary to specify the full path for XML files that are stored in the "standard" OOPSMP xml directory.

    Sometimes however it is convenient to have a self-contained single XML file. This is particularly useful when running experiments, since it allows to store the setup in just one file. The program OOPSMP::PrintInputProgram provides such functionality. The user specifies the name of the program XML file that the user wants to be inlined and the name of the output file where the inlined XML should be written. See the documentation of OOPSMP::PrintInputProgram and XML setup OOPSMP/input/xml/UserPrograms/PrintInputProgram.xml for more details.

  10. How are single/multiple robot(s) motion-planning problems setup via XML specifications?

    Motion planning methods in OOPSMP are designed to work seamlessly for problem instances that involve just one robot or many robots of possibly different types. This is achieved by providing functionality for centralized motion planning that allows motion planning methods to treat many robots as just one single robot.

    All motion planning methods in OOPSMP use an instance of the class OOPSMP::CoreRobotData, which provides access to common components that are needed by motion planning methods, e.g., workspace, collision detector, state space, state sampler, path generator, local planner.

    When dealing with multiple robots, it is desirable to provide access to the state space, state sampler, path generator, and local planner of each individual robot, but also to provide access to a centralized state space, state sampler, path generator, and local planner. This is achieved by using an instance of the class OOPSMP::CoreRobotsData. The class OOPSMP::CoreRobotsData not only extends the class OOPSMP::CoreRobotData, but also provides access to the OOPSMP::CoreRobotData associated with each individual robot.

    Using the plug-and-play functionality of OOPSMP, the user can setup problems for single or multiple robots by simply specifying the motion planning components in an XML file.

    Setup single-robot 2D problem

    Setup single-robot 3D problem
    • Follow instructions for single-robot 2D problem, but replace 2 with 3

    Setup single-robot kinematic car problem

    BestRandomControlPathGenerator: go to OOPSMP/input/xml/Core/Path/SelectedPathGenerator.xml and set the selection to Core/Path/RandomControlPathGenerator.xml or to Core/Path/BestRandomControlPathGenerator.xml


    Setup multiple-robots 2D problem
    • Select PQPCollisionDetector2D: go to OOPSMP/input/xml/Utils/Geometry/Collision/SelectedCollisionDetector.xml and set the selection to Utils/Geometry/Collision/PQPCollisionDetector2D.xml
    • Select a 2D workspace: go to OOPSMP/input/xml/Utils/Geometry/Workspace/SelectedWorkspace.xml and set the selection to Utils/Geometry/Workspace/Workspace2D/SelectedWorkspace2D.xml
    • Setup 2D moving parts: go toOOPSMP/input/xml/Utils/Geometry/Workspace/Workspace2D/Robots2D/SelectedRobots2D.xml and add as many calls to addMovingPart as the number of robots you would like to have
    • Select CoreRobotsData: go to OOPSMP/input/xml/Core/Data/SelectedCoreRobotData.xml and set the selection to Core/Data/CoreRobotsData.xml
    • Setup components for each robot: go to OOPSMP/input/xml/Core/Data/CoreRobotsData.xml and add as many calls to addCoreRobotData as the number of moving parts that you selected in the previous steps. 
            <comment>
        Core components of the i-th robot: state space, valid state sampler, path generator, and local planner.

        Replace SelectedStateSpace_i with the state space for the i-th robot
        Replace SelectedPathGenerator_i with the path generator for the i-th robot
        Replace SelectedValidStateSampler_i with the state sampler for the i-th robot
        Replace SelectedLocalPlanner_i with the local planner for the i-th robot
     </comment>
     <call fn = "addCoreRobotData"><arg type = "pointer">
        <call fn = "setStateSpace"><arg type = "pointer">
           <readContentFromFile>Core/StateSpace/SelectedStateSpace_i.xml</readContentFromFile>
        </arg></call>
        <call fn = "setPathGenerator"><arg type = "pointer">
           <readContentFromFile>Core/Path/SelectedPathGenerator_i.xml</readContentFromFile>
        </arg></call>
        <call fn = "setValidStateSampler"><arg type = "pointer">
           <readContentFromFile>Core/Sampler/SelectedValidStateSampler_i.xml</readContentFromFile>
        </arg></call>
        <call fn = "setLocalPlanner"><arg type = "pointer">
           <readContentFromFile>Core/LocalPlanner/SelectedLocalPlanner_i.xml</readContentFromFile>
        </arg></call>
     </call>

    Setup multiple-robots 3D problem
    • Follow instructions for multiple-robots 2D problem, but replace 2 with 3

  11. What are some common errors when setting up motion-planning problems?

    Initially, it is quite common to forget that changes to one component may require changes in other components as well. For example, when changing the workspace from 2D to 3D it may also be necessary to change the collision detector, state space, and path generator. Similarly, changes to the state space may require changes to the workspace, collision detector, and path generator, and so on.

    Also, number of robots should not be greater than the number of moving parts in the workspace, since the geometry of the i-th robot is assumed to be the i-th moving part.

  12. What should be done in case of a plugin error?

    There could be several reasons as to why a plugin error occurs. One possibility is that not all the required dynamic libraries were loaded and thus OOPSMP is unable to create certain class objects that were specified in the XML file. You could try loading all the dlls by running OOPSMP with the command 
       //Linux/Unix
   ./bin/oopsmp program.xml lib/*.so
   
   //Mac OS X v10.4 (Tiger) / Mac OS X v10.5 (Leopard)
   ./bin/oospmp program.xml lib/*.dylib

   //MS Windows: compiled with Microsoft Visual Studio
   bin\debug\oopsmp program.xml lib\*.dll lib\debug\*.dll
   
   //MS Windows: compiled with MinGW/GCC
   bin\oopsmp program.xml lib\*.dll
    If this fixes the problem, then you could try to figure out exactly which dynamic libraries are needed for your particular program, since it may not be necessary to load all the dynamic libraries. Look at the plugin error and see where that class/function that causes the plugin error appears in the code and then try to load the corresponding dynamic library. For example, if a plugin error is related to StateSpace, which appears in OOPSMP/src/Core/, then try loading OOPSMPCore dynamic library.

    Another possibility is that XML specification is incorrect, i.e., requires creating an instance of an abstract class or requires creating an instance of a class for which no corresponding dlls exist. If this is the case, then simply edit the XML file and remove/fix the specification that causes the plugin error.

    A third possibility is that some of the dynamic libraries were loaded with errors. This usually occurs when the developer forgets to implement certain functions and classes. For each dynamic library, OOPSMP prints out [ok] if the dynamic library is loaded without any errors and some error message if the dll file is loaded with errors. So the programmer can first try to fix these dll errors and then run the program again.

  13. Why are there errors related to OpenGL and GLUT?

    One possible reason could be that OpenGL and GLUT were not installed properly and the system fails to find the library paths for OpenGL and GLUT libraries. First, check if you can run other programs that use OpenGL and GLUT. If you cannot, then probably you need to place the OpenGL and GLUT libraries in the proper place for your system. Otherwise, locate where the OpenGL and GLUT libraries are and edit the file OOPSMP/CMakeLists.txt to properly indicate the paths for these library files.

    OOPSMP assumes that the header files for OpenGL/GLUT are found in <OpenGL/gl.h>, <OpenGL/glu.h>, <GLUT/glut.h> for Mac computers and in <GL/gl.h>, <GL/glu.h>, <GL/glut.h> for all other systems. If this is not the case, then you can copy the header files into the appropriate directories.

    Furthermore, if the directory is not in the path of the compiler, then you need to add the specifications to the cmake files. In particular, you need to edit the file OOPSMP/CMakeLists.txt and add to this file the correct include directories using the command 
       INCLUDE_DIRECTORIES(path_up_to_OpenGL_dir path_up_to_GLUT_dir)

  14. Why are there compiler errors when using RegisterFnFactory macros?

    OOPSMP uses variadic macros, i.e., macros with a variable number of arguments, to register class functions for plug-and-play functionality. Variadic macros are part of the C99 standard, but some older compilers might not support variadic macros. In fact, Microsoft Visual Studio prior to v.8 did not support variadic macros.

    If your compiler does not support variadic macros and you cannot use a different/newer compiler that supports variadic macros then
    1. if your compiler is not Microsoft Visual Studio then add the following line to OOPSMP/CMakeLists.txt: 
            ADD_DEFINITIONS(-DOOPSMP_NO_VARIADIC_MACROS)
      (For Microsoft Visual Studio, OOPSMP automatically detects the version number and sets the flag OOPSMP_NO_VARIADIC_MACROS for versions prior to v.8)
    2. go through the source files of OOPSMP and replace each occurence of RegisterFnFactory with RegisterFnFactoryN, where N is the number of arguments of the function that is being registered for plug-and-play.
    3. if you are registering a function with more than 6 arguments, then go to OOPSMP/src/Utils/General/OOPSMPFactory.H and add macro definitions after RegisterFnFactory6 macro.

  15. Why don't collision detection and triangulation work correctly?

    OOPSMP relies on external packages for collision detection and triangulation. In particular, OOPSMP uses PQP for collision detection and Triangulate for 2D polygon triangulation. Follow the installation steps carefully to ensure that these packages have been properly installed. If these packages are properly installed, then they should work correctly.

  16. Why can't windows find the dlls?

    When creating a shared library for MS Windows, a file with extension .lib and a file with extension .dll are created. The .lib is required during the compilation process as it tells the compiler the classes and functions that have been exported. The .dll is needed during execution.

    The compiler needs to know the directory path where to find these .lib and .dll files. Similarly, when running the executable, the system needs to know where to find the .dll files. MS Windows provides a mechanism for specifying search paths for .lib and .dll files. Edit the path environment variable to include the directory where the OOPSMP libraries are located. When compiling in debug mode, the executable is created in OOPSMP\projects\bin\debug\ and the libraries are created in OOPSMP\projects\lib\debug\. Similarly, when compiling in release mode, the executable is created in OOPSMP\projects\bin\release\ and the libraries are created in OOPSMP\projects\lib\release\. So just add the following three paths to the PATH variable:
    • path\OOPSMP\projects\lib\
    • path\OOPSMP\projects\lib\debug\
    • path\OOPSMP\projects\lib\release\
    where path is the directory where OOPSMP is located.
Copyright 2008 Rice University. For news, updates, and recent developments visit the main OOPSMP page.