improved READMEs.

Soy-Robotics · Jun 16, 2015 · 4a58f95 · 4a58f95
1 parent 1b7fdbf
commit 4a58f95
Show file tree

Hide file tree

Showing 4 changed files with 62 additions and 19 deletions.
diff --git a/README.md b/README.md
@@ -15,6 +15,7 @@
   - [OpenCL with AMD](#opencl-with-amd)
   - [OpenCL with Nvidia](#opencl-with-nvidia)
   - [OpenCL with Intel](#opencl-with-intel)
+- [Citation](#citation)
 - [Screenshots](#screenshots)
 
 ## Recent changes
@@ -42,6 +43,10 @@ It contains:
 First you should look at this FAQ and the [FAQ from libfreenect2](https://github.com/OpenKinect/libfreenect2#faq).
 Secondly, look at [issue page from libfreenect2](https://github.com/OpenKinect/libfreenect2/issues) and the [issue page of iai_kinect2](https://github.com/code-iai/iai_kinect2/issues) for similar issues and solutions.
 
+#### Will it work with OpenCV 3.0
+
+Right now it will not work with OpenCV 3.0. The default version in Ubuntu and ROS and therefore also for the iai_kinect2 package is OpenCV 2.4.x.
+
 #### kinect2_bridge is not working / crashing, what is wrong?
 
 There are many reasons why `kinect2_bridge` might not working. The first thing to find out whether the problem is related to `kinect2_bridge` or `libfreenect2`. A good tool for testing is `Protonect`, it is a binary located in `libfreenect2/examples/protonect/bin/Protonect`. It uses libfreenect directly with a minimal dependency on other libraries, so it is a good tool for the first tests.
@@ -64,7 +69,11 @@ cd libfreenect2/build
 make & sudo make install
 ```
 
-#### rosdep: Cannot locate rosdep definition for [kinect2_bridge] or [depth_registration]
+#### kinect2_bridge hangs and prints "waiting for clients to connect"
+
+This is the normal behavior. 'kinect2_bridge' will only process data when clients are connected (ROS nodes listening to at least one of the topics). This saves CPU and GPU resources. As soon as you start the `kinect_viewer` or `rostopic hz` on one of the topics, processing should start.
+
+#### rosdep: Cannot locate rosdep definition for [kinect2_bridge] or [kinect2_registration]
 
 `rosdep` will output errors on not being able to locate `[kinect2_bridge]` and `[kinect2_registration]`. That is fine because they are all part of the iai_kinect2 package and `rosdep` does not know these packages.
 
@@ -81,10 +90,10 @@ If you found no solution in the issues, feel free to open a new issue for your p
 ## Dependencies
 
 - ROS Hydro/Indigo
-- OpenCV
-- PCL
-- Eigen (optional)
-- OpenCL (optional)
+- OpenCV (2.4.x, using the one from the official Ubuntu repositories is recommended)
+- PCL (1.7.x, using the one from the official Ubuntu repositories is recommended)
+- Eigen (optional, but recommeded)
+- OpenCL (optional, but recommeded)
 - [libfreenect2](https://github.com/OpenKinect/libfreenect2)
 
 ## Install
@@ -212,6 +221,30 @@ echo 0 > /sys/module/i915/parameters/enable_cmd_parser
 ...
 ```
 
+## Citation
+
+If you used `iai_kinect2` for your work, please cite it.
+
+```tex
+@misc{iai_kinect2,
+  author = {Wiedemeyer, Thiemo},
+  title = {{IAI Kinect2}},
+  organization = {Institute for Artificial Intelligence},
+  address = {University Bremen},
+  year = {2014 -- 2015},
+  howpublished = {\url{https://github.com/code-iai/iai\_kinect2}},
+  note = {Accessed June 12, 2015}
+}
+```
+
+The result should look something similar to this (may depend on the bibliography style used):
+
+```
+T. Wiedemeyer, “IAI Kinect2,” https://github.com/code-iai/iai_kinect2,
+Institute for Artificial Intelligence, University Bremen, 2014 – 2015,
+accessed June 12, 2015.
+```
+
 ## Screenshots
 
 Here are some screenshots from our toolkit:

diff --git a/kinect2_bridge/README.md b/kinect2_bridge/README.md
@@ -27,14 +27,16 @@ This is a bridge between [libfreenect2](https://github.com/OpenKinect/libfreenec
 
 For the depth registration the camera intrinsics and extrinsics need to be known. The program reads in the values from the `data/<serialnumber>` folder. For each new sensor you need to add a subfolder with the serial number of the device as the folder name. In this folder you need to provide 4 yaml files with the intrinsics and extrinsics. These files can be created by the `kinect2_calibration` tool (or you can copy the files provided in one of the other folders, but results can be sub optimal). The device serial number is shown when `kinect2_bridge` or `Protonect` from libfreenect2 is started, it also appears in `dmesg` when you connect the sensor. [More information on calibration](../kinect2_calibration#calibrating-the-kinect-one).
 
-When `kinect2_bridge` is running you can use the `registration_viewer` to display the images or point cloud: `rosrun registration_viewer viewer image` or `rosrun registration_viewer viewer cloud`.
+When `kinect2_bridge` is running you can use the `kinect2_viewer` to display the images or point cloud: `rosrun kinect2_viewer kinect2_viewer sd image` or `rosrun kinect2_viewer kinect2_viewer sd cloud`.
 
 ## Topics
 
 ### HD Topics
 
 The images in this topics have a FullHD resolution (1920x1080).
 
+*Note: For correct registration of the depth image to the color image it is needed to perform a calibration.*
+
 ```
 /kinect2/hd/camera_info
 /kinect2/hd/image_color
@@ -54,6 +56,8 @@ The images in this topics have a FullHD resolution (1920x1080).
 
 The images in this topics have a quater FullHD resolution (960x540).
 
+*Note: For correct registration of the depth image to the color image it is needed to perform a calibration.*
+
 ```
 /kinect2/qhd/camera_info
 /kinect2/qhd/image_color
@@ -73,16 +77,21 @@ The images in this topics have a quater FullHD resolution (960x540).
 
 This are the raw IR and depth images from the sensor (512x424).
 
+*Note: The registration of the color image is available without a calibration. Parameters for the registration are provided by the sensor itself.*
+
 ```
-/kinect2/ir/camera_info
-/kinect2/ir/image_depth
-/kinect2/ir/image_depth/compressed
-/kinect2/ir/image_depth_rect
-/kinect2/ir/image_depth_rect/compressed
-/kinect2/ir/image_ir
-/kinect2/ir/image_ir/compressed
-/kinect2/ir/image_ir_rect
-/kinect2/ir/image_ir_rect/compressed
+/kinect2/sd/camera_info
+/kinect2/sd/image_color_rect
+/kinect2/sd/image_color_rect/compressed
+/kinect2/sd/image_depth
+/kinect2/sd/image_depth/compressed
+/kinect2/sd/image_depth_rect
+/kinect2/sd/image_depth_rect/compressed
+/kinect2/sd/image_ir
+/kinect2/sd/image_ir/compressed
+/kinect2/sd/image_ir_rect
+/kinect2/sd/image_ir_rect/compressed
+/kinect2/sd/points
 ```
 
 ## Notes

diff --git a/kinect2_calibration/README.md b/kinect2_calibration/README.md
@@ -145,9 +145,10 @@ splot 'plot.dat' using 1:2:5 with dots palette title "Difference relative to XY-
 
 Example calibration results can be found in the directory [kinect2_bridge/data/](../kinect2_bridge/data).
 
-The following images were made before and after the calibration, using the registration viewer.
- - For the superimposed images: `rosrun registration_viewer viewer sd image raw`
- - For the point cloud images: `rosrun registration_viewer viewer`
+The following images were made before and after the calibration, using the kinect2 viewer.
+ - For the superimposed images: `rosrun kinect2_viewer kinect2_viewer hd image`
+ - For the point cloud images: `rosrun kinect2_viewer kinect2_viewer hd cloud`
+ - For the superimposed and point cloud images: `rosrun kinect2_viewer kinect2_viewer hd both`
 
 raw here stands for raw data transmission aka uncompressed.
 

diff --git a/kinect2_viewer/CMakeLists.txt b/kinect2_viewer/CMakeLists.txt
@@ -45,7 +45,7 @@ endif()
 ## DEPENDS: system dependencies of this project that dependent projects also need
 catkin_package(
 #  INCLUDE_DIRS include
-#  LIBRARIES registration_viewer
+#  LIBRARIES kinect2_viewer
 #  CATKIN_DEPENDS other_catkin_pkg
 #  DEPENDS system_lib
 )