IntelliSort

IntelliSort 是一个面向 Ubuntu 的智能分拣项目，组合使用 Orbbec/OpenNI 深度相机、RGB 相机、YOLO 目标检测和串口机械臂控制，实现目标识别、三维定位、标定矩阵生成和抓取分拣。

当前仓库已经从“若干独立脚本”整理成 uv 管理的 Python 项目。主入口是 intellisort CLI，根目录旧脚本仍然保留为兼容包装器。

功能概览

• intellisort sort：运行完整分拣流程，启动目标检测和机械臂抓取。
• intellisort calibrate：生成相机到机械臂的变换矩阵。
• intellisort aruco-demo：显示深度图和彩色图，实时查看 ArUco 检测效果。
• intellisort detect-video：只运行 YOLO RGB 检测。
• intellisort aruco-probe：识别测试图像对应的 ArUco 字典。
• intellisort extract-frames：按间隔抽帧。

项目结构

.
├── src/intellisort/
│   ├── cli.py
│   ├── config.py
│   ├── pipelines/
│   ├── robot/
│   ├── tools/
│   └── vision/
├── save_parms/
│   ├── image_to_arm.npy
│   └── arm_to_image.npy
├── best.pt
├── yolov8n.pt
└── README.md

核心模块说明：

• src/intellisort/pipelines/sorting_pipeline.py：YOLO 检测、深度坐标换算和分拣抓取主流程。
• src/intellisort/pipelines/camera_robot_calibration.py：Aruco 标定和图像/机械臂坐标变换。
• src/intellisort/vision/openni_camera.py：OpenNI 初始化、深度流和坐标换算。
• src/intellisort/robot/serial_arm_controller.py：串口机械臂控制和 G-code 发送。
• src/intellisort/tools/：单独的工具脚本。

环境要求

• Ubuntu 22.04 或相近发行版
• Python 3.10 到 3.12
• uv
• Orbbec/OpenNI2 运行库
• 可用的串口设备，例如 /dev/ttyUSB0
• 本地模型权重文件，例如 best.pt

Ubuntu 环境准备

1. 安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 安装系统依赖

OpenCV、OpenNI 和相机驱动依赖比较依赖本机环境，至少建议准备：

sudo apt update
sudo apt install -y python3-dev libgl1 libglib2.0-0

如果你的 OpenNI2 SDK 不是系统默认位置，需要记住它的库目录，后续通过 INTELLISORT_OPENNI_REDIST 或 --openni-redist 传入。

3. 配置串口权限

sudo usermod -aG dialout "$USER"

重新登录后确认设备路径，例如：

ls /dev/ttyUSB*

安装项目依赖

仓库已经改成 uv 项目，依赖写在 pyproject.toml。

uv sync

说明：

• openni 已尽量写入 pyproject.toml，但它仍然依赖单独安装的 OpenNI2 运行库。
• 如果你在 Python 3.12 下遇到 openni 安装或导入问题，优先切换到 Python 3.10 或 3.11。

常用运行方式

运行完整分拣流程

uv run intellisort sort

运行标定

uv run intellisort calibrate

查看 ArUco 深度演示

uv run intellisort aruco-demo

只运行 YOLO 检测

uv run intellisort detect-video

抽帧

uv run intellisort extract-frames input.mp4 output_frames --frame-interval 20

配置项

默认配置可以通过命令行参数或环境变量覆盖，常用项如下：

export INTELLISORT_MODEL_PATH=best.pt
export INTELLISORT_SERIAL_PORT=/dev/ttyUSB0
export INTELLISORT_CAMERA_INDEX=0
export INTELLISORT_OPENNI_REDIST=/opt/OpenNI2/Redist
export INTELLISORT_IMAGE_TO_ARM=save_parms/image_to_arm.npy
export INTELLISORT_ARM_TO_IMAGE=save_parms/arm_to_image.npy

命令行参数优先于环境变量。

模型和标定文件

• best.pt：当前默认检测模型。
• yolov8n.pt：备用或实验模型。
• save_parms/image_to_arm.npy：图像坐标到机械臂坐标的变换矩阵。
• save_parms/arm_to_image.npy：机械臂坐标到图像坐标的变换矩阵。

如果标定文件不存在，intellisort calibrate 会重新生成。

旧脚本兼容

以下历史文件仍可直接运行，但它们现在只是新包入口的包装器：

• main.py
• yolov8_test.py
• calibration_test.py
• Getdepthvalue.py
• aruco_detect.py
• detect_video.py

已知限制

• 当前实现仍然依赖真实硬件，未提供完整模拟器。
• openni Python 包较旧，不保证所有 Python 3.12 环境都稳定。
• 机械臂投放点和 YOLO 类别映射仍写在代码中，后续如需更强可维护性，建议再抽成独立配置文件。
• Ubuntu 作为主平台，Windows 仅保留历史兼容说明，不再是主文档路线。