# detected_objects_3d

**Repository Path**: hagonglingzhi/detected_objects_3d

## Basic Information

- **Project Name**: detected_objects_3d
- **Description**: 基于 ROS2 Humble + Intel RealSense D435i + YOLOv8，实现实时物体检测与三维坐标估计。系统订阅相机发布的彩色图、对齐深度图和相机内参，利用 YOLOv8 进行目标检测，并通过几何反投影计算每个物体在相机坐标系下的真实三维坐标（单位：mm），结果通过 ROS2 话题发布，可用于机械臂抓取、导航等下游任务。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-06
- **Last Updated**: 2026-03-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# detected_objects_3d（HP60C 版本）

## 📌 项目简介

`detected_objects_3d` 是一个基于 **ROS2 Humble + HP60C 双目深度相机 + YOLOv8** 的三维目标检测项目。

系统通过 **HP60C 相机 ROS2 驱动（ascamera）** 获取彩色图像、深度图像和相机内参，利用 **YOLOv8** 进行实时目标检测，并通过几何反投影计算目标在**相机坐标系下的三维坐标（单位：mm）**，最终以 **JSON 格式** 通过 ROS2 话题发布，可直接用于：

* 🤖 机械臂抓取
* 🚗 机器人导航 / 避障
* 🧭 三维感知与定位
* 📦 目标空间测量

---

## 📦 功能特性

✅ 支持 **HP60C 双目深度相机**（基于 ascamera ROS2 驱动）
✅ 使用 **YOLOv8** 进行实时目标检测（默认 `yolov8n.pt`，可替换）
✅ 计算目标在**相机坐标系下的 X / Y / Z 坐标（单位：mm）**
✅ 同步订阅彩色图、深度图和相机内参
✅ 发布结构化 **JSON 消息** 到 `/detected_objects_3d`
✅ OpenCV 实时显示检测框 + 3D 坐标
✅ 已在 **Ubuntu 22.04 + ROS2 Humble（VMware / 实机）** 环境验证

---

## 🧰 环境依赖

* Ubuntu 22.04
* ROS2 Humble
* **HP60C 深度相机**
* Python 3.10+
* NumPy < 2.0（⚠️ 兼容 `cv_bridge` 必需）

---

## 📂 项目结构

```text
detected_objects_3d/
├── detected_objects_3d/
│   ├── __init__.py
│   ├── detect_3d.py          # 3D 检测主节点（HP60C）
│   ├── yolov8n.pt            # YOLOv8 模型文件（可替换）
│   └── run_detect_3d_hp60c.sh # HP60C 启动脚本
├── requirements.txt          # Python 依赖
├── doc/
│   └── demo.mp4              # D435i效果演示视频
└── README.md
```

---

## ⚙️ HP60C 相机驱动安装（ascamera）

### 1️⃣ 安装系统依赖

```bash
sudo apt update
sudo apt install -y \
  libgflags-dev \
  nlohmann-json3-dev \
  libgoogle-glog-dev \
  ros-humble-image-transport \
  ros-humble-image-publisher
```

---

### 2️⃣ 克隆 ascamera 驱动

```bash
cd ~/ros2_ws/src
git clone https://gitee.com/hagonglingzhi/ascamera.git
```

---

### 3️⃣ 安装 udev 规则（非常重要）

```bash
cd ~/ros2_ws/src/ascamera/scripts
sudo bash create_udev_rules.sh
sudo udevadm control --reload-rules
sudo udevadm trigger
```

📌 **建议重启一次系统，确保相机权限生效**

---

### 4️⃣ 修改 HP60C 启动文件

```bash
cd ~/ros2_ws/src/ascamera/launch
gedit hp60c.launch.py
```

请确认或修改以下内容：

* `configPath` 指向正确的 **HP60C 配置文件路径**
* 分辨率 / 帧率符合你当前机器性能

---

### 5️⃣ 编译 ascamera（根据平台选择）

#### x86_64（PC / 虚拟机）

```bash
cd ~/ros2_ws
colcon build --packages-select ascamera \
  --symlink-install \
  --cmake-args -DCROSS_COMPILE=x86_64-linux-gnu
```

#### Jetson / ARM（示例）

```bash
# Jetson Nano / Xavier
-DCROSS_COMPILE=aarch64-linux-gnu

# 32 位 ARM
-DCROSS_COMPILE=arm-linux-gnueabihf
```

---

### 6️⃣ 启动 HP60C 相机

```bash
source ~/ros2_ws/install/setup.bash
ros2 launch ascamera hp60c.launch.py
```

检查话题：

```bash
ros2 topic list
```

查看图像：

```bash
ros2 run rqt_image_view rqt_image_view
```

---

## ⚙️ detected_objects_3d 安装与配置

### 1️⃣ 创建 Python 虚拟环境（推荐）

```bash
cd ~/ros2_ws/src/detected_objects_3d
python3 -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt
```

#### requirements.txt

```txt
numpy<2.0
ultralytics>=8.0.0
```

---

### 2️⃣ 编译 ROS2 包

```bash
cd ~/ros2_ws
colcon build --packages-select detected_objects_3d
source install/setup.bash
```

---

## ▶️ 使用步骤

### 步骤 1：启动 HP60C 相机

```bash
ros2 launch ascamera hp60c.launch.py
```

---

### 步骤 2：启动 3D 检测节点

```bash
cd ~/ros2_ws/src/detected_objects_3d
source .venv/bin/activate
./run_detect_3d_hp60c.sh
```

确保脚本有执行权限：

```bash
chmod +x run_detect_3d_hp60c.sh
```

---

### 步骤 3：查看结果

#### 🖼 OpenCV 窗口

显示内容示例：

```text
cup 0.87 | XYZ(120, 78, 515) mm
```

#### 📡 ROS2 话题

```bash
ros2 topic echo /detected_objects_3d
```

---

## 📡 发布消息格式

**话题名：**

```text
/detected_objects_3d
```

**类型：**

```text
std_msgs/String   （JSON 字符串）
```

**示例：**

```json
{
  "class": "cup",
  "confidence": 0.874,
  "pixel_center": [435, 255],
  "camera_xyz_mm": [120.36, 78.81, 515.0]
}
```

---

## 📐 坐标系说明（相机坐标系）

* **X**：向右为正
* **Y**：向下为正
* **Z**：向前为正（深度方向）
* **单位**：毫米（mm）

---

## 🔍 验证与调试

### 1️⃣ 检查相机话题

```bash
ros2 topic list | grep image
ros2 topic hz /camera/color/image_raw
```

### 2️⃣ 检查检测结果

```bash
ros2 topic echo /detected_objects_3d
```

### 3️⃣ 检查 NumPy 版本

```bash
source .venv/bin/activate
python -c "import numpy; print(numpy.__version__)"
```

应输出 `1.x.x`（如 `1.26.4`）

---

## 🛠️ 常见问题

### Q1：没有 XYZ 坐标？

* 确认深度图话题正常
* 确认使用的是 **彩色相机内参**
* 确认 HP60C 已正确输出深度

### Q2：运行报 `_ARRAY_API not found`？

```bash
pip install "numpy<2.0"
```

### Q3：HP60C 无法识别？

* 检查 udev 规则是否安装
* 确认 USB 权限
* 尝试重新插拔或重启