diff --git a/docs/UML/robots.png b/docs/UML/robots.png new file mode 100644 index 0000000..de9dee4 Binary files /dev/null and b/docs/UML/robots.png differ diff --git a/docs/figures/baxter.png b/docs/figures/baxter.png new file mode 100644 index 0000000..e23a65d Binary files /dev/null and b/docs/figures/baxter.png differ diff --git a/docs/figures/bb8.png b/docs/figures/bb8.png new file mode 100644 index 0000000..e1abdc7 Binary files /dev/null and b/docs/figures/bb8.png differ diff --git a/docs/figures/cassie.png b/docs/figures/cassie.png new file mode 100644 index 0000000..e6a04fd Binary files /dev/null and b/docs/figures/cassie.png differ diff --git a/docs/figures/centauro.png b/docs/figures/centauro.png new file mode 100644 index 0000000..3f22058 Binary files /dev/null and b/docs/figures/centauro.png differ diff --git a/docs/figures/cogimon.png b/docs/figures/cogimon.png new file mode 100644 index 0000000..f31e785 Binary files /dev/null and b/docs/figures/cogimon.png differ diff --git a/docs/figures/coman.png b/docs/figures/coman.png new file mode 100644 index 0000000..2bebe28 Binary files /dev/null and b/docs/figures/coman.png differ diff --git a/docs/figures/crab.png b/docs/figures/crab.png new file mode 100644 index 0000000..7e98d4d Binary files /dev/null and b/docs/figures/crab.png differ diff --git a/docs/figures/cubli.png b/docs/figures/cubli.png new file mode 100644 index 0000000..56659d4 Binary files /dev/null and b/docs/figures/cubli.png differ diff --git a/docs/figures/fetch.png b/docs/figures/fetch.png new file mode 100644 index 0000000..d189311 Binary files /dev/null and b/docs/figures/fetch.png differ diff --git a/docs/figures/hyq2max.png b/docs/figures/hyq2max.png new file mode 100644 index 0000000..ea59be3 Binary files /dev/null and b/docs/figures/hyq2max.png differ diff --git a/docs/figures/phantomx.png b/docs/figures/phantomx.png new file mode 100644 index 0000000..83d4664 Binary files /dev/null and b/docs/figures/phantomx.png differ diff --git a/docs/figures/pleurobot.png b/docs/figures/pleurobot.png new file mode 100644 index 0000000..7868f27 Binary files /dev/null and b/docs/figures/pleurobot.png differ diff --git a/docs/figures/pyrobolearn.png b/docs/figures/pyrobolearn.png new file mode 100755 index 0000000..ab7ff34 Binary files /dev/null and b/docs/figures/pyrobolearn.png differ diff --git a/docs/figures/softhand.png b/docs/figures/softhand.png new file mode 100644 index 0000000..6109e04 Binary files /dev/null and b/docs/figures/softhand.png differ diff --git a/docs/figures/walkman.png b/docs/figures/walkman.png new file mode 100644 index 0000000..b24c46c Binary files /dev/null and b/docs/figures/walkman.png differ diff --git a/docs/figures/wam.png b/docs/figures/wam.png new file mode 100644 index 0000000..f6eddf3 Binary files /dev/null and b/docs/figures/wam.png differ diff --git a/docs/source/actions.rst b/docs/source/actions.rst index e69de29..d54f408 100644 --- a/docs/source/actions.rst +++ b/docs/source/actions.rst @@ -0,0 +1,18 @@ +Actions +======= + +In PRL, every concept is modelized as a class. This is also true for actions which are used by the policies. + + +How to use a particular action? +------------------------------ + +example of actions with robot + + +How to create your own action? +------------------------------ + + +FAQs +---- diff --git a/docs/source/algorithms.py b/docs/source/algorithms.py deleted file mode 100644 index e69de29..0000000 diff --git a/docs/source/algorithms.rst b/docs/source/algorithms.rst new file mode 100644 index 0000000..629ef83 --- /dev/null +++ b/docs/source/algorithms.rst @@ -0,0 +1,2 @@ +Algorithms +========== diff --git a/docs/source/approximators.rst b/docs/source/approximators.rst new file mode 100644 index 0000000..c52a075 --- /dev/null +++ b/docs/source/approximators.rst @@ -0,0 +1,13 @@ +Approximators +============= + +An ``Approximator`` accepts as inputs the ``State``, ``Action``, and learning ``Model``, and connects them. +Approximators are used by other classes in the PRL framework. + +How to use an approximator? +--------------------------- + + +How to create your own approximator? +------------------------------------ + diff --git a/docs/source/environments.rst b/docs/source/environments.rst index e69de29..baddf92 100644 --- a/docs/source/environments.rst +++ b/docs/source/environments.rst @@ -0,0 +1,33 @@ +Environments +============ + +- World +- States +- Actions +- Rewards + +Available environments include ... + + +How to use an environment? +-------------------------- + + +Design +------ + + +How to create my own environment? +--------------------------------- + + +What are the differences with the OpenAI gym's environments? +------------------------------------------------------------ + +To better depict the differences, let's consider an environment which contains a quadruped robot and the goal is that it learns to walk. Usually, as it can be seen on multiple repositories, people would inherit from the gym ``Env`` class and call it something similar to ``QuadrupedFlatTerrainWalkEnv(Env)``. Inside of ``step`` function, they would compute the next states and rewards. Now suppose, you would like to change ... + +In our framework, the ``world``, ``states``, and ``rewards`` are given to the PRL ``Env`` class. This means that if you would like to change the world, reward function, or states you can do it outside the function. + +- Actions + +Having said that, we tried to make PRL compatible with OpenAI gym at the exception that the returned state is not a array but a list of arrays. diff --git a/docs/source/faqs.rst b/docs/source/faqs.rst new file mode 100644 index 0000000..644f9f4 --- /dev/null +++ b/docs/source/faqs.rst @@ -0,0 +1,6 @@ +FAQs +==== + +* How to add a completely new component, for instance, a state estimator or navigation (SLAM) module? There are multiple steps: 1. you have to divide your code into submodules that are minimal, do not depend on various pieces of code. 2. Compositonality 3. Flexibility: if I want to change something how easy is it? + + diff --git a/docs/source/index.rst b/docs/source/index.rst index be750f3..c61d17a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,7 +8,7 @@ Welcome to PyRoboLearn's documentation! .. toctree:: :maxdepth: 2 - :caption: PyRoboLearn + :caption: Introduction readme @@ -18,6 +18,23 @@ Welcome to PyRoboLearn's documentation! installation +.. toctree:: + :maxdepth: 4 + :caption: PyRoboLearn + + pyrobolearn + simulators + worlds + robots + interfaces + states + actions + rewards + environments + models + approximators + algorithms + .. toctree:: :maxdepth: 2 :caption: Examples diff --git a/docs/source/interfaces.rst b/docs/source/interfaces.rst index 02c7fe0..6d4d714 100644 --- a/docs/source/interfaces.rst +++ b/docs/source/interfaces.rst @@ -1,38 +1,83 @@ Interfaces and Bridges ====================== -I/O interfaces. -Bridges. +**I/O interfaces** allows you to receive/send data from/to different devices. Interfaces are divided into 3 categories, ``InputInterface`` which can only receive data from a particular device and save it in memory, ``OutputInterface`` which can only send data given by PRL to the interface, and ``InputOutputInterface`` which allows you to receive and send data. Interfaces include for instance webcam, speaker, mouse, keyboard, game controller, and so on. -Available interfaces: -* camera: asus_xtion, webcam, kinect, openpose -* controllers: mouse+keyboard, spacemouse, playstation, xbox -* speech +To avoid a direct coupling with the interface and an element in PRL such as a robot, **bridges** are introduced. Bridges makes the connection between an interface and an element in PRL (like a robot, an object in the world, the world itself, the world camera, etc). For instance, you could have a game controller and when moving one of its joystick forward, you would like for a quadcopter to take off while for a wheeled robot to move forward instead. For both examples, the values returned by the joystick is the same but you would like to have different behaviors depending on the type of robots. It might be even the case that someone would like to map the game controller events in a different way that you did. This is exactly the raison d'être of such bridges; to map an interface with an element in PRL. Different bridges can be implemented for the same interface as the user sees fit. + +Available interfaces in PRL include: + +- camera: webcam, asus_xtion, kinect, openpose +- controllers: mouse+keyboard, spacemouse, playstation, xbox +- speech: recognizer, translator, and synthesizer +- VR: Oculus (through Windows) + +They are available in `pyrobolearn/tools/interfaces/ `_ folder while bridges are available in the `pyrobolearn/tools/bridges/ `_ folder. How to use an interface/bridge in PRL? -------------------------------------- +The following snippet show how to use the space mouse interface. -You can check for more examples in the [`examples/interfaces`](https://github.com/robotlearn/pyrobolearn/tree/master/examples/interfaces) folder. + + + +You can check for more examples in the `examples/interfaces `_ folder. How to create your own interface/bridge? ---------------------------------------- -Let's say that you have a new interface, for instance, a EMG sensor. +Let's say that you have a new interface, for instance, an EMG sensor that measures the electrical activity of muscles, and you would like based on the sensed values makes a robot behave in a certain way. For instance, you would like the robot to be more stiff (see teleimpedance for more info). + +- In order to create your interface, you will have to inherit one of the following interfaces: ``InputInterface``, ``OutputInterface``, ``InputOutputInterface`` based on the type of device you have. In our case, we have an EMG sensor which provides the sensed values as *inputs* to PRL, thus we will inherit from ``InputInterface``. + +.. code-block:: python + :linenos: + + # please add the word `Interface` at the end of your class so we can based on its name alone + # knows it is an interface. + class EMGInterface(InputInterface): + """ + Description + """ + + def __init__(self, use_thread=False, sleep_dt=0, verbose=False, *args, **kwargs): + # initialize your variables/attributes + ... + + # call at the end the parent constructor + super(EMGInterface, self).__init__(self, use_thread, sleep_dt, verbose) + + def run(self): + """main method to implement. This method is automatically called when using threads, and you + have to call it when you are not using threads.""" + # get the last sensed data and save it in one of the attributes of this class + ... + +- Now, let's create a bridge that connects the above interface with a manipulator robot. + +.. code-block:: python + :linenos: + + # please add the word `Interface` at the end of your class so we can based on its name alone + # knows it is an interface. + class EMGBridge(InputInterface): FAQs and Troubleshootings ------------------------- -* I have an `ImportError` with one of the interface, why? Some libraries have to be installed and configured manually. To ease the installation process, there is a docker file as well as bash scripts in the `pyrobolearn/scripts/` folder. +- I have an ``ImportError`` with one of the interface, why? Some libraries have to be installed and configured manually. To ease the installation process, there is a docker file as well as bash scripts in the `pyrobolearn/scripts/ `_ folder. Future works ------------ +* add an interface to get the values sensed by an android/Iphone smartphone (which might have an accelerometer, gyroscope, microphone, etc.) +* add HTC Vive interface * add a Facial Expression Recognition (FER) module * add Google assistant / Alexa * implement interfaces for haptic devices diff --git a/docs/source/models.py b/docs/source/models.py deleted file mode 100644 index e69de29..0000000 diff --git a/docs/source/models.rst b/docs/source/models.rst new file mode 100644 index 0000000..82166ea --- /dev/null +++ b/docs/source/models.rst @@ -0,0 +1,21 @@ +Models +====== + +Learning models. + +- DMP + +How to use a learning model? +---------------------------- + + +Design +------ + +Models are independent of the other elements in PRL, but are used by other elements in PRL. + + +How to create your own model? +----------------------------- + + diff --git a/docs/source/pyrobolearn.rst b/docs/source/pyrobolearn.rst index a52bdde..7612e67 100644 --- a/docs/source/pyrobolearn.rst +++ b/docs/source/pyrobolearn.rst @@ -1,13 +1,29 @@ PyRoboLearn =========== +PyRoboLearn is a Python framework in robot learning for education and research. PyRoboLearn is meant to be a free and open-source tool. + Goal ----- Problem formulation ------------------- +General idea. + +- lack of benchmarks +- lack of flexibility and modularity +- lack of generalization +- high coupling + +For instance: + +Full example. + + +Main idea of PyRoboLearn and solution to above problem. + + Hardware/Software requirements ------------------------------ diff --git a/docs/source/readme.rst b/docs/source/readme.rst index 7868920..c267a4d 100644 --- a/docs/source/readme.rst +++ b/docs/source/readme.rst @@ -1,7 +1,5 @@ -PyRoboLearn -=========== -.. include:: ../../README.md +.. include:: ../../README.rst Design Decisions ================ diff --git a/docs/source/rewards.rst b/docs/source/rewards.rst index e69de29..bd62a80 100644 --- a/docs/source/rewards.rst +++ b/docs/source/rewards.rst @@ -0,0 +1,18 @@ +Rewards +======= + +In PRL, every concept is modelized as a class. This is also true for rewards which are returned by the environment. + + +How to use a particular reward? +------------------------------- + +example of rewards + + +How to create your own reward? +------------------------------ + + +FAQs +---- diff --git a/docs/source/robots.rst b/docs/source/robots.rst index 4ae3ff2..f6f321a 100644 --- a/docs/source/robots.rst +++ b/docs/source/robots.rst @@ -9,6 +9,37 @@ More than 64 robots have been implemented in PRL and include various kind of rob GIF +.. image:: ../figures/coman.png + :width: 9% + :alt: coman +.. image:: ../figures/wam.png + :width: 9% + :alt: wam +.. image:: ../figures/fetch.png + :width: 9% + :alt: fetch +.. image:: ../figures/cassie.png + :width: 9% + :alt: cassie +.. image:: ../figures/hyq2max.png + :width: 9% + :alt: hyq2max +.. image:: ../figures/phantomx.png + :width: 9% + :alt: phantomx +.. image:: ../figures/pleurobot.png + :width: 9% + :alt: pleurobot +.. image:: ../figures/softhand.png + :width: 9% + :alt: softhand +.. image:: ../figures/centauro.png + :width: 9% + :alt: baxter +.. image:: ../figures/walkman.png + :width: 9% + :alt: walkman + Note that for few of them such as the ones that require the simulation of fluids such as quadcopters. The corresponding class implements the dynamical simulation. For such classes, as I did not spend too much time one it, some improvements might be needed for better realism. @@ -16,6 +47,7 @@ How to use a robot in PRL? -------------------------- .. code-block:: python + :linenos: from itertools import count import pyrobolearn as prl @@ -45,35 +77,35 @@ How to use a robot in PRL? world.step(sim.dt) -You can check for more examples in the [`examples/robots`](https://github.com/robotlearn/pyrobolearn/tree/master/examples/robots) folder. You can also check for [`examples/kinematics`](https://github.com/robotlearn/pyrobolearn/tree/master/examples/kinematics) and [`examples/dynamics`](https://github.com/robotlearn/pyrobolearn/tree/master/examples/dynamics). +You can check for more examples in the `examples/robots `_ folder. You can also check for `examples/kinematics `_ and `examples/dynamics `_. Design ------ -The most abstract class is the `Body` class which is described in `pyrobolearn/robots/base.py`. From it, you can already access to multiple functionalities/attributes, such as its position and orientation. It only depends on the simulator. +The most abstract class is the ``Body`` class which is described in `pyrobolearn/robots/base.py `_. From it, you can already access to multiple functionalities/attributes, such as its position and orientation. It only depends on the simulator. -Inheriting from one of its child classes is the most interesting (for our purpose) `Robot` class, described in `robot.py`. It is the parent class of several classes such as: +.. image:: ../UML/robots.png + :alt: UML diagram for Robot + :align: center -- `Manipulator` defined in `pyrobolearn/robots/manipulator.py` -- `LeggedRobot` defined in `pyrobolearn/robots/legged_robot.py` -- `WheeledRobot` defined in `pyrobolearn/robots/wheeled_robot.py` -- `Hand` defined in `pyrobolearn/robots/hand.py` +Inheriting from one of its child classes is the most interesting (for our purpose) ``Robot`` class, described in `robot.py `_. It is the parent class of several classes such as: + +- ``Manipulator`` defined in `manipulator.py `_ +- ``LeggedRobot`` defined in `legged_robot.py `_ +- ``WheeledRobot`` defined in `wheeled_robot.py `_ +- ``Hand`` defined in `hand.py `_ - etc. - -UML picture - - -Note that `Robot` only depends on the simulator interface, and is independent of other modules in PRL (at the exception of some utils method that are useful to perform some transformations). +Note that ``Robot`` only depends on the simulator interface (aggregation relationship), and is independent of other modules in PRL (at the exception of some util methods that are useful to perform some transformations). How to create your own robot? ----------------------------- -To illustrate how to create your own robot, let's assume you want to create a humanoid robot (biped and bi-manipulator) called `Asimov`. +To illustrate how to create your own robot, let's assume you want to create a humanoid robot (biped and bi-manipulator) called ``Asimov``. -1. First, you have to get (or create) its URDF file and the associated meshes. Let's put them in a directory called `asimov`, and move it in the `pyrobolearn/robots/urdfs/` folder where all the other URDFs are. +1. First, you have to get (or create) its URDF file and the associated meshes. Let's put them in a directory called ``asimov``, and move it in the ``pyrobolearn/robots/urdfs/`` folder where all the other URDFs are. 2. If you want to use it directly and to not create a specific class, you can just call: @@ -102,10 +134,11 @@ To illustrate how to create your own robot, let's assume you want to create a hu # perform a step in the world and pause for `sim.dt` world.step(sim.dt) -3. Instead of the second point, let's create a proper class `Asimov` that inherits from the `BipedRobot` and `BiManipulator` (and thus inherits their functionalities) in a Python file `asimov.py`: +3. Instead of the second point, let's create a proper class ``Asimov`` that inherits from the ``BipedRobot`` and ``BiManipulator`` (and thus inherits their functionalities) in a Python file ``asimov.py``: .. code-block:: python :linenos: + #!/usr/bin/env python """Short description about your robot @@ -168,7 +201,7 @@ To illustrate how to create your own robot, let's assume you want to create a hu ... -3. If you want to be able to load your robot from the world using its name (by calling `world.load_robot('asimov')`), add the Python file `asimov.py` in the `pyrobolearn/robots/` folder. The `__init__.py` inside that folder will automatically go through all the files and add the robots inside the `implemented_robots` list which is accessed by `World`. Note that you can also accessed to this list by calling `pyrobolearn.robots.implemented_robots`. If you also want to be able to call your robot using `from pyrobolearn.robots import Asimov`, you will have to add the line `from .asimov import Asimov` in the `pyrobolearn/robots/__init__.py`. +3. If you want to be able to load your robot from the world using its name (by calling ``world.load_robot('asimov')``), add the Python file ``asimov.py`` in the `pyrobolearn/robots/ `_ folder. The ``__init__.py`` inside that folder will automatically go through all the files and add the robots inside the ``implemented_robots`` list which is accessed by ``World``. Note that you can also accessed to this list by calling ``pyrobolearn.robots.implemented_robots``. If you also want to be able to call your robot using ``from pyrobolearn.robots import Asimov``, you will have to add the line ``from .asimov import Asimov`` in the `pyrobolearn/robots/__init__.py `_. 4. Now, you can call your robot in the framework. @@ -203,91 +236,93 @@ Sensors and Actuators FAQs and Troubleshootings ------------------------- -* The mass/inertia matrix of some links are not correct in the simulator, what should I do? - * If you use the Bullet simulator (which uses `pybullet`), you have to specify the mass and inertia matrix for each link. If a link doesn't have these attributes defined, pybullet automatically attribute a mass of 1kg and an identity inertia matrix (which is ridiculous huge). Normally, links without a mass and inertia matrices defined in a URDF file are dummy links that are used to represent a reference frame. To set a reasonable inertia matrix, please refer to ["Adding Physical and Collision Properties to a URDF Model"](http://wiki.ros.org/urdf/Tutorials/Adding%20Physical%20and%20Collision%20Properties%20to%20a%20URDF%20Model) and ["Inertial parameters of triangle meshes"](http://gazebosim.org/tutorials?tut=inertia&cat=build_robot). - * It is possible that some masses / inertia matrices have not been correctly set in the original URDF. I cleaned most of the URDF files but some links might have escaped my attention. Please open an issue on [Github](https://github.com/robotlearn/pyrobolearn), or check the 2 [links](http://wiki.ros.org/urdf/Tutorials/Adding%20Physical%20and%20Collision%20Properties%20to%20a%20URDF%20Model) [above](http://gazebosim.org/tutorials?tut=inertia&cat=build_robot) on how to set reasonable inertia values. +- The mass/inertia matrix of some links are not correct in the simulator, what should I do? + * If you use the Bullet simulator (which uses ``pybullet``), you have to specify the mass and inertia matrix for each link. If a link doesn't have these attributes defined, pybullet automatically attribute a mass of 1kg and an identity inertia matrix (which is ridiculous huge). Normally, links without a mass and inertia matrices defined in a URDF file are dummy links that are used to represent a reference frame. To set a reasonable inertia matrix, please refer to `"Adding Physical and Collision Properties to a URDF Model" `_ and `"Inertial parameters of triangle meshes" `_. + * It is possible that some masses / inertia matrices have not been correctly set in the original URDF. I cleaned most of the URDF files but some links might have escaped my attention. Please open an issue on `Github `_, or check the 2 `links `_ `above `_ on how to set reasonable inertia values. -* How to convert a xacro file to a URDF file? Type `rosrun xacro xacro --inorder path/to/.urdf.xacro > .urdf` or `rosrun xacro xacro.py --inorder path/to/.urdf.xacro > .urdf` +- How to convert a xacro file to a URDF file? Type ``rosrun xacro xacro --inorder path/to/.urdf.xacro > .urdf`` or ``rosrun xacro xacro.py --inorder path/to/.urdf.xacro > .urdf`` -* When I set the `fixed_base` to `False`, the robot has still a fixed base, what is happening? The first link (often called base_link or world_link in most URDF files) shouldn't have a mass/inertia of zero, this causes the robot to have a fixed base. Remove the corresponding tag from the urdf. +- When I set the ``fixed_base`` to ``False``, the robot has still a fixed base, what is happening? The first link (often called base_link or world_link in most URDF files) shouldn't have a mass/inertia of zero, this causes the robot to have a fixed base. Remove the corresponding tag from the urdf. -* I noticed that some functionalities are missing in one of the robot class? I probably forgot to implement it. Please open an issue on [Github](https://github.com/robotlearn/pyrobolearn) or create a pull request. +- I noticed that some functionalities are missing in one of the robot class? I probably forgot to implement it. Please open an issue on `Github `_ or create a pull request. -* There is an error in one of the functionalities? Or, I have another question or want to suggest an improvement? Please open an issue on [Github](https://github.com/robotlearn/pyrobolearn) or a create a pull request. +- There is an error in one of the functionalities? Or, I have another question or want to suggest an improvement? Please open an issue on `Github `_ or a create a pull request. Future works ------------ -* add more robots - * [hexapods](https://github.com/resibots/hexapod_ros/tree/master/hexapod_description) -* improve the flexibility/modularity by allowing to remove/add/replace links to/from the main robot. For instance: - * add a gripper to a manipulator robot, or replace a gripper with another - * remove a leg to a legged robot (which is interesting to simulate damage recovery scenarios) -* might need to define different URDFs for different simulators +- add more robots. Here are few other robots that might interest the users: + - `hexapods `_ + - `ROS robots `_ + - `Universal robots `_ +- improve the flexibility/modularity by allowing to remove/add/replace links to/from the main robot. For instance: + - add a gripper to a manipulator robot, or replace a gripper with another + - remove a leg from a legged robot (which is interesting to simulate damage recovery scenarios) +- might need to define different URDFs for different simulators References ---------- All the robots were found in the following github repositories (and several were cleaned by me): -- [Aibo](https://github.com/dkotfis/aibo_ros) -- [Allegrohand](https://github.com/simlabrobotics/allegro_hand_ros) -- [Ant](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf) -- Atlas: [1](https://github.com/openai/roboschool), [2](https://github.com/erwincoumans/pybullet_robots) -- [Ballbot](https://github.com/CesMak/bb) -- [Baxter](https://github.com/RethinkRobotics/baxter_common) -- BB8: [1](http://www.theconstructsim.com/bb-8-gazebo-model/), [2](https://github.com/eborghi10/BB-8-ROS) -- [Blackbird](https://hackaday.io/project/160882-blackbird-bipedal-robot) -- [Cartpole](https://github.com/bulletphysics/bullet3/blob/master/data/cartpole.urdf) but modified to be able to have multiple links specified at runtime -- Cassie: [1](https://github.com/UMich-BipedLab/Cassie_Model), [2](https://github.com/agilityrobotics/cassie-gazebo-sim), [3](https://github.com/erwincoumans/pybullet_robots) -- [Centauro](https://github.com/ADVRHumanoids/centauro-simulator) -- [Cogimon](https://github.com/ADVRHumanoids/iit-cogimon-ros-pkg) -- [Coman](https://github.com/ADVRHumanoids/iit-coman-ros-pkg) -- [Crab](https://github.com/tuuzdu/crab_project) -- [Cubli](https://github.com/xinsongyan/cubli) -- [Darwin](https://github.com/HumaRobotics/darwin_description) -- [e.Do](https://github.com/Comau/eDO_description) -- [E-puck](https://github.com/gctronic/epuck_driver_cpp) -- [F10 racecar](https://github.com/erwincoumans/pybullet_robots/tree/master/data/f10_racecar) -- [Fetch](https://github.com/fetchrobotics/fetch_ros) -- [Flappy]() -- [Franka Emika](https://github.com/frankaemika/franka_ros) -- [Half Cheetah](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf) -- [Hopper](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf) -- [Hubo](https://github.com/robEllenberg/hubo-urdf) -- [Humanoid](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf) -- [Husky](https://github.com/husky/husky) -- [HyQ](https://github.com/iit-DLSLab/hyq-description) -- [HyQ2Max](https://github.com/iit-DLSLab/hyq2max-description) -- ICub: [1](https://github.com/robotology-playground/icub-models), [2](https://github.com/robotology-playground/icub-model-generator). There are currently few problems with this robot. -- [Jaco](https://github.com/JenniferBuehler/jaco-arm-pkgs) -- KR5: [1](https://github.com/a-price/KR5sixxR650WP_description), [2](https://github.com/ros-industrial/kuka_experimental) -- Kuka IIWA: [1](https://github.com/IFL-CAMP/iiwa_stack), [2](https://github.com/bulletphysics/bullet3/tree/master/data/kuka_iiwa) -- Kuka LWR: [1](https://github.com/CentroEPiaggio/kuka-lwr), [2](https://github.com/bulletphysics/bullet3/tree/master/data/kuka_lwr) -- [Laikago](https://github.com/erwincoumans/pybullet_robots) -- [Little Dog](https://github.com/RobotLocomotion/LittleDog) -- [Manipulator2D](https://github.com/domingoesteban/robolearn_robots_ros) -- [Minitaur](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/quadruped) -- [Lincoln MKZ car](https://bitbucket.org/DataspeedInc/dbw_mkz_ros) -- [Morphex](https://gist.github.com/lanius/cb8b5e0ede9ff3b2b2c1bc68b95066fb) -- Nao: [1](https://github.com/ros-naoqi/nao_robot), and [2](https://github.com/ros-naoqi/nao_meshes) -- OpenDog: [1](https://github.com/XRobots/openDog), and [2](https://github.com/wiccopruebas/opendog_project) -- [Pepper](https://github.com/ros-naoqi/pepper_robot) -- [Phantom X](https://github.com/HumaRobotics/phantomx_description) -- [Pleurobot](https://github.com/KM-RoBoTa/pleurobot_ros_pkg) -- [PR2](https://github.com/pr2/pr2_common) -- [Quadcopter](https://github.com/wilselby/ROS_quadrotor_simulator) -- [Rhex](https://github.com/grafoteka/rhex) -- [RRbot](https://github.com/ros-simulation/gazebo_ros_demos) -- Sawyer: [1](https://github.com/RethinkRobotics/sawyer_robot), [2](https://github.com/erwincoumans/pybullet_robots) -- [SEA hexapod](https://github.com/alexansari101/snake_ws) -- [SEA snake]( https://github.com/alexansari101/snake_ws) -- [Shadow hand](https://github.com/shadow-robot/sr_common) -- [Soft hand](https://github.com/CentroEPiaggio/pisa-iit-soft-hand) -- [Swimmer](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf) -- [Valkyrie](https://github.com/openhumanoids/val_description) -- [Walker 2D](https://github.com/bulletphysics/bullet3/tree/master/examples/pybullet/gym/pybullet_data/mjcf) -- [Walk-man](https://github.com/ADVRHumanoids/iit-walkman-ros-pkg) -- [Wam](https://github.com/jhu-lcsr/barrett_model) -- [Youbot](https://github.com/youbot): this includes the youbot base without any arms, one kuka arm, 2 kuka arms, and the kuka arm without the wheeled base. + +- `Aibo `_ +- `Allegrohand `_ +- `Ant `_ +- Atlas: `1 `_, `2 `_ +- `Ballbot `_ +- `Baxter `_ +- BB8: `1 `_, `2 `_ +- `Blackbird `_ +- `Cartpole `_ but modified to be able to have multiple links specified at runtime +- Cassie: `1 `_, `2 `_, `3 `_ +- `Centauro `_ +- `Cogimon `_ +- `Coman `_ +- `Crab `_ +- `Cubli `_ +- `Darwin `_ +- `e.Do `_ +- `E-puck `_ +- `F10 racecar `_ +- `Fetch `_ +- `Franka Emika `_ +- `Half Cheetah `_ +- `Hopper `_ +- `Hubo `_ +- `Humanoid `_ +- `Husky `_ +- `HyQ `_ +- `HyQ2Max `_ +- ICub: `1 `_, `2 `_. There are currently few problems with this robot. +- `Jaco `_ +- KR5: `1 `_, `2 `_ +- Kuka IIWA: `1 `_, `2 `_ +- Kuka LWR: `1 `_, `2 `_ +- `Laikago `_ +- `Little Dog `_ +- `Manipulator2D `_ +- `Minitaur `_ +- `Lincoln MKZ car `_ +- `Morphex `_ +- Nao: `1 `_, and `2 `_ +- OpenDog: `1 `_, and `2 `_ +- `Pepper `_ +- `Phantom X `_ +- `Pleurobot `_ +- `PR2 `_ +- `Quadcopter `_ +- `Rhex `_ +- `RRbot `_ +- Sawyer: `1 `_, `2 `_ +- `SEA hexapod `_ +- `SEA snake `_ +- `Shadow hand `_ +- `Soft hand `_ +- `Swimmer `_ +- `Valkyrie `_ +- `Walker 2D `_ +- `Walk-man `_ +- `Wam `_ +- `Youbot `_: this includes the youbot base without any arms, one kuka arm, 2 kuka arms, and the kuka arm without the wheeled base. diff --git a/docs/source/simulators.rst b/docs/source/simulators.rst index 7dc741d..5fce84f 100644 --- a/docs/source/simulators.rst +++ b/docs/source/simulators.rst @@ -1,17 +1,17 @@ Simulators ========== -The simulator is the starting point in the *PyRoboLearn* (PRL) framework. To avoid a tight coupling with a particular simulator, a `Simulator` interface class (from which all the other simulators inherit from) has been implemented. Other . +The simulator is the starting point in the *%PyRoboLearn** (PRL) framework. To avoid a tight coupling with a particular simulator, a ``Simulator`` interface class (from which all the other simulators inherit from) has been implemented. Other . + +We provide the ``Bullet`` interface. -We provide the `Bullet` interface. -Goal open-source. The general idea is that you would be able to change the simulator if you wish without having to modify any other lines of code. See example below. How to use a particular simulator in PRL? ----------------------------------------- -For the moment, the only fully operational interface is `Bullet`. Some few other interfaces have been partially implemented (see Future works). Here is a snippet on how to use the `Bullet` simulator in PRL: +For the moment, the only fully operational interface is ``Bullet``. Some few other interfaces have been partially implemented (see Future works). Here is a snippet on how to use the ``Bullet`` simulator in PRL: .. code-block:: python @@ -36,7 +36,7 @@ For the moment, the only fully operational interface is `Bullet`. Some few other sim.step(sim.dt) -You can check for more examples in the [`examples/simulators`](https://github.com/robotlearn/pyrobolearn/tree/master/examples/simulators) folder. +You can check for more examples in the `examples/simulators `_ folder. Design @@ -51,28 +51,28 @@ UML How to create an interface to a simulator? ------------------------------------------ -To create your own Simulator, you have to inherit from the `Simulator` class defined in `pyrobolearn/simulators/simulator.py`. +To create your own Simulator, you have to inherit from the ``Simulator`` class defined in `pyrobolearn/simulators/simulator.py `_. FAQs and Troubleshootings ------------------------- -* What are the differences between [`BulletClient`](https://github.com/bulletphysics/bullet3/blob/master/examples/pybullet/gym/pybullet_utils/bullet_client.py) and the Bullet defined in PRL? There are few differences but the design of the abstract `Simulator` class as well as the `Bullet` class was heavily inspired by the methods provided in `PyBullet`. The subtil differences include: - * a full documentation embedded in the code of `Bullet`. The documentation for each function provided in the original pybullet is described on a Google doc available [here](https://docs.google.com/document/d/10sXEhzFRSnvFcl3XxNGhnD4N2SedqwdAvK3dsihxVUA). This is not optimal when coding where a user often wants to access the documentation through the code using `function?` or `help(function)` in a Python console. - * follow the PEP8 style guideline. For instance, the names of the method are given by `create_collision_shape` instead of `createCollisionShape`. - * automatic conversion to numpy arrays from lists that are returned by `pybullet`, and vice-versa. Some methods (not all of them) in the original pybullet raises an error when given a numpy array. I identified these methods and convert these numpy arrays to lists. Also, some matrices returned by some methods in the original pybullet are returned as a list of int/float instead of numpy arrays. The conversion to numpy array and the reshaping to the correct shapes is thus also performed in the `Bullet` class. - * enforce consistency; for instance, some angles that were returned from or provided to some methods in the original pybullet, were for some in degrees while for others in radians. This can lead to some bugs that could be hard to detect if the user is not aware of that. In Bullet, all the returned/provided angles are in radians. +* What are the differences between `BulletClient `_ and the ``Bullet`` defined in PRL? There are few differences but the design of the abstract ``Simulator`` class as well as the `Bullet` class was heavily inspired by the methods provided in PyBullet. The subtil differences include: + * a full documentation embedded in the code of ``Bullet``. The documentation for each function provided in the original pybullet is described on a Google doc available `here `_. This is not optimal when coding where a user often wants to access the documentation through the code using ``function?`` or ``help(function)`` in a Python console. + * follow the PEP8 style guideline. For instance, the names of the method are given by ``create_collision_shape`` instead of ``createCollisionShape``. + * automatic conversion to numpy arrays from lists that are returned by ``pybullet``, and vice-versa. Some methods (not all of them) in the original pybullet raises an error when given a numpy array. I identified these methods and convert these numpy arrays to lists. Also, some matrices returned by some methods in the original pybullet are returned as a list of int/float instead of numpy arrays. The conversion to numpy array and the reshaping to the correct shapes is thus also performed in the ``Bullet`` class. + * enforce consistency; for instance, some angles that were returned from or provided to some methods in the original pybullet, were for some in degrees while for others in radians. This can lead to some bugs that could be hard to detect if the user is not aware of that. In ``Bullet``, all the returned/provided angles are in radians. Future works ------------ My main objectives for future works are the implementation of: -* the Mujoco interface; I originally did not start with it as it is closed-source and requires a License. However, it is used a lot in research and thus it could be interesting to have it as well. -* the Gazebo-ROS interface; a part has already been implemented but it is far from over. -* the Isaac interface if Nvidia provided a nice Python API. +- the Mujoco interface; I originally did not start with it as it is closed-source and requires a License. However, it is used a lot in research and thus it could be interesting to have it as well. +- the Gazebo-ROS interface; a part has already been implemented but it is far from over. +- the Isaac interface if Nvidia provided a nice Python API. Possible other future works might include the implementation of: -* the DART interface; there is a minimal implementation of it when I was playing around with it -* the opensim interface; this interface is for musculoskeletal models but this can be interesting when testing algorithms/models. +- the DART interface; there is a minimal implementation of it when I was playing around with it +- the opensim interface; this interface is for musculoskeletal models but this can be interesting when testing algorithms/models. diff --git a/docs/source/states.rst b/docs/source/states.rst index e69de29..7ac56f6 100644 --- a/docs/source/states.rst +++ b/docs/source/states.rst @@ -0,0 +1,18 @@ +States +====== + +In PRL, every concept is modelized as a class. This is also true for states which are returned by the environment. + + +How to use a particular state? +------------------------------ + +example of states with robot + + +How to create your own state? +----------------------------- + + +FAQs +---- diff --git a/docs/source/worlds.rst b/docs/source/worlds.rst index 396b1d6..418dcbb 100644 --- a/docs/source/worlds.rst +++ b/docs/source/worlds.rst @@ -1,29 +1,77 @@ Worlds ====== -The world is the second important item in PRL; it is, with the `Body` class, the only class that can access the simulator. +The world is the second important item in PRL; it is, with the ``Body`` class (see next section), the only class that can access the simulator. As it name implies, it allows you to create a world in the simulator, load various objects in it, and change the world's and objects' physical properties. From it, you can also access to the main camera (if the GUI is enabled in the simulator), and move it as you wish. The world can be seen as a wrapper around the simulator which provides you extra functionalities where each function calls different methods of the simulator. Finally, the world also allows you to load and generate terrains. How to use the world in PRL? ---------------------------- -You can get the world camera. +Here is a snippet showing how to create a simple world in PRL: -light +.. code-block:: python + :linenos: + + from itertools import count + import pyrobolearn as prl + + + # create simulator + simulator = prl.simulators.Bullet() + + # create basic world (with floor and gravity) + world = prl.worlds.BasicWorld(simulator) + + # load a sphere in the world + sphere = world.load_sphere(position=[0, 0, 5]) + + # run the simulator + for t in count(): + # follow the sphere falling with the main camera + world.camera.follow(sphere, distance=2) + + # perform a step in the simulator and sleep for `sim.dt` + world.step() + + +Note that you can get access to the world camera, and change its position and orientation. You can also follow an object moving with the camera as done in the code above. + +For more examples, you can check the `examples/worlds `_ folder. + + +Design +------ + +As it can be seen on the UML diagram below the ``World`` depends on the ``Simulator`` and the various ``Body`` (see next section) loaded in it (as well as few util functions). + + +UML picture + + +Later, we will see that world is notably given to the environment along with the states and rewards. + + +How to create your own world? +----------------------------- + +Creating your own world basically boils down to inheriting from the ``World`` or ``BasicWorld`` (if you want a floor and enable gravity by default) class, and write in the constructor what you want your world to load when instantiated. -You can check for more examples in the [`examples/worlds`](https://github.com/robotlearn/pyrobolearn/tree/master/examples/worlds) folder. FAQs and Troubleshootings ------------------------- -* Why do the `Body` class (and all the classes that inherit from it such as `Robot`) can access the simulator as well? This is because, creating a world when the `Simulator` is the real world doesn't make much sense. The Robot is completely independent of the World. +- Why do the ``Body`` class (and all the classes that inherit from it such as ``Robot``) can access the simulator as well? + - This is because, creating a world when the ``Simulator`` consists to be the real world doesn't make much sense. The ``Robot`` is completely independent of the ``World``, while the converse is not true. +- I got an error while loading a 3D object / mesh? + - The most common error is because the given format is not supported by the simulator. Try to convert it in ``.obj`` using for instance `meshlab `_ (which is an open-source free tool to process and edit 3D meshes) -Where can I find 3d models? ---------------------------- +Where can I find 3d models to load in the world? +------------------------------------------------ -* If it a combination of simple shapes linked together, you can build it in the simulator. -* Pybullet data -* gazebo database -* +- If it a combination of simple shapes linked together, you can build it in the simulator. +- `Pybullet data `_ +- `Gazebo database `_ +- `Turbosquid `_ +- `free3d `_