Fix render_mode argument (#48)

* Deprecated render in pybulet in favor of render_mode

* Deprecate render in envs and add render_mode

* Update readme

* Update examples

* update notebook

* Update doc

* Update version

README.md

@@ -35,7 +35,7 @@ pip install -e panda-gym
 import gymnasium as gym
 import panda_gym
 
-env = gym.make('PandaReach-v3', render=True)
+env = gym.make('PandaReach-v3', render_mode="human")
 
 observation, info = env.reset()
 

docs/_static/notebook/PickAndPlace.ipynb

@@ -48,18 +48,18 @@
     "import gymnasium as gym\n",
     "import panda_gym\n",
     "\n",
-    "env = gym.make(\"PandaPickAndPlace-v3\", render=True)\n",
+    "env = gym.make(\"PandaPickAndPlace-v3\", render_mode=\"rgb_array\")\n",
     "observation, info = env.reset()\n",
     "\n",
-    "images = [env.render(\"rgb_array\")]\n",
+    "images = [env.render()]\n",
     "for _ in range(1000):\n",
     "    action = env.action_space.sample()\n",
     "    observation, reward, terminated, truncated, info = env.step(action)\n",
-    "    images.append(env.render(\"rgb_array\"))\n",
+    "    images.append(env.render())\n",
     "\n",
     "    if terminated or truncated:\n",
     "        observation, info = env.reset()\n",
-    "        images.append(env.render(\"rgb_array\"))\n",
+    "        images.append(env.render())\n",
     "\n",
     "env.close()"
    ]
@@ -107,8 +107,19 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "name": "python",
+   "version": "3.9.6 (default, Sep 26 2022, 11:37:49) \n[Clang 14.0.0 (clang-1400.0.29.202)]"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6"
+   }
   }
  },
  "nbformat": 4,

docs/conf.py

@@ -23,7 +23,7 @@
 author = "Quentin Gallouédec"
 
 # The full version, including alpha/beta/rc tags
-release = "v3.0.0"
+release = "v3.0.1"
 
 
 # -- General configuration ---------------------------------------------------

docs/custom/custom_env.rst

@@ -17,8 +17,8 @@ Then, you have to inherit from the :py:class:`RobotTaskEnv<panda_gym.envs.core.R
     class MyRobotTaskEnv(RobotTaskEnv):
         """My robot-task environment."""
 
-        def __init__(self, render=False):
-            sim = PyBullet(render=render)
+        def __init__(self, render_mode):
+            sim = PyBullet(render_mode=render_mode)
             robot = MyRobot(sim)
             task = MyTask(sim)
             super().__init__(robot, task)
@@ -32,16 +32,14 @@ You can now test your environment by running the following code.
 
 .. code-block:: python
 
-    env = MyRobotTaskEnv(render=True)
+    env = MyRobotTaskEnv(render_mode="human")
 
     observation, info = env.reset()
 
     for _ in range(1000):
         action = env.action_space.sample() # random action
         observation, reward, terminated, truncated, info = env.step(action)
-        env.render() # wait a bit to give a realistic temporal rendering
 
         if terminated or truncated:
             observation, info = env.reset()
-            env.render() # wait a bit to give a realistic temporal rendering
 

docs/custom/custom_robot.rst

@@ -132,12 +132,11 @@ The robot is ready. To see it move, execute the following code.
 
     from panda_gym.pybullet import PyBullet
 
-    sim = PyBullet(render=True)
+    sim = PyBullet(render_mode="human")
     robot = MyRobot(sim)
 
     for _ in range(50):
         robot.set_action(np.array([1.0]))
         sim.step()
-        sim.render()
 
 To see how to use this robot to define a new environment, see the :ref:`custom environment<custom_env>` section. 

docs/custom/custom_task.rst

@@ -74,7 +74,7 @@ The task is ready. To test it, execute the following code.
 
     from panda_gym.pybullet import PyBullet
 
-    sim = PyBullet(render=True)
+    sim = PyBullet(render_mode="human")
     task = MyTask(sim)
 
     task.reset()

docs/guide/quick_start.rst

@@ -10,18 +10,16 @@ Once ``panda-gym`` installed, you can start the "Reach" task by executing the fo
     import gymnasium as gym
     import panda_gym
 
-    env = gym.make('PandaReach-v3', render=True)
+    env = gym.make('PandaReach-v3', render_mode="human")
 
     observation, info = env.reset()
 
     for _ in range(1000):
         action = env.action_space.sample() # random action
         observation, reward, terminated, truncated, info = env.step(action)
-        env.render() # wait the right amount of time to make the rendering real-time
 
         if terminated or truncated:
             observation, info = env.reset()
-            env.render() # wait the right amount of time to make the rendering real-time
     
 
 Obviously, since the chosen actions are random, you will not see any learning. To access the section dedicated to the learning of the tasks, refer to the section :ref:`Train with stable-baselines3<train_with_sb3>`.

docs/usage/manual_control.rst

@@ -10,7 +10,7 @@ It is possible to manually control the robot, giving it deterministic actions, d
     import gymnasium as gym
     import panda_gym
 
-    env = gym.make("PandaReach-v3", render=True)
+    env = gym.make("PandaReach-v3", render_mode="human")
     observation, info = env.reset()
 
     for _ in range(1000):

docs/usage/save_restore_state.rst

@@ -12,7 +12,7 @@ It is possible to save a state of the entire simulation environment. This is use
 
     import panda_gym
 
-    env = gym.make("PandaReachDense-v3", render=True)
+    env = gym.make("PandaReachDense-v3", render_mode="human")
     observation, _ = env.reset()
 
     for _ in range(1000):

docs/usage/train_with_sb3.rst

@@ -60,8 +60,8 @@ For example, to train an agent with TQC on ``PandaPickAndPlace-v3``:
 Enjoy
 ~~~~~
 
-To visualize the trained agent, follow the `instructions <https://stable-baselines3.readthedocs.io/en/master/guide/rl_zoo.html#enjoy-a-trained-agent>`_ in the SB3 documentation. It is necessary to add ``--env-kwargs render:True`` when running the enjoy script.
+To visualize the trained agent, follow the `instructions <https://stable-baselines3.readthedocs.io/en/master/guide/rl_zoo.html#enjoy-a-trained-agent>`_ in the SB3 documentation. It is necessary to add ``--env-kwargs render_mode:human`` when running the enjoy script.
 
 .. code-block:: bash 
 
-    python enjoy.py --algo <ALGO> --env <ENV> --folder <TRAIN_AGENT_FOLDER> --env-kwargs render:True
+    python enjoy.py --algo <ALGO> --env <ENV> --folder <TRAIN_AGENT_FOLDER> --env-kwargs render_mode:human

examples/reach.py

@@ -2,7 +2,7 @@
 
 import panda_gym
 
-env = gym.make("PandaReach-v3", render=True)
+env = gym.make("PandaReach-v3", render_mode="human")
 
 observation, info = env.reset()
 

examples/rgb_rendering.py

@@ -3,21 +3,21 @@
 
 import panda_gym
 
-env = gym.make("PandaStack-v3", render=True)
+env = gym.make("PandaStack-v3", render_mode="rgb_array")
 images = []
 
 
 observation, info = env.reset()
-images.append(env.render("rgb_array"))
+images.append(env.render())
 
 for _ in range(1000):
     action = env.action_space.sample()
     observation, reward, terminated, truncated, info = env.step(action)
-    images.append(env.render("rgb_array"))
+    images.append(env.render())
 
     if terminated or truncated:
         observation, info = env.reset()
-        images.append(env.render("rgb_array"))
+        images.append(env.render())
 
 env.close()
 

panda_gym/envs/core.py

@@ -1,3 +1,4 @@
+import warnings
 from abc import ABC, abstractmethod
 from typing import Any, Dict, Optional, Tuple
 
@@ -291,23 +292,20 @@ def close(self) -> None:
 
     def render(
         self,
-        mode: str = "human",
         width: int = 720,
         height: int = 480,
         target_position: Optional[np.ndarray] = None,
         distance: float = 1.4,
         yaw: float = 45,
         pitch: float = -30,
         roll: float = 0,
+        mode: Optional[str] = None,
     ) -> Optional[np.ndarray]:
         """Render.
 
-        If mode is "human", make the rendering real-time. All other arguments are
-        unused. If mode is "rgb_array", return an RGB array of the scene.
+        If render mode is "rgb_array", return an RGB array of the scene. Else, do nothing.
 
         Args:
-            mode (str): "human" of "rgb_array". If "human", this method waits for the time necessary to have
-                a realistic temporal rendering and all other args are ignored. Else, return an RGB array.
             width (int, optional): Image width. Defaults to 720.
             height (int, optional): Image height. Defaults to 480.
             target_position (np.ndarray, optional): Camera targetting this postion, as (x, y, z).
@@ -316,13 +314,20 @@ def render(
             yaw (float, optional): Yaw of the camera. Defaults to 45.
             pitch (float, optional): Pitch of the camera. Defaults to -30.
             roll (int, optional): Rool of the camera. Defaults to 0.
+            mode (str, optional): Deprecated: This argument is deprecated and will be removed in a future
+                version. Use the render_mode argument of the constructor instead.
 
         Returns:
             RGB np.ndarray or None: An RGB array if mode is 'rgb_array', else None.
         """
+        if mode is not None:
+            warnings.warn(
+                "The 'mode' argument is deprecated and will be removed in "
+                "a future version. Use the 'render_mode' argument of the constructor instead.",
+                DeprecationWarning,
+            )
         target_position = target_position if target_position is not None else np.zeros(3)
         return self.sim.render(
-            mode,
             width=width,
             height=height,
             target_position=target_position,