README ====== .. contents:: :depth: 2 :local: 1. About -------- This repository contains the main part of the Laustracker software that uses computer vision to track little robots moving through a labyrinth and displays a 2D / 3D visualisation. The source code is hosted at `Bitbucket <https://bitbucket.org/>`_, because Bitbucket allows free unlimited private repositories, in contrast to the better known `GitHub <https://github.com/>`_. https://bitbucket.org/christianjann/laustracker-main A short summary page is online at: http://laustracker.jann.cc And the API documentation: http://liblaustracker.jann.cc 2. PREREQUISITES ---------------- This project requires: * Cross-platform Make (CMake) v2.8.3+ * GNU Make or equivalent. * GCC C++ compiler. * Boost C++ Libraries v1.37+ [HEADERS and LIBRARIES] * Development files for OpenCV (sudo yum install opencv-devel) * uEye drivers (http://www.ids-imaging.de/) * libueyecam (have a look at the thirdparty/libueyecam/ directory) * ROS (Robot Operating System) libraries and tools http://www.ros.org/wiki/ROS/Installation * Pygame http://www.pygame.org/ (sudo yum install pygame pygame-devel) * OpenSceneGraph http://www.openscenegraph.org/ (sudo yum install OpenSceneGraph-devel) 3. BUILDING ----------- This project uses the Cross-platform Make (CMake) build system. However, we have conveniently provided a wrapper configure script and Makefile so that the typical build invocation of "./configure" followed by "make" will work. For a list of all possible build targets, use the command "make help". NOTE: Users of CMake may believe that the top-level Makefile has been generated by CMake; it hasn't, so please do not delete that file. 4. INSTALLING ------------- Once the project has been built (see "BUILDING"), execute "sudo make install". 5. Project organization ----------------------- The project is organized as follows: - AUTHORS - CMakeLists.txt - COPYING - ChangeLog - Doxyfile - INSTALL - Makefile - README - bin/ - build/ - configure - doxygen/ - include/ - lib/ - src/ - src/liblaustracker/ - share/ - thirdparty/ - tools/ AUTHORS This is where contributors to the project should sign their names. CMakeLists.txt This is the top-level build configuration file. It is used by CMake for building the project. Please see the CMake Manual for the full list of available commands. COPYING You should place a plaintext copy of your project's license in this file. Or, you can put an English explanation of the rules of copying your source code, and refer the reader to the "LICENSE" file for the official license agreement that they must follow. ChangeLog For each version, you should annotate the changes between versions in this file. Doxyfile This file configures Doxygen. Please see the Doxygen Configuration Manual on how to customize this file to fit your needs. INSTALL This is where you should place instructions for how to install your product. If you use CMake's builtin "INSTALL(...)" commands for indicating which files to install and where those files should go, then the content of this file should be something along the lines of "Build the project using 'make', then install using 'sudo make install'". Makefile This is a simple Makefile wrapper for "CMakeLists.txt". It allows you to build the CMake project with the usual invocation of "make", without ever having to invoke cmake. README This is where you should place basic documentation for your project. It should include instructions on building your project, instructions on how to use or invoke your project, a list of known bugs, and any other information that you would like users to know. bin/ This is where all executable files built by the project are generated. You can use the "ADD_EXECUTABLE" command in CMake to specify additional executables to generate. If you place this project in Subversion, you will probably want to set the "svn:ignore" property to "*" for this folder (i.e. "svn propset svn:ignore '*' bin"). build/ This is where CMake will generate intermediate build products, including CMake's variable and configuration cache. You should generally not touch this folder. If you place this project in Subversion, you will probably want to set the "svn:ignore" property to "*" for this folder (i.e. "svn propset svn:ignore '*' build"). configure This BASH script invokes CMake. It is there so that user's who are familiar with the "./configure", then "make", then "sudo make install" will feel comfortable using your project. You do not need to touch or edit this file. You can use "make" directly, without first invoking "./configure", since the configuration step will run if necessary. doxygen/ This is where the project's Doxygen documentation will be generated, if you invoke the "make docs" or "make doxygen" targets. If you place this project in a Subversion repository, you will probably want to invoke "svn propset svn:ignore '*' docs". include/ You should place your project's public header files (i.e. the header files that you want the user's of your project to able to include) in a subfolder of "include/". The name of the subfolder should correspond to your project's name. The "include/" folder is automatically added to the header search paths, so if you create a master header file for your project named "projectname.h" and place it in "include/projectname/", then you will be able to include it from your source code using "#include <projectname/projectname.h>". lib/ This is where all library files built by the project are generated. You can use the "ADD_LIBRARY" command in CMake to specify additional libraries to generate. If you place this project in Subversion, you will probably want to set the "svn:ignore" property to "*" for this folder (i.e. "svn propset svn:ignore '*' lib"). share/ You should place any data files that your project needs in a subfolder of this folder. The name of the subfolder should, in some way, correspond to your project's name. src/ You should place your source files in this folder or in a subfolder of this folder. You may need to edit the "CMakeLists.txt" file, so that the appropriate build targets are generated (e.g. if you have multiple different executable or library modules). src/liblaustracker/ All source files of liblaustracker are placed in this folder. The "CMakeLists.txt" file in this directory will automatically compile all sources in the folder into a single executable. thirdparty/ If you would like to bundle thirdparty dependencies with your project, this would be a reasonable location to place them. Otherwise, you can delete this folder. tools/ This contains any scripts, CMake modules, or other components that are needed to build the project or which facilitate project building and development. If you create a script to stylize the code according to your project's specifications or if you create a script to validate that project guidelines are being followed, the "bin" subfolder of "tools" would be the appropriate location to place those scripts. If you need to add modules to CMake (e.g. to implement "FIND_PACKAGE" for an additional package), you should place those scripts in "tools/share/cmake". You can already find examples of such modules for locating Log4Cxx and UnitTest++.