Add in a README file explaining how to build, run, and use the programs.

Signed-off-by: Chris Lalancette <[email protected]>

Author: clalancette

image_tools_py/README

@@ -0,0 +1,109 @@
+This is a demonstration of the Quality of Service (QoS) features of ROS 2 using Python.
+There are two programs implemented here: cam2image_py, and showimage_py.  Note that in
+order for these programs to work, an OpenCV binding for Python3 must be available.  As
+of this writing (January 11, 2017), only OpenCV 3 or later supports Python3.  Instructions
+for compiling OpenCV3 for Python3 are available here:
+
+http://stackoverflow.com/questions/20953273/install-opencv-for-python-3-3
+
+The condensed rundown that works on Ubuntu16.04 and will install to /usr/local is:
+$ sudo apt install python3 build-essential cmake git libgtk2.0-dev pkg-config libavcodec-dev libavformat-dev libswscale-dev python3.5-dev libpython3-dev python3-numpy libtbb2 libtbb-dev libjpeg-dev libpng-dev libtiff-dev libjasper-dev libdc1394-22-dev
+$ git clone https://github.com/opencv/opencv
+$ cd opencv
+$ git checkout 3.2.0
+$ mkdir release
+$ cd release
+$ cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local ..
+$ make -j8
+$ sudo make install
+
+CAM2IMAGE_PY
+------------
+This is a Python program that will take data from an attached camera, and publish the
+data to a topic called "image", with the type sensor_msgs::msg::Image.  If a camera
+isn't available, this program can also generate a default image and smoothly "move"
+it across the screen, simulating motion.  The usage output from the program looks like
+this:
+
+usage: cam2image_py.py [-h] [-b] [-d QUEUE_DEPTH] [-f FREQUENCY] [-k {0,1}]
+                       [-r {0,1}] [-s {0,1}] [-x WIDTH] [-y HEIGHT]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -b, --burger          Produce images of burgers rather than connecting to a
+                        camera (default: False)
+  -d QUEUE_DEPTH, --depth QUEUE_DEPTH
+                        Queue depth (default: 10)
+  -f FREQUENCY, --frequency FREQUENCY
+                        Publish frequency in Hz (default: 30)
+  -k {0,1}, --keep {0,1}
+                        History QoS setting, 0 - keep last sample, 1 - keep
+                        all the samples (default: 1)
+  -r {0,1}, --reliability {0,1}
+                        Reliability QoS setting, 0 - best effort, 1 - reliable
+                        (default: 1)
+  -s {0,1}, --show {0,1}
+                        Show the camera stream (default: 0)
+  -x WIDTH, --width WIDTH
+                        Image width (default: 320)
+  -y HEIGHT, --height HEIGHT
+                        Image height (default: 240)
+
+The -d, -k, and -r parameters control various aspects of the QoS implementation, and
+are the most interesting to play with when testing out QoS.
+
+Note that this program also subscribes to a topic called "flip_image" of type
+std_msgs::msg::Bool.  If flip_image is set to False, the data coming out of the camera
+is sent as usual.  If flip_image is set to True, the data coming out of the camera is
+flipped around the Y axis.
+
+If the -s parameter is set to 1, then this program opens up a (local) window to show
+the images that are being published.  However, these images are *not* coming in through
+the ROS 2 pub/sub model, so this window cannot show off the QoS parameters (it is mostly
+useful for debugging).  See SHOWIMAGE_PY below for a program that can show QoS over the
+pub/sub model.
+
+SHOWIMAGE_PY
+------------
+This is a Python program that subscribes to the "image" topic, waiting for data.  As
+new data comes in, this program accepts the data and can optionally render it to
+the screen.  The usage output from the program looks like this:
+
+usage: showimage_py.py [-h] [-d QUEUE_DEPTH] [-k {0,1}] [-r {0,1}] [-s {0,1}]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d QUEUE_DEPTH, --depth QUEUE_DEPTH
+                        Queue depth (default: 10)
+  -k {0,1}, --keep {0,1}
+                        History QoS setting, 0 - keep last sample, 1 - keep
+                        all the samples (default: 1)
+  -r {0,1}, --reliability {0,1}
+                        Reliability QoS setting, 0 - best effort, 1 - reliable
+                        (default: 1)
+  -s {0,1}, --show {0,1}
+                        Show the camera stream (default: 0)
+
+The -d, -k, and -r parameters control various aspects of the QoS implementation, and
+are the most interesting to play with when testing out QoS.
+
+If the -s parameter is set to 1, then this program opens up a window to show the images
+that have been received over the ROS 2 pub/sub model.  This program should be used
+in conjunction with CAM2IMAGE_PY to demonstrate the ROS 2 QoS capabilities over lossy/slow
+links.
+
+EXAMPLE USAGE
+-------------
+To use the above programs, you would run them something like the following:
+
+# In the first terminal, run the data publisher.  This will connect to the 1st camera
+# available, and print out "Publishing image #" for each image it publishes.
+$ python3 cam2image_py.py
+
+# In a second terminal, run the data subscriber.  This will subscribe to the "image"
+# topic and render any frames it receives.
+$ python3 showimage_py.py -s 1
+
+# If you don't have a local camera, you can use the -b parameter to generate data on
+# the fly rather than get data from a camera:
+$ python3 cam2image_py.py -b