raphael/msckf_vio
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add readme and license

Browse Source
This commit is contained in:
Ke Sun 2017-11-30 14:29:26 -05:00
commit 3555944610
2 changed files with 133 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
LICENSE.txt Normal file
View File

@ -0,0 +1,36 @@
COPYRIGHT AND PERMISSION NOTICE
Penn Software MSCKF_VIO
Copyright (C) 2017 The Trustees of the University of Pennsylvania
All rights reserved.
The Trustees of the University of Pennsylvania (“Penn”) and Ke Sun, Kartik Mohta, the developer (“Developer”) of Penn Software MSCKF_VIO (“Software”) give recipient (“Recipient”) and Recipient’s Institution (“Institution”) permission to use, copy, and modify the software in source and binary forms, with or without modification for non-profit research purposes only provided that the following conditions are met:
1) All copies of Software in binary form and/or source code, related documentation and/or other materials provided with the Software must reproduce and retain the above copyright notice, this list of conditions and the following disclaimer.
2) Recipient shall have the right to create modifications of the Software (“Modifications”) for their internal research and academic purposes only.
3) All copies of Modifications in binary form and/or source code and related documentation must reproduce and retain the above copyright notice, this list of conditions and the following disclaimer.
4) Recipient and Institution shall not distribute Software or Modifications to any third parties without the prior written approval of Penn.
5) Recipient will provide the Developer with feedback on the use of the Software and Modifications, if any, in their research. The Developers and Penn are permitted to use any information Recipient provides in making changes to the Software. All feedback, bug reports and technical questions shall be sent to:
sunke@seas.upenn.edu
kmohta@seas.upenn.edu
6) Recipient acknowledges that the Developers, Penn and its licensees may develop modifications to Software that may be substantially similar to Recipient’s modifications of Software, and that the Developers, Penn and its licensees shall not be constrained in any way by Recipient in Penn’s or its licensees’ use or management of such modifications. Recipient acknowledges the right of the Developers and Penn to prepare and publish modifications to Software that may be substantially similar or functionally equivalent to your modifications and improvements, and if Recipient or Institution obtains patent protection for any modification or improvement to Software, Recipient and Institution agree not to allege or enjoin infringement of their patent by the Developers, Penn or any of Penn’s licensees obtaining modifications or improvements to Software from the Penn or the Developers.
7) Recipient and Developer will acknowledge in their respective publications the contributions made to each other’s research involving or based on the Software. The current citations for Software are:
8) Any party desiring a license to use the Software and/or Modifications for commercial purposes shall contact The Penn Center for Innovation at 215-898-9591.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS, CONTRIBUTORS, AND THE TRUSTEES OF THE UNIVERSITY OF PENNSYLVANIA "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER, CONTRIBUTORS OR THE TRUSTEES OF THE UNIVERSITY OF PENNSYLVANIA BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

97
README.md Normal file
View File

@ -0,0 +1,97 @@
# MSCKF\_VIO
<!--
[![Build Status](https://travis-ci.org/KumarRobotics/velodyne_puck.svg?branch=master)](https://travis-ci.org/KumarRobotics/velodyne_puck)
-->
<!--
![Picture of Velodyne Puck](http://velodynelidar.com/images/products/vlp-16/puck.png)
-->
The `MSCKF_VIO` package is a stereo implementation of the MSCKF algorithm introduced in [1] with modifications. The software takes in synchronized stereo image pairs and IMU messages and generates real-time 6DOF pose estimation of the IMU frame.
The software is tested on Ubuntu 16.04 with ROS Kinetic.
Video: [https://www.youtube.com/watch?v=OXSB8Bze0cY](https://www.youtube.com/watch?v=OXSB8Bze0cY)
Paper: The paper will be available soon.
## License
Penn Software License. See LICENSE.txt for further details.
## Dependencies
Most of the dependencies are standard including `Eigen`, `OpenCV`, and `Boost`. The standard shipment from Ubuntu 16.04 and ROS Kinetic works fine. One special requirement is `suitesparse`, which can be installed through,
```
sudo apt-get install libsuitesparse-dev
```
## Compling
The software is a standard catkin package. Make sure the package is on `ROS_PACKAGE_PATH` after cloning the package to your workspace. And the normal procedure for compling a catkin package will work.
```
cd your_work_space
catkin_make --pkg msckf_vio --cmake-args -DCMAKE_BUILD_TYPE=Release
```
## Calibration
An accurate calibration is crucial for successfully running the software. To get the best performance of the software, the stereo cameras and IMU should be hardware synchronized. [Kalibr](https://github.com/ethz-asl/kalibr) can be used to calibrate the transformantion between the stereo cameras and IMU. The yaml file generated by Kalibr can be directly used in this software with slight modifications. See `example_calib.yaml` in the `config` folder for the modifications.
## Example Usage
There are launch files prepared for the EuRoC and fast flight dataset separately. Upon launching the `msckf_vio_*.launch`, two ros nodes are created:
* `image_processor` takes the stereo images to detect and track features.
* `vio` takes the feature measurements and tightly fuses them with the IMU messages to estimate pose.
### `image_processor` node
**Subscribed Topics**
`imu` (`sensor_msgs/Imu`)
IMU messages is used for compensating rotation in feature tracking, and 2-point RANSAC.
`camx_image` (`sensor_msgs/Image`)
Synchronized stereo images.
**Published Topics**
`features` (`msckf_vio/CameraMeasurement`)
Records the feature measurements on the current stereo image pair.
`tracking_info` (`msckf_vio/TrackingInfo`)
Records the feature tracking status for debugging purpose.
`debug_stereo_img` (`sensor_msgs::Image`)
Draw current features on the stereo images for debugging purpose. Note that this debugging image is only generated upon subscription.
### `vio` node
**Subscribed Topics**
`imu` (`sensor_msgs/Imu`)
IMU measurements.
`features` (`msckf_vio/CameraMeasurement`)
Stereo feature measurements from the `image_processor` node.
**Published Topics**
`odom` (`nav_msgs/Odometry`)
Odometry of the IMU frame including a proper covariance.
`feature_point_cloud` (`sensor_msgs/PointCloud2`)
Shows current features in the map which may be used for estimation.
[1] Mourikis, Anastasios I., and Stergios I. Roumeliotis. "A multi-state constraint Kalman filter for vision-aided inertial navigation." Robotics and automation, 2007 IEEE international conference on. IEEE, 2007.