PybulletBasic/pybullet_basic_en.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Table of contents**<a id='toc0_'></a>    \n",
    "- [What is pybullet](#toc1_)    \n",
    "- [Importing Necessary Libraries](#toc2_)    \n",
    "- [Starting pybullet](#toc3_)    \n",
    "- [Initial Setup for Simulation](#toc4_)    \n",
    "- [Loading the Floor](#toc5_)    \n",
    "- [Loading Objects](#toc6_)    \n",
    "- [Loading the Robot](#toc7_)    \n",
    "- [Setting the Camera Position](#toc8_)    \n",
    "- [Displaying Debug Text](#toc9_)    \n",
    "- [Running the Simulation](#toc10_)    \n",
    "\n",
    "<!-- vscode-jupyter-toc-config\n",
    "\tnumbering=false\n",
    "\tanchor=true\n",
    "\tflat=false\n",
    "\tminLevel=1\n",
    "\tmaxLevel=6\n",
    "\t/vscode-jupyter-toc-config -->\n",
    "<!-- THIS CELL WILL BE REPLACED ON TOC UPDATE. DO NOT WRITE YOUR TEXT IN THIS CELL -->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc1_'></a>[What is pybullet](#toc0_)\n",
    "pybullet is a physics simulation engine and a library for controlling robots and performing physical simulations.\n",
    "\n",
    "While ROS (Robot Operating System) is often used for robot simulation and control, setting up the ROS environment can be complex. On the other hand, pybullet is a Python library, making it easy to use as long as you have a Python environment.\n",
    "\n",
    "Here, we will introduce only the basic functions.  \n",
    "For a manual summarizing the functions available in pybullet, refer to [this link](https://github.com/bulletphysics/bullet3/blob/master/docs/pybullet_quickstartguide.pdf)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc2_'></a>[Importing Necessary Libraries](#toc0_)\n",
    "\n",
    "When using pybullet, you need to import `pybullet`.   \n",
    "Additionally, to load files used by pybullet, you also need to import `pybullet_data`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "pybullet build time: Nov 28 2023 23:45:17\n"
     ]
    }
   ],
   "source": [
    "import pybullet\n",
    "import pybullet_data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc3_'></a>[Starting pybullet](#toc0_)\n",
    "When using pybullet, you start the server for physical simulation using `pybullet.connect`.\n",
    "\n",
    "The types of servers available are:\n",
    "- `pybullet.GUI`\n",
    "- `pybullet.DIRECT`\n",
    "- `pybullet.SHARED_MEMORY`\n",
    "- `pybullet.UDP`\n",
    "- `pybullet.TCP`\n",
    "\n",
    "Basically, use `pybullet.DIRECT` for CUI and `pybullet.GUI` for GUI.\n",
    "\n",
    "<br>\n",
    "\n",
    "This time, we will use the GUI, so we will start the server by specifying `pybullet.GUI`.\n",
    "Running the cell below will start the pybullet GUI.  \n",
    "(Note that in environments like Google Colab where the GUI cannot be displayed, you need to start the server by specifying `pybullet.DIRECT`.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "startThreads creating 1 threads.\n",
      "starting thread 0\n",
      "started thread 0 \n",
      "argc=2\n",
      "argv[0] = --unused\n",
      "argv[1] = --start_demo_name=Physics Server\n",
      "ExampleBrowserThreadFunc started\n",
      "X11 functions dynamically loaded using dlopen/dlsym OK!\n",
      "X11 functions dynamically loaded using dlopen/dlsym OK!\n",
      "Creating context\n",
      "Created GL 3.3 context\n",
      "Direct GLX rendering context obtained\n",
      "Making context current\n",
      "GL_VENDOR=Mesa\n",
      "GL_RENDERER=llvmpipe (LLVM 15.0.7, 256 bits)\n",
      "GL_VERSION=4.5 (Core Profile) Mesa 23.2.1-1ubuntu3.1~22.04.2\n",
      "GL_SHADING_LANGUAGE_VERSION=4.50\n",
      "pthread_getconcurrency()=0\n",
      "Version = 4.5 (Core Profile) Mesa 23.2.1-1ubuntu3.1~22.04.2\n",
      "Vendor = Mesa\n",
      "Renderer = llvmpipe (LLVM 15.0.7, 256 bits)\n",
      "b3Printf: Selected demo: Physics Server\n",
      "startThreads creating 1 threads.\n",
      "starting thread 0\n",
      "started thread 0 \n",
      "MotionThreadFunc thread started\n"
     ]
    }
   ],
   "source": [
    "physics_client = pybullet.connect(pybullet.GUI) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc4_'></a>[Initial Setup for Simulation](#toc0_)\n",
    "Before starting the simulation, we perform initial setup.\n",
    "- Reset the simulation space\n",
    "- Add paths to necessary data for pybullet\n",
    "- Set gravity\n",
    "- Set the time elapsed per step (in seconds)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ven = Mesa\n",
      "ven = Mesa\n"
     ]
    }
   ],
   "source": [
    "pybullet.resetSimulation() # Reset the simulation space\n",
    "pybullet.setAdditionalSearchPath(pybullet_data.getDataPath()) # Add paths to necessary data for pybullet\n",
    "pybullet.setGravity(0.0, 0.0, -9.8) # Set gravity as on Earth\n",
    "time_step = 1./240.\n",
    "pybullet.setTimeStep(time_step) # Set the time elapsed per step"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc5_'></a>[Loading the Floor](#toc0_)\n",
    "pybullet provides several standard models. Here, we will load `plane.urdf`, a file that defines the floor.\n",
    "\n",
    "---\n",
    "\n",
    "A urdf file is an \"XML format file that defines robot models\" and can define links and joints of a robot.  \n",
    "While it is generally used to define robots, `plane.urdf` defines a floor model instead of a robot.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load the floor\n",
    "plane_id = pybullet.loadURDF(\"plane.urdf\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc6_'></a>[Loading Objects](#toc0_)\n",
    "By using the `createCollisionShape`, `createVisualShape`, and `createMultiBody` functions, you can create objects of arbitrary sizes (such as boxes and spheres)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load the box\n",
    "# Determine the weight, size, position, and orientation of the box\n",
    "mass = 5 # kg\n",
    "box_size = [0.3, 0.3, 0.3]\n",
    "position = [2, 0, 0.3]\n",
    "orientation = [1, 0, 0, 0] # Quaternion\n",
    "box_collision_id = pybullet.createCollisionShape(pybullet.GEOM_BOX, halfExtents=box_size)\n",
    "box_visual_id = pybullet.createVisualShape(pybullet.GEOM_BOX, halfExtents=box_size, rgbaColor=[1,0,0,1]) # Red, semi-transparent\n",
    "box_body_id = pybullet.createMultiBody(mass, box_collision_id, box_visual_id, position, orientation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc7_'></a>[Loading the Robot](#toc0_)\n",
    "We will load a urdf file of a robot that we have defined ourselves.\n",
    "By specifying the \"path to the urdf file\" as an argument to the `loadURDF` function, you can generate the robot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load the robot\n",
    "car_start_pos = [0, 0, 0.1]  # Set the initial position (x, y, z)\n",
    "car_start_orientation = pybullet.getQuaternionFromEuler([0, 0, 0])  # Set the initial orientation (roll, pitch, yaw)\n",
    "# The mesh in the urdf file does not seem to reflect textures, so each link is colored with the rgba tag\n",
    "car_id = pybullet.loadURDF(\"../urdf/simple_two_wheel_car.urdf\", car_start_pos, car_start_orientation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc8_'></a>[Setting the Camera Position](#toc0_)\n",
    "You can set the camera in GUI mode using the `resetDebugVisualizerCamera` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set the camera position and other parameters in GUI mode\n",
    "camera_distance = 4.0\n",
    "camera_yaw = 0.0 # deg\n",
    "camera_pitch = -20 # deg\n",
    "camera_target_position = [0.0, 0.0, 0.0]\n",
    "pybullet.resetDebugVisualizerCamera(camera_distance, camera_yaw, camera_pitch, camera_target_position)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc9_'></a>[Displaying Debug Text](#toc0_)\n",
    "By using the `addUserDebugText` function, you can display text at any position in the simulation space.\n",
    "\n",
    "Additionally, with `addUserDebugLine`, you can draw a line connecting any two points in the simulation space, which is useful for visualizing the movement path of a mobile robot or the trajectory of a robot arm's end-effector.\n",
    "\n",
    "In this way, pybullet provides convenient features for visualizing simulation results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Display text on the screen\n",
    "text_position = [0.0, 0.0, 2.0]\n",
    "life_time = 10.0 # Display duration (seconds)\n",
    "pybullet.addUserDebugText(\"test text\", text_position, textSize=2, lifeTime=life_time)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc10_'></a>[Running the Simulation](#toc0_)\n",
    "By using the `stepSimulation` function, time in the simulation space advances by the amount set with `setTimeStep`.  \n",
    "Here, we are running the simulation for 200 time steps while giving speed commands to both wheels of the mobile robot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "ename": "",
     "evalue": "",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31mThe Kernel crashed while executing code in the current cell or a previous cell. \n",
      "\u001b[1;31mPlease review the code in the cell(s) to identify a possible cause of the failure. \n",
      "\u001b[1;31mClick <a href='https://aka.ms/vscodeJupyterKernelCrash'>here</a> for more info. \n",
      "\u001b[1;31mView Jupyter <a href='command:jupyter.viewOutput'>log</a> for further details."
     ]
    }
   ],
   "source": [
    "import time\n",
    "RIGHT_WHEEL_JOINT_IDX = 0\n",
    "LEFT_WHEEL_JOINT_IDX = 1\n",
    "for i in range(200):\n",
    "    pybullet.setJointMotorControl2(car_id, LEFT_WHEEL_JOINT_IDX, pybullet.VELOCITY_CONTROL, targetVelocity=10)\n",
    "    pybullet.setJointMotorControl2(car_id, RIGHT_WHEEL_JOINT_IDX, pybullet.VELOCITY_CONTROL, targetVelocity=10)\n",
    "    pybullet.stepSimulation()\n",
    "    time.sleep(time_step)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}