{"id":16568064,"url":"https://github.com/jam643/thetrolleyproblemgame","last_synced_at":"2025-04-13T05:13:18.129Z","repository":{"id":88463726,"uuid":"325657667","full_name":"jam643/TheTrolleyProblemGame","owner":"jam643","description":"This over-engineered game is my attempt to brush up on vehicle dynamics and path tracking algorithms by coding them from scratch. The game conceals an underlying framework of tunable path tracking controllers (Pure-Pursuit, Stanley, Kinematic/Dynamic LQR), customizable vehicle dynamics models, spline-based path generation, etc.","archived":false,"fork":false,"pushed_at":"2024-09-02T15:50:39.000Z","size":32332,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T05:13:06.730Z","etag":null,"topics":["autonomous-driving","autonomous-vehicles","lqr-controller","mpc-control","path-tracking","pygame","robotics","stanley-controller"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jam643.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2020-12-30T22:08:59.000Z","updated_at":"2025-01-11T11:07:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"37e91ad2-7fd8-467a-88d6-b142d0ac4423","html_url":"https://github.com/jam643/TheTrolleyProblemGame","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jam643%2FTheTrolleyProblemGame","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jam643%2FTheTrolleyProblemGame/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jam643%2FTheTrolleyProblemGame/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jam643%2FTheTrolleyProblemGame/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jam643","download_url":"https://codeload.github.com/jam643/TheTrolleyProblemGame/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665746,"owners_count":21142123,"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","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-driving","autonomous-vehicles","lqr-controller","mpc-control","path-tracking","pygame","robotics","stanley-controller"],"created_at":"2024-10-11T21:08:11.241Z","updated_at":"2025-04-13T05:13:18.102Z","avatar_url":"https://github.com/jam643.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca id=\"readme-top\"\u003e\u003c/a\u003e\n\n\u003cdiv style=\"text-align: center;\"\u003e\n    \u003cimg src=\"images/TrolleyProblemBanner.gif\" width=\"1000\"\u003e\n\u003c/div\u003e\n\n\n![License](https://shields.io/badge/license-Apache%202-green?style=for-the-badge)\n![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/in/jam643/)\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-this-project\"\u003eAbout This Project\u003c/a\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#gameplay-mode\"\u003eGameplay Mode\u003c/a\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#sandbox-mode\"\u003eSandbox Mode\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#path-tracking-controllers\"\u003ePath Tracking Controllers\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#vehicle-model\"\u003eVehicle Model\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#path-generation\"\u003ePath Generation\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#setup\"\u003eSetup\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n## About This Project\n\nThis over-engineered game is my attempt to brush up on vehicle dynamics and path tracking algorithms by coding them from scratch. The game conceals an underlying framework of tunable path tracking controllers (Pure-Pursuit, Stanley, Kinematic/Dynamic LQR), customizable vehicle dynamics models, spline-based path generation, etc.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Gameplay Mode\n\nThe game involves the user drawing a path (B-spline) with their mouse that the autonomous vehicle will follow using one of several path tracking algorithms. The goal is to guide the AV safely to the end of each level, avoiding collisions with the walls.\n\n\u003cimg src=\"images/gameplay.gif\" width=\"800\"\u003e\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Sandbox Mode\n\nSandbox mode allows the user to interactively experiment and tune a variety of parameters, controlling everything from the vehicle dynamics model to the path tracking algorithms and tuning parameters. The code is written following several OOP software design patterns (Composite, Factory, Bridge, etc.) to enable abstraction (e.g. any controller can be run with any vehicle model and any path generation type) and maintainability.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n### Path Tracking Controllers\n\nUsers can tune (in realtime) and experiment with several path tracking controllers of varying complexity. See below video for example: \n\n\u003cimg src=\"images/path_trackers.gif\" width=\"800\"\u003e\n\nBrief comparison of the various path tracking controllers implemented:\n\n|                        | **Description**                                                                                                                            | **Model Used**                  | **Robustness**                                                        | **Stability**                                                                           | **Linearity**                     |\n| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------- |\n| **Pure Pursuit**       | Geometric method that follows a look-ahead point on the path based on vehicle speed                                                        | Kinematic, simple bicycle model | Less robust to dynamic changes, struggles with sharp turns            | Generally stable but can lose stability in sharp turns, high speeds, or small lookahead | Non-linear                        |\n| **Stanley Controller** | Minimizes cross-track error and heading error through a proportional control strategy, used in DARPA's Grand Challenge by Standford's team | Kinematic, bicycle model        | Robust to small disturbances, but may oscillate in certain conditions | Lyapunov stable, particularly for straight paths                                        | Non-linear                        |\n| **Kinematic LQR**      | Uses linear quadratic regulator to minimize deviations in position and velocity using a kinematic model                                    | Kinematic, linearized model     | Moderately robust with careful tuning                                 | Stable within the Region of Attraction (ROA)                                            | Linearized around operating point |\n| **Dynamic LQR**        | Uses linear quadratic regulator to minimize deviations including dynamic effects like forces and acceleration                              | Dynamic, linearized model       | Highly robust, especially in dynamic and high-speed environments      | Stable within the Region of Attraction (ROA)                                            | Linearized around operating point |\n\n\nUsers can also click the `Docs` button to go to [a Jupyter Notebook page](https://github.com/jam643/TheTrolleyProblemGame/blob/master/control/docs/Path%20Tracking%20Controls.ipynb) containing derivations of some of the control strategies as well as sample code calling the controllers:\n\n\u003cimg src=\"images/path_tracker_docs.gif\" width=\"800\"\u003e\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n### Vehicle Model\n\nThe user can switch between kinematic vs dynamic vehicle models as well as different integration schemes. The user can also update the vehicle model parameters (mass, length, etc) in real time which will also update the parameters used by the path tracking algorithm (where relevant).\n\n\u003cimg src=\"images/vehicle_model.gif\" width=\"800\"\u003e\n\nUsers can also click the `Docs` button to go to [a Jupyter Notebook page](https://github.com/jam643/TheTrolleyProblemGame/blob/master/dynamics/docs/VehicleMotionModel.ipynb) containing derivations of the dynamic/kinematic bicycle model equations-of-motion as well as sample code calling the models:\n\n\u003cimg src=\"images/vehicle_model_docs.gif\" width=\"800\"\u003e\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n### Path Generation\n\nPaths are generated with B-Splines for $C^2$ continuity. There are 2 path generation modes:\n\n1) Manual Gen: path spawns from the mouse cursor which the user controls\n2) Auto Gen: path is generated by some parameterizable function generator (e.g. sine wave)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Setup\n\nFirst time only:\n```bash\npip install --user pipenv\npip install --user pipenv-shebang\npipenv sync\npipenv run ipykernel_setup\n```\nStart game:\n```bash\n./TheTrolleyProblemGame.py\n```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nJesse Miller - jam643@cornell.edu\n\nProject Link: [https://github.com/jam643/TheTrolleyProblemGame](https://github.com/jam643/TheTrolleyProblemGame)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjam643%2Fthetrolleyproblemgame","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjam643%2Fthetrolleyproblemgame","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjam643%2Fthetrolleyproblemgame/lists"}