From 6530af363dad38e5940c91c10523c05a86e55511 Mon Sep 17 00:00:00 2001 From: Adam Allevato Date: Fri, 2 Jun 2017 10:20:19 -0700 Subject: [PATCH] Updated documentation and started preparing package for primetime --- CMakeLists.txt | 192 ++----------------------------- mainpage.dox | 10 ++ msg/Classification2D.msg | 5 +- msg/Detection2D.msg | 9 +- msg/Detection2DArray.msg | 6 +- msg/Detection3D.msg | 9 +- msg/Detection3DArray.msg | 4 +- msg/ObjectHypothesis.msg | 8 +- msg/ObjectHypothesisWithPose.msg | 15 ++- msg/VisionInfo.msg | 42 +++++-- package.xml | 44 +------ setup.py | 12 ++ 12 files changed, 100 insertions(+), 256 deletions(-) create mode 100644 mainpage.dox create mode 100644 setup.py diff --git a/CMakeLists.txt b/CMakeLists.txt index 7ab8f2c..4dd31eb 100644 --- a/CMakeLists.txt +++ b/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 +) \ No newline at end of file diff --git a/mainpage.dox b/mainpage.dox new file mode 100644 index 0000000..52d9cff --- /dev/null +++ b/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. + + +*/ \ No newline at end of file diff --git a/msg/Classification2D.msg b/msg/Classification2D.msg index 841503a..3ce7596 100644 --- a/msg/Classification2D.msg +++ b/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 diff --git a/msg/Detection2D.msg b/msg/Detection2D.msg index c2a369f..e1dec12 100644 --- a/msg/Detection2D.msg +++ b/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 diff --git a/msg/Detection2DArray.msg b/msg/Detection2DArray.msg index f4ba4b5..91fce73 100644 --- a/msg/Detection2DArray.msg +++ b/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 diff --git a/msg/Detection3D.msg b/msg/Detection3D.msg index c170276..efe9edb 100644 --- a/msg/Detection3D.msg +++ b/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 diff --git a/msg/Detection3DArray.msg b/msg/Detection3DArray.msg index 5583d41..8ba1382 100644 --- a/msg/Detection3DArray.msg +++ b/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 diff --git a/msg/ObjectHypothesis.msg b/msg/ObjectHypothesis.msg index 66361b1..4abd5a0 100644 --- a/msg/ObjectHypothesis.msg +++ b/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 \ No newline at end of file diff --git a/msg/ObjectHypothesisWithPose.msg b/msg/ObjectHypothesisWithPose.msg index 0ba7f56..e92d302 100644 --- a/msg/ObjectHypothesisWithPose.msg +++ b/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 \ No newline at end of file diff --git a/msg/VisionInfo.msg b/msg/VisionInfo.msg index e3cb469..063b1c4 100644 --- a/msg/VisionInfo.msg +++ b/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 \ No newline at end of file diff --git a/package.xml b/package.xml index 15a40ec..1bfe001 100644 --- a/package.xml +++ b/package.xml @@ -1,47 +1,17 @@ vision_msgs - 0.0.0 + 1.0.0 - PROPOSED DRAFT of: Classifier-agnostic computer vision classification and - detection messages. + Messages for interfacing with various computer vision pipelines, such as + object + detectors. - - - Adam Allevato - - - - - BSD - - - - - - - - - - - Adam Allevato - - - - - - - - - - - - catkin message_generation @@ -50,9 +20,5 @@ sensor_msgs geometry_msgs - - - - - + diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..e6a9952 --- /dev/null +++ b/setup.py @@ -0,0 +1,12 @@ +#!/usr/bin/env python + +from distutils.core import setup +from catkin_pkg.python_setup import generate_distutils_setup + +d = generate_distutils_setup( + # scripts=['bin/myscript'], + packages=['vision_msgs'], + package_dir={'': 'src'} +) + +setup(**d) \ No newline at end of file