ir-sim
A Python based lightweight robot simulator for the development of algorithms in robotics navigation, control, and learning.
Science Score: 36.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
○CITATION.cff file
-
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
○DOI references
-
○Academic publication links
-
✓Committers with academic emails
2 of 8 committers (25.0%) from academic institutions -
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (13.4%) to scientific vocabulary
Keywords
Repository
A Python based lightweight robot simulator for the development of algorithms in robotics navigation, control, and learning.
Basic Info
- Host: GitHub
- Owner: hanruihua
- License: mit
- Language: Python
- Default Branch: main
- Homepage: https://ir-sim.readthedocs.io/en/stable/
- Size: 133 MB
Statistics
- Stars: 574
- Watchers: 7
- Forks: 71
- Open Issues: 4
- Releases: 42
Topics
Metadata Files
README.md
Documentation: 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).
- 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 |
| :--------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------: |
| | In scenarios involving multiple circular differential robots, each robot employs Reciprocal Velocity Obstacle (RVO) behavior to avoid collisions. See Usage - collision avoidance |
|
| A car-like robot controlled via keyboard navigates a binary map using a 2D LiDAR sensor to detect obstacles. See Usage - grid map |
|
| A car-like robot controlled via keyboard navigates a grid map generated from 3D habitat spaces datasets like HM3D, MatterPort3D, Gibson, etc. See Usage - grid map hm3d|
|
| Each robot employing RVO behavior is equipped with a field of view (FOV) to detect other robots within this area. See Usage - fov |
|
| A car-like robot navigates through the randomly generated and moving obstacles. See Usage - dynamic random obstacles |
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 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 steptime: 0.1 # 10Hz calculate each step sampletime: 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
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
Omni-Directional mobile Robot
Ackermann Steering mobile Robot |
| Sensors | 2D LiDAR
FOV detector |
| Geometries | Circle
Rectangle
Polygon
linestring
Binary Grid Map |
| Behaviors | dash (Move directly toward the goal)
rvo (Move toward the goal using Reciprocal Velocity Obstacle behavior)|
Projects Using IR-SIM
Academic Projects:
- rl-rvo-nav: [RAL & ICRA2023] A Reinforcement Learned based RVO behavior for multi-robot navigation.
- RDA_planner: [RAL & IROS2023] An Accelerated Collision Free Motion Planner for Cluttered Environments.
- NeuPAN: [T-RO 2025] Direct Point Robot Navigation with End-to-End Model-based Learning.
Deep Reinforcement Learning Projects:
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 for more details.
Acknowledgement
Owner
- Name: Han
- Login: hanruihua
- Kind: user
- Location: Hong Kong
- Company: The University of Hong Kong
- Repositories: 5
- Profile: https://github.com/hanruihua
Ph.D. student. Research interest: Intelligent Robotics, Reinforcement Learning, Navigation, Optimization
GitHub Events
Total
- Create event: 61
- Issues event: 38
- Release event: 23
- Watch event: 393
- Delete event: 48
- Issue comment event: 77
- Push event: 687
- Pull request review comment event: 7
- Pull request review event: 14
- Pull request event: 103
- Fork event: 55
Last Year
- Create event: 61
- Issues event: 38
- Release event: 23
- Watch event: 393
- Delete event: 48
- Issue comment event: 77
- Push event: 687
- Pull request review comment event: 7
- Pull request review event: 14
- Pull request event: 103
- Fork event: 55
Committers
Last synced: 9 months ago
Top Committers
| Name | Commits | |
|---|---|---|
| Han | h****h@c****k | 1,153 |
| reinis | i****i@g****m | 8 |
| YupuLu | y****a@f****m | 7 |
| han | 7****8@q****m | 4 |
| Han | h****h@c****m | 4 |
| Guoliang LI | l****g@c****o | 3 |
| Harsh Mahesheka | h****0@i****n | 1 |
| Emmanuel Ferdman | e****n@g****m | 1 |
Committer Domains (Top 20 + Academic)
Issues and Pull Requests
Last synced: 6 months ago
All Time
- Total issues: 22
- Total pull requests: 60
- Average time to close issues: 8 days
- Average time to close pull requests: about 5 hours
- Total issue authors: 16
- Total pull request authors: 6
- Average comments per issue: 1.5
- Average comments per pull request: 0.42
- Merged pull requests: 46
- Bot issues: 0
- Bot pull requests: 5
Past Year
- Issues: 22
- Pull requests: 60
- Average time to close issues: 8 days
- Average time to close pull requests: about 5 hours
- Issue authors: 16
- Pull request authors: 6
- Average comments per issue: 1.5
- Average comments per pull request: 0.42
- Merged pull requests: 46
- Bot issues: 0
- Bot pull requests: 5
Top Authors
Issue Authors
- reiniscimurs (4)
- ljaniec (2)
- time-cat (2)
- SoumyaJanaJGEC2001 (1)
- ZhuPiter-1mol (1)
- HAN-bo-nan (1)
- NathanGavenski (1)
- LiuXingZhi11 (1)
- Adithya1976 (1)
- Situ-Weixi (1)
- keizer7 (1)
- Sekiro-x (1)
- aly-pr (1)
- sisijunn (1)
- Violetstar12 (1)
Pull Request Authors
- hanruihua (43)
- reiniscimurs (6)
- dependabot[bot] (5)
- GuoliangLI1998 (3)
- harshmahesheka (1)
- emmanuel-ferdman (1)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 1
-
Total downloads:
- pypi 1,288 last-month
- Total dependent packages: 0
- Total dependent repositories: 0
- Total versions: 48
- Total maintainers: 1
pypi.org: ir-sim
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.
- Homepage: https://ir-sim.readthedocs.io/en/stable/
- Documentation: https://ir-sim.readthedocs.io/en/stable/
- 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.
-
Latest release: 2.7.2
published 6 months ago
Rankings
Maintainers (1)
Dependencies
- imageio *
- matplotlib *
- numpy *
- pathlib *
- pynput *
- pyyaml *
- scipy *