{"id":15640623,"url":"https://github.com/winstxnhdw/kinematicbicyclemodel","last_synced_at":"2025-04-06T15:12:26.874Z","repository":{"id":47226754,"uuid":"305915086","full_name":"winstxnhdw/KinematicBicycleModel","owner":"winstxnhdw","description":"A description of the Kinematic Bicycle Model written in Cython with an animated example.","archived":false,"fork":false,"pushed_at":"2025-02-17T17:02:41.000Z","size":64131,"stargazers_count":82,"open_issues_count":0,"forks_count":26,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-30T14:11:24.325Z","etag":null,"topics":["animation","bicycle-model","cython","kinematic-modeling","mathematical-modelling","python","uv"],"latest_commit_sha":null,"homepage":"","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/winstxnhdw.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}},"created_at":"2020-10-21T05:12:15.000Z","updated_at":"2025-03-24T09:40:09.000Z","dependencies_parsed_at":"2024-11-07T03:18:25.706Z","dependency_job_id":"31b7d8ca-11e6-4d68-900a-41e8167c4781","html_url":"https://github.com/winstxnhdw/KinematicBicycleModel","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/winstxnhdw%2FKinematicBicycleModel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winstxnhdw%2FKinematicBicycleModel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winstxnhdw%2FKinematicBicycleModel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winstxnhdw%2FKinematicBicycleModel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/winstxnhdw","download_url":"https://codeload.github.com/winstxnhdw/KinematicBicycleModel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247500468,"owners_count":20948880,"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":["animation","bicycle-model","cython","kinematic-modeling","mathematical-modelling","python","uv"],"created_at":"2024-10-03T11:38:47.980Z","updated_at":"2025-04-06T15:12:26.855Z","avatar_url":"https://github.com/winstxnhdw.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kinematic Bicycle Model\n\n[![python](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12%20|%203.13-blue)](https://www.python.org/)\n![main.yml](https://github.com/winstxnhdw/KinematicBicycleModel/actions/workflows/main.yml/badge.svg)\n![formatter.yml](https://github.com/winstxnhdw/KinematicBicycleModel/actions/workflows/formatter.yml/badge.svg)\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"resources/animation_wide.gif\" /\u003e\n\u003c/div\u003e\n\n## Abstract\n\nThis repository contains a implementation of the Kinematic Bicycle model. The model can be defined with the following state-space representation,\n\n$$\n\\frac{d}{dt}\n\\begin{pmatrix}\nx \\\\\ny \\\\\n\\theta \\\\\nv\n\\end{pmatrix} =\n\\begin{pmatrix}\nv\\cos{\\theta} \\\\\nv\\sin{\\theta} \\\\\n\\frac{v\\tan{\\delta}}{L} \\\\\na\n\\end{pmatrix}\n$$\n\nwhere $v$ is the vehicle's velocity in the x-axis, $\\theta$ is the vehicle's yaw, $\\delta$ is the steering angle, $L$ is the vehicle's wheelbase and $a$ is the acceleration/throttle. You may read more about the Kinematic Bicycle Model [here](https://thomasfermi.github.io/Algorithms-for-Automated-Driving/Control/BicycleModel.html).\n\n## Installation\n\n```bash\npip install git+https://github.com/winstxnhdw/KinematicBicycleModel\n```\n\n## Usage\n\nThe model is written entirely in [Cython](https://cython.org), completely typesafe, and drops the Global Interpreter Lock (GIL) whenever possible. The following code sample demonstrates how to use the model.\n\n\u003e [!WARNING]\\\n\u003e This model is not picklable as it relies on `__cinit__` for fast initialisation.\n\n```python\nfrom kbm import KinematicBicycleModel\n\nmodel = KinematicBicycleModel(wheelbase=2.96, max_steer=0.57596, delta_time=0.05)\nstate = model.compute_state(\n    x=0.0,\n    y=0.0,\n    yaw=0.0,\n    steer=0.0,\n    velocity=0.0,\n    acceleration=5.0\n)\n\nprint(f\"The vehicle is at ({state['x']}, {state['y']})\")\nprint(f\"The vehicle is facing {state['yaw']} rad\")\nprint(f\"The vehicle is steering at {state['steer']} rad\")\nprint(f\"The vehicle is moving at {state['velocity']} m/s\")\nprint(f\"The vehicle is turning at {state['angular_velocity']} rad/s\")\n```\n\nSince the GIL is dropped, the model may take advantage of multithreaded parallelism. The following code sample demonstrates an example of this.\n\n```python\nfrom concurrent.futures import ThreadPoolExecutor\nfrom random import uniform\n\nfrom kbm import KinematicBicycleModel\n\nmodel = KinematicBicycleModel(wheelbase=2.96, max_steer=0.57596, delta_time=0.05)\nrandom_steer_values = (uniform(-3.14159, 3.14159) for _ in range(1000))\n\n\ndef compute_state(steer: float):\n    return model.compute_state(x=0.0, y=0.0, yaw=0.0, steer=steer, velocity=0.0, acceleration=5.0)\n\n\nstate_with_highest_angular_velocity = max(\n    ThreadPoolExecutor().map(compute_state, random_steer_values),\n    key=lambda state: state[\"angular_velocity\"],\n)\n\n```\n\n## Limitations\n\nJust like with all other bicycle models, this model is a discrete model and loses its accuracy when the time step is set too large or the vehicle is made to travel at unreasonably high speeds. Usually, the FPS of the simulation should be set to the highest possible value for the greatest accuracy. However, for rendering high-quality GIFs, 50 FPS is found to be most optimal. See the [GIF89a specification](https://www.w3.org/Graphics/GIF/spec-gif89a.txt).\n\n## Demo\n\nRecursively git clone the repository\n\n```bash\ngit clone --recursive https://github.com/winstxnhdw/KinematicBicycleModel.git\n```\n\nPlay the animation\n\n```bash\nuv run animate.py\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinstxnhdw%2Fkinematicbicyclemodel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwinstxnhdw%2Fkinematicbicyclemodel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinstxnhdw%2Fkinematicbicyclemodel/lists"}