kgeebelen/test repository overview

.. This file is also integrated into the HTML documentation (doc/build/html/index.html). You can go to the html version directly for a better reading experience. If the html file doesn't exist, you need to compile it manually. See "How to start" section below.

############### Introduction ###############

About OASE

In order to create a simple working environment for the implementation of state estimation algorithms, like a Kalman filter, the OASE (\ O\nline A\synchronous S\tate E\stimator) Toolbox is developed at Flanders Make.

This toolbox provides a fast and easy interface for the user and can be integrated with ROS for online applications. This toolbox is considered as a valuable asset for the estimation algorithm research as its modularized design enables an easy way to test different algorithm designs.

At this moment, the main estimation technology implemented in this toolbox is an EKF (Extended Kalman Filter). Other algorithms are also under development, such as null-space Kalman filter, unscented Kalman filter, Least-square solvers or particle filter.

The main features of the toolbox can be summarized as follows:

1. Low calculation time

   • In this toolbox, the system model and observation functions, as well as the Jacobin matrix, are derived analytically using Casadi. Afterwards, C functions will be created to run the calculation. This ensures the main calculations of the filter is performed with very low calculation time.

#. Handle complex data scheme

• In most of practical cases, different sensors have different sample rate and their data will not be synchronized. Meanwhile, there might be delay of the data due to data transmission or pre-processing (e.g. for camera images). By indicating the time stamp of each data, the toolbox can handle the data automatically.

• The measurement function of the system can be separated into multiple functions to modularize the implementation (normally one for each sensor), and the observation data for different observation functions can be fed to the filter separately.

#. Easy to use

• The toolbox is developed in Python which demands less programming skills, and it can be used in different environments.

• The toolbox includes commonly used vehicle and sensor models. It’s also fast and easy to add customized new models.

• It also provides utility modules/classes to help the user on post-processing and data analyses.

Get It Ready

⁠Installation

At this moment the OASE toolbox does not require installation. As long as the search path is properly configured and required packages are installed (see below).

⁠Dependency

⁠Installed by pip

The OASE toolbox is using some widely used packages, such as numpy, matplotlib, and etc. A requirement file is prepared in the root folder of the toolbox (requirements.txt). Users can use pip to install all packages at once::

pip install -r requirements.txt

⁠ROS packages

Some helper classes and examples in the OASE toolbox require two ROS related packages, namely: rospy and rosbag. They are not available from pip at this moment. There are two ways to install them:

1. Install a ROS distribution (Recommended)

   Users can follow the instructions from ROS <http://wiki.ros.org/ROS/Installation>_ to install a ROS distribution. A full install is recommended. Once the ROS is installed and the environment is setup (source the right bash script), those two packages will be available.

2. Install them system-wise

   In debian based Linux system, those two packages can also be installed by::

   sudo apt install python-rosbag python-rospy
   

   Copy

⁠Other System-wise Packages

Depending on your Linux distribution, some system-wise packages may not be installed by default, which may cause issues during install Python packages or using the toolbox. Before using the toolbox, it is recommended to run the following commands in debian based Linux systems (like Ubuntu) to install some packages::

sudo apt install python-tk python3-tk python-dev python3-dev

For other Linux distributions, please use corresponding package handling tools to install the packages.

⁠Python 2 vs 3

The OASE is developed with the goal that to be compatible with both Python 2 and 3. The main frame of the toolbox has been tested using simple test cases. However, some modules in the toolbox are developed to work with ROS, which only support Python 2. Therefore, a part of the toolbox may only works in Python 2, including:

1. The CameraModel class, which is using python-cv2

#. The BagReader class, which is using rosbag

.. Note:: As the main application of OASE is with ROS at this moment, the use of OASE in Python 3 has not been tested extensively, especially for the compiled version (using Cyphon).

.. Warning:: The compiled OASE toolbox is Python version specific, i.e., the package compiled in Python3 will not be compatible to Python2, and vice versa. Please make sure to use the toolbox in the right environment.

How To Start

In order to help users to learn and use this toolbox, different kinds of documentations are prepared, including:

1. Detailed doc-string for all modules to explain the API of the toolbox.

#. A guideline about how the toolbox works and the general work flow. This guideline is integrated with the documentation generated from in-line comments using the Sphinx tool. Users can find this documentation at doc/build/html/index.html.

#. Some simple toy examples are provided in the example folder to show the basics of using the toolbox. They are placed in example/agv and example/drone.

#. A realistic off-line example to run an EKF on drone flight test data. The code, data file and configuration files can be found in example/drone_ros.

The file structure of the toolbox is as following::

oase
├── doc
│   └── build
│       └── html
│           └── index.html
├── example
│   ├── agv
│   ├── drone (DEPRECATED)
│   └── drone_ros
├── README.rst
├── requirements.txt
└── *.py (or *.so for compiled version)

For users who retrieved the source codes of OASE from SVN or Git, the html documentation needs to be build from source. This can be done easily with Sphinx. Please make sure the latest Sphinx has been installed on your PC. The version tested by developers is 3.0.x.

For Ubuntu user, you can install Sphinx system wise with::

# For python2:
sudo apt install python-sphinx

# For python3:
sudo apt install python3-sphinx

.. note:: As the Python2 has reached the end of its life, the Sphinx package installed within Python2 environment is relatively old, which may cause problems for building the documentations. It is strongly recommended to run the Sphinx in a Python3 virtual environment to avoid potential problems.

To create the documentation, go to the oase/doc folder to run::

make html

Contact

Jia Wan: [email protected]⁠

Kurt Geebelen: [email protected]⁠