## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links 
## note.0= [[ROS/Introduction]]
## descriptive title for the tutorial
## title = Quick start guide
## multi-line description to be displayed in search 
## description = Begin here. This tutorial demonstrates how to open a Kinect (or other OpenNI device) in ROS, introduces ROS tools for visualization and configuration, and explains how to get registered (depth + RGB) outputs like color point clouds.
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for 
## level= BeginnerCategory
## keywords =
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TableOfContents(4)>>

== Opening the device ==

Open a command line and launch the OpenNI driver like this:
{{{
roslaunch openni_launch openni.launch
}}}

That's it! `openni.launch` opens your Kinect and processes the raw data into convenient outputs like [[pcl|point clouds]]. See the [[openni_launch#openni.launch|reference documentation]] for all topics published by `openni.launch`. We'll explore some of them below.

== Visualizing the data ==

=== rviz ===

We'll use the [[rviz]] 3D visualization environment to view point clouds:
{{{
rosrun rviz rviz
}}}

Set the Fixed Frame (top of the Display panel under Global Options) to `/camera_link`.

In the Displays panel, click Add and choose the [[rviz/DisplayTypes/PointCloud|PointCloud2 display]]. Set its topic to `/camera/depth/points`. Turning the background color to light gray can help with viewing.

This is the ''unregistered'' point cloud in the frame of the depth (IR) camera. It is not matched with the RGB camera images. We'll get to color point clouds below. For now, set Color Transformer to `AxisColor` to colormap the points by distance.

{{attachment:RvizWithDisplaysPanel.png|rviz|width=100%}}

Also try opening an [[http://www.ros.org/wiki/rviz/DisplayTypes/Image|image display]] and check out the various image topics.

=== Image viewers ===

Alternatively you can use [[image_view]] to view both the RGB image:
{{{
rosrun image_view image_view image:=/camera/rgb/image_color
}}}

and the depth image:
{{{
rosrun image_view image_view image:=/camera/depth/image
}}}

||{{attachment:rgb.jpg|RGB|width=100%}}||{{attachment:depth.png|Depth|width=100%}}||

[[image_view]] also contains the `disparity_view` viewer for <<MsgLink(sensor_msgs/DisparityImage)>> messages:
{{{
rosrun image_view disparity_view image:=/camera/depth/disparity
}}}

{{attachment:disparity.png|Disparity|width=50%}}

Although useful for visualization, for general 3D processing you are encouraged to use the point cloud or depth image topics rather than disparity images, which are particular to stereo. See [[http://www.ros.org/reps/rep-0118.html|REP 118]] for technical details about depth images.

== Registration: matching depth to color ==

The depth and color images come from two separate, slightly offset, cameras, so they do not perfectly overlap. However, for each pixel in the depth image, we can calculate its position in 3D space and reproject it into the image plane of the RGB camera. In this way we build up a ''registered'' depth image, where each pixel is aligned with its counterpart in the RGB image.

## TODO In calibration tutorial, we will see a second approach to registration provided in ROS

OpenNI has a builtin registration capability, which uses the Kinect factory calibration. We can use [[dynamic_reconfigure]] to change the ROS OpenNI driver's settings at runtime. Open the dynamic reconfigure GUI:
{{{
rosrun rqt_reconfigure rqt_reconfigure
}}}

Select `/camera/driver` from the drop-down menu. Enable the `depth_registration` checkbox.

{{attachment:ReconfigureGui.png|Reconfigure GUI}}

Note that the ROS driver is now receiving registered depth images from the underlying OpenNI framework; it does not have access to the unregistered data. The ROS driver no longer publishes in the unregistered `/camera/depth/` namespace, but instead in /`camera/depth_registered/`.

For example, to view the registered disparity image:
{{{
rosrun image_view disparity_view image:=/camera/depth_registered/disparity
}}}

{{attachment:disparity_reg.png|Disparity registered|width=50%}}

Now let's look at the registered point cloud. Go back to `rviz`, and change the topic of your !PointCloud2 display to `/camera/depth_registered/points`. Set Color Transformer to `RGB8`. You should see a color, 3D point cloud of your scene.

{{attachment:RvizColor.png|rviz|width=100%}}

## TODO Where to go from here - link to various tutorials

## AUTOGENERATED DO NOT DELETE 
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE