Render API

gym/core.py

@@ -1,6 +1,16 @@
 """Core API for Environment, Wrapper, ActionWrapper, RewardWrapper and ObservationWrapper."""
 import sys
-from typing import Generic, Optional, SupportsFloat, Tuple, TypeVar, Union
+from typing import (
+    Any,
+    Dict,
+    Generic,
+    List,
+    Optional,
+    SupportsFloat,
+    Tuple,
+    TypeVar,
+    Union,
+)
 
 from gym import spaces
 from gym.logger import deprecation, warn
@@ -14,6 +24,44 @@
 
 ObsType = TypeVar("ObsType")
 ActType = TypeVar("ActType")
+RenderFrame = TypeVar("RenderFrame")
+
+
+class _EnvDecorator(type):  # TODO: remove with gym 1.0
+    """Metaclass used for adding deprecation warning to the mode kwarg in the render method."""
+
+    def __new__(cls, name, bases, attr):
+        if "render" in attr.keys():
+            attr["render"] = _EnvDecorator._deprecate_mode(attr["render"])
+
+        return super().__new__(cls, name, bases, attr)
+
+    @staticmethod
+    def _deprecate_mode(render_func):  # type: ignore
+        render_return = Optional[Union[RenderFrame, List[RenderFrame]]]
+
+        def render(
+            self: object, *args: Tuple[Any], **kwargs: Dict[str, Any]
+        ) -> render_return:
+            if "mode" in kwargs.keys():
+                deprecation(
+                    "The argument mode in render method is deprecated; "
+                    "use render_mode during environment initialization instead.\n"
+                    "See here for more information: https://www.gymlibrary.ml/content/api/"
+                )
+            elif self.spec is not None and "render_mode" not in self.spec.kwargs.keys():  # type: ignore
+                deprecation(
+                    "You are calling render method, "
+                    "but you didn't specified the argument render_mode at environment initialization. "
+                    "To maintain backward compatibility, the environment will render in human mode.\n"
+                    "If you want to render in human mode, initialize the environment in this way: "
+                    "gym.make('EnvName', render_mode='human') and don't call the render method.\n"
+                    "See here for more information: https://www.gymlibrary.ml/content/api/"
+                )
+
+            return render_func(self, *args, **kwargs)
+
+        return render
 
 
 class Env(Generic[ObsType, ActType]):
@@ -43,8 +91,11 @@ class Env(Generic[ObsType, ActType]):
     Note: a default reward range set to :math:`(-\infty,+\infty)` already exists. Set it if you want a narrower range.
     """
 
+    __metaclass__ = _EnvDecorator
+
     # Set this in SOME subclasses
     metadata = {"render_modes": []}
+    render_mode = None  # define render_mode if your environment supports rendering
     reward_range = (-float("inf"), float("inf"))
     spec = None
 
@@ -130,42 +181,34 @@ def reset(
         if seed is not None:
             self._np_random, seed = seeding.np_random(seed)
 
-    def render(self, mode="human"):
-        """Renders the environment.
+    # TODO: remove kwarg mode with gym 1.0
+    def render(self, mode="human") -> Optional[Union[RenderFrame, List[RenderFrame]]]:
+        """Compute the render frames as specified by render_mode attribute during initialization of the environment.
 
-        A set of supported modes varies per environment. (And some
+        The set of supported modes varies per environment. (And some
         third-party environments may not support rendering at all.)
-        By convention, if mode is:
+        By convention, if render_mode is:
+
+        - None (default): no render is computed.
+        - human: render return None.
+          The environment is continuously rendered in the current display or terminal. Usually for human consumption.
+        - single_rgb_array: return a single frame representing the current state of the environment.
+          A frame is a numpy.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image.
+        - rgb_array: return a list of frames representing the states of the environment since the last reset.
+          Each frame is a numpy.ndarray with shape (x, y, 3), as with single_rgb_array.
+        - ansi: Return a list of strings (str) or StringIO.StringIO containing a
+          terminal-style text representation for each time step.
+          The text can include newlines and ANSI escape sequences (e.g. for colors).
 
-        - human: render to the current display or terminal and
-          return nothing. Usually for human consumption.
-        - rgb_array: Return a numpy.ndarray with shape (x, y, 3),
-          representing RGB values for an x-by-y pixel image, suitable
-          for turning into a video.
-        - ansi: Return a string (str) or StringIO.StringIO containing a
-          terminal-style text representation. The text can include newlines
-          and ANSI escape sequences (e.g. for colors).
+        Note:
+            Rendering computations is performed internally even if you don't call render().
+            To avoid this, you can set render_mode = None and, if the environment supports it,
+            call render() specifying the argument 'mode'.
 
         Note:
             Make sure that your class's metadata 'render_modes' key includes
             the list of supported modes. It's recommended to call super()
             in implementations to use the functionality of this method.
-
-        Example:
-            >>> import numpy as np
-            >>> class MyEnv(Env):
-            ...    metadata = {'render_modes': ['human', 'rgb_array']}
-            ...
-            ...    def render(self, mode='human'):
-            ...        if mode == 'rgb_array':
-            ...            return np.array(...) # return RGB frame suitable for video
-            ...        elif mode == 'human':
-            ...            ... # pop up a window and render
-            ...        else:
-            ...            super().render(mode=mode) # just raise an exception
-
-        Args:
-            mode: the mode to render with, valid modes are `env.metadata["render_modes"]`
         """
         raise NotImplementedError
 

gym/envs/box2d/bipedal_walker.py

@@ -9,6 +9,7 @@
 from gym import error, spaces
 from gym.error import DependencyNotInstalled
 from gym.utils import EzPickle
+from gym.utils.renderer import Renderer
 
 try:
     import Box2D
@@ -159,12 +160,13 @@ class BipedalWalker(gym.Env, EzPickle):
 
     """
 
-    metadata = {"render_modes": ["human", "rgb_array"], "render_fps": FPS}
+    metadata = {
+        "render_modes": ["human", "rgb_array", "single_rgb_array"],
+        "render_fps": FPS,
+    }
 
-    def __init__(self, hardcore: bool = False):
+    def __init__(self, render_mode: Optional[str] = None, hardcore: bool = False):
         EzPickle.__init__(self)
-        self.screen = None
-        self.clock = None
         self.isopen = True
 
         self.world = Box2D.b2World()
@@ -252,6 +254,12 @@ def __init__(self, hardcore: bool = False):
         # ]
         # state += [l.fraction for l in self.lidar]
 
+        assert render_mode is None or render_mode in self.metadata["render_modes"]
+        self.render_mode = render_mode
+        self.renderer = Renderer(self.render_mode, self._render)
+        self.screen = None
+        self.clock = None
+
     def _destroy(self):
         if not self.terrain:
             return
@@ -500,6 +508,7 @@ def ReportFixture(self, fixture, point, normal, fraction):
                 return fraction
 
         self.lidar = [LidarCallback() for _ in range(10)]
+        self.renderer.reset()
         if not return_info:
             return self.step(np.array([0, 0, 0, 0]))[0]
         else:
@@ -589,9 +598,18 @@ def step(self, action: np.ndarray):
             done = True
         if pos[0] > (TERRAIN_LENGTH - TERRAIN_GRASS) * TERRAIN_STEP:
             done = True
+
+        self.renderer.render_step()
         return np.array(state, dtype=np.float32), reward, done, {}
 
     def render(self, mode: str = "human"):
+        if self.render_mode is not None:
+            return self.renderer.get_renders()
+        else:
+            return self._render(mode)
+
+    def _render(self, mode: str = "human"):
+        assert mode in self.metadata["render_modes"]
         try:
             import pygame
             from pygame import gfxdraw
@@ -600,7 +618,7 @@ def render(self, mode: str = "human"):
                 "pygame is not installed, run `pip install gym[box2d]`"
             )
 
-        if self.screen is None:
+        if self.screen is None and mode == "human":
             pygame.init()
             pygame.display.init()
             self.screen = pygame.display.set_mode((VIEWPORT_W, VIEWPORT_H))
@@ -653,18 +671,19 @@ def render(self, mode: str = "human"):
         self.lidar_render = (self.lidar_render + 1) % 100
         i = self.lidar_render
         if i < 2 * len(self.lidar):
-            l = (
+            single_lidar = (
                 self.lidar[i]
                 if i < len(self.lidar)
                 else self.lidar[len(self.lidar) - i - 1]
             )
-            pygame.draw.line(
-                self.surf,
-                color=(255, 0, 0),
-                start_pos=(l.p1[0] * SCALE, l.p1[1] * SCALE),
-                end_pos=(l.p2[0] * SCALE, l.p2[1] * SCALE),
-                width=1,
-            )
+            if hasattr(single_lidar, "p1") and hasattr(single_lidar, "p2"):
+                pygame.draw.line(
+                    self.surf,
+                    color=(255, 0, 0),
+                    start_pos=(single_lidar.p1[0] * SCALE, single_lidar.p1[1] * SCALE),
+                    end_pos=(single_lidar.p2[0] * SCALE, single_lidar.p2[1] * SCALE),
+                    width=1,
+                )
 
         for obj in self.drawlist:
             for f in obj.fixtures:
@@ -717,18 +736,16 @@ def render(self, mode: str = "human"):
         )
 
         self.surf = pygame.transform.flip(self.surf, False, True)
-        self.screen.blit(self.surf, (-self.scroll * SCALE, 0))
+
         if mode == "human":
+            self.screen.blit(self.surf, (-self.scroll * SCALE, 0))
             pygame.event.pump()
             self.clock.tick(self.metadata["render_fps"])
             pygame.display.flip()
-
-        if mode == "rgb_array":
+        elif mode in {"rgb_array", "single_rgb_array"}:
             return np.transpose(
-                np.array(pygame.surfarray.pixels3d(self.screen)), axes=(1, 0, 2)
+                np.array(pygame.surfarray.pixels3d(self.surf)), axes=(1, 0, 2)
             )
-        else:
-            return self.isopen
 
     def close(self):
         if self.screen is not None:
@@ -829,6 +846,5 @@ def __init__(self):
         a[3] = knee_todo[1]
         a = np.clip(0.5 * a, -1.0, 1.0)
 
-        env.render()
         if done:
             break

gym/envs/box2d/car_racing.py

@@ -10,6 +10,7 @@
 from gym.envs.box2d.car_dynamics import Car
 from gym.error import DependencyNotInstalled, InvalidAction
 from gym.utils import EzPickle
+from gym.utils.renderer import Renderer
 
 try:
     import Box2D
@@ -151,12 +152,19 @@ class CarRacing(gym.Env, EzPickle):
     """
 
     metadata = {
-        "render_modes": ["human", "rgb_array", "state_pixels"],
+        "render_modes": [
+            "human",
+            "rgb_array",
+            "state_pixels",
+            "single_rgb_array",
+            "single_state_pixels",
+        ],
         "render_fps": FPS,
     }
 
     def __init__(
         self,
+        render_mode: Optional[str] = None,
         verbose: bool = False,
         lap_complete_percent: float = 0.95,
         domain_randomize: bool = False,
@@ -170,6 +178,7 @@ def __init__(
         self.contactListener_keepref = FrictionDetector(self, lap_complete_percent)
         self.world = Box2D.b2World((0, 0), contactListener=self.contactListener_keepref)
         self.screen = None
+        self.surf = None
         self.clock = None
         self.isopen = True
         self.invisible_state_window = None
@@ -199,6 +208,10 @@ def __init__(
             low=0, high=255, shape=(STATE_H, STATE_W, 3), dtype=np.uint8
         )
 
+        assert render_mode is None or render_mode in self.metadata["render_modes"]
+        self.render_mode = render_mode
+        self.renderer = Renderer(self.render_mode, self._render)
+
     def _destroy(self):
         if not self.road:
             return
@@ -441,6 +454,7 @@ def reset(
                 )
         self.car = Car(self.world, *self.track[0][1:4])
 
+        self.renderer.reset()
         if not return_info:
             return self.step(None)[0]
         else:
@@ -466,7 +480,7 @@ def step(self, action: Union[np.ndarray, int]):
         self.world.Step(1.0 / FPS, 6 * 30, 2 * 30)
         self.t += 1.0 / FPS
 
-        self.state = self.render("state_pixels")
+        self.state = self._render("single_state_pixels")
 
         step_reward = 0
         done = False
@@ -484,9 +498,17 @@ def step(self, action: Union[np.ndarray, int]):
                 done = True
                 step_reward = -100
 
+        self.renderer.render_step()
         return self.state, step_reward, done, {}
 
     def render(self, mode: str = "human"):
+        if self.render_mode is not None:
+            return self.renderer.get_renders()
+        else:
+            return self._render(mode)
+
+    def _render(self, mode: str = "human"):
+        assert mode in self.metadata["render_modes"]
         try:
             import pygame
         except ImportError:
@@ -496,7 +518,6 @@ def render(self, mode: str = "human"):
 
         pygame.font.init()
 
-        assert mode in ["human", "state_pixels", "rgb_array"]
         if self.screen is None and mode == "human":
             pygame.init()
             pygame.display.init()
@@ -519,7 +540,13 @@ def render(self, mode: str = "human"):
         trans = (WINDOW_W / 2 + trans[0], WINDOW_H / 4 + trans[1])
 
         self._render_road(zoom, trans, angle)
-        self.car.draw(self.surf, zoom, trans, angle, mode != "state_pixels")
+        self.car.draw(
+            self.surf,
+            zoom,
+            trans,
+            angle,
+            mode not in ["state_pixels", "single_state_pixels"],
+        )
 
         self.surf = pygame.transform.flip(self.surf, False, True)
 
@@ -539,9 +566,9 @@ def render(self, mode: str = "human"):
             self.screen.blit(self.surf, (0, 0))
             pygame.display.flip()
 
-        if mode == "rgb_array":
+        if mode in {"rgb_array", "single_rgb_array"}:
             return self._create_image_array(self.surf, (VIDEO_W, VIDEO_H))
-        elif mode == "state_pixels":
+        elif mode in {"state_pixels", "single_state_pixels"}:
             return self._create_image_array(self.surf, (STATE_W, STATE_H))
         else:
             return self.isopen