From cdc79c749eb2e4968e673e01f081e4999242d01e Mon Sep 17 00:00:00 2001
From: Markus Grotz <markus.grotz@kit.edu>
Date: Wed, 16 Nov 2022 10:27:35 +0100
Subject: [PATCH] update doc
---
docs/api.rst | 5 +---
docs/examples.rst | 59 +++++++++++++++++++++++++++++++++++--
docs/index.rst | 67 +-----------------------------------------
docs/users_guide.rst | 69 ++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 128 insertions(+), 72 deletions(-)
create mode 100644 docs/users_guide.rst
diff --git a/docs/api.rst b/docs/api.rst
index 168b576d..4966bfb9 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -1,8 +1,5 @@
API Reference
-==============
-
-If you are looking for information on a specific function.
-
+*************
API Reference for Robot Module
==============================
diff --git a/docs/examples.rst b/docs/examples.rst
index 303bdc5f..867dadff 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -2,10 +2,20 @@ Examples
========
+Example code snippets can be found in the [examples
+folder](https://git.h2t.iar.kit.edu/sw/armarx/python3-armarx/-/tree/master/examples)
+of the code repository.
+
+In the following,
+
+
Retrieving a proxy
------------------
+Retrieving a proxy of a running component is straightforward. Interface can be
+directly imported and proxy can be accessed using the `get_proxy` method.
+
.. highlight:: python
.. code-block:: python
@@ -19,13 +29,20 @@ Retrieving a proxy
Creating a proxy
----------------
+An instance of the class that inherits the interace has to be created first.
+Methods that are specified in the interface have to be implemented. In this
+case `generateRandomInt`. Result parameters have to match the return value as
+specified in the interface. The parameter `Ice::IceContext` is also passed to
+every method that are defined in the interface. Once an instance of the class
+is created it can be registered with `ice_manager.register_object` and a name
+of the proxy. Other components can then load the interface and access the
+component via the name of the proxy.
+
.. highlight:: python
.. code-block:: python
- #!/usr/bin/env python
-
import random
from armarx import RNGProviderComponentInterface
@@ -47,3 +64,41 @@ Creating a proxy
if __name__ == '__main__':
main()
+
+
+Processing images
+-----------------
+
+The module `armarx_vision.image_processor` provides a class to conveniently
+process images from armarx. Here the `process_images` method has to be
+implemented. The method has two parameters `images` and `info`. The former
+contains the images and the latter contains information about the images, e.g.
+the timestamp. The return value of the method is a tuple of result images and
+information about these.
+The approach is similar to :ref:`Creating a proxy`. Note that
+this method does not have an `Ice::IceContext` as it is not specified by a
+slice interface. The method `ImageProcessor.on_connect()` takes care of
+subscribing to the component that publishes the images, i.e.
+`visionx::ImageProviderInterface`. Additionally, a component is created
+internally that handles the result images.
+
+
+
+.. highlight:: python
+.. code-block:: python
+
+ from armarx_vision.image_processor import ImageProcessor
+
+
+
+ class TestImageProcessor(ImageProcessor):
+
+ def process_images(self, images, info):
+ info.timeProvided = 1633428148974550
+ result_image = np.random.random(images.shape) * 128
+ return result_image, info
+
+ image_processor = TestImageProcessor("ExampleImageProvider")
+ image_processor.on_connect()
+
+
diff --git a/docs/index.rst b/docs/index.rst
index 38ea356a..d8f839a3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,78 +1,13 @@
-from 🤖 import armarx as â¤
-**************************
-Welcome to armarx python binding's documentation. Grab the latest version with
-:ref:`Installation` and then get an overview with the :ref:`Quickstart`
-
.. toctree::
:maxdepth: 3
:caption: Contents:
- :ref:`Quickstart`
+ users_guide
installation
examples
api
-User's Guide
-============
-
-Checkout section :ref:`Quickstart` for a quick introduction. For more detailed
-instructions on the installation see section :ref:`Installation`. The ArmarX
-Python bindings share some configuration with the statecharts. Section
-:ref:`Configuration` gives more details. :ref:`Examples` lists some examples.
-
-
-Quickstart
-----------
-
-Grab the latest version with `poetry add armarx` or `pip install armarx`.
-
-To access a proxy via ice you can load the interface with the import keyword.
-For convenience, functions such as `get_proxy` are automatically injected with
-default parameters.
-
-.. highlight:: python
-.. code-block:: python
-
- from armax import PlatformNavigatorPrx
-
- platform_navigator = PlatformNavigatorPrx.get_proxy()
- platform_navigator.movePlatform(6000, -7300, 2.2)
-
-
-That's it. Happy coding.
-
-
-
-Robots module
--------------
-
-The `armarx_robots` module is an easy and convient way to control a robot.
-
-.. highlight:: python
-.. code-block:: python
-
- from armarx_robots import A6
-
- # we use the ARMAR-6 robot
- robot = A6()
- # use the text-to-speech system to say something
- robot.say('Hello World')
-
- # look at a specific target, i.e. in front of the robot
- from armarx import FramedPositionBase
- position = FramedPositionBase(0, 1000, 1650, frame='root', agent='Armar6'))
- robot.gaze.fixate(position)
-
- # close both hands
- robot.close_hand('both')
- robot.say('Here it is.')
-
- #execute the handover action.
- robot.handover()
-
-
-
Indices and tables
==================
diff --git a/docs/users_guide.rst b/docs/users_guide.rst
new file mode 100644
index 00000000..4e8eb10d
--- /dev/null
+++ b/docs/users_guide.rst
@@ -0,0 +1,69 @@
+from 🤖 import armarx as â¤
+**************************
+Welcome to armarx python binding's documentation. Grab the latest version with
+:ref:`Installation` and then get an overview with the :ref:`Quickstart`
+If you are looking for information on a specific function checkout the API :ref:`API Reference`.
+
+.. image:: _static/war-machine.jpg
+ :scale: 50 %
+ :alt: ArmarX Python bindings
+ :align: center
+
+
+User's Guide
+============
+
+Checkout section :ref:`Quickstart` for a quick introduction. For more detailed
+instructions on the installation see section :ref:`Installation`. The ArmarX
+Python bindings share some configuration with the statecharts. Section
+:ref:`Configuration` gives more details. :ref:`Examples` lists some examples.
+
+
+Quickstart
+----------
+
+Grab the latest version with `poetry add armarx` or `pip install armarx`.
+
+To access a proxy via ice you can load the interface with the import keyword.
+For convenience, functions such as `get_proxy` are automatically injected with
+default parameters.
+
+.. highlight:: python
+.. code-block:: python
+
+ from armax import PlatformNavigatorPrx
+
+ platform_navigator = PlatformNavigatorPrx.get_proxy()
+ platform_navigator.movePlatform(6000, -7300, 2.2)
+
+
+That's it. Happy coding.
+
+
+
+Robots module
+-------------
+
+The `armarx_robots` module is an easy and convient way to control a robot.
+
+.. highlight:: python
+.. code-block:: python
+
+ from armarx_robots import A6
+
+ # we use the ARMAR-6 robot
+ robot = A6()
+ # use the text-to-speech system to say something
+ robot.say('Hello World')
+
+ # look at a specific target, i.e. in front of the robot
+ from armarx import FramedPositionBase
+ position = FramedPositionBase(0, 1000, 1650, frame='root', agent='Armar6'))
+ robot.gaze.fixate(position)
+
+ # close both hands
+ robot.close_hand('both')
+ robot.say('Here it is.')
+
+ #execute the handover action.
+ robot.handover()
--
GitLab