{
 "metadata": {
  "language": "Julia",
  "name": "",
  "signature": "sha256:5f6c8ab152f38b39757738142c5d4414cba6df073484926e33475b22310db861"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Base Code\n",
      "=========\n",
      "\n",
      "This represents the base code used in the traffic propagation models.\n",
      "\n",
      "## File Overview\n",
      "\n",
      "The files and their purpose are listed below"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "| File               | Purpose       |\n",
      "| ------------------ | ------------- |\n",
      "| Curves.jl          | Representation for lane centerline curves, which include interpolated values such as curvature and distance along the lane |\n",
      "| Features.jl        | A module defining all features. Can be used to extract features from original dataset |\n",
      "| FilesystemUtils.jl | A set of filesystem utilities |\n",
      "| StreetMap.jl       | A module defining the street network used in this work. Allows for computing lane projections and making queries relative to the road network |\n",
      "| Trajdata.jl        | The base data class storing processed source data |\n",
      "| splines.jl         | Used in Curves.jl to represent / fit splines. |"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The primary files are Julia modules and can thus be imported freely for use."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "using Features\n",
      "using Trajdata\n",
      "using StreetMap\n",
      "using FilesystemUtils\n",
      "using Curves"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Some potentially sensitive Bosch-specific segements of code have been removed. "
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Features\n",
      "\n",
      "Allows for the extraction of feature values for cars in scenes.\n",
      "\n",
      "The primary use case for Features is to extract them from a `PrimaryDataset` object. The `get()` function is readily available for thus purpose. \n",
      "\n",
      "Each feature is a separate type extending `AbstractFeature`. A feature's type is `::Feature_NAME`, for example: `::Feature_Speed`. A corresponding const type alias is exported using the all caps name, for example: `SPEED`. Multiple dispatch allows for the easy extraction of features from the data:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "get(SPEED, primary_dataset, street_network, car_index, valid_frame_index)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "`get()` always returns a `Float64`. \n",
      "\n",
      "Additional information for each type is also available:\n",
      "\n",
      "`description()` - a string describing the feature\n",
      "\n",
      "`units()` - a string describing the units, ex: \"m\"\n",
      "\n",
      "`isint()` and `isbool()` - whether the variable is boolean and/or discrete\n",
      "\n",
      "`upperbound()` and `lowerbound()` - the max and min value of the feature, -Inf or Inf if none exists\n",
      "\n",
      "`couldna()` - whether the feature could produce `NA` - represented internally by `NA_ALIAS = Inf`\n",
      "\n",
      "`symbol()` - the `Symbol` for the feature\n",
      "\n",
      "`lsymbol()` - a `LaTeXString` from the feature\n",
      "\n",
      "`sym2ftr()` - get the `Feature` from its `Symbol`"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Features are constructed using Julia's metaprogramming capabilities via the `create_feature_basics()` function. `get()` is implemented for each feature by hand."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Trajdata\n",
      "\n",
      "Provides the `PrimaryDataset` type used to represent the processed driving data. Exports a large number of functions related to extracting and manipulating the driving data.\n",
      "\n",
      "Of greatest importance are the following concepts:\n",
      "\n",
      "- `frameind` is the frame index, or the index in the original dataset where frameind = 1 is the first frame and frameind = 2 is the second frame, 0.05 seconds later\n",
      "\n",
      "- `validfind` is a valid frame index. Frames at the beginning and end of the dataset are off the highway. Validfind = 1 is the first frame on the highway, validfind = 2 is the second, etc. They are almost always consecutive.\n",
      "\n",
      "- `carind` refers to the index of a vehicle in a particular frame. The ego vehicle always has index `CARIND_EGO = -1`. If there are 5 other vehicles in a frame, they will have index 0, 1, 2, 3, and 4.\n",
      "\n",
      "- `carid` refers to the identification number of a vehicle, provided by Bosch. The ego vehicle always has id `CARID_EGO = -1`. A vehicle's id number will not change during a drive and should be consistent across frames."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## StreetMap\n",
      "\n",
      "Provides a data structure used to represent the street network structure. It is based off of the Road Network Definition Format developed for the DARPA Grand Challenge. This structure, however, is tiled into 250 x 250 meter chunks for faster lookups.\n",
      "\n",
      "The `StreetNetwork` type contains both a tile dictionary and a graph connecting nodes. Each lane centerline is represented by a set of nodes with roughly 1 meter spacing. For additional details see the source code.\n",
      "\n",
      "One of the primary purposes of a `StreetNetwork` is to allow for the projection of a vehicle position and orientation to a lane-relative frame. This is achieved using `project_point_to_streetmap()` and related functions."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Example:\n",
      "![alt text](zoom_sn.png \"Zoomed-in network example\")"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [],
     "language": "python",
     "metadata": {},
     "outputs": []
    }
   ],
   "metadata": {}
  }
 ]
}