安装#

IR-SIM 支持运行在 Linux、macOS 与 Windows 上的 Python 3.10+，可通过 pip 或 conda 进行安装。

安装说明

使用 pip 安装 IR-SIM：

python -m pip install ir-sim

这将安装软件包以及基础环境所需的核心依赖。

conda 是一个用于管理软件包与环境的系统。

  1. 先安装 conda。

2. Create a new conda environment with Python and pip,

conda create --name irsim_env python=3.12 pip
conda activate irsim_env

或激活一个已有的环境

3. Install ir-sim in the virtual environment

python -m pip install ir-sim

uv 是一个极其快速的 Python 包与项目管理器。

使用 uv 安装 IR-SIM：

uv venv
uv pip install ir-sim

或使用 uv 的项目管理功能：

uv add ir-sim

强烈建议在全新的虚拟环境（uv 或 conda）中从源码安装 IR-SIM。

按以下步骤从源码安装 IR-SIM：

  1. 克隆官方 IR-SIM git repository，或 fork 该仓库。

git clone https://github.com/hanruihua/ir-sim.git

  1. 进入克隆目录的顶层

cd ir-sim

  1. 若希望以可编辑模式使用 IR-SIM，请运行

python -m pip install -e .

否则运行

python -m pip install .

若使用 uv，执行

uv sync

验证安装#

使用安装了 IR-SIM 的环境中的 Python 解释器，打印已安装的版本：

python -c "import irsim; print(irsim.__version__)"

如果该命令能够正常输出版本号且没有导入错误，则核心安装已经就绪。接下来可按照 快速开始 运行场景。

安装附加功能#

键盘控制

IR-SIM 支持通过键盘进行交互式机器人仿真。请安装以下键盘控制依赖：

python -m pip install "ir-sim[keyboard]"

将安装：

  • pynput —— 处理键盘与鼠标输入

全部功能

如需安装全部可选运行时依赖与功能：

python -m pip install "ir-sim[all]"

包含：

  • 键盘控制（pynput）

  • 增强的视频支持（imageio[ffmpeg]）

  • ORCA 群组行为（pyrvo）

开发环境#

以下依赖组仅在开发 IR-SIM 本身时需要；运行普通仿真无需安装。

代码检查

IR-SIM 使用 Ruff 进行代码检查。若要在本地安装 lint 依赖组，请运行

uv sync --group lint

包含：

  • Ruff —— 代码检查工具

  • ty —— 类型提示工具

  • black —— 代码格式化工具

测试

使用 test 依赖组（源于 pyproject.toml）安装测试依赖：

uv sync --group test

运行测试：

uv run pytest

生成覆盖率报告：

uv run pytest --cov . --cov-report=xml --cov-report=html

对代码库执行类型检查：

uvx ty check
文档

使用 docs 依赖组（源于 pyproject.toml）安装文档依赖：

uv sync --group docs

在本地构建 HTML 文档：

cd docs
make html

输出文件将位于 docs/build/html``（或视环境位于 ``docs/_build/html）。

全部开发依赖组

安装全部开发依赖组：

uv sync --all-groups

包含：

  • lint 组

  • test 组

  • docs 组