Initial commit

Co-authored-by: Ananta Pandey <[email protected]>
Co-authored-by: Eric Sebastián Soto <[email protected]>
Co-authored-by: Chris Anderson <[email protected]>
Co-authored-by: Samara Trilling <[email protected]>
Co-authored-by: Douwe Osinga <[email protected]>

.circleci/config.yml

@@ -0,0 +1,45 @@
+# Python CircleCI 2.0 configuration file
+#
+# Check https://circleci.com/docs/2.0/language-python/ for more details
+#
+version: 2
+jobs:
+  build:
+    docker:
+      - image: danvk/yarn-python36:0.0.1
+
+    working_directory: ~/repo
+
+    steps:
+      - checkout
+
+      # Download and cache dependencies
+      - restore_cache:
+          keys:
+          - v1-dependencies-{{ checksum "requirements.txt" }}-{{ checksum "yarn.lock" }}
+          # fallback to using the latest cache if no exact match is found
+          - v1-dependencies-
+
+      - run:
+          name: install dependencies
+          command: |
+            python3.6 -m venv venv
+            . venv/bin/activate
+            pip install -r requirements.txt
+            yarn
+
+      - save_cache:
+          paths:
+            - ./venv
+            - ~/.yarn
+            - ~/.cache/yarn
+          key: v1-dependencies-{{ checksum "requirements.txt" }}-{{ checksum "yarn.lock" }}
+
+      # run tests!
+      - run:
+          name: run tests
+          command: |
+            . venv/bin/activate
+            flake8
+            nosetests
+            yarn test

.circleci/images/primary/Dockerfile

@@ -0,0 +1,9 @@
+FROM kkarczmarczyk/node-yarn:8.0
+
+# Install python3.6 from source.
+RUN wget https://www.python.org/ftp/python/3.6.3/Python-3.6.3.tgz && \
+  tar xvf Python-3.6.3.tgz && \
+  cd Python-3.6.3 && \
+  ./configure --enable-optimizations && \
+  make -j8 && \
+  make altinstall

.gitignore

@@ -0,0 +1,15 @@
+*__pycache__*
+output/*
+.vscode
+dist
+
+node_modules
+
+# Generated static files
+*.bundle.js
+*.bundle.js.map
+*.pbf
+*.egg-info
+
+# MacOS
+.DS_Store

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "bracketSpacing": false,
+  "jsxBracketSameLine": true
+}

MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include sumo_web3d *
+recursive-exclude sumo_web3d *.pyc
+

README.md

@@ -0,0 +1,221 @@
+# SUMO-Web3D
+
+![Screenshot of SUMO-Web3D showing an intersection with cars and a bus](screenshots/acosta-ixn.png)
+
+Visualization of [SUMO][] in 3D in a web browser using TraCI and three.js.
+
+## Setup
+
+SUMO-Web3D is available on PyPI:
+
+    pip install sumo-web3d
+    sumo-web3d
+    # then open http://localhost:5000 in your browser
+
+You'll need to have SUMO installed and the `SUMO_HOME` environment variable set.
+
+To run your own simulations, use the `-c` command line argument:
+
+    sumo-web3d -c path/to/your/simulation.sumocfg
+
+![Screenshot of Bologna Acosta simulation](screenshots/acosta-wideview.png)
+
+## Usage
+
+When you start `sumo-web3d`, it runs `sumo` as a subprocess and starts your simulation.
+
+You can interact with the visualization using the mouse or the keyboard:
+
+- Mouse
+    - Click and drag to pan around the visualization.
+    - Right-click and drag to rotate.
+    - Use the mouse wheel to zoom in and out.
+- Keyboard
+    - `h`/`l` or `a`/`d` pan the camera left and right
+    - `j`/`k` or `w`/`s` move the camera forward or backward
+    - `↑`/`↓` rotate the camera up or down
+    - `←`/`→` rotate the camera left and right
+    - `ctrl` + `↑`/`↓` move the camera up and down
+
+You can send valid arguments and flags to the SUMO executable.
+
+    sumo-web3d --sumo-args '--scale 10 --step-length 0.1'
+
+* `--scale 10`:
+    Increase the number of vehicles defined in the route file by 10x.
+* `--step-length 0.1`:
+    Each frame should advance by 0.1s, rather than the default of 1s. This results in smoother animation.
+
+![Screenshot of Toronto](screenshots/toronto-wideview.png)
+
+## Development
+
+SUMO-Web3D is written in Python (Python3) and TypeScript.
+
+To get going, we recommend setting up a Python virtual environment:
+
+    python -m venv $name_of_virtual_environment
+    source $name_of_virtual_environment/bin/activate
+
+Then install both Python and JS dependencies:
+
+    pip install -r requirements.txt
+    yarn
+
+Download SUMO following the OS-specific [build instructions][downloading] in the SUMO
+documentation. Note that pre-compiled downloads exist for Windows and Linux, but Mac
+users will likely have to download and compile their own binaries. If you're a Mac user,
+watch out for any yellow "this is broken, do something else" messages to save some time.
+
+After downloading SUMO, you'll need to declare the installation directory as an environment
+variable (`$SUMO_HOME`) so the generation scripts have access to the tools included with your
+installation. To do this, include a line such as the following to your `~/.bash_profile` (adjust
+it depending on your path and directory name):
+
+    export SUMO_HOME=$HOME/git/sumo-0.31.0
+
+### Up and Running
+
+Build the client-side JavaScript bundle:
+
+    yarn webpack
+
+Run the server:
+
+    python sumo_web3d/sumo_web3d.py
+
+Then visit http://localhost:5000/ to view the built-in scenarios.
+
+If you want to load a specific SUMO configuration, use the `-c` flag:
+
+    python sumo_web3d/sumo_web3d.py -c path/to/your/scenario.sumocfg
+
+If you'd like to iterate on the frontend code, run:
+
+    yarn develop
+
+instead of `yarn webpack` and `python sumo_web3d/sumo_web3d.py`.
+
+![Screenshot of Toronto's Gardiner elevated highway](screenshots/toronto-gardiner.png)
+
+### Architecture
+
+There are three main components of the SUMO-Web3D visualization:
+
+1. **SUMO**
+    SUMO-Web3D runs SUMO as a subprocess. Any simulation that runs in SUMO should run with
+    SUMO-Web3D.
+2. **SUMO-Web3D Server**
+    The SUMO-Web3D server is a python process that communicates with SUMO using TraCI.
+    It maintains a list of vehicles and people in the simulation and sends frame-by-frame
+    diffs to the client. It also reformats SUMO network files for consumption by the client.
+3. **SUMO-Web3D Client**
+    The visualization itself is written using TypeScript, React and three.js. It reads the
+    network and shape data for the simulation and produces a 3D scene. It then applies the
+    updates as they come in over the network. Communication with the server happens via a
+    websocket.
+
+### Adding a new scenario to the server
+
+You can add custom SUMO simulations to appear in the scenario dropdown. In order to so, you must
+update the `scenarios.json` file with the required information. Any scenario must have a name that
+(when hyphen-cased) is unique from all the others. The scenario must also have a valid path to
+the `.sumocfg` file.
+
+    [
+        {
+            "name": "pedestring striping",
+            "description": "Demonstration of pedestrian congestion in crosswalks",
+            "config_file": "tests/pedestrian-striping/test.sumocfg"
+        },
+        {
+            "name": "person_number",
+            "description": "Demonstration of a person gettin on and off the bus",
+            "config_file": "tests/person_number/person_number.sumocfg"
+        }
+    ]
+
+### Adding more SUMO unit tests
+
+For development, it's often easier to use SUMO unit tests rather than a larger simulation like
+Toronto. To do so, clone SUMO and build the examples:
+
+    git clone https://github.com/planetsumo/sumo.git
+    cd sumo
+
+If on Mac, install dependencies:
+
+    brew install automake xerces-c gdal cmake libtool pkg-config
+    brew cask install xquartz
+    brew install fox
+
+And then build:
+
+    cmake CMakeLists.txt
+    make -f Makefile.cvs
+    export CPPFLAGS="-I/opt/X11/include $CPPFLAGS"; export LDFLAGS="-L/opt/X11/lib $LDFLAGS"
+    ./configure && make
+    make examples
+
+If that didn't work, check [SUMO build documentation][sumobuild] to debug.
+
+Then to add the desired scenario to the scenario.json file, e.g.:
+
+    {
+        "name": "cross3ltl",
+        "description": "An interesection with multi-lane roads and traffic lights",
+        "config_file": "$SUMO_HOME/examples/sumo/simple_nets/cross/cross3ltl/test.sumocfg"
+    }
+
+When you next run the microsim, the unit test should be available:
+
+    python sumo_web3d/sumo_web3d.py --sumo-args '--step-length 0.1 --scale 3'
+
+### Feature Overview
+
+The visualization has several core features useful for exploring and debugging. Developers should
+verify these features work as expected before submitting a pull request.
+
+1. **Scenario dropdown:**
+    The sidebar contains a dropdown field that lets you seamlessly switch
+    among different SUMO configurations without restarting the server. Selecting a scenario will
+    reload the page and start the new scenario from timestamp 0.
+1. **Simulation controls:**
+    The sidebar contains controls for pausing/resuming and canceling/restarting the simulation. A
+    slider lets you control the speed.
+1. **Camera Controls:**
+    You can zoom and pan around the simulation in 3D with a keyboard, mouse, or trackpad.
+1. **Quick Find panel:**
+    This panel contains buttons that will move the camera to a random object in the simulation.
+    You can choose from any type of supported vehicle, pedestrians, and traffic lights. If smoke
+    testing, be sure to try out all three since they work slightly differently.
+1. **Statistics:**
+    The sidebar displays the following statistics to describe the current state of simulation:
+    vehicle counts, payload size, and timestamp.
+1. **Click details:**
+    When you click on a point, the sidebar will display information about the objects at that
+    point, including edges, vehicles, and links to view that point on other mapping platforms.
+    Clicking on a vehicle or pedestrian will also display in the sidebar some live-updating
+    details about their position.
+1. **Vehicle following:**
+    When you click on a vehicle or pedestrian, the click details in the sidebar will contain a
+    button to follow that vehicle. Following a vehicle locks the camera on that vehicle’s path
+    until you unfollow it or it is removed from the scene.
+1. **Show route:**
+    When you click on a vehicle, you will also see in the sidebar an option to show its route.
+    Toggling this option will highglight the vehicle's route from starting edge to destination edge.
+1. **Memory management:**
+    Vehicles and pedestrians are deleted in memory as they complete their routes. The simulation
+    should be able to reach completion without crashing or freezing. To verify, run the Toronto
+    simulation until all vehicles and pedestrians have arrrived at their destination. When adding
+    new scenarios, run them till their simulation end time (managed by duarouter) to check against
+    leaks.
+
+
+[sumo]: http://sumo.dlr.de/wiki/SUMO_User_Documentation
+[downloading]: http://sumo.dlr.de/wiki/Developer/Main#Build_instructions
+[xquartz]: https://www.xquartz.org/
+[sumobuild]: https://github.com/planetsumo/sumo#build-and-installation
+[extract]: https://mapzen.com/data/metro-extracts/metro/toronto_canada/101735835/Toronto/
+[osmconvert]: http://wiki.openstreetmap.org/wiki/Osmconvert
+[design-doc]: https://docs.google.com/document/d/1JTLETGdZMA2y8b9HGhedPcYFg6SQ4NSqdXtSmFKIlkI/edit

frontend/declarations/chai-roughly.d.ts

@@ -0,0 +1,10 @@
+// Copyright 2018 Sidewalk Labs | http://www.eclipse.org/legal/epl-v20.html
+declare namespace Chai {
+  interface Assertion {
+    roughly: RoughAssertion;
+  }
+}
+
+interface RoughAssertion extends Chai.Assertion {
+  (tolerance: number): Chai.Assertion;
+}

frontend/declarations/dat.gui.d.ts

@@ -0,0 +1,2 @@
+// Copyright 2018 Sidewalk Labs | http://www.eclipse.org/legal/epl-v20.html
+declare module 'dat.gui/build/dat.gui.js';

frontend/declarations/stats.d.ts

@@ -0,0 +1,28 @@
+// Copyright 2018 Sidewalk Labs | http://www.eclipse.org/legal/epl-v20.html
+declare class Stats {
+  constructor();
+  REVISION: number;
+  dom: HTMLDivElement;
+
+  /**
+   * @param value 0:fps, 1: ms, 2: mb, 3+: custom
+   */
+  showPanel(value: number): void;
+  begin(): void;
+  end(): number;
+  update(): void;
+
+  addPanel(panel: Stats.Panel): Stats.Panel;
+}
+
+declare namespace Stats {
+  class Panel {
+    constructor(name: string, foregroundColor: string, backgroundColor: string);
+    dom: HTMLCanvasElement;
+    update(value: number, maxValue: number): void;
+  }
+}
+
+declare module 'stats.js' {
+  export = Stats;
+}

frontend/declarations/string-hash.d.ts

@@ -0,0 +1,6 @@
+// Copyright 2018 Sidewalk Labs | http://www.eclipse.org/legal/epl-v20.html
+declare var stringHash: (input: string) => number;
+
+declare module 'string-hash' {
+  export = stringHash;
+}

frontend/declarations/three-mtl-loader.d.ts

@@ -0,0 +1,2 @@
+// Copyright 2018 Sidewalk Labs | http://www.eclipse.org/legal/epl-v20.html
+declare module 'three-mtl-loader';