| Name | ir-sim JSON |
| Version |
2.7.0
JSON |
| download |
| home_page | None |
| Summary | IR-SIM is an open-source, lightweight robot simulator based on Python, designed for robotics navigation, control, and learning. This simulator provides a simple and user-friendly framework for simulating robots, sensors, and environments, facilitating the development and testing of robotics algorithms with minimal hardware requirements. |
| upload_time | 2025-08-09 18:17:20 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2022 Ruihua Han <hanrh@connect.hku.hk>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
robotics
simulation
navigation
control
learning
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!-- <div align="center">
<img src="docs/image/ir-sim_logos/logo1_nobg.png" width = "200" >
</div> -->
<div align="center">
# Intelligent Robot Simulator (IR-SIM)
<a href="https://pypi.org/project/ir-sim/"><img src='https://img.shields.io/pypi/v/ir-sim?color=orange' alt='Github Release'></a>
<a href="https://github.com/hanruihua/ir-sim?tab=MIT-1-ov-file"><img src='https://img.shields.io/badge/License-MIT-blue' alt='License'></a>
<a href="https://pepy.tech/project/ir-sim"><img src="https://img.shields.io/pepy/dt/ir-sim" alt="PyPI Downloads"></a>
<a href="https://codecov.io/gh/hanruihua/ir-sim" > <img src="https://codecov.io/gh/hanruihua/ir-sim/branch/main/graph/badge.svg?token=OSC8I5QCQ0"/> </a>
<a href="https://ir-sim.readthedocs.io/en/stable/"> <img alt="Read the Docs" src="https://img.shields.io/readthedocs/ir-sim"/> </a>
<a href="https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue"> <img src="https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue" alt="Python Version"></a>
</div>
**Documentation:** [https://ir-sim.readthedocs.io/en](https://ir-sim.readthedocs.io/en)
**IR-SIM** is an open-source, Python-based, lightweight robot simulator designed for navigation, control, and learning. It provides a simple, user-friendly framework with built-in collision detection for modeling robots, sensors, and environments. Ideal for academic and educational use, IR-SIM enables rapid prototyping of robotics and AI algorithms in custom scenarios with minimal coding and hardware requirements.
## Features
- Simulate robot platforms with diverse kinematics, sensors, and behaviors ([support](#support)).
- Quickly configure and customize scenarios using straightforward YAML files. No complex coding required.
- Visualize simulation outcomes using a naive visualizer matplotlib for immediate debugging.
- Support collision detection and behavior control for each object.
## Demonstrations
| Scenarios | Description |
| :--------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------: |
| <img src="https://github.com/user-attachments/assets/5930b088-d400-4943-8ded-853c22eae75b" alt="drawing" width="280"/> | In scenarios involving multiple circular differential robots, each robot employs Reciprocal Velocity Obstacle (RVO) behavior to avoid collisions. See [Usage - collision avoidance](https://github.com/hanruihua/ir-sim/blob/main/usage/11collision_avoidance/collision_avoidance.py) |
| <img src="https://github.com/user-attachments/assets/3257abc1-8bed-40d8-9b51-e5d90b06ee06" alt="drawing" width="280"/> | A car-like robot controlled via keyboard navigates a binary map using a 2D LiDAR sensor to detect obstacles. See [Usage - grid map](https://github.com/hanruihua/ir-sim/blob/main/usage/10grid_map/grid_map.py) |
| <img src="https://github.com/user-attachments/assets/0fac81e7-60c0-46b2-91f0-efe4762bb758" alt="drawing" width="280"/> | A car-like robot controlled via keyboard navigates a grid map generated from 3D habitat spaces datasets like [HM3D](https://aihabitat.org/datasets/hm3d/), [MatterPort3D](https://niessner.github.io/Matterport/), [Gibson](http://gibsonenv.stanford.edu/database/), etc. See [Usage - grid map hm3d](https://github.com/hanruihua/ir-sim/blob/main/usage/10grid_map/grid_map_hm3d.py)|
| <img src="https://github.com/user-attachments/assets/7aa809c2-3a44-4377-a22d-728b9dbdf8bc" alt="drawing" width="280"/> | Each robot employing RVO behavior is equipped with a field of view (FOV) to detect other robots within this area. See [Usage - fov](https://github.com/hanruihua/ir-sim/blob/main/usage/15fov_world/fov_world.py) |
| <img src="https://github.com/user-attachments/assets/1cc8a4a6-2f41-4bc9-bc59-a7faff443223" alt="drawing" width="280"/> | A car-like robot navigates through the randomly generated and moving obstacles. See [Usage - dynamic random obstacles](https://github.com/hanruihua/ir-sim/blob/main/usage/08random_obstacle/dynamic_random.py) |
## Prerequisite
- Python: >= 3.9
## Installation
- Install this package from PyPi:
```
pip install ir-sim
```
This does not include dependencies for all features of the simulator. To install additional optional dependencies, use the following pip commands:
```
# install dependencies for keyboard control
pip install ir-sim[keyboard]
# install dependencies for testing
pip install ir-sim[test]
# install all optional dependencies
pip install ir-sim[all]
```
- Or if you want to install the latest main branch version (which is more up-to-date than the PyPI version) from the source code:
```
git clone https://github.com/hanruihua/ir-sim.git
cd ir-sim
pip install -e .
```
- If you are using `uv`
```
git clone https://github.com/hanruihua/ir-sim.git
cd ir-sim
uv sync
```
## Usage
### Quick Start
```python
import irsim
env = irsim.make('robot_world.yaml') # initialize the environment with the configuration file
for i in range(300): # run the simulation for 300 steps
env.step() # update the environment
env.render() # render the environment
if env.done(): break # check if the simulation is done
env.end() # close the environment
```
YAML Configuration: robot_world.yaml
```yaml
world:
height: 10 # the height of the world
width: 10 # the width of the world
step_time: 0.1 # 10Hz calculate each step
sample_time: 0.1 # 10 Hz for render and data extraction
offset: [0, 0] # the offset of the world on x and y
robot:
kinematics: {name: 'diff'} # omni, diff, acker
shape: {name: 'circle', radius: 0.2} # radius
state: [1, 1, 0] # x, y, theta
goal: [9, 9, 0] # x, y, theta
behavior: {name: 'dash'} # move toward to the goal directly
color: 'g' # green
```
### Advanced Usage
The advanced usages are listed in the [usage](https://github.com/hanruihua/ir-sim/tree/main/usage)
## Support
Currently, the simulator supports the following features. Further features, such as additional sensors, behaviors, and robot models, are under development.
| **Category** | **Features** |
| ------------ | ------------------------------------------------------------------------------------------------ |
| **Kinematics** | Differential Drive mobile Robot<br>Omni-Directional mobile Robot<br>Ackermann Steering mobile Robot |
| **Sensors** | 2D LiDAR <br> FOV detector |
| **Geometries** | Circle<br>Rectangle<br>Polygon <br> linestring <br> Binary Grid Map |
| **Behaviors** | dash (Move directly toward the goal)<br> rvo (Move toward the goal using Reciprocal Velocity Obstacle behavior)|
## Projects Using IR-SIM
- Academic Projects:
- [rl-rvo-nav](https://github.com/hanruihua/rl_rvo_nav): [RAL & ICRA2023] A Reinforcement Learned based RVO behavior for multi-robot navigation.
- [RDA_planner](https://github.com/hanruihua/RDA_planner): [RAL & IROS2023] An Accelerated Collision Free Motion Planner for Cluttered Environments.
- [NeuPAN](https://github.com/hanruihua/NeuPAN): [T-RO 2025] Direct Point Robot Navigation with End-to-End Model-based Learning.
- Deep Reinforcement Learning Projects:
- [DRL-robot-navigation-IR-SIM](https://github.com/reiniscimurs/DRL-robot-navigation-IR-SIM)
- [AutoNavRL](https://github.com/harshmahesheka/AutoNavRL)
## Contributing
This project is under development. I appreciate and welcome all contributions. Just open an issue or a pull request. Please refer to the [CONTRIBUTING.md](https://github.com/hanruihua/ir-sim/blob/main/CONTRIBUTING.md) for more details.
## Acknowledgement
- [PythonRobotics](https://github.com/AtsushiSakai/PythonRobotics)
Raw data
{
"_id": null,
"home_page": null,
"name": "ir-sim",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "robotics, simulation, navigation, control, learning",
"author": null,
"author_email": "Han Ruihua <hanrh@connect.hku.hk>",
"download_url": "https://files.pythonhosted.org/packages/4e/1d/4d5caedd95942c5099c1a59c20418cf74abd0e077b44309d8dc028084b16/ir_sim-2.7.0.tar.gz",
"platform": null,
"description": "<!-- <div align=\"center\">\n<img src=\"docs/image/ir-sim_logos/logo1_nobg.png\" width = \"200\" >\n</div> -->\n\n\n<div align=\"center\">\n\n# Intelligent Robot Simulator (IR-SIM)\n\n<a href=\"https://pypi.org/project/ir-sim/\"><img src='https://img.shields.io/pypi/v/ir-sim?color=orange' alt='Github Release'></a>\n<a href=\"https://github.com/hanruihua/ir-sim?tab=MIT-1-ov-file\"><img src='https://img.shields.io/badge/License-MIT-blue' alt='License'></a>\n<a href=\"https://pepy.tech/project/ir-sim\"><img src=\"https://img.shields.io/pepy/dt/ir-sim\" alt=\"PyPI Downloads\"></a>\n<a href=\"https://codecov.io/gh/hanruihua/ir-sim\" > <img src=\"https://codecov.io/gh/hanruihua/ir-sim/branch/main/graph/badge.svg?token=OSC8I5QCQ0\"/> </a>\n<a href=\"https://ir-sim.readthedocs.io/en/stable/\"> <img alt=\"Read the Docs\" src=\"https://img.shields.io/readthedocs/ir-sim\"/> </a>\n<a href=\"https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue\"> <img src=\"https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue\" alt=\"Python Version\"></a>\n</div>\n\n**Documentation:** [https://ir-sim.readthedocs.io/en](https://ir-sim.readthedocs.io/en)\n\n**IR-SIM** is an open-source, Python-based, lightweight robot simulator designed for navigation, control, and learning. It provides a simple, user-friendly framework with built-in collision detection for modeling robots, sensors, and environments. Ideal for academic and educational use, IR-SIM enables rapid prototyping of robotics and AI algorithms in custom scenarios with minimal coding and hardware requirements.\n\n## Features\n\n- Simulate robot platforms with diverse kinematics, sensors, and behaviors ([support](#support)). \n- Quickly configure and customize scenarios using straightforward YAML files. No complex coding required.\n- Visualize simulation outcomes using a naive visualizer matplotlib for immediate debugging.\n- Support collision detection and behavior control for each object.\n\n## Demonstrations\n\n| Scenarios | Description |\n| :--------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------: |\n| <img src=\"https://github.com/user-attachments/assets/5930b088-d400-4943-8ded-853c22eae75b\" alt=\"drawing\" width=\"280\"/> | In scenarios involving multiple circular differential robots, each robot employs Reciprocal Velocity Obstacle (RVO) behavior to avoid collisions. See [Usage - collision avoidance](https://github.com/hanruihua/ir-sim/blob/main/usage/11collision_avoidance/collision_avoidance.py) |\n| <img src=\"https://github.com/user-attachments/assets/3257abc1-8bed-40d8-9b51-e5d90b06ee06\" alt=\"drawing\" width=\"280\"/> | A car-like robot controlled via keyboard navigates a binary map using a 2D LiDAR sensor to detect obstacles. See [Usage - grid map](https://github.com/hanruihua/ir-sim/blob/main/usage/10grid_map/grid_map.py) |\n| <img src=\"https://github.com/user-attachments/assets/0fac81e7-60c0-46b2-91f0-efe4762bb758\" alt=\"drawing\" width=\"280\"/> | A car-like robot controlled via keyboard navigates a grid map generated from 3D habitat spaces datasets like [HM3D](https://aihabitat.org/datasets/hm3d/), [MatterPort3D](https://niessner.github.io/Matterport/), [Gibson](http://gibsonenv.stanford.edu/database/), etc. See [Usage - grid map hm3d](https://github.com/hanruihua/ir-sim/blob/main/usage/10grid_map/grid_map_hm3d.py)|\n| <img src=\"https://github.com/user-attachments/assets/7aa809c2-3a44-4377-a22d-728b9dbdf8bc\" alt=\"drawing\" width=\"280\"/> | Each robot employing RVO behavior is equipped with a field of view (FOV) to detect other robots within this area. See [Usage - fov](https://github.com/hanruihua/ir-sim/blob/main/usage/15fov_world/fov_world.py) |\n| <img src=\"https://github.com/user-attachments/assets/1cc8a4a6-2f41-4bc9-bc59-a7faff443223\" alt=\"drawing\" width=\"280\"/> | A car-like robot navigates through the randomly generated and moving obstacles. See [Usage - dynamic random obstacles](https://github.com/hanruihua/ir-sim/blob/main/usage/08random_obstacle/dynamic_random.py) |\n\n\n## Prerequisite\n\n- Python: >= 3.9\n\n## Installation\n\n- Install this package from PyPi:\n\n```\npip install ir-sim\n```\n\nThis does not include dependencies for all features of the simulator. To install additional optional dependencies, use the following pip commands:\n\n```\n# install dependencies for keyboard control\npip install ir-sim[keyboard]\n\n# install dependencies for testing\npip install ir-sim[test]\n\n# install all optional dependencies\npip install ir-sim[all] \n```\n\n- Or if you want to install the latest main branch version (which is more up-to-date than the PyPI version) from the source code:\n\n```\ngit clone https://github.com/hanruihua/ir-sim.git \ncd ir-sim \npip install -e . \n```\n\n- If you are using `uv`\n\n```\ngit clone https://github.com/hanruihua/ir-sim.git \ncd ir-sim \nuv sync\n```\n\n## Usage\n\n### Quick Start\n\n```python\n\nimport irsim\n\nenv = irsim.make('robot_world.yaml') # initialize the environment with the configuration file\n\nfor i in range(300): # run the simulation for 300 steps\n\n env.step() # update the environment\n env.render() # render the environment\n\n if env.done(): break # check if the simulation is done\n \nenv.end() # close the environment\n```\n\nYAML Configuration: robot_world.yaml\n\n```yaml\n\nworld:\n height: 10 # the height of the world\n width: 10 # the width of the world\n step_time: 0.1 # 10Hz calculate each step\n sample_time: 0.1 # 10 Hz for render and data extraction \n offset: [0, 0] # the offset of the world on x and y \n\nrobot:\n kinematics: {name: 'diff'} # omni, diff, acker\n shape: {name: 'circle', radius: 0.2} # radius\n state: [1, 1, 0] # x, y, theta\n goal: [9, 9, 0] # x, y, theta\n behavior: {name: 'dash'} # move toward to the goal directly \n color: 'g' # green\n```\n\n### Advanced Usage\n\nThe advanced usages are listed in the [usage](https://github.com/hanruihua/ir-sim/tree/main/usage)\n\n\n## Support\n\nCurrently, the simulator supports the following features. Further features, such as additional sensors, behaviors, and robot models, are under development.\n\n| **Category** | **Features** |\n| ------------ | ------------------------------------------------------------------------------------------------ |\n| **Kinematics** | Differential Drive mobile Robot<br>Omni-Directional mobile Robot<br>Ackermann Steering mobile Robot |\n| **Sensors** | 2D LiDAR <br> FOV detector |\n| **Geometries** | Circle<br>Rectangle<br>Polygon <br> linestring <br> Binary Grid Map |\n| **Behaviors** | dash (Move directly toward the goal)<br> rvo (Move toward the goal using Reciprocal Velocity Obstacle behavior)|\n\n\n## Projects Using IR-SIM\n\n- Academic Projects:\n - [rl-rvo-nav](https://github.com/hanruihua/rl_rvo_nav): [RAL & ICRA2023] A Reinforcement Learned based RVO behavior for multi-robot navigation.\n - [RDA_planner](https://github.com/hanruihua/RDA_planner): [RAL & IROS2023] An Accelerated Collision Free Motion Planner for Cluttered Environments.\n - [NeuPAN](https://github.com/hanruihua/NeuPAN): [T-RO 2025] Direct Point Robot Navigation with End-to-End Model-based Learning.\n\n- Deep Reinforcement Learning Projects:\n - [DRL-robot-navigation-IR-SIM](https://github.com/reiniscimurs/DRL-robot-navigation-IR-SIM)\n - [AutoNavRL](https://github.com/harshmahesheka/AutoNavRL)\n\n## Contributing\n\nThis project is under development. I appreciate and welcome all contributions. Just open an issue or a pull request. Please refer to the [CONTRIBUTING.md](https://github.com/hanruihua/ir-sim/blob/main/CONTRIBUTING.md) for more details.\n\n## Acknowledgement\n\n- [PythonRobotics](https://github.com/AtsushiSakai/PythonRobotics)\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2022 Ruihua Han <hanrh@connect.hku.hk>\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "IR-SIM is an open-source, lightweight robot simulator based on Python, designed for robotics navigation, control, and learning. This simulator provides a simple and user-friendly framework for simulating robots, sensors, and environments, facilitating the development and testing of robotics algorithms with minimal hardware requirements.",
"version": "2.7.0",
"project_urls": {
"Documentation": "https://ir-sim.readthedocs.io/en/stable/",
"Homepage": "https://ir-sim.readthedocs.io/en/stable/",
"Issues": "https://github.com/hanruihua/ir-sim/issues",
"Repository": "https://github.com/hanruihua/ir-sim"
},
"split_keywords": [
"robotics",
" simulation",
" navigation",
" control",
" learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4db9774a9922eb22b91dc6b7d7434ba3441c104a5aa39606233990656d202e28",
"md5": "f48833f76845c7215135223ef5033a31",
"sha256": "0be539c3302ef10d0727cd389fe73cd02fa35fb6243e8063b16a9c5e7bc90ca2"
},
"downloads": -1,
"filename": "ir_sim-2.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f48833f76845c7215135223ef5033a31",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 667132,
"upload_time": "2025-08-09T18:17:19",
"upload_time_iso_8601": "2025-08-09T18:17:19.405773Z",
"url": "https://files.pythonhosted.org/packages/4d/b9/774a9922eb22b91dc6b7d7434ba3441c104a5aa39606233990656d202e28/ir_sim-2.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4e1d4d5caedd95942c5099c1a59c20418cf74abd0e077b44309d8dc028084b16",
"md5": "497299a680388ad2189b05555da533bd",
"sha256": "902c038b32adb2f35b505c3cf863bd74ba2304db7d6fca79f8705f2a33c7c889"
},
"downloads": -1,
"filename": "ir_sim-2.7.0.tar.gz",
"has_sig": false,
"md5_digest": "497299a680388ad2189b05555da533bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 657939,
"upload_time": "2025-08-09T18:17:20",
"upload_time_iso_8601": "2025-08-09T18:17:20.890691Z",
"url": "https://files.pythonhosted.org/packages/4e/1d/4d5caedd95942c5099c1a59c20418cf74abd0e077b44309d8dc028084b16/ir_sim-2.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 18:17:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hanruihua",
"github_project": "ir-sim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ir-sim"
}
