{"id":20200445,"url":"https://github.com/da-luce/cornell-autobike","last_synced_at":"2026-02-27T13:42:45.409Z","repository":{"id":157649837,"uuid":"556964090","full_name":"da-luce/cornell-autobike","owner":"da-luce","description":"Codebase of the Cornell Autonomous Bicycle Team","archived":false,"fork":false,"pushed_at":"2025-04-28T21:44:00.000Z","size":167456,"stargazers_count":1,"open_issues_count":10,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-28T22:52:06.240Z","etag":null,"topics":["autonomous-vehicles","cornell","docker","machine-learning","mapping","matplotlib","numba","numpy","osmnx","pytest","python3","qlearning","robotics","scipy","tk"],"latest_commit_sha":null,"homepage":"https://www.cuautobike.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/da-luce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-24T21:05:30.000Z","updated_at":"2024-11-14T00:03:57.000Z","dependencies_parsed_at":"2023-09-22T04:46:24.929Z","dependency_job_id":"71ed77df-0dbf-4193-944e-e4f7b719d568","html_url":"https://github.com/da-luce/cornell-autobike","commit_stats":null,"previous_names":["da-luce/q-learning","da-luce/cornell-autobike"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/da-luce/cornell-autobike","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/da-luce%2Fcornell-autobike","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/da-luce%2Fcornell-autobike/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/da-luce%2Fcornell-autobike/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/da-luce%2Fcornell-autobike/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/da-luce","download_url":"https://codeload.github.com/da-luce/cornell-autobike/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/da-luce%2Fcornell-autobike/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267127948,"owners_count":24040154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-26T02:00:08.937Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autonomous-vehicles","cornell","docker","machine-learning","mapping","matplotlib","numba","numpy","osmnx","pytest","python3","qlearning","robotics","scipy","tk"],"created_at":"2024-11-14T04:43:54.415Z","updated_at":"2026-02-27T13:42:40.364Z","avatar_url":"https://github.com/da-luce.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Autobike Software\n\n[![codecov](https://codecov.io/gh/da-luce/cornell-autobike/graph/badge.svg?token=DG2EJ0SJPB)](https://codecov.io/gh/da-luce/cornell-autobike)\n![Test Status](https://github.com/da-luce/cornell-autobike/actions/workflows/test.yml/badge.svg)\n\n- [Autobike Software](#autobike-software)\n  - [Important Links](#important-links)\n  - [Installation](#installation)\n    - [MacOS](#macos)\n    - [Linux](#linux)\n    - [Windows](#windows)\n    - [X Window Forwarding](#x-window-forwarding)\n      - [MacOS](#macos-1)\n      - [Linux](#linux-1)\n      - [Windows](#windows-1)\n  - [Running the Software](#running-the-software)\n    - [1. Build the Image](#1-build-the-image)\n    - [2. Run in a Container](#2-run-in-a-container)\n    - [3. Working with ROS2](#3-working-with-ros2)\n      - [Getting Started](#getting-started)\n      - [Building](#building)\n      - [Running a Package](#running-a-package)\n      - [Visualizing with ROSBoard](#visualizing-with-rosboard)\n      - [Other ROS GUIs](#other-ros-guis)\n    - [4. Testing and Code Quality](#4-testing-and-code-quality)\n  - [Best Practices](#best-practices)\n    - [Adding Dependencies](#adding-dependencies)\n    - [Directory Structure and Testing](#directory-structure-and-testing)\n  - [Architecture](#architecture)\n  - [Infrastructure](#infrastructure)\n    - [Why Docker?](#why-docker)\n    - [Why ROS?](#why-ros)\n  - [Git Basics](#git-basics)\n    - [Git Resources](#git-resources)\n  - [Citations](#citations)\n\n---\n\n## Important Links\n\n- [Software Planning Repo](https://github.com/da-luce/Autobike-Software-Planning/)\n- [Vision Repo](https://github.com/da-luce/Autobike-Vision)\n- [Old Navigation Repo](https://github.com/CornellAutonomousBikeTeam/Bike-Simulation-python)\n- [Navigation Repo](https://github.com/da-luce/cornell-autobike)\n- [Autobike Google Drive](https://drive.google.com/drive/folders/0B9FAXBSQ_mBLU25zc3h3VmR3MXc?resourcekey=0-_FN2UezNOB-4-eSO1g_xPw\u0026usp=sharing)\n- [Slack Channel](https://cuautonomousbike.slack.com/archives/C05PP2TQFCG)\n\n---\n\n## Installation\n\n### MacOS\n\n1. If not already installed, install [Homebrew](https://brew.sh/), a package\n   manager for MacOS and Linux\n2. Install Docker\n\n   ```text\n   brew install --cask docker\n   ```\n\n3. Open the newly installed _Docker Desktop_ application\n   1. You should be able to find it in the application folder\n   2. Otherwise, use Spotlight search (\u003ckbd\u003e⌘\u003c/kbd\u003e + \u003ckbd\u003espace\u003c/kbd\u003e) and\n      search for \"Docker\"\n4. Select \"Use recommended settings\"\n5. Skip remaining steps if possible\n\n### Linux\n\n1. See [Docker install documentation](https://docs.docker.com/engine/install/)\n   (ask Ari)\n\n### Windows\n\n1. See [Docker install documentation](https://docs.docker.com/engine/install/)\n   (untested)\n\n### X Window Forwarding\n\nThis is primarily for reference, and if you are running MacOS then you should be all set.\n\n#### MacOS\n\n1. Install [XQuartz](https://www.xquartz.org/) via Homebrew\n\n    ```text\n    brew install --cask xquartz\n    ```\n\n2. Logout and login of your Mac to activate XQuartz as default X11 server\n3. Open XQuartz\n\n    ```text\n    open -a XQuartz\n    ```\n\n4. Go to Security Settings (Menu Bar -\u003e XQuartz -\u003e Settings -\u003e Security Settings)\n   and ensure that \"Allow connections from network clients\" is on\n5. Restart your laptop (FIXME: this step may not be necessary?)\n6. Allow X11 forwarding from localhost via xhost\n\n    ```text\n    xhost + localhost\n    ```\n\n  \u003e [!IMPORTANT]\n  \u003e This must be run in the xterm window opened by default by XQuartz _every time_ XQuartz is started\n\n7. Run a command that invokes a GUI via `docker compose`, e.g.\n\n    ```text\n    docker compose run autobike python3 src/unrosified/state_pred/bike_sim.py\n    ```\n\n    FIXME: while we are switching over to ROS, this command probably won't work :(\n\n  \u003e [!NOTE]\n  \u003e If you are using `docker run` (not recommended), you need to add the follow option:\n  \u003e\n  \u003e ```text\n  \u003e --env DISPLAY=host.docker.internal:0\n  \u003e ```\n  \u003e\n  \u003e This is already provided in [`docker-compose.yml`](./docker-compose.yml), so\n  \u003e there is no need to pass any flags when using `docker compose`.\n\n#### Linux\n\nIn _theory_ this should be easier as most distros already use Xwindows,\nbut I know for a fact that the steps differ compared to Mac.\n\nMay have to bind this volume:\n\n```text\n--volume=\"$HOME/.Xauthority:/root/.Xauthority:rw\"\n```\n\nMay have to set\n\n```text\n--net=host\n```\n\nor\n\n```text\n--add-host=host.docker.internal:host-gateway\n```\n\nMay have to bind x11 socket:\n\n```text\n--volume /tmp/.X11-unix:/tmp/.X11-unix\n```\n\nMay have to set DISPLAY to\n\n`--env DISPLAY=unix$DISPLAY` or `--env DISPLAY=$DISPLAY`\n\nI'm not sure. Stack Overflow has a sea of possibilities.\n\nMay the odds be ever in your favor...\n\n#### Windows\n\nNo clue.\n\n---\n\n## Running the Software\n\n\u003e [!NOTE]\n\u003e These steps assume you are in the top level of your copy of the repository. If you\n\u003e haven't already, clone the repository onto your machine:\n\u003e\n\u003e ```bash\n\u003e git clone git@github.com:da-luce/cornell-autobike.git\n\u003e ```\n\n### 1. Build the Image\n\nIf it is your first time running the code with Docker or there have been changes made to the Dockerfile, you need to build the Docker image:\n\n```bash\ndocker build -t autobike:latest .\n```\n\nRunning `docker image ls` should now show this image, alongside any others you have built:\n\n```text\nREPOSITORY       TAG       IMAGE ID       CREATED         SIZE\nautobike         latest    121bfa1d2778   2 minutes ago   3.67GB\n```\n\n\u003e [!NOTE]\n\u003e Images can be deleted with `docker image rm`. Try adding the `--no-cache` flag if a rebuild isn't working as expected.\n\n### 2. Run in a Container\n\nTo create a [container](https://docs.docker.com/guides/docker-concepts/the-basics/what-is-a-container/) and run code, you can use one of the following techniques:\n\n- Interactive shell: `docker compose run --rm autobike`\n- One off command: `docker compose run --rm autobike \u003cyour command\u003e`\n\n[`docker compose`](./docker-compose.yml) specifies all the command line args you would normally run using plain `docker run`. The following notes are present if for some reason you are only using `docker run` and for explanation of the information in [`./docker-compose.yml`](./docker-compose.yml).\n\n\u003e [!NOTE]\n\u003e When no tag is selected, Docker uses the `latest` tag by [defualt](https://docs.docker.com/reference/cli/docker/image/tag/).\n\n\u003e [!NOTE]\n\u003e The [volume](https://docs.docker.com/engine/storage/volumes/) is mounted such that changes to your local code are immediately reflected in the container.\n\n\u003e [!WARNING]\n\u003e If the volume is not specified in the command line arguments, the container will run\n\u003e with the code that was present when the image was _built_ (this could be quite a while\n\u003e ago).\n\nExample of a one off command:\n\n```bash\ndocker compose run --rm autobike ros2 run demo_nodes_cpp talker\n```\n\n\u003e [!NOTE]\n\u003e Spinning up a new container isn't free--it can take a few moments. As such, an interactive shell is often the preferred method of development.\n\n\u003e [!TIP]\n\u003e Create an alias in your `.bashrc` (or whatever shell you are using) to avoid getting carpal tunnel\n\u003e\n\u003e ```bash\n\u003e alias autobike=\"docker compose run --rm autobike\"\n\u003e ```\n\u003e\n\u003e A quick way to do this if you are using Bash:\n\u003e\n\u003e ```bash\n\u003e echo \u003cabove_command\u003e \u003e\u003e ~/.bashrc\n\u003e ```\n\u003e\n\u003e Or Zsh (default on MacOS):\n\u003e\n\u003e ```bash\n\u003e echo \u003cabove_command\u003e \u003e\u003e ~/.zshrc\n\u003e ```\n\n### 3. Working with ROS2\n\n#### Getting Started\n\n- [What is ROS2?](https://github.com/ros2)\n- [Why are we using ROS?](#why-ros)\n- [ROS2 Docs](https://docs.ros.org/en/humble/Installation.html)\n\nROS2 utilizes packages and nodes to organize and manage modular components in a robotic system. Most importantly, it is widely supported and offers built-in compatibility with the sensors we use. We define our ROS packages in `./src`. See this [tutorial](https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Writing-A-Simple-Py-Publisher-And-Subscriber.html) on how to write your first package. The [waypoints](./src/waypoints/) package should serve as a good example of how to build a simple package.\n\n#### Building\n\nROS2 uses [colcon](https://colcon.readthedocs.io/en/released/) to build, test, and manage workspaces.\nIt can automatically detect package types (e.g., CMake, Python, etc.) and build them accordingly.\n\nTo build the project, run `build` in a container. You should see `colcon` build the packages:\n\n```text\nStarting \u003e\u003e\u003e waypoints\nFinished \u003c\u003c\u003c waypoints [0.59s]\n\nSummary: 1 package finished [0.88s]\n```\n\n\u003e [!NOTE]\n\u003e `build` is essentially an alias for `colcon build \u0026\u0026 source install/setup.bash`.\n\u003e\n\u003e WARNING: If not using the alias, this should all be done in the **top level directory**, or else you will have build artifacts all over the place. The alias forces the correct directory.\n\n\u003e [!TIP]\n\u003e If you encounter strange behavior, it’s often a good idea to clean your workspace before rebuilding: `rm -rf build/ install/ log/`. There is an alias `clean` to make this easier.\n\n#### Running a Package\n\nPackages may define an entry point to be run independently. For example: `ros2 run waypoints waypoints` runs the waypoint node. You should see the node generating waypoints:\n\n```text\n[INFO] [1723919908.828374763] [waypoints_node]: Waypoint routing node started\n[INFO] [1723919909.943448889] [waypoints_node]: Published path with 119 waypoints\n```\n\n\u003e [!IMPORTANT]\n\u003e Every time a package changes, you need to [rebuild](#building) it to see the changes (even python code!)\n\n#### Visualizing with ROSBoard\n\n1. Start both services in the background on the same network: `docker compose up -d`. The dev container will exit, this is alright. You should see something like:\n\n    ```text\n    [+] Running 3/3\n    ✔ Network cornell-autobike_rosnet  Created         0.0s\n    ✔ Container autobike_dev           Started         0.2s\n    ✔ Container rosboard               Started         0.4s\n    ```\n\n2. Attach to the dev container: `docker compose exec autobike bash`\n3. Run a demo: `ros2 run demo_nodes_cpp talker`. You should see something like this being logged in your terminal:\n\n    ```text\n    [INFO] [1723831327.616574043] [talker]: Publishing: 'Hello World: 1'\n    [INFO] [1723831328.618190002] [talker]: Publishing: 'Hello World: 2'\n    [INFO] [1723831329.618042586] [talker]: Publishing: 'Hello World: 3'\n    ```\n\n4. Go to [`localhost:8888`](http://localhost:8888/), and you should see the `/chatter` topic being logged in the dashboard!\n\n![rosboard demo](./assets/rosboard.png)\n\n5. Run `docker compose down` when you are done.\n\n\u003e [!NOTE]\n\u003e If you are struggling to get this working, try deleting all your containers and restarting at [step 1](#visualizing-with-rosboard).\n\n#### Other ROS GUIs\n\nCertain ROS tools like `rqt` and `rqt_graph` can work quite well using [X11 forwarding](#x-window-forwarding), even on macOS with Apple Silicon. However, more complex 3D visualization tools like `RViz2` and simulation environments like `Gazebo` seem to struggle with X forwarding on macOS, especially on Apple Silicon (issues from XQuartz to Docker to everything between), or don't work outright.\n\nOn the NVIDIA Jetson, tools like RViz and Gazebo should work smoothly without these limitations using X11 forwarding.\n\nFor Apple Silicon, using a VNC server inside the container is an alternative solution, but performance has been lackluster in practice due to latency and rendering issues.\n\nA potential solution for visualizing built-in ROS message types in these environments is to use ROSboard. ROSboard renders ROS data types using WebGL directly in a web browser, bypassing the need for complex GUI forwarding or VNC setups. This approach works cross-platform, offering a lightweight and responsive alternative for visualizing ROS topics. More work is needed if we are rending custom data types though.\n\n### 4. Testing and Code Quality\n\nWe use [black](https://github.com/psf/black) for formatting, [pylint](https://pypi.org/project/pylint/) for linting, and [mypy](https://mypy.readthedocs.io/en/stable/) for type checking. If you are using [VS Code](https://code.visualstudio.com/), the provided [VS Code settings](.vscode/settings.json) should automatically setup everything you need. Just make sure you have the [recommended extensions](./.vscode/extensions.json) installed.\n\nFor other IDEs, there may be extensions provided for these tools, or you could just use the CLI equivalents. Make sure to pass the `pyproject.toml` file as an arg (e.g. `--rcfile=pyproject.toml` or `--config=pyproject.toml`) to use the same formatting and linting settings as the rest of the project. For your convenience, there are aliases defined in `.bashrc` within the container (these are sourced from [`shell_env.sh`](./shell_env.sh)).\n\n| Procedure               | Tool                                                           | Command                                        | Alias          |\n| ----------------------- | -------------------------------------------------------------- | ---------------------------------------------- | -------------- |\n| **Linting**             | [pylint](https://pypi.org/project/pylint/)                     | `pylint --rcfile=pyproject.toml src/`          | `lint`         |\n| **Testing** (Method 1)  | [pytest](https://docs.pytest.org/en/stable/)                   | `pytest`                                       | `pytest`       |\n| **Testing** (Method 2)* | [colcon](https://colcon.readthedocs.io/en/released/) + pytest  | `colcon test --event-handlers console_direct+` | `coltest`      |\n| **Formatting**          | [black](https://pypi.org/project/black/)                       | `black --config pyproject.toml .`              | `format`       |\n| **Formatting**          | [black](https://pypi.org/project/black/)                       | `black --config pyproject.toml --check .`      | `format_check` |\n| **Type checking**       | [mypy](https://mypy-lang.org/)                                 | `mypy --config-file=pyproject.toml src/`       | `type_check`   |\n| Building                | [colcon]([colcon](https://colcon.readthedocs.io/en/released/)) | `colcon build`                                 | `build`        |\n\n*_colcon will automatically collect package pytest tests and run them. It is difficult to get both of these to work at the same time. You should ensure that `pytest` always works as this is what we use to validate PRs. Colcon does not support code coverage with the same ease that pytest does._\n\n\u003e [!IMPORTANT]\n\u003e You need to `build` before running pytest!\n\n\u003e [!NOTE]\n\u003e Docker runs the container in a non-interactive shell, which by default does not load\n\u003e `.bashrc` unless explicitly told to when running a \"one off command.\" So if you are\n\u003e within the container, running `lint` will lint just fine. However, to run it as a one off,\n\u003e you need to use the `-i` flag with bash: `docker compose run --rm autobike bash -ic \"lint\"`\n\n---\n\n## Best Practices\n\n### Adding Dependencies\n\nWhen adding dependencies (pip, apt, etc.) in [pyproject.toml](./pyproject.toml) or [Dockerfile](./Dockerfile), always pin a specific version.\n\n### Directory Structure and Testing\n\n```text\nsrc/\n├─ package_a/\n├─ package_b/\n│  ├─ resource/\n│  │  ├─ package_b\n│  ├─ test/\n│  │  ├─ test_package_b_node.py\n│  ├─ package_b/\n│  │  ├─ package_b_node.py\n│  │  ├─ __init__.py\n│  ├─ README.md\n│  ├─ setup.py\n│  ├─ package.xml\n```\n\n- Nodes should prioritize using standardized [ROS 2 common data types](https://github.com/ros2/common_interfaces). These types are widely supported across the ROS ecosystem, ensuring better compatibility and integration with other ROS packages and sensors.\n- The [waypoints](./src/waypoints/) package should serve as a good example of how to build a simple package.\n- Each package should contain a `README.md` which contains basic documentation on how one should use the file along wih other relevant info:\n  - Exported constants and functions\n  - Implementation documentation as seen fit\n  - **Citations** and **sources**\n  - Perhaps, add a small [Mermaid](https://mermaid.live) diagram\n- Each package should have a corresponding `test/test_package_X.py` file containing `pytest` tests\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TD\n\n    %% Sensors Input Layer\n    sensors:::graySubgraph\n    subgraph sensors[Sensors]\n        depth(ZED 2 Depth):::orange\n        camera(Visual Camera)\n        gps(GPS)\n        rtk(RTK)\n    end\n\n    %% Legend\n    legend:::graySubgraph\n    subgraph legend[Legend]\n        ross_node(ROS Node)\n        pub(Publisher) --\u003e|ROS Topic| sub(Subscriber)\n        subsystem:::graySubgraph\n        subgraph subsystem[Bike Subsystem]\n        end\n        current(Currently Working On):::orange\n    end\n\n    %% Perception Layer\n    depth --\u003e|/sensor/depth| grid\n    camera --\u003e|/sensor/image| road_sign_detection\n    camera --\u003e|/sensor/image| boundary_detection\n    camera --\u003e|/sensor/image| object_detection\n    gps --\u003e|/sensor/gps| localization\n    rtk --\u003e|/sensor/rtk| localization\n\n    perception:::graySubgraph\n    subgraph perception[Perception]\n\n        %% YOLO Subsystem\n        YOLO:::graySubgraph\n        subgraph YOLO[YOLO Model]\n            road_sign_detection(Road Signage Recognition)\n            object_detection(Object Detection \u0026 Classification)\n        end\n\n        boundary_detection(Boundary \u0026 Lane Detection)\n        grid(Occupancy Grid):::orange\n        localization(Localization)\n        c_space(Configuration Space):::orange\n\n        object_detection --\u003e|/perception/objects| c_space\n        boundary_detection --\u003e|/perception/boundaries| c_space\n        grid --\u003e|/perception/occupancy_grid| c_space\n        localization --\u003e|/perception/current_state| c_space\n    end\n\n    %% Planning and Decision-Making Layer\n    road_sign_detection --\u003e|/perception/roadsigns| decision_making\n    c_space --\u003e|/perception/c_space| path_planning\n\n    planning:::graySubgraph\n    subgraph planning[Planning]\n\n        decision_making(Decision Making)\n        ui(\u003ca href='https://github.com/dheera/rosboard'\u003erosboard\u003c/a\u003e)\n        path_planning(Hybrid A* Planning):::orange\n        pure_pursuit(Pure Pursuit):::orange\n    end\n\n    waypoints(Static Waypoint Routing)\n    waypoints --\u003e|/planning/waypoints| path_planning\n\n    decision_making --\u003e|/planning/throttle| control\n    decision_making --\u003e|/planning/braking| control\n    path_planning --\u003e|/planning/path| pure_pursuit\n    pure_pursuit --\u003e|/planning/steering_velocity| control\n\n    %% Control Layer\n    control:::graySubgraph\n    subgraph control[Control]\n        steering_control[\\Steering Control/]:::blue\n        braking_control[\\Braking System Control/]:::blue\n        acceleration_control[\\Acceleration Control/]:::blue\n    end\n\n    classDef blue fill:#E6F7FF,stroke:#66B2FF,stroke-width:2px,color:#66B2FF;\n    classDef orange fill:#FFE6CC,stroke:#FF8C00,stroke-width:2px,color:#FF8C00;\n    classDef red fill:#FFE6E6,stroke:#FF6666,stroke-width:2px,color:#FF6666;\n    classDef green fill:#E6FFE6,stroke:#66CC66,stroke-width:2px,color:#66CC66;\n    classDef purple fill:#F3E6FF,stroke:#9933FF,stroke-width:2px,color:#9933FF;\n    classDef gray fill:#F0F0F0,stroke:#A0A0A0,stroke-width:1px,color:#A0A0A0;\n    classDef graySubgraph fill:transparent,stroke:#A0A0A0,stroke-width:2px,color:#A0A0A0;\n```\n\n- **Sensors Layer**: Responsible for collecting raw data from various sensors, including LiDAR, cameras, GPS, and RTK. These sensors provide crucial information about the environment, such as obstacles, road markings, and the bicycle’s location. This data is the foundation for perception, localization, and decision-making processes.\n\n- **Static Route Mapping Layer**: Uses offline OpenStreetMap (OSM) data to generate a static route with predefined waypoints. This static route is used as the baseline path that the dynamic path planning will refine based on real-time conditions.\n\n- **Perception Layer**: The perception layer processes raw sensor data to create a detailed understanding of the surrounding environment. It includes subsystems for detecting objects, recognizing road signs, identifying lane boundaries, and generating an occupancy grid. This data is combined into a 2D, discretized configuration space (C-space), which represents \"the actual free space zone for the movement of robot and guarantees that the vehicle or robot must not collide with the obstacle\" [^1]. The C-space first accounts for boundaries, such as lane lines or the edge of the road. The goal is to \"hug\" the right-most boundary relatively closely, by closing off anything past the right-most boundary and penalizing movement away from it. Hence, the C-space effectively represents our \"bike lane.\" The occupancy grid accounts for unexpected objects in our \"bike lane,\" expanding obstacles in the environment to include a safety margin that accounts for the bounding box of the bike. Not sure how we incorporate YOLO.\n\n- **Localization Layer**: Estimates the current state of the bicycle, including its position and orientation, using data from GPS and real time kinematics (RTK). The Kalman filter refines these estimates, while the kinematic model predicts future states.\n\n- **Planning and Decision-Making Layer**: Plans the optimal path to the next waypoint [^2]. The path planning subsystem refines the route through the configuration space--we aim to use a Hybrid A* algorithm [^3]. The behavioral planning module handles high-level decisions, such as stopping at red lights or and obeying road rules (this is not as important as path planning). Given the path, we can easily deduce how we need to adjust our steering/speed to achieve the next point.\n\n- **Control Layer**: This is not our responsibility\n\n---\n\n## Infrastructure\n\n### Why Docker?\n\n- Code is always reproducible and consistent across all environments\n- Docker encapsulates everything we need, including system-level dependencies, apt packages, and other tools, not just Python libraries like virtual environments do\n- Installing ROS any other way is beyond painful\n\n### Why ROS?\n\n- ROS (Robot Operating System) is widely used across the robotics industry, providing a reliable and well-supported framework\n- ROS provides built-in tools and frameworks for asynchronous communication (e.g., publishers, subscribers, services, and actions), so we don't need to implement these from scratch\n- ROS includes powerful tools for visualizing data (e.g., RViz) and monitoring system performance, aiding in development and debugging\n- Yes, ROS [sucks](https://news.ycombinator.com/item?id=24280204#24301628) in [numerous ways](https://answers.ros.org/question/316916/why-did-ros-prevail/), but ultimately we would be shooting ourselves in the foot by not using it. If it's good enough for [NASA](https://science.nasa.gov/mission/viper/lunar-operations), we can make it work for our use case.\n\n## Git Basics\n\n- **Clone the Repository:**\n  - To start working on the project, clone the repository to your local machine:\n\n    ```bash\n    git clone git@github.com:da-luce/cornell-autobike.git\n    ```\n\n- **Navigate to the Repository:**\n  - Change your current directory to the project directory:\n\n    ```bash\n    cd cornell-autobike\n    ```\n\n- **Create a New Branch:**\n  - Before making changes, create a new branch off of `main`:\n\n    ```bash\n    git checkout -b \u003cfeature-name\u003e main\n    ```\n\n    - Replace `\u003cfeature-name\u003e` with a descriptive name for your feature (without the `\u003c\u003e`).\n    - Example: `git checkout -b add-user-auth main`\n\n- **Make Changes and Commit:**\n  - Work on your feature or changes. When ready, stage and commit your changes:\n\n    ```bash\n    git add .\n    git commit -m \"Descriptive message about what you changed\"\n    ```\n\n- **Push Your Branch to GitHub:**\n  - After committing your changes, push your branch to GitHub:\n\n    ```bash\n    git push origin \u003cfeature-name\u003e\n    ```\n\n- **Create a Pull Request:**\n  - Go to the repository on GitHub and navigate to the [Pull Requests page](https://github.com/da-luce/cornell-autobike/pulls).\n  - Create a pull request to merge your branch into the `dev` branch.\n\n### Git Resources\n\n- [Git Basics Documentation](https://git-scm.com/doc)\n- [Pro Git Book](https://git-scm.com/book/en/v2)\n- [GitHub Guides](https://guides.github.com/)\n\n---\n\n## Citations\n\n[^1]: [Debnath, Sanjoy \u0026 Omar, Rosli \u0026 Abdul Latip, Nor Badariyah. (2019). A Review on Energy Efficient Path Planning Algorithms for Unmanned Air Vehicles: 5th ICCST 2018, Kota Kinabalu, Malaysia, 29-30 August 2018. 10.1007/978-981-13-2622-6_51.](https://www.researchgate.net/publication/327271383_A_Review_on_Energy_Efficient_Path_Planning_Algorithms_for_Unmanned_Air_Vehicles_5th_ICCST_2018_Kota_Kinabalu_Malaysia_29-30_August_2018)\n\n[^2]: [Mohamed Reda, Ahmed Onsy, Amira Y. Haikal, Ali Ghanbari, Path planning algorithms in the autonomous driving system: A comprehensive review, Robotics and Autonomous Systems, Volume 174, 2024, 104630, ISSN 0921-8890, https://doi.org/10.1016/j.robot.2024.104630.](https://www.sciencedirect.com/science/article/pii/S0921889024000137)\n\n[^3]: [https://medium.com/@junbs95/gentle-introduction-to-hybrid-a-star-9ce93c0d7869](https://medium.com/@junbs95/gentle-introduction-to-hybrid-a-star-9ce93c0d7869)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fda-luce%2Fcornell-autobike","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fda-luce%2Fcornell-autobike","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fda-luce%2Fcornell-autobike/lists"}