230 lines
10 KiB
Markdown
230 lines
10 KiB
Markdown
# 🛠️ AutoCalib-Workshop: 传感器自动标定仿真车间
|
||
|
||
本项目基于 NVIDIA Isaac Sim 和 ROS 2，搭建了一个用于多传感器联合标定（Camera + LiDAR）的仿真车间环境。场景内置了 4 个全局机械式旋转激光雷达和标定相机，用于输出高精度的合成数据，以供标定算法和 SLAM 算法的测试与验证。
|
||
|
||
## 📑 目录
|
||
1. [环境依赖](#1-环境依赖)
|
||
2. [快速开始](#2-快速开始)
|
||
3. [输出的 ROS 2 话题](#3-输出的-ros-2-话题)
|
||
4. [团队协作与 Git 配置指南 (必读)](#4-团队协作与-git-配置指南-必读)
|
||
5. [开发与分支规范](#5-开发与分支规范)
|
||
6. [相关文档](#6-相关文档)
|
||
|
||
---
|
||
|
||
## 1. 环境依赖
|
||
|
||
本项目不依赖 Omniverse Launcher，而是采用 **纯 Python (pip) 安装的 Isaac Sim**，便于团队在不同机器（或云端服务器）上快速复现环境。
|
||
|
||
- **操作系统:** Ubuntu 22.04
|
||
- **ROS 2:** Humble Hawksbill
|
||
- **Python 环境:** Conda (Python 3.10)
|
||
- **仿真引擎:** Isaac Sim 4.2+ (`isaacsim` pip package)
|
||
|
||
---
|
||
|
||
## 2. 快速开始
|
||
|
||
### 2.1 克隆代码
|
||
> ⚠️ **注意**：如果您是本团队的开发者，请优先完成 [第 4 节的 Git 配置指南](#4-团队协作与-git-配置指南-必读)，然后再克隆代码。
|
||
|
||
使用 HTTPS 方式克隆（无需提前配置 SSH）：
|
||
```bash
|
||
git clone https://github.com/RuiLi-Class/AutoCalib-Workshop.git
|
||
cd AutoCalib-Workshop
|
||
```
|
||
|
||
### 2.2 配置虚拟环境与依赖
|
||
请确保机器上已安装 Miniconda 或 Anaconda。
|
||
|
||
```bash
|
||
# 创建并激活 Conda 环境
|
||
conda create -n AutoCalib_Workshop python=3.10 -y
|
||
conda activate AutoCalib_Workshop
|
||
|
||
# 安装 Isaac Sim 核心包 (基于 NVIDIA 官方源)
|
||
pip install isaacsim==4.2.0.2 isaacsim-extscache-physics==4.2.0.2 isaacsim-extscache-kit==4.2.0.2 isaacsim-extscache-kit-sdk==4.2.0.2 --extra-index-url https://pypi.nvidia.com
|
||
|
||
# 安装 boto3 botocore s3transfer 功能包，将下列脚本复制到终端执行
|
||
python -c """
|
||
import sys
|
||
import os
|
||
import glob
|
||
import subprocess
|
||
|
||
# 1. 动态获取当前的 Python 环境根目录 (例如 /home/nvidia/.../AutoCalib_Workshop)
|
||
env_base = sys.prefix
|
||
|
||
# 2. 使用通配符动态搜索 isaacsim 的 pip_prebundle 目录，无视具体版本号和系统用户名
|
||
search_pattern = os.path.join(env_base, 'lib', 'python*', 'site-packages', 'isaacsim', 'extscache', 'omni.kit.pip_archive*', 'pip_prebundle')
|
||
matches = glob.glob(search_pattern)
|
||
|
||
if not matches:
|
||
print('❌ 错误: 在当前环境中未找到 Isaac Sim 的 pip_prebundle 缓存目录。请确认 Isaac Sim 已正确安装。')
|
||
sys.exit(1)
|
||
|
||
prebundle_path = matches[0]
|
||
sys.path.insert(0, prebundle_path)
|
||
|
||
try:
|
||
import botocore
|
||
ver = botocore.__version__
|
||
print('=========================================')
|
||
print(f'[*] 成功动态定位到底层 botocore 路径: {prebundle_path}')
|
||
print(f'[*] Isaac Sim 内部的 botocore 版本为: {ver}')
|
||
print(f'[*] 正在为你安装完美匹配的 boto3=={ver} ...')
|
||
print('=========================================')
|
||
|
||
# 3. 强制安装匹配的 boto3
|
||
subprocess.check_call([sys.executable, '-m', 'pip', 'install', f'boto3=={ver}'])
|
||
print('[*] 🎉 修复完成！现在运行仿真脚本不会再报版本冲突错误了。')
|
||
except ImportError:
|
||
print('❌ 错误: 找到了目录，但里面没有 botocore 模块。')
|
||
"""
|
||
```
|
||
|
||
### 2.3 运行仿真车间
|
||
每次运行前，请务必先 source ROS 2 环境，否则底层的 ROS 2 Bridge 插件将无法加载并发布话题！
|
||
|
||
```bash
|
||
# 1. 激活 ROS 2 环境 (请根据实际安装路径调整)
|
||
source /opt/ros/humble/setup.bash
|
||
|
||
# 2. 激活 Python 虚拟环境
|
||
conda activate AutoCalib_Workshop
|
||
|
||
# 3. 启动仿真脚本
|
||
python build_calibration_room.py
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 输出的 ROS 2 话题
|
||
|
||
脚本成功运行后，将在局域网内广播以下 ROS 2 话题。可直接使用 RViz2 订阅查看。
|
||
|
||
💡 **RViz2 可视化提示：** 必须将 RViz2 的 Fixed Frame 设置为 `World`，方可查看到静止、规整的 3D 车间点云。
|
||
|
||
| 数据类型 | 话题名称 (Topic) | 说明 |
|
||
|------------------| -------------------------------- | -------------------------------------------------- |
|
||
| TF 树 s | `/tf` | 包含所有雷达与相机的全局坐标关系 (World -> Lidar_xx) |
|
||
| 图像 |`/workshop/camera/image_raw` | 标定板对齐相机 (720p, 20Hz) |
|
||
| 点云 (前左) | `/workshop/lidar/fl/pointcloud` | 机械旋转雷达 FL (fullScan 模式聚合的 360° 全帧点云) |
|
||
| 点云 (前右) | `/workshop/lidar/fr/pointcloud` | 机械旋转雷达 FR (fullScan 模式聚合的 360° 全帧点云) |
|
||
| 点云 (后左) | `/workshop/lidar/bl/pointcloud` | 机械旋转雷达 BL (fullScan 模式聚合的 360° 全帧点云) |
|
||
| 点云 (后右) | `/workshop/lidar/br/pointcloud` | 机械旋转雷达 BR (fullScan 模式聚合的 360° 全帧点云) |
|
||
|
||
---
|
||
|
||
## 4. 团队协作与 Git 配置指南 (必读)
|
||
|
||
新加入的团队成员，请严格按照以下步骤配置本地 Git 环境，以便顺畅地与组织私有仓库进行交互（使用 HTTPS 方式）。
|
||
|
||
### 4.1 声明你的 Git 身份
|
||
在首次提交代码前，必须全局设置你的身份信息：
|
||
|
||
```bash
|
||
git config --global user.name "你的名字或GitHub用户名"
|
||
git config --global user.email "你注册GitHub的邮箱@example.com"
|
||
```
|
||
|
||
### 4.2 配置 HTTPS 访问 (使用 Personal Access Token)
|
||
由于 GitHub 已废弃密码验证，HTTPS 方式需要使用 **Personal Access Token (PAT)** 作为密码。请按以下步骤生成并配置 token：
|
||
|
||
1. **生成 Token：**
|
||
- 登录 GitHub，点击右上角头像 → **Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)**。
|
||
- 点击 **Generate new token (classic)**。
|
||
- 在 **Note** 中输入用途说明（例如 “Isaac Sim 开发”）。
|
||
- 设置过期时间（建议选 90 天或自定义）。
|
||
- 在 **Select scopes** 中勾选 **`repo`**（完全控制私有仓库）以及必要的 **`workflow`** 权限（如需操作 GitHub Actions）。
|
||
- 点击 **Generate token**，**立即复制并保存生成的 token**（页面刷新后将无法再次查看）。
|
||
|
||
2. **配置 Git 凭据存储（避免每次输入密码）：**
|
||
```bash
|
||
# 启用 Git 凭据缓存（默认缓存 15 分钟）
|
||
git config --global credential.helper cache
|
||
|
||
# 或者使用更持久的存储（凭据将明文保存在磁盘，请确保系统安全）
|
||
git config --global credential.helper store
|
||
```
|
||
|
||
|
||
3. **首次推送时输入凭据：**
|
||
- 执行 `git push` 等需要鉴权的操作时，Git 会提示输入用户名和密码。
|
||
- **用户名**：输入你的 GitHub 用户名。
|
||
- **密码**：输入刚才生成的 Personal Access Token（不是你的登录密码）。
|
||
- 如果配置了 credential helper，后续操作将不再重复提示。
|
||
|
||
### 4.3 关键：切勿忽略 .gitignore
|
||
Isaac Sim 和 ROS 2 运行期间会产生海量的缓存文件（如 `*.usd.cache`、`__pycache__`、`log/` 等）。
|
||
|
||
**严禁将这些大文件推送到远程仓库！**
|
||
本仓库根目录已配置好 `.gitignore` 文件，请在执行 `git add .` 时确保不要使用 `-f` 强行添加被忽略的文件。
|
||
|
||
---
|
||
|
||
## 5. 开发与分支规范
|
||
|
||
为了保证代码库的稳定，请团队成员遵守以下 Git 协作工作流。
|
||
|
||
### 5.1 分支命名规范
|
||
在创建新分支时，请使用 **前缀/功能描述** 的格式（例如：`feature/lidar-sync`）。
|
||
|
||
| 前缀 | 适用场景 | 示例 |
|
||
| ---------- | -------------------------------------- | ----------------------------- |
|
||
| `feature/` | **新功能**：新增传感器、模型或标定算法 | `feature/add-calibration-node` |
|
||
| `bugfix/` | **修复错误**：解决代码逻辑、话题发布等 Bug | `bugfix/fix-tf-error` |
|
||
| `docs/` | **文档更新**：修改 README 或注释 | `docs/update-readme` |
|
||
| `refactor/`| **代码重构**：优化代码结构而不改变功能 | `refactor/clean-lidar-logic` |
|
||
| `test/` | **测试**：增加单元测试或仿真验证脚本 | `test/calibration-verify` |
|
||
|
||
### 5.2 保护主分支
|
||
绝对不要直接在 `main` 分支上开发和提交代码。`main` 分支仅用于存放稳定、经过测试的代码。
|
||
|
||
### 5.3 切分支干活
|
||
开始新功能开发（如编写新的标定算法节点）时，请从最新的 `main` 切出一个独立分支：
|
||
```bash
|
||
git checkout main
|
||
git pull origin main
|
||
git checkout -b feature/your_feature_name
|
||
```
|
||
|
||
### 5.4 提交与推送
|
||
```bash
|
||
git add .
|
||
git commit -m "feat: 添加了xxx功能"
|
||
git push origin feature/your_feature_name
|
||
```
|
||
|
||
### 5.5 代码合并 (Code Review)
|
||
开发完成后，请在 GitHub 页面上针对您的分支发起 **Pull Request (PR)**。由其他团队成员进行 Code Review，确认无误后再 Merge 合并入 `main` 分支。
|
||
|
||
---
|
||
|
||
关于大文件的处理（可选）
|
||
如果你希望优化仓库，可以考虑使用 Git LFS 管理大文件：
|
||
bash
|
||
复制
|
||
# 1. 安装 Git LFS
|
||
git lfs install
|
||
|
||
# 2. 追踪大文件（例如 .usd 文件）
|
||
git lfs track "*.usd"
|
||
|
||
# 3. 提交 .gitattributes 文件
|
||
git add .gitattributes
|
||
git commit -m "Add Git LFS tracking for large files"
|
||
⚠️ 注意：如果已经提交了大文件到历史记录，需要使用 git lfs migrate 来重写历史，否则只是追踪新文件。
|
||
|
||
---
|
||
|
||
## 6. 相关文档
|
||
|
||
本项目包含多个子模块，相关文档位置如下：
|
||
|
||
| 文档 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| **AGV 标定系统总述** | [`agv_calib_brain/README.md`](./agv_calib_brain/README.md) | 自动化标定车间整体架构、核心能力、快速开始 |
|
||
| **仿真启动指南** | [`agv_calib_brain/SIMULATION_GUIDE.md`](./agv_calib_brain/SIMULATION_GUIDE.md) | 如何单独启动 Isaac 仿真各组件 |
|
||
| **源码目录说明** | [`agv_calib_brain/src/README.md`](./agv_calib_brain/src/README.md) | 源码组织结构、边界规则 |
|
||
| **Isaac 仿真车间** | 本文档 | Isaac Sim 环境配置、基础仿真运行 | |