Updated documentation and started preparing package for primetime

CMakeLists.txt

@@ -1,54 +1,13 @@
 cmake_minimum_required(VERSION 2.8.3)
 project(vision_msgs)
 
-## Add support for C++11, supported in ROS Kinetic and newer
-# add_definitions(-std=c++11)
-
-## Find catkin macros and libraries
-## if COMPONENTS list like find_package(catkin REQUIRED COMPONENTS xyz)
-## is used, also find other catkin packages
 find_package(catkin REQUIRED COMPONENTS
+  message_generation
   std_msgs
   sensor_msgs
-  geometry_msgs
-  message_generation)
-
-## System dependencies are found with CMake's conventions
-# find_package(Boost REQUIRED COMPONENTS system)
-
-
-## Uncomment this if the package has a setup.py. This macro ensures
-## modules and global scripts declared therein get installed
-## See http://ros.org/doc/api/catkin/html/user_guide/setup_dot_py.html
-# catkin_python_setup()
+  geometry_msgs)
 
-################################################
-## Declare ROS messages, services and actions ##
-################################################
-
-## To declare and build messages, services or actions from within this
-## package, follow these steps:
-## * Let MSG_DEP_SET be the set of packages whose message types you use in
-##   your messages/services/actions (e.g. std_msgs, actionlib_msgs, ...).
-## * In the file package.xml:
-##   * add a build_depend tag for "message_generation"
-##   * add a build_depend and a run_depend tag for each package in MSG_DEP_SET
-##   * If MSG_DEP_SET isn't empty the following dependency has been pulled in
-##     but can be declared for certainty nonetheless:
-##     * add a run_depend tag for "message_runtime"
-## * In this file (CMakeLists.txt):
-##   * add "message_generation" and every package in MSG_DEP_SET to
-##     find_package(catkin REQUIRED COMPONENTS ...)
-##   * add "message_runtime" and every package in MSG_DEP_SET to
-##     catkin_package(CATKIN_DEPENDS ...)
-##   * uncomment the add_*_files sections below as needed
-##     and list every .msg/.srv/.action file to be processed
-##   * uncomment the generate_messages entry below
-##   * add every package in MSG_DEP_SET to generate_messages(DEPENDENCIES ...)
-
-# Generate messages in the 'msg' folder
-add_message_files(
-  FILES
+add_message_files(FILES
   BoundingBox2D.msg
   BoundingBox3D.msg
   Classification2D.msg
@@ -62,146 +21,15 @@ add_message_files(
   VisionInfo.msg
 )
 
-## Generate services in the 'srv' folder
-# add_service_files(
-#   FILES
-#   Service1.srv
-#   Service2.srv
-# )
-
-## Generate actions in the 'action' folder
-# add_action_files(
-#   FILES
-#   Action1.action
-#   Action2.action
-# )
-
-## Generate added messages and services with any dependencies listed here
-generate_messages(
-  DEPENDENCIES
+generate_messages(DEPENDENCIES
   std_msgs
   sensor_msgs
   geometry_msgs
 )
 
-################################################
-## Declare ROS dynamic reconfigure parameters ##
-################################################
-
-## To declare and build dynamic reconfigure parameters within this
-## package, follow these steps:
-## * In the file package.xml:
-##   * add a build_depend and a run_depend tag for "dynamic_reconfigure"
-## * In this file (CMakeLists.txt):
-##   * add "dynamic_reconfigure" to
-##     find_package(catkin REQUIRED COMPONENTS ...)
-##   * uncomment the "generate_dynamic_reconfigure_options" section below
-##     and list every .cfg file to be processed
-
-## Generate dynamic reconfigure parameters in the 'cfg' folder
-# generate_dynamic_reconfigure_options(
-#   cfg/DynReconf1.cfg
-#   cfg/DynReconf2.cfg
-# )
-
-###################################
-## catkin specific configuration ##
-###################################
-## The catkin_package macro generates cmake config files for your package
-## Declare things to be passed to dependent projects
-## INCLUDE_DIRS: uncomment this if you package contains header files
-## LIBRARIES: libraries you create in this project that dependent projects also need
-## CATKIN_DEPENDS: catkin_packages dependent projects also need
-## DEPENDS: system dependencies of this project that dependent projects also need
-catkin_package(
-#  INCLUDE_DIRS include
-#  LIBRARIES vision_msgs
-  CATKIN_DEPENDS std_msgs sensor_msgs geometry_msgs message_runtime
-#  DEPENDS system_lib
-)
-
-###########
-## Build ##
-###########
-
-## Specify additional locations of header files
-## Your package locations should be listed before other locations
-# include_directories(include)
-
-## Declare a C++ library
-# add_library(${PROJECT_NAME}
-#   src/${PROJECT_NAME}/vision_msgs.cpp
-# )
-
-## Add cmake target dependencies of the library
-## as an example, code may need to be generated before libraries
-## either from message generation or dynamic reconfigure
-# add_dependencies(${PROJECT_NAME} ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})
-
-## Declare a C++ executable
-## With catkin_make all packages are built within a single CMake context
-## The recommended prefix ensures that target names across packages don't collide
-# add_executable(${PROJECT_NAME}_node src/vision_msgs_node.cpp)
-
-## Rename C++ executable without prefix
-## The above recommended prefix causes long target names, the following renames the
-## target back to the shorter version for ease of user use
-## e.g. "rosrun someones_pkg node" instead of "rosrun someones_pkg someones_pkg_node"
-# set_target_properties(${PROJECT_NAME}_node PROPERTIES OUTPUT_NAME node PREFIX "")
-
-## Add cmake target dependencies of the executable
-## same as for the library above
-# add_dependencies(${PROJECT_NAME}_node ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})
-
-## Specify libraries to link a library or executable target against
-# target_link_libraries(${PROJECT_NAME}_node
-#   ${catkin_LIBRARIES}
-# )
-
-#############
-## Install ##
-#############
-
-# all install targets should use catkin DESTINATION variables
-# See http://ros.org/doc/api/catkin/html/adv_user_guide/variables.html
-
-## Mark executable scripts (Python etc.) for installation
-## in contrast to setup.py, you can choose the destination
-# install(PROGRAMS
-#   scripts/my_python_script
-#   DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
-# )
-
-## Mark executables and/or libraries for installation
-# install(TARGETS ${PROJECT_NAME} ${PROJECT_NAME}_node
-#   ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
-#   LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
-#   RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
-# )
-
-## Mark cpp header files for installation
-# install(DIRECTORY include/${PROJECT_NAME}/
-#   DESTINATION ${CATKIN_PACKAGE_INCLUDE_DESTINATION}
-#   FILES_MATCHING PATTERN "*.h"
-#   PATTERN ".svn" EXCLUDE
-# )
-
-## Mark other files for installation (e.g. launch and bag files, etc.)
-# install(FILES
-#   # myfile1
-#   # myfile2
-#   DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION}
-# )
-
-#############
-## Testing ##
-#############
-
-## Add gtest based cpp test target and link libraries
-# catkin_add_gtest(${PROJECT_NAME}-test test/test_vision_msgs.cpp)
-# if(TARGET ${PROJECT_NAME}-test)
-#   target_link_libraries(${PROJECT_NAME}-test ${PROJECT_NAME})
-# endif()
-
-## Add folders to be run by python nosetests
-# catkin_add_nosetests(test)
+catkin_package(CATKIN_DEPENDS
+  message_runtime
+  std_msgs
+  sensor_msgs
+  geometry_msgs
+)

mainpage.dox

@@ -0,0 +1,10 @@
+/**
+\mainpage
+\htmlinclude manifest.html
+
+\b sensor_msgs is a package which collects the common message data types for
+robot sensors. It also provides a set of methods for conversion between these
+data types.
+
+
+*/

msg/Classification2D.msg

@@ -1,11 +1,12 @@
 # Defines a 2D classification result.
 #
 # This result does not contain any position information. It is designed for
-# classifiers, which simply provide probabilities given a source image.
+# classifiers, which simply provide class probabilities given a source image.
 
 Header header
 
-# Class probabilities
+# A list of class probabilities. This list need not provide a probability for
+# every possible class, just ones that are nonzero, or above some user-defined
 ObjectHypothesis[] results
 
 # The 2D data that generated these results (i.e. region proposal cropped out of

msg/Detection2D.msg

@@ -1,17 +1,18 @@
 # Defines a 2D detection result.
 #
 # This is similar to a 2D classification, but includes position information,
-# allowing a classification result for a specific crop or image point to
-# to be located in the larger image.
+#   allowing a classification result for a specific crop or image point to
+#   to be located in the larger image.
 
 Header header
 
 # Class probabilities
 ObjectHypothesisWithPose[] results
 
-# 2D bounding box surrounding the object.
+# A 2D bounding box surrounding the object, specified in the coordinates of the
+#   original input image.
 BoundingBox2D bbox
 
 # The 2D data that generated these results (i.e. region proposal cropped out of
-# the image). Not required for all use cases, so it may be empty.
+#   the image). Not required for all use cases, so it may be empty.
 sensor_msgs/Image source_img

msg/Detection2DArray.msg

@@ -1,5 +1,5 @@
-# A list of 3D detections, for a multi-object 2D detector.
+# A list of 2D detections, for a multi-object 2D detector.
 
-# list of the detected proposals. For a multi-proposal detector, this list could
-# have many objects.
+# A list of the detected proposals. A multi-proposal detector might generate
+#   this list with many candidate detections generated from a single input.
 Detection2D[] detections

msg/Detection3D.msg

@@ -1,18 +1,19 @@
 # Defines a 3D detection result.
 #
 # This extends a basic 3D classification by including position information,
-# allowing a classification result for a specific position in an image to
-# to be located in the larger image.
+#   allowing a classification result for a specific position in an image to
+#   to be located in the larger image.
 
 Header header
 
 # Class probabilities. Does not have to include hypotheses for all possible
-# object ids, the scores for any ids not listed are assumed to be 0.
+#   object ids, the scores for any ids not listed are assumed to be 0.
 ObjectHypothesisWithPose[] results
 
 # 3D bounding box surrounding the object.
 BoundingBox3D bbox
 
 # The 3D data that generated these results (i.e. region proposal cropped out of
-# the image). Not required for all detectors, so it may be empty.
+#   the image). This information is not required for all detectors, so it may be
+#   empty.
 sensor_msgs/PointCloud2 source_cloud

msg/Detection3DArray.msg

@@ -1,5 +1,5 @@
 # A list of 3D detections, for a multi-object 3D detector.
 
-# list of the detected proposals. For a multi-proposal detector, this list could
-# have many objects.
+# A list of the detected proposals. A multi-proposal detector might generate
+#   this list with many candidate detections generated from a single input.
 Detection3D[] detections

msg/ObjectHypothesis.msg

@@ -1,8 +1,10 @@
 # An object hypothesis that contains no position information.
 
-# ID of element detected.
+# The unique numeric ID of object detected. To get additional information about
+#   this ID, such as its human-readable name, listeners should perform a lookup
+#   in a metadata database. See vision_msgs/VisionInfo.msg for more detail.
 int64 id
 
-# The probability or confidence value of the detected element. Should be in the
-# range 0-1.
+# The probability or confidence value of the detected object. By convention,
+#   this value should lie in the range [0-1].
 float64 score

msg/ObjectHypothesisWithPose.msg

@@ -1,14 +1,19 @@
-# ID of element detected.
+# An object hypothesis that contains position information.
+
+# The unique numeric ID of object detected. To get additional information about
+#   this ID, such as its human-readable name, listeners should perform a lookup
+#   in a metadata database. See vision_msgs/VisionInfo.msg for more detail.
 int64 id
 
-# The probability or confidence value of the detected element. Should be in the
-# range 0-1.
+# The probability or confidence value of the detected object. By convention,
+#   this value should lie in the range [0-1].
 float64 score
 
 # the 6D pose of the object hypothesis. This pose should be
 # defined as the pose of some fixed reference point on the object, such as the
 # geometric center of the bounding box or the center of mass of the object.
 # Note that this pose is not stamped; frame information can be defined by parent
-# messages. Also note that different classes predicted
-# for the same input data may have different predicted 6D poses.
+#   messages.
+# Also note that different classes predicted
+#   for the same input data may have different predicted 6D poses.
 geometry_msgs/Pose pose

msg/VisionInfo.msg

@@ -1,22 +1,40 @@
-# Provides meta-information about a classifier (or detector).
+# Provides meta-information about a visual pipeline.
 #
 # This message serves a similar purpose to sensor_msgs/CameraInfo, but instead
-# of being tied to hardware, it represents information about a specific computer
-# vision classfier or detector. This information stays constant (or relatively
-# constant) over time, and so it is wasteful to send it with each individual
-# detection message. By listening to these messages, subscribers will receive
-# the context in which published vision messages are to be interpreted.
+#   of being tied to hardware, it represents information about a specific
+#   computer vision pipeline. This information stays constant (or relatively
+#   constant) over time, and so it is wasteful to send it with each individual
+#   result. By listening to these messages, subscribers will receive
+#   the context in which published vision messages are to be interpreted.
+# Each vision pipeline should publish its VisionInfo messages to its own topic,
+#   in a manner similar to CameraInfo.
 
 # Used for sequencing
 Header header
 
-# Name of the classifier
+# Name of the vision pipeline. This should be a value that is meaningful to an
+#   outside user.
 string method
 
-# ROS parameter name where the metadata database is stored in XML format.
-# The exact information stored in the database is left up to the user.
-string database_param
+# Location where the metadata database is stored. The recommended location is
+#   as an XML string on the ROS parameter server, but the exact implementation
+#   and information is left up to the user.
+# The database should store information attached to numeric ids. Each
+#   numeric id should map to an atomic, visually recognizable element. This
+#   definition is intentionally vague to allow extreme flexibility. The elements
+#   could be classes in a pixel segmentation algorithm, object classes in a
+#   detector, different people's faces in a face detection algorithm, etc.
+#   Vision pipelines report results in terms of numeric IDs, which map into this
+#   database.
+# The information stored in this database is, again, left up to the user. The
+#   database could be as simple as a map from ID to class name, or it could
+#   include information such as object meshes or colors to use for
+#   visualization.
+string database_location
 
-# locally-incremented metadata database version. This counter is incremented
-# each time the classifier responds to changes in the metadata database.
+# Metadata database version. This counter is incremented
+#   each time the pipeline begins using a new version of the database (useful
+#   in the case of online training or user modifications).
+#   The counter value can be monitored by listeners to ensure that the pipeline
+#   and the listener are using the same metadata.
 int32 database_version