1. Robot Moving and Sensing.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Robot Class\n",
    "\n",
    "In this project, we'll be localizing a robot in a 2D grid world. The basis for simultaneous localization and mapping (SLAM) is to gather information from a robot's sensors and motions over time, and then use information about measurements and motion to re-construct a map of the world.\n",
    "\n",
    "### Uncertainty\n",
    "\n",
    "As you've learned, robot motion and sensors have some uncertainty associated with them. For example, imagine a car driving up hill and down hill; the speedometer reading will likely overestimate the speed of the car going up hill and underestimate the speed of the car going down hill because it cannot perfectly account for gravity. Similarly, we cannot perfectly predict the *motion* of a robot. A robot is likely to slightly overshoot or undershoot a target location.\n",
    "\n",
    "In this notebook, we'll look at the `robot` class that is *partially* given to you for the upcoming SLAM notebook. First, we'll create a robot and move it around a 2D grid world. Then, **you'll be tasked with defining a `sense` function for this robot that allows it to sense landmarks in a given world**! It's important that you understand how this robot moves, senses, and how it keeps track of different landmarks that it sees in a 2D grid world, so that you can work with it's movement and sensor data.\n",
    "\n",
    "---\n",
    "\n",
    "Before we start analyzing robot motion, let's load in our resources and define the `robot` class. You can see that this class initializes the robot's position and adds measures of uncertainty for motion. You'll also see a `sense()` function which is not yet implemented, and you will learn more about that later in this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# import some resources\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import random\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# the robot class\n",
    "class robot:\n",
    "\n",
    "    # --------\n",
    "    # init: \n",
    "    #   creates a robot with the specified parameters and initializes \n",
    "    #   the location (self.x, self.y) to the center of the world\n",
    "    #\n",
    "    def __init__(self, world_size = 100.0, measurement_range = 30.0,\n",
    "                 motion_noise = 1.0, measurement_noise = 1.0):\n",
    "        self.measurement_noise = 0.0\n",
    "        self.world_size = world_size\n",
    "        self.measurement_range = measurement_range\n",
    "        self.x = world_size / 2.0\n",
    "        self.y = world_size / 2.0\n",
    "        self.motion_noise = motion_noise\n",
    "        self.measurement_noise = measurement_noise\n",
    "        self.landmarks = []\n",
    "        self.num_landmarks = 0\n",
    "\n",
    "\n",
    "    # returns a positive, random float\n",
    "    def rand(self):\n",
    "        return random.random() * 2.0 - 1.0\n",
    "\n",
    "\n",
    "    # --------\n",
    "    # move: attempts to move robot by dx, dy. If outside world\n",
    "    #       boundary, then the move does nothing and instead returns failure\n",
    "    #\n",
    "    def move(self, dx, dy):\n",
    "\n",
    "        x = self.x + dx + self.rand() * self.motion_noise\n",
    "        y = self.y + dy + self.rand() * self.motion_noise\n",
    "\n",
    "        if x < 0.0 or x > self.world_size or y < 0.0 or y > self.world_size:\n",
    "            return False\n",
    "        else:\n",
    "            self.x = x\n",
    "            self.y = y\n",
    "            return True\n",
    "    \n",
    "\n",
    "    # --------\n",
    "    # sense: returns x- and y- distances to landmarks within visibility range\n",
    "    #        because not all landmarks may be in this range, the list of measurements\n",
    "    #        is of variable length. Set measurement_range to -1 if you want all\n",
    "    #        landmarks to be visible at all times\n",
    "    #\n",
    "    \n",
    "    ## TODO: complete the sense function\n",
    "    def sense(self):\n",
    "        ''' This function does not take in any parameters, instead it references internal variables\n",
    "            (such as self.landamrks) to measure the distance between the robot and any landmarks\n",
    "            that the robot can see (that are within its measurement range).\n",
    "            This function returns a list of landmark indices, and the measured distances (dx, dy)\n",
    "            between the robot's position and said landmarks.\n",
    "            This function should account for measurement_noise and measurement_range.\n",
    "            One item in the returned list should be in the form: [landmark_index, dx, dy].\n",
    "            '''\n",
    "           \n",
    "        measurements = []\n",
    "        \n",
    "        ## TODO: iterate through all of the landmarks in a world\n",
    "        for i, landmark in enumerate(self.landmarks):\n",
    "        ## TODO: For each landmark\n",
    "        ## 1. compute dx and dy, the distances between the robot and the landmark\n",
    "            dx = landmark[0] - self.x\n",
    "            dy = landmark[1] - self.y\n",
    "        ## 2. account for measurement noise by *adding* a noise component to dx and dy\n",
    "        ##    - The noise component should be a random value between [-1.0, 1.0)*measurement_noise\n",
    "        ##    - Feel free to use the function self.rand() to help calculate this noise component\n",
    "        ##    - It may help to reference the `move` function for noise calculation\n",
    "            dx = dx + self.rand()*self.measurement_noise\n",
    "            dy = dy + self.rand()*self.measurement_noise\n",
    "        ## 3. If either of the distances, dx or dy, fall outside of the internal var, measurement_range\n",
    "        ##    then we cannot record them; if they do fall in the range, then add them to the measurements list\n",
    "        ##    as list.append([index, dx, dy]), this format is important for data creation done later\n",
    "            if abs(dx) <= self.measurement_range and abs(dy) <= self.measurement_range:\n",
    "                measurements.append([i, dx, dy])\n",
    "        ## TODO: return the final, complete list of measurements\n",
    "        return measurements\n",
    "\n",
    "    \n",
    "    # --------\n",
    "    # make_landmarks: \n",
    "    # make random landmarks located in the world\n",
    "    #\n",
    "    def make_landmarks(self, num_landmarks):\n",
    "        self.landmarks = []\n",
    "        for i in range(num_landmarks):\n",
    "            self.landmarks.append([round(random.random() * self.world_size),\n",
    "                                   round(random.random() * self.world_size)])\n",
    "        self.num_landmarks = num_landmarks\n",
    "    \n",
    "    \n",
    "    # called when print(robot) is called; prints the robot's location\n",
    "    def __repr__(self):\n",
    "        return 'Robot: [x=%.5f y=%.5f]'  % (self.x, self.y)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Define a world and a robot\n",
    "\n",
    "Next, let's instantiate a robot object. As you can see in `__init__` above, the robot class takes in a number of parameters including a world size and some values that indicate the sensing and movement capabilities of the robot.\n",
    "\n",
    "In the next example, we define a small 10x10 square world, a measurement range that is half that of the world and small values for motion and measurement noise. These values will typically be about 10 times larger, but we ust want to demonstrate this behavior on a small scale. You are also free to change these values and note what happens as your robot moves!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "world_size         = 10.0    # size of world (square)\n",
    "measurement_range  = 5.0     # range at which we can sense landmarks\n",
    "motion_noise       = 0.2      # noise in robot motion\n",
    "measurement_noise  = 0.2      # noise in the measurements\n",
    "\n",
    "# instantiate a robot, r\n",
    "r = robot(world_size, measurement_range, motion_noise, measurement_noise)\n",
    "\n",
    "# print out the location of r\n",
    "print(r)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualizing the World\n",
    "\n",
    "In the given example, we can see/print out that the robot is in the middle of the 10x10 world at (x, y) = (5.0, 5.0), which is exactly what we expect!\n",
    "\n",
    "However, it's kind of hard to imagine this robot in the center of a world, without visualizing the grid itself, and so in the next cell we provide a helper visualization function, `display_world`, that will display a grid world in a plot and draw a red `o` at the location of our robot, `r`. The details of how this function wors can be found in the `helpers.py` file in the home directory; you do not have to change anything in this `helpers.py` file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# import helper function\n",
    "from helpers import display_world\n",
    "\n",
    "# define figure size\n",
    "plt.rcParams[\"figure.figsize\"] = (5,5)\n",
    "\n",
    "# call display_world and display the robot in it's grid world\n",
    "print(r)\n",
    "display_world(int(world_size), [r.x, r.y])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Movement\n",
    "\n",
    "Now you can really picture where the robot is in the world! Next, let's call the robot's `move` function. We'll ask it to move some distance `(dx, dy)` and we'll see that this motion is not perfect by the placement of our robot `o` and by the printed out position of `r`. \n",
    "\n",
    "Try changing the values of `dx` and `dy` and/or running this cell multiple times; see how the robot moves and how the uncertainty in robot motion accumulates over multiple movements.\n",
    "\n",
    "#### For a `dx` = 1, does the robot move *exactly* one spot to the right? What about `dx` = -1? What happens if you try to move the robot past the boundaries of the world?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# choose values of dx and dy (negative works, too)\n",
    "dx = 1\n",
    "dy = 2\n",
    "r.move(dx, dy)\n",
    "\n",
    "# print out the exact location\n",
    "print(r)\n",
    "\n",
    "# display the world after movement, not that this is the same call as before\n",
    "# the robot tracks its own movement\n",
    "display_world(int(world_size), [r.x, r.y])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Landmarks\n",
    "\n",
    "Next, let's create landmarks, which are measurable features in the map. You can think of landmarks as things like notable buildings, or something smaller such as a tree, rock, or other feature.\n",
    "\n",
    "The robot class has a function `make_landmarks` which randomly generates locations for the number of specified landmarks. Try changing `num_landmarks` or running this cell multiple times to see where these landmarks appear. We have to pass these locations as a third argument to the `display_world` function and the list of landmark locations is accessed similar to how we find the robot position `r.landmarks`. \n",
    "\n",
    "Each landmark is displayed as a purple `x` in the grid world, and we also print out the exact `[x, y]` locations of these landmarks at the end of this cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# create any number of landmarks\n",
    "num_landmarks = 3\n",
    "r.make_landmarks(num_landmarks)\n",
    "\n",
    "# print out our robot's exact location\n",
    "print(r)\n",
    "\n",
    "# display the world including these landmarks\n",
    "display_world(int(world_size), [r.x, r.y], r.landmarks)\n",
    "\n",
    "# print the locations of the landmarks\n",
    "print('Landmark locations [x,y]: ', r.landmarks)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sense\n",
    "\n",
    "Once we have some landmarks to sense, we need to be able to tell our robot to *try* to sense how far they are away from it. It will be up t you to code the `sense` function in our robot class.\n",
    "\n",
    "The `sense` function uses only internal class parameters and returns a list of the the measured/sensed x and y distances to the landmarks it senses within the specified `measurement_range`. \n",
    "\n",
    "### TODO: Implement the `sense` function \n",
    "\n",
    "Follow the `##TODO's` in the class code above to complete the `sense` function for the robot class. Once you have tested out your code, please **copy your complete `sense` code to the `robot_class.py` file in the home directory**. By placing this complete code in the `robot_class` Python file, we will be able to refernce this class in a later notebook.\n",
    "\n",
    "The measurements have the format, `[i, dx, dy]` where `i` is the landmark index (0, 1, 2, ...) and `dx` and `dy` are the measured distance between the robot's location (x, y) and the landmark's location (x, y). This distance will not be perfect since our sense function has some associated `measurement noise`.\n",
    "\n",
    "---\n",
    "\n",
    "In the example in the following cell, we have a given our robot a range of `5.0` so any landmarks that are within that range of our robot's location, should appear in a list of measurements. Not all landmarks are guaranteed to be in our visibility range, so this list will be variable in length.\n",
    "\n",
    "*Note: the robot's location is often called the **pose** or `[Pxi, Pyi]` and the landmark locations are often written as `[Lxi, Lyi]`. You'll see this notation in the next notebook.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# try to sense any surrounding landmarks\n",
    "measurements = r.sense()\n",
    "\n",
    "# this will print out an empty list if `sense` has not been implemented\n",
    "print(measurements)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Refer back to the grid map above. Do these measurements make sense to you? Are all the landmarks captured in this list (why/why not)?**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Data\n",
    "\n",
    "#### Putting it all together\n",
    "\n",
    "To perform SLAM, we'll collect a series of robot sensor measurements and motions, in that order, over a defined period of time. Then we'll use only this data to re-construct the map of the world with the robot and landmar locations. You can think of SLAM as peforming what we've done in this notebook, only backwards. Instead of defining a world and robot and creating movement and sensor data, it will be up to you to use movement and sensor measurements to reconstruct the world!\n",
    "\n",
    "In the next notebook, you'll see this list of movements and measurements (which you'll use to re-construct the world) listed in a structure called `data`. This is an array that holds sensor measurements and movements in a specific order, which will be useful to call upon when you have to extract this data and form constraint matrices and vectors.\n",
    "\n",
    "`data` is constructed over a series of time steps as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "data = []\n",
    "\n",
    "# after a robot first senses, then moves (one time step)\n",
    "# that data is appended like so:\n",
    "data.append([measurements, [dx, dy]])\n",
    "\n",
    "# for our example movement and measurement\n",
    "print(data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# in this example, we have only created one time step (0)\n",
    "time_step = 0\n",
    "\n",
    "# so you can access robot measurements:\n",
    "print('Measurements: ', data[time_step][0])\n",
    "\n",
    "# and its motion for a given time step:\n",
    "print('Motion: ', data[time_step][1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Final robot class\n",
    "\n",
    "Before moving on to the last notebook in this series, please make sure that you have copied your final, completed `sense` function into the `robot_class.py` file in the home directory. We will be using this file in the final implementation of slam!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:cvnd_1]",
   "language": "python",
   "name": "conda-env-cvnd_1-py"
  },
  "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}