documentation/source/debug_mode.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5711ae69",
   "metadata": {},
   "source": [
    "# Debugging mode\n",
    "\n",
    "[![Click and Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/metadriverse/metadrive/blob/main/documentation/source/debug_mode.ipynb)\n",
    "\n",
    "Some configurations can be turned on to debug the simulator. As a result, you can get more console output from the simulation and visualizations such as coordinates and physics to help develop features or fix bugs. To receive debug messages, set `debug=True` in the config when creating the environment. In debug mode, the `log_level` will be changed to `logging.DEBUG`, so you will get more information from MetaDrive, Panda3D, and RenderPipeline in the console."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3f6419b",
   "metadata": {},
   "source": [
    "## Debug physics\n",
    "\n",
    "<img src=\"figs/debug_physics.png\" width=\"600\" class=\"center\">\n",
    "\n",
    "It is important to make sure that physics world is accurate. For example, objects should have accurate bounding boxes in order to ensure the collision detection is correct. Specifying `debug=True` in environment config can turn on the debug mode. In this mode, you can visualize the physics world by pressing `1` (the one near `~`) on your keyboard. In the following example, we have automatically turned on the physics world visualizer for you by `env.engine.toggleDebug()`. Pressing `1` can turn if off."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4db05ca8",
   "metadata": {},
   "outputs": [],
   "source": [
    "from metadrive.envs.scenario_env import ScenarioEnv\n",
    "import numpy as np\n",
    "import os\n",
    "render = not os.getenv('TEST_DOC')\n",
    "\n",
    "# create real-world environment with debug mode turned on\n",
    "env = ScenarioEnv(dict(use_render=render, debug=True)) \n",
    "env.reset(seed=0)\n",
    "# turn on physics world visualizer\n",
    "env.engine.toggleDebug()\n",
    "\n",
    "try:\n",
    "    for i in range(200):\n",
    "        o,r,d,t,i = env.step([0,1])\n",
    "        if d:\n",
    "            break\n",
    "finally:\n",
    "    env.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6b6365a",
   "metadata": {},
   "source": [
    "The default debug mode only visualizes the object in the world called **\"dynamics physics world\"**. In this world, objects can have interactions following the physics law like collision, friction, and gravity. At the same time, there exists another physics world called **\"static physics world\"**, where objects won't participate in collision and enjoy zero gravity. However, one can still query this world to know if an object in dynamics physics world has contact with objects in the static physics world. Therefore, we usually put objects that are still like crosswalks, lane lines and lanes in this world. As a result, we can know which lane the car is on or if it is on a lane line or sidewalk, while keep the simulation at a high FPS as we only *step* the dynamics physics world.\n",
    "\n",
    "<img src=\"figs/debug_static.png\" width=\"600\">\n",
    "\n",
    "To visualize the dynamics physics world and static physics world together, we can turn on the `config['debug_static_world']=True`. The following example visualizes both physics worlds by adding objects which are supposed to be in static physics world to the dynamics physics world. You will also experience a FPS drop, which explains why we separate the physics world into two."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "be13c259",
   "metadata": {},
   "outputs": [],
   "source": [
    "from metadrive.envs.scenario_env import ScenarioEnv\n",
    "import numpy as np\n",
    "import os\n",
    "render = not os.getenv('TEST_DOC')\n",
    "\n",
    "# create real-world environment with debug mode turned on\n",
    "env = ScenarioEnv(dict(use_render=render, debug=True, debug_static_world=True)) \n",
    "env.reset(seed=0)\n",
    "# turn on physics world visualizer\n",
    "env.engine.toggleDebug()\n",
    "\n",
    "try:\n",
    "    for i in range(200):\n",
    "        o,r,d,t,i = env.step([0,1])\n",
    "        if d:\n",
    "            break\n",
    "finally:\n",
    "    env.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "688cfa36",
   "metadata": {},
   "source": [
    "There is a more aggressive option `debug_physics_world` to debug the physics engine. It will turn off all graphics and only keep the line frames representing physics bodies. Turn it on via `debug_physics_world=True`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3ec6b94d",
   "metadata": {},
   "outputs": [],
   "source": [
    "from metadrive.envs.scenario_env import ScenarioEnv\n",
    "import numpy as np\n",
    "import os\n",
    "render = not os.getenv('TEST_DOC')\n",
    "\n",
    "# create real-world environment with debug mode turned on\n",
    "env = ScenarioEnv(dict(use_render=render, \n",
    "                       debug=True, \n",
    "                       debug_physics_world=True, \n",
    "                       debug_static_world=True)) \n",
    "env.reset(seed=0)\n",
    "# turn on physics world visualizer\n",
    "env.engine.toggleDebug()\n",
    "\n",
    "try:\n",
    "    for i in range(200):\n",
    "        o,r,d,t,i = env.step([0,1])\n",
    "        if d:\n",
    "            break\n",
    "finally:\n",
    "    env.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22c09cbd",
   "metadata": {},
   "source": [
    "## Debug Panda3D \n",
    "\n",
    "<img src=\"figs/pstats.png\" width=\"600\">\n",
    "\n",
    "In addition to the errors raised from MetaDrive, sometimes the game engine, Panda3D, will throw errors and warnings about the rendering service. To enable the logging of Panda3D, set `env_config[\"debug_panda3d\"]=True`. Besides, you can turn on Panda3D's profiler via `env_config[\"pstats\"]=True` and launch the `pstats` in the terminal. It can be used to analyze your program in terms of the time consumed for different functions like rendering, physics and so on, which is very useful if you are developing some graphics related features."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7b3e2ecb",
   "metadata": {},
   "outputs": [],
   "source": [
    "# launch pstats (bash)\n",
    "!pstats"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6b16389f",
   "metadata": {},
   "outputs": [],
   "source": [
    "from metadrive.envs.base_env import BaseEnv\n",
    "import os\n",
    "render = not os.getenv('TEST_DOC')\n",
    "\n",
    "# create environment\n",
    "env = BaseEnv(dict(use_render=render, debug=True, debug_panda3d=True, pstats=True))\n",
    "\n",
    "# reset environment\n",
    "env.reset()\n",
    "try:\n",
    "    for i in range(1000):\n",
    "        env.step(env.action_space.sample())\n",
    "finally:\n",
    "    env.close()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3db6ecf9",
   "metadata": {},
   "source": [
    "## Show coordinates\n",
    "\n",
    "<img src=\"figs/coordinates.png\" width=\"600\">\n",
    "\n",
    "Coordinates are important for developing robotics systems. To show the coordinates for the map, the world and objects, please set `show_coordinate=True` when creating the environment. \n",
    "There are three types of coordinates will be shown: \n",
    "- World/global coordinates which moves with the car. The `+x` direction is marked in red and is longer. The `+y` direction is in green and shorter.\n",
    "- Lane coordinates marking the longitudinal and lateral direction of each lane. For each lane, the green line is the `+longitudinal` direction and the red line is `+lateral` direction. \n",
    "- Object's local coordinate. The longer line points to `+x` direction and the shorter line points to `+y` direction.\n",
    " "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "844c2552",
   "metadata": {},
   "outputs": [],
   "source": [
    "from metadrive.envs.metadrive_env import MetaDriveEnv\n",
    "from metadrive.policy.idm_policy import IDMPolicy\n",
    "import os\n",
    "test = os.getenv('TEST_DOC')\n",
    "\n",
    "\n",
    "# create environment\n",
    "env = MetaDriveEnv(dict(use_render=not test, \n",
    "                        show_coordinates=True, \n",
    "                        agent_policy=IDMPolicy,\n",
    "                        num_scenarios=1,\n",
    "                        map=\"XCO\"))\n",
    "\n",
    "# reset environment\n",
    "env.reset()\n",
    "try:\n",
    "    for i in range(1000):\n",
    "        o,r,d,t,_ = env.step([0,0])\n",
    "        if d:\n",
    "            break\n",
    "finally:\n",
    "    env.close()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}