diff --git a/.gitignore b/.gitignore index d922450..2b80ce7 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,6 @@ apps/data/ *.obj *.3ds -*.png *.ply *.mtl *.bag diff --git a/doc/doc_config.py.in b/doc/doc_config.py.in index 81b769d..ed58bcc 100644 --- a/doc/doc_config.py.in +++ b/doc/doc_config.py.in @@ -9,7 +9,7 @@ breathe_default_project = '${PROJECT_NAME}' breathe_projects = dict(object_recognition_core='${CMAKE_CURRENT_BINARY_DIR}/../api/xml') # for release -ork_module_url_root = 'http://wg-perception.github.com/' +ork_module_url_root = 'http://wg-perception.github.io/' intersphinx_mapping = {'orkcapture': (ork_module_url_root + 'capture', None), 'orklinemod': (ork_module_url_root + 'linemod', None), diff --git a/doc/source/api/db.rst b/doc/source/api/db.rst index 4a9fbdf..4f3f88a 100644 --- a/doc/source/api/db.rst +++ b/doc/source/api/db.rst @@ -21,5 +21,5 @@ Core Types Implementing your own DB type ----------------------------- -If you want to create your own DB type, look at the examples from the core like CouchDb or filesystem. -You just have to inherit from ``ObjectDb``. +If you want to create your own DB type, look at the examples from the core, like +CouchDb or filesystem. Your new database must inherit from ``ObjectDb``. diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index 6164347..a2e5987 100644 --- a/doc/source/api/index.rst +++ b/doc/source/api/index.rst @@ -26,9 +26,10 @@ by getting automatic docs from it ...). .. toctree:: :maxdepth: 2 - + generic.rst training.rst detection.rst source_sink.rst cells.rst + db.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index e57e3f8..45b3561 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -34,7 +34,7 @@ 'sphinx.ext.doctest', 'sphinx.ext.graphviz', 'sphinx.ext.intersphinx', - 'sphinx.ext.pngmath', + 'sphinx.ext.imgmath', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'breathe'] @@ -142,7 +142,7 @@ # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = 'art/or.svg' +html_logo = 'img/or.svg' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 diff --git a/doc/source/detection/detection.rst b/doc/source/detection/detection.rst index 6160698..959fbd4 100644 --- a/doc/source/detection/detection.rst +++ b/doc/source/detection/detection.rst @@ -1,107 +1,5 @@ -:orphan: - -.. _detection: - -Detection -######### -.. highlight:: ectosh - -.. contents:: - -Using the different trained objects, we can now detect them. - -Use -*** - -.. toggle_table:: - :arg1: Non-ROS - :arg2: ROS - -.. toggle:: Non-ROS - - Just run the detection.py script in /apps. This will run continuously on the input image/point cloud. - - .. code-block:: sh - - ./apps/detection -c detection.ork - - The server requires a configuration file through the ``-c`` option. - -.. toggle:: ROS - - If you want continuous detection, you can just run the detection script: - - .. code-block:: sh - - rosrun object_recognition_core detection -c `rospack find object_recognition_tod`/conf/detection.ros.ork - - Then again, there is also an actionlib server as detailed on :ref:`actionlib server `: - - .. code-block:: sh +.. Old page, kept to avoid breaking links - rosrun object_recognition_ros server -c `rospack find object_recognition_tod`/conf/detection.ros.ork - - This will start a server with a given configuration file. - If you want to test the server, just execute the client once: - - .. code-block:: sh - - rosrun object_recognition_ros client - - You can also use roslaunch if you want traditional actionlib support. There is a ``config_file`` argument - that can help you choose different pipelines: - - .. code-block:: sh - - roslaunch object_recognition_ros server.robot.launch - -A typical command line session might look like:: - - % apps/detection -c `rospack find object_recognition_tod`/conf/detection.ros.ork - [ INFO] [1317692023.717854617]: Initialized ros. node_name: /ecto_node_1317692023710501315 - Threadpool executing [unlimited] ticks in 5 threads. - [ INFO] [1317692024.254588151]: Subscribed to topic:/camera/rgb/camera_info with queue size of 0 - [ INFO] [1317692024.255467268]: Subscribed to topic:/camera/depth_registered/camera_info with queue size of 0 - [ INFO] [1317692024.256186358]: Subscribed to topic:/camera/depth_registered/image with queue size of 0 - [ INFO] [1317692024.256863212]: Subscribed to topic:/camera/rgb/image_color with queue size of 0 - model_id: e2449bdc43fd6d9dd646fcbcd012daaa - span: 0.433393 meters - 1 - ***Starting object: 0 - * starting RANSAC - added : 1 - added : 0 - * n inliers: 1824 - [-0.056509789, 0.99800211, 0.028263446; - 0.94346958, 0.062639669, -0.32548648; - -0.32660651, 0.0082725696, -0.94512439] - [-0.32655218; 0.03684178; 0.85040951] - ********************* found 1poses - [ INFO] [1317692117.187226953]: publishing to topic:/object_ids - [ INFO] [1317692117.188155476]: publishing to topic:/poses - - -Command Line Interface -********************** -.. program-output:: ../../../apps/detection --help - :in_srcdir: - -Configuration File -****************** - -The configuration file is where you define your graph and with the current ORK, you can choose any of the following sources: - -.. program-output:: python -c "from object_recognition_core.utils.doc import config_yaml_for_ecto_cells; print '\n'.join(config_yaml_for_ecto_cells('source'))" - :shell: - -any of the following sinks: - -.. program-output:: python -c "from object_recognition_core.utils.doc import config_yaml_for_ecto_cells; print '\n'.join(config_yaml_for_ecto_cells('sink'))" - :shell: - -or the following pipelines: - -.. program-output:: python -c "from object_recognition_core.utils.doc import config_yaml_for_ecto_cells; print '\n'.join(config_yaml_for_ecto_cells('detection_pipeline'))" - :shell: +:orphan: -More of any of those can be added by the user obviously +This document has moved, please see :ref:`Detection `. \ No newline at end of file diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst new file mode 100644 index 0000000..4723439 --- /dev/null +++ b/doc/source/getting_started.rst @@ -0,0 +1,343 @@ +.. _getting_started: + +================================================================================ +Getting Started with ORK +================================================================================ + +-------------------------------------------------------------------------------- +Introduction +-------------------------------------------------------------------------------- + +Welcome! This guide will help you get started with the Object Recognition +Kitchen. In this guide, you'll learn how to install and ORK packages to do a +very simple detection task: finding the pose of a can of soda on a flat surface. + +.. contents:: + +-------------------------------------------------------------------------------- +Overview +-------------------------------------------------------------------------------- +ORK has several different detectors available. One of the simplest is called +``tabletop``, and it can be used to detect objects regardless of textures, as +long as you have a mesh of the object. This is the best detector for our +tutorial, since you can use any soda can you have nearby to test the detector. +After you're done with this tutorial, you can explore other detectors and +see if they work better for what you're trying to accomplish. + +-------------------------------------------------------------------------------- +Requirements +-------------------------------------------------------------------------------- +Before starting, you should make sure that you have the following items: + +- A computer with Ubuntu 16.04 and ROS Kinetic installed (``ros-kinetic-desktop-full``) +- A depth camera. This tutorial includes guides for two types of cameras: + the Asus Xtion Pro/Pro Live and the Orbbec Astra. +- A can of soda (12 fl. oz./355 mL)--the object you'll be detecting. + The color (brand) is not important, as long as the can is not mostly black + (some depth cameras have a hard time detecting black objects). +- Flat area to perform detection. 0.5m x0.5m should be a large enough area. + +-------------------------------------------------------------------------------- +Step 1: Set up Workspace +-------------------------------------------------------------------------------- + +First, be sure to have your terminal set up to use ROS! You may have already +done this step as part of installation, but if you're not sure, it doesn't hurt +to do it again. + +.. code-block:: sh + + source /opt/ros/kinetic/setup.sh # source your ros distribution + +.. code-block:: sh + + cd ~ # go to your home directory + + mkdir -p ork_ws/src # create a new workspace folder + cd ork_ws/src # enter the workspace folder + catkin_init_workspace # initialize the workspace + +-------------------------------------------------------------------------------- +Step 2: Install ORK +-------------------------------------------------------------------------------- + +First, install some required dependencies. You may already have some or all of +these packages on your system. + +.. code-block:: sh + + sudo apt install git libopenni-dev ros-kinetic-ecto* \ + ros-kinetic-opencv-candidate ros-kinetic-moveit-core ros-kinetic-rviz \ + ros-kinetic-rqt-reconfigure + +The easiest way to install ORK is via the ``apt`` packages, such as +``ros-kinetic-object-recognition-core``. Unfortunately, not all of the packages +are available via ``apt install``, especially for newer ROS distros (including +kinetic). So, we will build the packages we need from source, which is why we +set up a new catkin workspace in the previous step. Run the following commands +in the ``ork_ws/src`` directory (if you're following the tutorial, you're +already there): + +.. code-block:: sh + + git clone http://github.com/wg-perception/object_recognition_core + git clone http://github.com/wg-perception/tabletop + git clone http://github.com/wg-perception/object_recognition_msgs + git clone http://github.com/wg-perception/object_recognition_ros + git clone http://github.com/wg-perception/object_recognition_ros_visualization + git clone http://github.com/wg-perception/ork_tutorials + + cd .. # go to workspace root + catkin_make # build everything (this will take a few minutes) + source devel/setup.bash # add the new packages to your ROS package path + +During this tutorial, you will be launching a lot of different terminals, and +many of them need to have ROS and/or ``ork_ws/devel/setup.bash`` sourced. +You will probably find it useful to add the ``source`` commands to your +``~/.bashrc`` file. + +-------------------------------------------------------------------------------- +Step 3: Install your camera +-------------------------------------------------------------------------------- + +Click the button below that corresponds to your camera type. + +.. toggle_table:: + :arg1: Asus Xtion + :arg2: Orbbec Astra + +.. toggle:: Asus Xtion + + .. code-block:: sh + + sudo apt install ros-kinetic-openni2-camera ros-kinetic-openni2-launch + +.. toggle:: Orbbec Astra + + .. code-block:: sh + + sudo apt install ros-kinetic-astra-camera ros-kinetic-astra-launch + + You also have to update your udev rules to allow access to the USB camera. + Follow the guide at http://wiki.ros.org/astra_camera. + +-------------------------------------------------------------------------------- +Step 4: Install the CouchDB Backend +-------------------------------------------------------------------------------- + +ORK needs a way to store objects that it knows how to detect. When you train +the system, objects will be added to this knowledge base. The default way to +store objects is with a database system called CouchDB. The details of how +CouchDB works are not important; you just have to install it. From a terminal, +run: + +.. code-block:: sh + + sudo apt install couchdb + +You can check that the database is running as expected by running this command: + +.. code-block:: sh + + curl -X GET http://localhost:5984 + # If CouchDB is working, you should get terminal output similar to the following: + # {"couchdb":"Welcome","version":"1.0.1"} + + +-------------------------------------------------------------------------------- +Step 5: Add an object to the database +-------------------------------------------------------------------------------- + +Congratulations, you are done with installation! Now you can add an object +to the CouchDB database for later detection. You'll be using a model of a soda +can, which is included in the ``ork_tutorials`` repository. + +First, download the soda can model: + +.. code-block:: sh + + wget https://github.com/wg-perception/ork_tutorials/raw/master/data/coke.stl + +Then, add the model to the database (your terminal needs to have ROS and +your new ``ork_ws/devel/setup.bash`` sourced): + +.. code-block:: sh + + rosrun object_recognition_core object_add.py -n "soda_can" -d "A can of soda" + rosrun object_recognition_core mesh_add.py coke.stl + +-------------------------------------------------------------------------------- +Step 6: Set up your ORK configuration file +-------------------------------------------------------------------------------- + +ORK uses configuration files, which usually have the extension ``.ork``, to +create *sources*, *sinks*, and *pipelines*. Roughly speaking, sources create +data, sinks accept data, and pipelines define how data flows from sources to +sinks. + +For this tutorial, you don't have to concern yourself with the details of +``.ork`` files. Instead, you can download pre-written ones that are already set +up for your camera. + +The configuration file we'll use is located at +``ork_ws/src/ork_tutorials/conf/gettingstarted.ork``. + +-------------------------------------------------------------------------------- +Step 7: Run detection +-------------------------------------------------------------------------------- + +Click the button below that corresponds to your camera type. + +.. toggle_table:: + :arg1: Asus Xtion + :arg2: Orbbec Astra + +First, launch the camera driver to generate depth clouds and publish them to +ROS topics. Make sure your camera is plugged in. Then, from a terminal, +with ROS sourced, run + +.. toggle:: Asus Xtion + + .. code-block:: sh + + roslaunch openni2_launch openni2.launch + +.. toggle:: Orbbec Astra + + .. code-block:: sh + + roslaunch astra_launch astra.launch + +Next, you need to enable *registration*. This will align the color and depth +images coming from the camera, which greatly increases recognition accuracy. To +enable registration, use the ``rqt_reconfigure`` program by running the +following command **in a new terminal** (do not close the terminal running the +camera driver from above): + +.. code-block:: sh + + rosrun rqt_reconfigure rqt_reconfigure + +The ``rqt_reconfigure`` window should pop up. Using the panel on the left, +drill down to ``camera/driver``. In the right panel, check the box for +``depth_registration``. Once the box is checked, you can safely close +rqt_reconfigure (and the terminal you used to launch it). + +.. image:: img/getting_started/depth_registration_box.png + :alt: Screenshot of the rqt_reconfigure interface, showing the + depth_registration checkbox + :align: center + +Now you can run the actual detector. In a terminal, with ROS and ``ork_ws`` +sourced, run + +.. code-block:: sh + + rosrun object_recognition_core detection -c `rospack find object_recognition_tutorials`/conf/gettingstarted.ork + +-------------------------------------------------------------------------------- +Step 8: View detection results +-------------------------------------------------------------------------------- + +If all is going smoothly, you are now detecting objects using your camera! But, +you have no way to tell if it's actually working or not. You can view the output +on the terminal (ROS and ``ork_ws`` must be sourced) by running + +``rostopic echo recognized_object_array``. + +You can also use RViz to visualize what's happening. + +- Set your RViz Fixed Frame to ``camera_link``. +- Use the Add button to add three Displays: a DepthCloud, an ORKTable, and an + ORKObject + + .. image:: img/getting_started/ros_views.png + :alt: Screenshot of the Add Display panel in RViz, showing the ORK + Displays. + :align: center + +- On the DepthCloud, set the Depth Map Topic to ``/camera/depth/image_rect``, + and set the Color Image Topic to ``/camera/rgb/image_rect_color``. You + should see the depth camera's colored points in the RViz window. + + .. image:: img/getting_started/depth_camera_topics.png + :alt: Screenshot of the DepthCloud Display in RViz, with the correct + topic names highlighted. + :align: center + + .. image:: img/getting_started/point_cloud.png + :alt: Screenshot of the RViz, showing a point cloud of the soda can. + :align: center +- On the ORKObject, set the topic to ``/recognized_object_array``. +- On the ORKTable, set the topic to ``/table_array``. + + .. image:: img/getting_started/ork_topics.png + :alt: Screenshot of the ORK Displays in RViz, with the correct + topic names highlighted. + :align: center + +You should now be able to view the detected soda can! Try moving it around the +flat area. The detected planar surfaces are also shown, outlined in cyan. The +cyan arrows point in the direction of the estimated surface normal of the flat +plane (or "table"). + +.. image:: img/getting_started/detection.png + :alt: Successful detection of a soda can, as seen in RViz. + :align: center + + +================================================================================ +Troubleshooting +================================================================================ + +**Problem:** (ROS only) ``tabletop`` complains about the 3D inputs or seems to +wait for a ROS topic forever. + +**Solution:** It may be because ``tabletop`` is not listening to the topics that +the 3D camera is publishing. Just open the ``.ork`` configuration file you +supplied in the detection command (if you are following the tutorial, then +it is ``ork_tutorials/conf/gettingstarted.ork``). Check if the camera data +topics are the same as what are published by the 3D camera (you can check with +``rostopic list`` or similar commands). If the configuration file does not match +the published camera topics, you will need to modify them in the configuration +file so they match. + +**Problem:** When running the tabletop detection command, you get the following +error message:: + + /usr/include/boost/smart_ptr/shared_ptr.hpp:412: + boost::shared_ptr::reference boost::shared_ptr::operator*() const + [with T = xn::NodeInfo, boost::shared_ptr::reference = xn::NodeInfo&]: Assertion `px != 0' failed + +**Solution:** This means that tabletop is receiving no messages from one (or +several) ROS topics that it subscribes as input. When you run into this +exception, please verify if those ROS topics is publishing messages as +expected (try 'rostopic echo ), and then relaunch your +tabletop pipeline. + +================================================================================ +Where to Go Next +================================================================================ + +Congratulations, you've learned the basics of ORK! Here are some suggestions for +next steps you can take. + +- You can try training and detecting other objects. Note that the ``tabletop`` + detector used in this tutorial can only detect objects that are axisymmetric. + So you could detect a bottle, but not a box. For non-axisymmetric objects, + you'll have to use a different detector. The ``tabletop`` detector also can't + detect the object when it's lying on its side. +- For discussion, or if you are having trouble with the tutorials, check out the + `Google Group `_. +- Bug reports should be posted as an issue on the appropriate GitHub repository. +- Check out the :ref:`Tutorials ` + page for specific details on how to run a few other detectors. +- Try downloading and running other detectors, such as the Textured Object + Detector (TOD). These other detectors might have more complex training steps + required, or other setup steps. Some of the detectors have tutorials, but for + the others, the best way to get going is to download the code from + `GitHub `_ and inspect the source + code and ``.ork`` files. +- You can run ORK without ROS, but the steps to install and run are pretty + different. This is also not a very common use case. Details are on the + :ref:`Installation ` page. \ No newline at end of file diff --git a/doc/source/img/getting_started/depth_camera_topics.png b/doc/source/img/getting_started/depth_camera_topics.png new file mode 100644 index 0000000..f20e2fe Binary files /dev/null and b/doc/source/img/getting_started/depth_camera_topics.png differ diff --git a/doc/source/img/getting_started/depth_registration_box.png b/doc/source/img/getting_started/depth_registration_box.png new file mode 100644 index 0000000..9772b8f Binary files /dev/null and b/doc/source/img/getting_started/depth_registration_box.png differ diff --git a/doc/source/img/getting_started/detection.png b/doc/source/img/getting_started/detection.png new file mode 100644 index 0000000..dee5380 Binary files /dev/null and b/doc/source/img/getting_started/detection.png differ diff --git a/doc/source/img/getting_started/ork_topics.png b/doc/source/img/getting_started/ork_topics.png new file mode 100644 index 0000000..6b15ae2 Binary files /dev/null and b/doc/source/img/getting_started/ork_topics.png differ diff --git a/doc/source/img/getting_started/point_cloud.png b/doc/source/img/getting_started/point_cloud.png new file mode 100644 index 0000000..4cceb4b Binary files /dev/null and b/doc/source/img/getting_started/point_cloud.png differ diff --git a/doc/source/img/getting_started/ros_views.png b/doc/source/img/getting_started/ros_views.png new file mode 100644 index 0000000..7059c3b Binary files /dev/null and b/doc/source/img/getting_started/ros_views.png differ diff --git a/doc/source/art/or.svg b/doc/source/img/or.svg similarity index 100% rename from doc/source/art/or.svg rename to doc/source/img/or.svg diff --git a/doc/source/index.rst b/doc/source/index.rst index 4604e54..42e5679 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,76 +1,109 @@ .. _index: +################################################################################ Object Recognition Kitchen -########################## - -.. highlight:: ectosh - -The Object Recognition Kitchen (``ORK``) is a project started at Willow Garage for object recognition. - -There is currently no unique method to perform object recognition. Objects can be textured, non textured, transparent, articulated, etc. For this reason, the Object Recognition Kitchen was designed to easily develop and run simultaneously several object recognition techniques. In short, ORK takes care of all the non-vision aspects of the problem for you (database management, inputs/outputs handling, robot/ROS integration ...) and eases reuse of code. - -``ORK`` is built on top of `ecto `_ which is a lightweight hybrid C++/Python framework for organizing computations as directed acyclic graphs. - -.. rubric:: Install - -Well, all good things must start so check out the :ref:`Install `. - -.. rubric:: Quickguide - -We know you can't wait; if you don't care about the intricacies and want to have a quick overview, follow the :ref:`Quick Guide ` - -.. rubric:: Tutorials - -Ok, now that you know a little, you can follow the :ref:`Tutorials `. - -.. rubric:: General Usage - -Now that you have a bit more time, we suggest you read about the :ref:`Infrastructure ` to understand how to interact with ``ORK``. You can then go through the different steps of object recognition: - - * :ref:`Data Capture ` ... - * ... from which you can perform :ref:`Training ` of object models ... - * ... that you can then use for :ref:`Detection ` - -.. rubric:: ROS integration - -The recognition kitchen was built in a ROS agnostic way, but ROS components were also developed for integration with the ROS ecosystem (e.g. publishers, subscribers, actionlib server, RViz plugin ...). For more info, check out the :ref:`ROS Integration `. - -.. rubric:: Recognition Pipelines - -Several object recognition pipelines have been implemented for this framework. Their documentation is work in progress :) : - -+----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ -| Techniques | 2D/3D | Types of object | Limitations | -+==============================================+==============+==============================+==============================================================+ -| :ref:`LINE-MOD ` | 2D and/or 3D | * rigid, Lambertian | * does not work with partial occlusions | -+----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ -| :ref:`tabletop ` | 3D | * rigid, Lambertian | * scales linearly with the number of objects | -| | | * rotationally symmetric | * the object is assumed to be on a table with no 3d rotation | -| | | * also finds planar surfaces | | -+----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ -| :ref:`TOD ` | 2D and 3D | * rigid, Lambertian | | -| | | * textured | | -+----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ -| :ref:`transparent objects | 2D and 3D | * rigid and transparent | * Training has to be done on a painted version of the object | -| ` | | | | -+----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ - -.. rubric:: Tools - -There are several tools that are used by some of the pipeline and you might need them for your own work or pipelines: - - * :ref:`Reconstruction ` - -Developers' corner -################## - -You like ``ORK`` ? Well you can add any pipeline or database to it. It is fairly simple and modular, just follow the :ref:`Developer Guide ` - -Contacts -######## - -For bug reports and comments, please use the `GitHub infrastructure `_ or -join us on the `Google Group `_. +################################################################################ + + +-------------------------------------------------------------------------------- +Notice: Documentation Update in Progress +-------------------------------------------------------------------------------- + +Hello ORK Users! The documentation is in the process of being updated and +upgraded. Information may have moved since the last time you visited. + +If you can't find something, please raise an issue on +`GitHub `_. Thanks! + +-------------------------------------------------------------------------------- +Overview +-------------------------------------------------------------------------------- + +The Object Recognition Kitchen (``ORK``) is a set of tools for object +recognition from camera data. The project was originally started at Willow +Garage, and although it is now a bit old, it still can prove useful for basic +object detection. + +Even in the most cutting-edge research papers, there is not one canonical "best" +way to perform object recognition. Objects can be textured, non-textured, +transparent, articulated, etc., and different approaches work best for each type +of object. For this reason, ORK was designed to run several object recognition +techniques simultaneously, each designed to detect a different type of object. + +When using/developing a new method you created or found, you usually have +to recreate the following functionality: + +- A way to store/query/use your training data +- A way to store/query/use your models +- An easy to train your objects +- Where your data is coming from (cameras, ROS rosbag, ROS topics) +- Where your data is going to +- ROS integration, by listening and publishing to the right topics +- The ability to compare detectors, by having several running at once + +``ORK`` takes care of this "plumbing" by providing base classes and a flexible +infrastructure, so you can work on the fun part: the detection algorithms. + +``ORK`` is built on top of `ecto `_, +which is a lightweight hybrid C++/Python framework for organizing computations +as directed acyclic graphs. It can be installed in several different ways: from +source or from ``apt`` packages, and either with ROS support or without. + +-------------------------------------------------------------------------------- +Getting Started +-------------------------------------------------------------------------------- + +- :ref:`Getting Started Guide ` -- This tutorial will guide you + through basic installation, training, and detection. + +-------------------------------------------------------------------------------- +Reference Documentation +-------------------------------------------------------------------------------- + +- :ref:`Installation ` + -- detailed instructions (beyond those in the Getting Started Guide) + on the different ways to install ORK. +- :ref:`Configuration Files ` + -- How to use ``ORK`` configuration files +- :ref:`Data Capture ` + -- How to capture training data from real-world objects +- :ref:`Training ` + -- Building recognition models from captured data +- :ref:`Detection ` + -- Detecting objects using recognition models +- :ref:`Pipelines ` + -- Different types of detectors in ORK +- :ref:`Pipeline tutorials ` + -- Tutorials on using different detectors +- :ref:`Databases ` + -- Information on database backends, for storing recognition models +- :ref:`ROS Integration ` + -- Details on ``ORK``'s integration with ROS +- :ref:`Reconstruction Tool ` + -- An ``ORK`` tool for reconstructing 3D models from several images + +-------------------------------------------------------------------------------- +Developers' Guide +-------------------------------------------------------------------------------- + +ORK is designed to be modular, to allow developers to extend it and replace +components. For example, you can use a different database backend to store +a list of recognition objects, or write your own detector. + +For more details, please read the :ref:`Developer Guide `. + +################################################################################ +Contact +################################################################################ + +For bug reports, issues, and to contribute, please use the appropriate +repository page on `GitHub `. For discussion +and troubleshooting, please visit the +`Google Group `_. + +-------------------------------------------------------------------------------- +BibTeX Citation +-------------------------------------------------------------------------------- If you want to cite this work, please use the BibTeX reference: @@ -79,5 +112,6 @@ If you want to cite this work, please use the BibTeX reference: @misc{ork_ros, Author = {Willow Garage, ROS community}, Title = "{ORK}: {O}bject {R}ecognition {K}itchen}, - howpublished = {\url{https://github.com/wg-perception/object_recognition_core}} - } + howpublished = + {\url{https://github.com/wg-perception/object_recognition_core}} + } \ No newline at end of file diff --git a/doc/source/index_developer.rst b/doc/source/index_developer.rst index de9274c..d323ff7 100644 --- a/doc/source/index_developer.rst +++ b/doc/source/index_developer.rst @@ -1,12 +1,14 @@ -:orphan: - .. _ork_developer: +:orphan: + object_recognition_core for developers ###################################### -Adding a pipeline to ``ORK`` is done by wrapping code and is usually only around 200/300 lines of Python/C++ but please -read the :ref:`Infrastructure ` docs first so that you know what a user will expect from you. +Adding a pipeline to ``ORK`` is done by wrapping code and is usually around +200/300 lines of Python/C++. You should read the reference documentation (see +the :ref:`docs homepage `) first, so that you know what is expected +of your pipeline. API *** diff --git a/doc/source/infrastructure/configuration.rst b/doc/source/infrastructure/configuration.rst index b5d32e9..824844b 100644 --- a/doc/source/infrastructure/configuration.rst +++ b/doc/source/infrastructure/configuration.rst @@ -1,45 +1,5 @@ -.. _configuration: +.. Old page, retained to avoid breaking links -Configuration File -################## +:orphan: -``ORK`` contains several scripts but two steps (obviously) require heavy configuration: those are -:ref:`Training ` and :ref:`Detection `. Those two steps are very flexible and can use several -inputs/outputs or any pipeline defined on the :ref:`Main Page `. - -Those are configured through a config file passed as an argument. For both cases, the file defines one or several -`ecto `_ cells that are connected together and executed in a pipeline. Each cell is -defined as follows: - -.. code-block:: yaml - - cell_name: - type: class_of_the_ecto_cell - module: Python_module_where_the_class_is - inputs: ['other_cell_name_1', 'other_cell_name_2'] (Optional) - outputs: ['other_cell_name_3', 'other_cell_name_4'] (Optional) - parameters: (Optional) - any_valid_JSON - -An example of a pipeline could therefore be: - - -.. code-block:: yaml - - cell1: - type: class1 - module: module1 - outputs: [cell2] - parameters: - parameter1: value1 - - cell2: - type: class2 - module: module2 - inputs: [cell1] (Optional: actually does not need to be as it's defined for cell1) - -The second cell could also have parameters. - -Once those relationships are defined, the cells can be properly initialized, linked and executed altogether. That might -seems like sparse information but it really is that simple. The easiest is to look at the different configuration files -for the different pipelines. +This document has moved, please see :ref:`Configuration `_. \ No newline at end of file diff --git a/doc/source/infrastructure/couch.rst b/doc/source/infrastructure/couch.rst index 190f0cf..e557be1 100644 --- a/doc/source/infrastructure/couch.rst +++ b/doc/source/infrastructure/couch.rst @@ -1,113 +1,7 @@ -Database -######## -.. _couchdb: http://couchdb.apache.org +.. Old page, retained to avoid breaking links -.. _object_recognition_core_db: - -Implementations -*************** - -Several DB implementations are provided by default. They accept the following parameters: - -CouchDb: - -.. program-output:: python -c "import object_recognition_core.boost.interface as db; print db.ObjectDb(db.ObjectDbParameters({'type':'CouchDB'})).parameters().raw" - -Filesystem: - -.. program-output:: python -c "import object_recognition_core.boost.interface as db; print db.ObjectDb(db.ObjectDbParameters({'type':'filesystem'})).parameters().raw" - -Empty (only for testing): - -.. program-output:: python -c "import object_recognition_core.boost.interface as db; print db.ObjectDb(db.ObjectDbParameters({'type':'empty'})).parameters().raw" - -Any custom implementation will have the "noncore" type. - -Couch Db -******** -We are using `couchdb`_ as our main database and it is the most tested implementation. To set up your local instance, all you must do is install couchdb, and ensure that the service has started. - -.. highlight:: ectosh - -The following should download and start the couch on Ubuntu like distros: - -.. code-block:: sh - - sudo apt-get install couchdb - - -To test that it is working properly: - -.. code-block:: sh - - curl -X GET http://localhost:5984 - % {"couchdb":"Welcome","version":"1.0.1"} - -The couchdb version should be greater than ``0.10.0``. - -Configuration -============= -If you would like to expose your couchdb instance to a different port, or bind to a different interface, besides the loopback, edit ``/etc/couchdb/local.ini``. - -For instance, changing the bind_address to ``0.0.0.0`` will allow your couchdb to be accessed on any interface. +:orphan: -:: - - [httpd] port = 5984 bind_address = 0.0.0.0 - -After editing this file, restart the couchdb service: - -.. code-block:: sh - - sudo service couchdb restart - -Web UI -====== - -We have a set of webpages that may be pushed to your couchdb instance that help browse the objects that you train, or models created. - -First make sure you have ``couchapp``: - -.. code-block:: sh - - sudo pip install -U couchapp - - -.. toggle_table:: - :arg1: From Source - :arg2: From ROS packages - -.. toggle:: From Source - - There is a make target for installing the web ui for your convenience.: - - .. code-block:: sh - - make or_web_ui - - This will push the app to the location specified in the Cmake cache, by the variable, ``OR_WEB_UI_LOCATION``. Use - ccache or cmake-gui to point it to a different location if you like. - - You can manually push it also, if you need more flexibility, or hate the cmake cache. cd to the - ``object_recognition/web_ui`` directory and run couchapp in a manner similar to the following.: - - .. code-block:: sh - - couchapp push . http://localhost:5984/or_web_ui - -.. toggle:: From ROS packages - - We provide a utility that automatically installs the visualizer on the DB. - - .. code-block:: bash - - rosrun object_recognition_core push.sh - -This will upload the contents of the directory to collection in your couchdb instance, called ``or_web_ui``. After this you can browse the web ui using the url http://localhost:5984/or_web_ui/_design/viewer/index.html - -Library -======= - -Object Recognition tools manipulate the database either using libCURL or python-couchdb. You may find it helpful to browse the default db HTML interface at http://localhost:5984/_utils +.. _object_recognition_core_db: -We also provide scripts located for maintenance located in the db_scripts folder. +This document has moved, please see :ref:`Databases `. \ No newline at end of file diff --git a/doc/source/infrastructure/infrastructure.rst b/doc/source/infrastructure/infrastructure.rst index af1a8e2..0df967b 100644 --- a/doc/source/infrastructure/infrastructure.rst +++ b/doc/source/infrastructure/infrastructure.rst @@ -1,30 +1,8 @@ -:orphan: - -.. _infrastructure: - -ORK for users -############# +.. Old page, retained to avoid breaking links -object_recognition_core provides an infrastructure for easy development and usage of object recognition pipelines. When -using/developing a new method you created or found, you usually always have to recreate the following: - - * figure out a way to store/query/use your training data - * figure out a way to store/query/use your models - * an easy to train your objects - * deal with where your data is coming from (cameras, ROS rosbag, ROS topics) - * deal with where your data is going to - * integrate it with ROS by listening to the right topics and publishing something - * compare it to other pipelines by having several pipelines running at once - -``ORK`` takes care of all that (and more !) by providing base classes and a flexible infrastructure because let's face -it, you want to work on the juicy stuff: the pipeline itself. +:orphan: -If you are a user, the docs are right below. +.. _infrastructure:: -User Docs -######### -.. toctree:: - :maxdepth: 2 - - couch.rst - configuration.rst +This document has moved, please see the Reference section at +:ref:`ORK Home `. \ No newline at end of file diff --git a/doc/source/install.rst b/doc/source/install.rst index a8b8fca..569d060 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -1,178 +1,7 @@ +.. Old page, kept to avoid breaking links + :orphan: .. _install: -To use ORK, you will need a compiled ORK and couchDB (for object management). Following instructions in this page will help you to: - - Install ORK either from precompiled ROS packages or from source code - - Install couchDB and setup the database for ORK - - Compile the documentation so that you can consult it locally (useful when no internet connection is around) - -Installation -############ - -From the ROS repositories -************************* - -Install the ``ros-*-object-recognition-core`` package from the official ROS repositories and the different pipelines (packages starting with ``ros-*-object-recognition-``). - -Download & Build from Source -**************************** - -First, build your workspace: - -.. code-block:: sh - - mkdir -p ork/src && cd ork/src - - -.. toggle_table:: - :arg1: Non-ROS - :arg2: ROS - - -.. toggle:: Non-ROS - - If you want to install from source without ROS, you need to have common dependencies (OpenCV, PCL) on your path. You also need to execute the following: - - - .. code-block:: bash - - git clone http://github.com/ros/catkin.git - ln -s catkin/cmake/toplevel.cmake CMakeLists.txt - cd ../ && git clone http://github.com/ros-infrastructure/catkin_pkg.git - export PYTHONPATH=`pwd`/catkin_pkg/src:$PYTHONPATH - cd src - - - ``catkin`` is a set of CMake macros that simplify build and maintenance. - - Then install the ``ecto`` modules: - - .. code-block:: sh - - git clone http://github.com/plasmodic/ecto - git clone http://github.com/plasmodic/ecto_image_pipeline - git clone http://github.com/plasmodic/ecto_openni - git clone http://github.com/plasmodic/ecto_opencv - git clone http://github.com/plasmodic/ecto_pcl - git clone http://github.com/plasmodic/ecto_ros - git clone http://github.com/wg-perception/opencv_candidate - - -.. toggle:: ROS - - First source your ROS setup file (adapt ``DISTRO`` to the ROS distribution you are using): - - .. code-block:: sh - - export DISTRO=indigo - sudo apt-get install libopenni-dev ros-${DISTRO}-catkin ros-${DISTRO}-ecto* ros-${DISTRO}-opencv-candidate ros-${DISTRO}-moveit-msgs - source /opt/ros/${DISTRO}/setup.sh - - -Then install any pipeline you need: - -.. code-block:: sh - - git clone http://github.com/wg-perception/object_recognition_core - git clone http://github.com/wg-perception/capture - git clone http://github.com/wg-perception/reconstruction - git clone http://github.com/wg-perception/linemod - git clone http://github.com/wg-perception/ork_renderer - git clone http://github.com/wg-perception/tabletop - git clone http://github.com/wg-perception/tod - git clone http://github.com/wg-perception/transparent_objects - -any ROS stuff: - -.. toggle_table:: - :arg1: Non-ROS - :arg3: ROS - -.. toggle:: Non-ROS - - Nothing for non-ROS. - - -.. toggle:: ROS - - .. code-block:: sh - - git clone http://github.com/wg-perception/object_recognition_msgs - git clone http://github.com/wg-perception/object_recognition_ros - git clone http://github.com/wg-perception/object_recognition_ros_visualization - - -and then build your code: - - -.. toggle_table:: - :arg1: Non-ROS - :arg2: ROS - - -.. toggle:: Non-ROS - - .. code-block:: sh - - cd ../ && mkdir build && cd build && cmake ../src && make - - -.. toggle:: ROS - - .. code-block:: sh - - cd ../ && catkin_make - - - -If you are a developer and have write access to the repositories, search and replace ``http://`` above and replace by ``git@github.com:``. - - -To maintain your code, each folder is each own ``git`` repository and you can pull/push from there. - -rosinstall file -*************** - -Under ROS, you can alternatively use that `rosinstall `_ file :download:`ork.rosinstall.indigo.jade` -on Indigo/Jade or :download:`ork.rosinstall.kinetic.plus` on Kinetic and above. - -To use on Kinetic, do the following: - -.. code-block:: bash - - mkdir ws && cd ws - wstool init src https://raw.github.com/wg-perception/object_recognition_core/master/doc/source/ork.rosinstall.kinetic.plus - cd src && wstool update -j8 - cd .. && rosdep install --from-paths src -i -y - catkin_make - source devel/setup.bash - -Configuring the database -######################## - -For that, just refer to the :ref:`DB Page `. - - -Building the documentation -########################## - -Before you can build the documentation (which you are reading right now), you need to have followed the installation instructions and have already successfully called ``make`` in the ``build`` folder. - -You then need some up to date packages: - -.. code-block:: sh - - sudo pip install -U breathe catkin-sphinx sphinxcontrib-programoutput - -From root, just type: - -.. code-block:: sh - - cd build - make doxygen - make sphinx-doc - -You will find the generated documentation under ``build/doc/html``. - -Once the documentation is built, you can simply copy it (except for the ``.doctree`` folder) to the ``gh-pages`` branch on GitHub. +This document has moved, please see :ref:`Installation `. \ No newline at end of file diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 0000000..624eebf --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,314 @@ +.. _installation: + +:orphan: + +################################################################################ +ORK Installation +################################################################################ + +-------------------------------------------------------------------------------- +Introduction +-------------------------------------------------------------------------------- + +This guide provides details on the various methods for installing ORK. A +complete ORK installation consists of several parts: + +- The dependencies +- The ORK core packages +- The ORK detector packages +- (if using ROS) the ORK ROS packages +- Camera drivers +- A database, for keeping track of objects trained into the detector +- (optional) compiled documentation (i.e., this web page) + +This guide goes step by step through the installation of each of these +components. Note that this guide assumes that if you are using ROS, it is +ROS Kinetic. Other versions of ROS should have a similar installation procedure, +but success is not guaranteed. + +.. contents:: + +-------------------------------------------------------------------------------- +0. Choose Installation Type +-------------------------------------------------------------------------------- + +The ROS version of ORK is more heavily used, and has much better supported +packages. Not using ROS will require you to install less packages, but it all +must be built from source. + +.. toggle_table:: + :arg1: ROS + :arg2: Without ROS + +-------------------------------------------------------------------------------- +1. ORK Dependencies +-------------------------------------------------------------------------------- + +The first step is to create a catkin workspace: + +.. code-block:: sh + + cd ~ # go to home directory + mkdir -p ork_ws/src # create a folder structure for the workspace + cd ork_ws/src # enter the source directory + +.. toggle:: ROS + + There are two ways to install dependencies for ORK: from source, or from + ``apt`` packages. Using ``apt`` packages is recommended for most users. + Building *dependencies* from source is not recommended a developer who is + also working on the dependency code. + + **Option 1: Use `apt` Packages** + + Run the following command: + + .. code-block:: sh + + sudo apt install git libopenni-dev ros-kinetic-ecto* ros-kinetic-opencv-candidate ros-kinetic-moveit-core + + **Option 2: Build from Source** + + If you choose this option, it is assumed that you know how to find + packages yourself, download them and any necessary dependencies, + and troubleshoot any problems while building them from source. + + Clone the following repositories: + + .. code-block:: sh + + git clone http://github.com/plasmodic/ecto + git clone http://github.com/plasmodic/ecto_image_pipeline + git clone http://github.com/plasmodic/ecto_openni + git clone http://github.com/plasmodic/ecto_opencv + git clone http://github.com/plasmodic/ecto_pcl + git clone http://github.com/plasmodic/ecto_ros + git clone http://github.com/wg-perception/opencv_candidate + + You will also need these additional packages, which you may already + have, or which you can get from source or ``apt``: + + .. code-block:: sh + + moveit_msgs (from https://github.com/ros-planning/moveit_msgs) + moveit_core (from https://github.com/ros-planning/moveit) + openni + + Once you have built and/or installed all of these dependencies, you + should be ready to move on. + +.. toggle:: Without ROS + + If you want to install from source without ROS, you need to have common + dependencies (OpenCV, PCL) installed and on your path. You also need to + execute the following: + + .. code-block:: sh + + git clone http://github.com/ros/catkin.git + ln -s catkin/cmake/toplevel.cmake CMakeLists.txt + cd ../ && git clone http://github.com/ros-infrastructure/catkin_pkg.git + export PYTHONPATH=`pwd`/catkin_pkg/src:$PYTHONPATH + cd src + + ``catkin`` is a set of CMake macros that simplify build and maintenance. + + Next, install ``ecto``: + + .. code-block:: sh + + git clone http://github.com/plasmodic/ecto + git clone http://github.com/plasmodic/ecto_image_pipeline + git clone http://github.com/plasmodic/ecto_openni + git clone http://github.com/plasmodic/ecto_opencv + git clone http://github.com/plasmodic/ecto_pcl + git clone http://github.com/plasmodic/ecto_ros + git clone http://github.com/wg-perception/opencv_candidate + +-------------------------------------------------------------------------------- +2. ORK Core and Detector +-------------------------------------------------------------------------------- + +.. toggle:: ROS + + Regardless of how you installed dependencies, the only way to install all ORK + packages is from source. Some ``apt`` packages exist linked to ros, including + ``ros-kinetic-object-recognition-core``, for example, but not all ORK + packages are up to date in this manner, and it's best to just use source for + everything. Instead of cloning individual repositories from github, you can + use the provided ``rosinstall`` file by running the following commands: + + .. code-block:: sh + + cd .. + wstool init src https://raw.github.com/wg-perception/object_recognition_core/master/doc/source/ork.rosinstall.kinetic.plus + cd src && wstool update -j8 + rosdep install --from-paths . -i -y + +.. toggle:: Without ROS + + Once you're in the ``ork_ws/src`` directory, clone code for the ORK core: + + .. code-block:: sh + + git clone http://github.com/wg-perception/object_recognition_core + + Then, clone any (or all) components that you're interested in using: + + .. code-block:: sh + + # Choose any + git clone http://github.com/wg-perception/capture + git clone http://github.com/wg-perception/reconstruction + git clone http://github.com/wg-perception/linemod + git clone http://github.com/wg-perception/ork_renderer + git clone http://github.com/wg-perception/tabletop + git clone http://github.com/wg-perception/tod + git clone http://github.com/wg-perception/transparent_objects + +-------------------------------------------------------------------------------- +3. ORK Packages for ROS +-------------------------------------------------------------------------------- + +.. toggle:: ROS + + Install some tools for visualization and editing the camera's configuration. + These tools are necessary if you want to do a detection procedure like the + one listed in the :ref:`Getting Started Guide ` or the + Tutorials. + + .. code-block:: sh + + sudo apt install ros-kinetic-rviz ros-kinetic-rqt-reconfigure + + Add the following repositories to your ``ork_ws/src`` directory as shown: + + .. code-block:: sh + + git clone http://github.com/wg-perception/object_recognition_msgs + git clone http://github.com/wg-perception/object_recognition_ros + git clone http://github.com/wg-perception/object_recognition_ros_visualization + +.. toggle:: Without ROS + + Skip this step. + +-------------------------------------------------------------------------------- +4. Build +-------------------------------------------------------------------------------- + +Now that you've collected all the source code, you can build: + + +.. toggle:: ROS + + .. code-block:: sh + + catkin_init_workspace + cd ../ + catkin_make + +.. toggle:: Without ROS + + .. code-block:: sh + + cd ../ + mkdir build + cd build + cmake ../src + make + +-------------------------------------------------------------------------------- +5. Camera Drivers +-------------------------------------------------------------------------------- + + +.. toggle:: ROS + + **ASUS Xtion, Microsoft Kinect 2** + + For the ASUS Xtion Pro or Microsoft Kinect 2, install openni2_camera and + openni2_launch: + + .. code-block:: sh + + sudo apt install ros-kinetic-openni2-camera ros-kinetic-openni2-launch + + + **Orbbec Astra** + + For the Orbbec Astra camera, install astra_camera and + astra_launch. You also have to update your udev rules to allow access to + the USB camera. Follow the guide at http://wiki.ros.org/astra_camera. + + .. code-block:: sh + + sudo apt install ros-kinetic-astra-camera ros-kinetic-astra-launch + +.. toggle:: Without ROS + + Install any device-specific drivers. + +-------------------------------------------------------------------------------- +6. Database Backend +-------------------------------------------------------------------------------- + +Several database backends are possible, as described on the +:ref:`Database reference`. + +More backend tutorials may be added here in the future, but for now, please +use CouchDB (the "default" choice). + +**CouchDB** + +Run the following command: + +.. code-block:: sh + + sudo apt install couchdb + +You can check that the database is running as expected by running this command: + +.. code-block:: sh + + curl -X GET http://localhost:5984 + # If CouchDB is working, you should get terminal output similar to the following: + # {"couchdb":"Welcome","version":"1.0.1"} + +-------------------------------------------------------------------------------- +7. (Optional) Compiling the Documentation +-------------------------------------------------------------------------------- + +Building the documentation requires several python packages, which you can +install using the ``pip`` package manager. If you plan on doing a lot of +work with Python on your machine, we highly recommend setting up a virtual +environment using ``virtualenv`` and ``virtualenvwrapper``. For more details, +please see +`this tutorial `_. +If you do not want to use a virtual environment, **do not** do a ``sudo pip +install`` to avoid permission errors. Instead, use ``pip install --user`` as +shown below. + +**Virtual Environment** + + With your virtual environment activated, run: + + .. code-block:: sh + + pip install -U breathe catkin-sphinx sphinxcontrib-programoutput + +**pip Local Packages** + + Run: + + .. code-block:: sh + + pip install -U --user breathe catkin-sphinx sphinxcontrib-programoutput + +From the root of your catkin workspace, run the following commands: + +.. code-block:: sh + + cd build + make doxygen + make sphinx-doc \ No newline at end of file diff --git a/doc/source/quickguide.rst b/doc/source/quickguide.rst index df54d84..9d2ddbc 100644 --- a/doc/source/quickguide.rst +++ b/doc/source/quickguide.rst @@ -1,204 +1,8 @@ -:orphan: +.. Old page, retained to avoid breaking links .. _quickguide: -Quick Guide -########### - -Instructions are slightly different on whether you use ROS or not. For ROS, instructions will work whether you build ``ROS`` from source or not. - -.. toggle_table:: - :arg1: From Source - :arg2: From ROS packages - -Install -******* - -Install ``ORK`` as detailed on the :ref:`Install ` page. - -If you want to visualize data in the database, you also need to run (be sure to have installed couchapp sudo pip install -U couchapp): - -.. toggle:: From Source - - .. code-block:: bash - - cd object_recognition_core/web_ui && ./push.sh - -.. toggle:: From ROS packages - - .. code-block:: bash - - rosrun object_recognition_core push.sh - -Setup Your Environment -********************** - -You need to setup your environment: - -.. toggle:: From Source - - .. code-block:: bash - - source devel/setup.sh - -.. toggle:: From ROS packages - - .. code-block:: bash - - source /opt/ros/DISTRO_NAME/setup.sh - -This will add all the necessary packages to your ``PATH``, ``LD_LIBRARY_PATH`` and ``PYTHONPATH``. - -.. toggle:: From ROS packages - - .. rubric:: Setup ROS - - Terminal 1: - - .. code-block:: sh - - roscore - - Terminal 2: - - .. code-block:: sh - - roslaunch openni_launch openni.launch - -Setup the capture workspace -*************************** - -First capture an ORB template of your capture workspace. It should be take from an planar frontal view, and the center of the image should be filled by the plane. Press 's' to save an image. The result will be placed in the directory given, e.g. my_textured_plane. Press 'q' to quit the template capture program. - -.. toggle:: From Source - - .. code-block:: sh - - ./object_recognition_capture/apps/orb_template -o my_textured_plane - -.. toggle:: From ROS packages - - Terminal 3: - - .. code-block:: sh - - rosrun object_recognition_capture orb_template -o my_textured_plane - - Try out tracking to see if you got a good template. Press 'q' to quit. - - .. code-block:: sh - - rosrun object_recognition_capture orb_track --track_directory my_textured_plane - - Uuse the SXGA (roughly 1 megapixel) mode of your openni device if possible. - - .. code-block:: sh - - rosrun dynamic_reconfigure dynparam set /camera/driver image_mode 1 - rosrun dynamic_reconfigure dynparam set /camera/driver depth_registration True - -Capture objects -*************** - -Once you are happy with the workspace tracking, its time to capure an object. Place an object at the origin of the workspace. An run the capture program in preview mode. Make sure the mask and pose are being picked up. - -.. toggle:: From Source - - .. code-block:: sh - - ./object_recognition_capture/apps/capture -i my_textured_plane --seg_z_min 0.01 -o silk.bag --preview - -.. toggle:: From ROS packages - - .. code-block:: sh - - rosrun object_recognition_capture capture -i my_textured_plane --seg_z_min 0.01 -o silk.bag --preview - -When satisified by the preview mode, run it for real. The following will capture a bag of 60 views where each view is normally distributed on the view sphere. The mask and pose displays should only refresh when a novel view is captured. The program will finish when 35 (-n) views are captured. Press 'q' to quit early. - -.. toggle:: From Source - - .. code-block:: sh - - ./object_recognition_capture/apps/capture -i my_textured_plane --seg_z_min 0.01 -o silk.bag - -.. toggle:: From ROS packages - - .. code-block:: sh - - rosrun object_recognition_capture capture -i my_textured_plane --seg_z_min 0.01 -o silk.bag - -Now time for upload. Make sure you install couch db on your machine. Give the object a name and useful tags seperated by a space, e.g. milk soy silk. - -.. toggle:: From Source - - .. code-block:: sh - - ./object_recognition_capture/apps/upload -i silk.bag -n 'Silk' milk soy silk --commit - -.. toggle:: From ROS packages - - .. code-block:: sh - - rosrun object_recognition_capture upload -i silk.bag -n 'Silk' milk soy silk --commit - -Train objects -************* - -Repeat the steps above for the objects you would like to recognize. Once you have captured and uploaded all of the data, it time to mesh and train object recognition. - -Meshing objects can be done in a batch mode as follows: - - -.. toggle:: From Source - - .. code-block:: sh - - ./object_recognition_reconstruction/apps/mesh_object --all --visualize --commit - -.. toggle:: From ROS packages - - .. code-block:: sh - - rosrun object_recognition_reconstruction mesh_object --all --visualize --commit - -The currently stored models are on http://localhost:5984/or_web_ui/_design/viewer/meshes.html - -Next objects should be trained. It may take some time between objects, this is normal. Also, this quickguide assumes that you are using :ref:`TOD ` which only works for textured objects. Please refer to the documentation of other methods. - -.. toggle:: From Source - - .. code-block:: sh - - ./object_recognition_core/apps/training \ - -c object_recognition_tod/conf/training.ork \ - --visualize - -.. toggle:: From ROS packages - - .. code-block:: sh - - rosrun object_recognition_core training \ - -c `rospack find object_recognition_tod`/conf/training.ork \ - --visualize - -Detect objects -************** - -Now we're ready for detection. First launch rviz, it should be subscribed to the right markers for recognition results. /markers is used for the results, and it is a marker array. - -.. toggle:: From Source - - .. code-block:: sh - - ./rosrun object_recognition_core/apps/detection \ - -c object_recognition_tod/conf/detection.ork \ - --visualize - -.. toggle:: From ROS packages - - .. code-block:: sh +:orphan: - rosrun object_recognition_core detection \ - -c `rospack find object_recognition_tod`/conf/detection.ros.ork \ - --visualize +This document has been updated and moved, please read the +:ref:`Getting Started Guide ` instead. \ No newline at end of file diff --git a/doc/source/reference/configuration.rst b/doc/source/reference/configuration.rst new file mode 100644 index 0000000..87d7c50 --- /dev/null +++ b/doc/source/reference/configuration.rst @@ -0,0 +1,47 @@ +.. _configuration: + +:orphan: + +Configuration File +################## + +``ORK`` contains several scripts but two steps (obviously) require heavy configuration: those are +:ref:`Training ` and :ref:`Detection `. Those two steps are very flexible and can use several +inputs/outputs or any pipeline defined on the :ref:`Main Page `. + +Those are configured through a config file passed as an argument. For both cases, the file defines one or several +`ecto `_ cells that are connected together and executed in a pipeline. Each cell is +defined as follows: + +.. code-block:: yaml + + cell_name: + type: class_of_the_ecto_cell + module: Python_module_where_the_class_is + inputs: ['other_cell_name_1', 'other_cell_name_2'] (Optional) + outputs: ['other_cell_name_3', 'other_cell_name_4'] (Optional) + parameters: (Optional) + any_valid_JSON + +An example of a pipeline could therefore be: + + +.. code-block:: yaml + + cell1: + type: class1 + module: module1 + outputs: [cell2] + parameters: + parameter1: value1 + + cell2: + type: class2 + module: module2 + inputs: [cell1] (Optional: actually does not need to be as it's defined for cell1) + +The second cell could also have parameters. + +Once those relationships are defined, the cells can be properly initialized, linked and executed altogether. That might +seems like sparse information but it really is that simple. The easiest is to look at the different configuration files +for the different pipelines. diff --git a/doc/source/reference/databases.rst b/doc/source/reference/databases.rst new file mode 100644 index 0000000..226e756 --- /dev/null +++ b/doc/source/reference/databases.rst @@ -0,0 +1,115 @@ +.. _databases: + +:orphan: + +Database +######## +.. _couchdb: http://couchdb.apache.org + +Implementations +*************** + +Several DB implementations are provided by default. They accept the following parameters: + +CouchDb: + +.. program-output:: python -c "import object_recognition_core.boost.interface as db; print db.ObjectDb(db.ObjectDbParameters({'type':'CouchDB'})).parameters().raw" + +Filesystem: + +.. program-output:: python -c "import object_recognition_core.boost.interface as db; print db.ObjectDb(db.ObjectDbParameters({'type':'filesystem'})).parameters().raw" + +Empty (only for testing): + +.. program-output:: python -c "import object_recognition_core.boost.interface as db; print db.ObjectDb(db.ObjectDbParameters({'type':'empty'})).parameters().raw" + +Any custom implementation will have the "noncore" type. + +Couch Db +******** +We are using `couchdb`_ as our main database and it is the most tested implementation. To set up your local instance, all you must do is install couchdb, and ensure that the service has started. + +.. highlight:: ectosh + +The following should download and start the couch on Ubuntu like distros: + +.. code-block:: sh + + sudo apt-get install couchdb + + +To test that it is working properly: + +.. code-block:: sh + + curl -X GET http://localhost:5984 + % {"couchdb":"Welcome","version":"1.0.1"} + +The couchdb version should be greater than ``0.10.0``. + +Configuration +============= +If you would like to expose your couchdb instance to a different port, or bind to a different interface, besides the loopback, edit ``/etc/couchdb/local.ini``. + +For instance, changing the bind_address to ``0.0.0.0`` will allow your couchdb to be accessed on any interface. + +:: + + [httpd] port = 5984 bind_address = 0.0.0.0 + +After editing this file, restart the couchdb service: + +.. code-block:: sh + + sudo service couchdb restart + +Web UI +====== + +We have a set of webpages that may be pushed to your couchdb instance that help browse the objects that you train, or models created. + +First make sure you have ``couchapp``: + +.. code-block:: sh + + sudo pip install -U couchapp + + +.. toggle_table:: + :arg1: From Source + :arg2: From ROS packages + +.. toggle:: From Source + + There is a make target for installing the web ui for your convenience.: + + .. code-block:: sh + + make or_web_ui + + This will push the app to the location specified in the Cmake cache, by the variable, ``OR_WEB_UI_LOCATION``. Use + ccache or cmake-gui to point it to a different location if you like. + + You can manually push it also, if you need more flexibility, or hate the cmake cache. cd to the + ``object_recognition/web_ui`` directory and run couchapp in a manner similar to the following.: + + .. code-block:: sh + + couchapp push . http://localhost:5984/or_web_ui + +.. toggle:: From ROS packages + + We provide a utility that automatically installs the visualizer on the DB. + + .. code-block:: bash + + rosrun object_recognition_core push.sh + +This will upload the contents of the directory to collection in your couchdb instance, called ``or_web_ui``. After this you can browse the web ui using the url http://localhost:5984/or_web_ui/_design/viewer/index.html + +Library +======= + +Object Recognition tools manipulate the database either using libCURL or python-couchdb. You may find it helpful to browse the default db HTML interface at http://localhost:5984/_utils + +We also provide scripts located for maintenance located in the db_scripts folder. diff --git a/doc/source/reference/detection.rst b/doc/source/reference/detection.rst new file mode 100644 index 0000000..c9bacfb --- /dev/null +++ b/doc/source/reference/detection.rst @@ -0,0 +1,105 @@ +.. _detection: + +:orphan: + +Detection +######### +.. highlight:: ectosh + +Using the different trained objects, we can now detect them. + +Use +*** + +.. toggle_table:: + :arg1: Non-ROS + :arg2: ROS + +.. toggle:: Non-ROS + + Just run the detection.py script in /apps. This will run continuously on the input image/point cloud. + + .. code-block:: sh + + ./apps/detection -c detection.ork + + The server requires a configuration file through the ``-c`` option. + +.. toggle:: ROS + + If you want continuous detection, you can just run the detection script: + + .. code-block:: sh + + rosrun object_recognition_core detection -c `rospack find object_recognition_tod`/conf/detection.ros.ork + + Then again, there is also an actionlib server as detailed on :ref:`actionlib server `: + + .. code-block:: sh + + rosrun object_recognition_ros server -c `rospack find object_recognition_tod`/conf/detection.ros.ork + + This will start a server with a given configuration file. + If you want to test the server, just execute the client once: + + .. code-block:: sh + + rosrun object_recognition_ros client + + You can also use roslaunch if you want traditional actionlib support. There is a ``config_file`` argument + that can help you choose different pipelines: + + .. code-block:: sh + + roslaunch object_recognition_ros server.robot.launch + +A typical command line session might look like:: + + % apps/detection -c `rospack find object_recognition_tod`/conf/detection.ros.ork + [ INFO] [1317692023.717854617]: Initialized ros. node_name: /ecto_node_1317692023710501315 + Threadpool executing [unlimited] ticks in 5 threads. + [ INFO] [1317692024.254588151]: Subscribed to topic:/camera/rgb/camera_info with queue size of 0 + [ INFO] [1317692024.255467268]: Subscribed to topic:/camera/depth_registered/camera_info with queue size of 0 + [ INFO] [1317692024.256186358]: Subscribed to topic:/camera/depth_registered/image with queue size of 0 + [ INFO] [1317692024.256863212]: Subscribed to topic:/camera/rgb/image_color with queue size of 0 + model_id: e2449bdc43fd6d9dd646fcbcd012daaa + span: 0.433393 meters + 1 + ***Starting object: 0 + * starting RANSAC + added : 1 + added : 0 + * n inliers: 1824 + [-0.056509789, 0.99800211, 0.028263446; + 0.94346958, 0.062639669, -0.32548648; + -0.32660651, 0.0082725696, -0.94512439] + [-0.32655218; 0.03684178; 0.85040951] + ********************* found 1poses + [ INFO] [1317692117.187226953]: publishing to topic:/object_ids + [ INFO] [1317692117.188155476]: publishing to topic:/poses + + +Command Line Interface +********************** +.. program-output:: ../../../apps/detection --help + :in_srcdir: + +Configuration File +****************** + +The configuration file is where you define your graph and with the current ORK, you can choose any of the following sources: + +.. program-output:: python -c "from object_recognition_core.utils.doc import config_yaml_for_ecto_cells; print '\n'.join(config_yaml_for_ecto_cells('source'))" + :shell: + +any of the following sinks: + +.. program-output:: python -c "from object_recognition_core.utils.doc import config_yaml_for_ecto_cells; print '\n'.join(config_yaml_for_ecto_cells('sink'))" + :shell: + +or the following pipelines: + +.. program-output:: python -c "from object_recognition_core.utils.doc import config_yaml_for_ecto_cells; print '\n'.join(config_yaml_for_ecto_cells('detection_pipeline'))" + :shell: + +More of any of those can be added by the user obviously diff --git a/doc/source/reference/pipelines.rst b/doc/source/reference/pipelines.rst new file mode 100644 index 0000000..0f2f25e --- /dev/null +++ b/doc/source/reference/pipelines.rst @@ -0,0 +1,26 @@ +.. _pipelines: + +:orphan: + +******************************************************************************** +Recognition Pipelines +******************************************************************************** + +Several object recognition pipelines have been implemented for this framework. +Their documentation is work in progress: + ++----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ +| Techniques | 2D/3D | Types of object | Limitations | ++==============================================+==============+==============================+==============================================================+ +| :ref:`LINE-MOD ` | 2D and/or 3D | * rigid, Lambertian | * does not work with partial occlusions | ++----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ +| :ref:`tabletop ` | 3D | * rigid, Lambertian | * scales linearly with the number of objects | +| | | * rotationally symmetric | * the object is assumed to be on a table with no 3d rotation | +| | | * also finds planar surfaces | | ++----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ +| :ref:`TOD ` | 2D and 3D | * rigid, Lambertian | | +| | | * textured | | ++----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ +| :ref:`transparent objects | 2D and 3D | * rigid and transparent | * Training has to be done on a painted version of the object | +| ` | | | | ++----------------------------------------------+--------------+------------------------------+--------------------------------------------------------------+ diff --git a/doc/source/training/training.rst b/doc/source/training/training.rst index f97f9d0..df0f786 100644 --- a/doc/source/training/training.rst +++ b/doc/source/training/training.rst @@ -1,51 +1,59 @@ -:orphan: - .. _training: +:orphan: + Training ######## .. highlight:: ectosh -.. contents:: - -Once some observations are stored in the database, models can be built from them. +Once some observations are stored in the database, models can be built from +them. You can store some observations in the database using the procedure +described in the :ref:`capture documentation `_. Config File *********** -Training, just like recognition, requires a configuration file but it usually only contains one cell that defines a -pipeline that reads data from the database and computes a model. Then again, nothing prevents you to train several -models at the same time by executing several pipelines. +Training, just like recognition, requires a +:ref:`configuration file `, but it usually only contains one cell +that defines a pipeline that reads data from the database and computes a model. +Then again, nothing prevents you to train several models at the same time by +executing several pipelines--but this would be an advanced use case! Use *** -.. toggle_table:: - :arg1: Non-ROS - :arg2: ROS +Training requires a configuration file, which is specified through the ``-c`` +option. You can choose whatever configuration file; a few are provided in +``object_recognition_server/conf``. -.. toggle:: Non-ROS +Some of the options in there can be overriden through the command line +for convenience. Change the following parameters to your needs: - Just run the training.py script in ``/apps``. It requires a configuration file through the ``-c`` option. Some of the - options in there can be overriden through the command line for convenience. Change the following parameters to your needs: - - * the ``object_ids`` should be the list of object ids you want to train on. If you want, you can also use object_names, - that are more human readable. object_ids is of the form ["6b3de86feee4e840280b4caad90003fb"] but there are two special - options: if it is "all", then all models are recomputed; if it is "missing", only the missing models are computed. +* the ``object_ids`` should be the list of object ids you want to train on. + If you want, you can also use object_names that are more human readable. + object_ids is of the form ["6b3de86feee4e840280b4caad90003fb"] but there + are two special options: if it is "all", then all models are recomputed; + if it is "missing", only the missing models are computed. +.. toggle_table:: + :arg1: ROS + :arg2: Without ROS .. toggle:: ROS - The training script can be run as follow: - + The training script can be run as follows: + .. code-block:: sh - - rosrun object_recognition_core training \ - -c `rospack find object_recognition_tod`/conf/training.ork \ - --visualize - You can choose whatever configuration file; a few are provided in ``object_recognition_server/conf``. + rosrun object_recognition_core training -c `rospack find object_recognition_tod`/conf/training.ork --visualize + +.. toggle:: Without ROS + + Run the training.py script in ``/apps``: + + .. code-block:: sh + ./object_recognition_core/apps/training -c object_recognition_tod/conf/training.ork --visualize A typical command line session might look like::