摘要:这个项目把头部相机、YOLOv5、圆柱图像几何、机器人坐标转换、六轴机械臂和灵巧手连接起来,完成同规格直立测试件的识别、接近、抓取、分类投放和返回。升级的关键,是让当前图像决定抓取位置,而不是由槽号选择一组固定坐标。实际开发也暴露了几条容易混淆的边界:检测框不等于抓取点,RGB-D相机不意味着运行链一定使用深度,位置标定不等于完整六维手眼标定,控制器接受指令也不等于物体已经入盒。本文沿真实源码解释这些接口,并用历史评估、真机日志和失败记录界定系统已经做到什么、还缺什么。

关键词:机器视觉;YOLOv5;RealSense D435;眼在手外;圆柱几何;机械臂;灵巧手;视觉抓取;Web控制;工程复盘。

版本范围:调查基线为2026年10月28日本地main分支提交c3e02aef5319cc72c21efbf0218d8c5c89fdbc60。当前正式运行描述文件仍指向v24-fix2;最新提交另增加了v25语音、文字和HTTPS候选层。二者共享原有分拣动作,但验证范围不同。本文编写期间只读源码与既有证据,没有启动相机、SDK、机器人、云接口或项目测试。历史数据按原版本引用,不作为最新版本重新验收。

https://github.com/VincentCassano/vision-guided-robotic-sorting

升级要解决的具体问题

项目面向电池外形测试件的自动分拣教学与实验。人工逐件判断和搬放需要持续关注工作区;若未来迁移到真实废旧电池,还涉及带电、破损和材料接触等额外问题。当前实验使用断电圆柱或空壳,验证的是视觉与执行的衔接,没有开展真实废旧电池的危险品处理验证,也没有通过颜色判断电池电化学状态。

原学校方案已经具备机械臂抓取、灵巧手动作和料盒投放能力。它的抓取位置由工作索引和固定间距计算,颜色任务也可以由预设位置决定。下面是保留在参考目录中的历史实现;它是比较基线,不是当前视觉入口。

源码 S01 · deployment/school_bin_reference/ohandtest.py · grasp_battery · L375–L412 · 完整函数;历史学校参考实现,当前不通过此函数计算视觉目标。

def grasp_battery(left_arm, right_arm):
    x, y  = divmod(GlobalVar.CURRENT_WORK_INDEX, 3)
    start_position = copy.deepcopy(GlobalVar.ARM_GRASP_POS)
    start_position[2] = start_position[2] + 0.080
    target_position = copy.deepcopy(GlobalVar.ARM_GRASP_POS)

    start_position[0] = start_position[0] - x * GlobalVar.X_BIAS
    target_position[0] = target_position[0] -  x * GlobalVar.X_BIAS

    # start_position[1] = start_position[1] - y * GlobalVar.Y_BIAS
    # target_position[1] = target_position[1] - y * GlobalVar.Y_BIAS
    start_position[1] = start_position[1] + y * GlobalVar.Y_BIAS
    target_position[1] = target_position[1] + y * GlobalVar.Y_BIAS

    left_arm.grasp_battery(start_position, target_position)
    left_arm.move_to(GlobalVar.HIGHT_POS)
    print("MOVE_TO IS RUNNING !!!!!!!!!!!")
    for pos in GlobalVar.SCAN_BATTERY_POS:
        left_arm.scan_battery(pos)
        time.sleep(0.5)
        requests.post(GlobalVar.INSPECT_URL, json={})
        time.sleep(1.5)
    left_arm.move_to(GlobalVar.SCAN_BATTERY_RESTART_POS)
    # 检测电池颜色放在相对应的分拣框内
    if GlobalVar.battery_color == "WHITE":
        left_arm.palce_object_recycle_area(GlobalVar.RECYCLE_WHITE_AREA)
        # print("True" + GlobalVar.battery_color)

    elif GlobalVar.battery_color == "RED":
        left_arm.palce_object_recycle_area(GlobalVar.RECYCLE_RED_AREA)
        # print("True" + GlobalVar.battery_color)
    else:
        left_arm.palce_object_recycle_area(GlobalVar.RECYCLE_AREA)
        # print("True" + GlobalVar.battery_color)

    left_arm.move_to_idle_position()
    GlobalVar.CURRENT_WORK_INDEX = GlobalVar.CURRENT_WORK_INDEX + 1
    requests.post(GlobalVar.CLEAR_INSPECT_URL, {})

CURRENT_WORK_INDEX先分解成行列,再把固定偏移加到ARM_GRASP_POS。因此,在这个函数里改变抓取位置的直接因素是索引,而不是本轮相机观察到的电池中心。它适合已知摆放规则的演示,不能单凭同时显示了识别画面就称为视觉驱动抓取。

升级后的要求更具体:在允许的工作区内改变测试件位置,重新观察后应生成新的目标;一次启动应能连续处理多个目标;黑色、红色和白色应按当前检测类别投放;观察画面应持续展示,操作者可以从网页控制任务。

这里的“自主”有明确范围。当前支持外径45.8mm、高98mm、直立且处于两种已测量支撑高度的测试件。物体可以改变平面位置,但相机、机器人、工作板之间的安装关系需要保持,近远腕姿和转运走廊仍来自现场记录。任意尺寸、任意高度、任意朝向和未知障碍环境,尚不在已经验证的能力里。

微信图片_20261028113301_510_8-VUJM.png

图1:2026年10月24日四件黑壳批次的原始相机帧,未重绘、未生成。画面展示九槽工作板、四个测试件和两侧料盒。它证明现场布局,不单独证明抓取精度。图像来源、内外层文件名及SHA256见图像溯源记录。

设备、环境与当前项目结构

硬件参数:哪些来自配置,哪些来自现场

组件

已确认信息

本项目中的职责与限制

机器人平台

现场有左右两臂和两只手;本项目记录左臂为睿尔曼RM65BI,六个关节

当前自动分拣控制左臂;未实现双臂任务协作。平台整机名称及右臂独立固件版本没有完整快照

左臂控制器

项目记录V1.6.5;运行日志SDK API 4.3.1

TCP调用读取关节、位姿、限位、保护和运动状态;软件信息某些字符串曾乱码,不能据此补齐所有固件字段

傲意灵巧手

配置身份为ROH-AP001 LBR 2-R RS485;执行端一只

通过机械臂末端RS485转发寄存器命令,设备地址2、端口1、115200波特率;六个位置控制通道不等于六个机械臂自由度

头部相机

Intel RealSense D435一台用于当前视觉链

RGB配置1280×720、BGR8、30fps;头部固定于相机到机器人基座标定关系。当前抓取链只启动RGB流

运行主机

真机日志为Linux、aarch64、Python 3.8.10

不能把Windows开发电脑或另一个x86离线环境当作机器人主机

工作板

亚克力九槽板;槽底到板顶实测9.6mm

定位模型有槽内和板顶两层;没有任意未知高度支持

测试件与料盒

圆柱外径45.8mm、高98mm,红白与黑色同规格、断电;正常品盒和废品盒

颜色决定逻辑投放目的地;方形只识别、不抓取

灵巧手协议、身份和电流配置可从battery_hand_verified_profile.json、school_device_identity.py与hand_bus_startup.py交叉核对。配置保存的六通道电流上限是1299mA,这只是本机保存值,不是本文推导的通用安全电流。

软件版本不能从目录名推断

软件或库

可确认版本/使用方式

证据口径

Linux / Python

真机历史SDK会话:aarch64、Python 3.8.10

已保存的真实动作worker环境;Ubuntu发行版精确版本未完整记录

机械臂SDK

API 4.3.1

真机日志与sdk_environment;二进制需匹配实际架构

YOLO

YOLOv5s v3权重;当前部署TorchScript

模型报告、导出验证和推理源码,不是YOLOv8/YOLO11

PyTorch / NumPy / OpenCV

当前使用torch、numpy、opencv-contrib-python;真机精确版本未完整锁定

requirements-web.txt是依赖清单,不是可重建的环境锁

RealSense SDK

Python接口pyrealsense2

相机源码明确使用;真机SDK与驱动具体版本待补

SciPy

几何求解使用least_squares、minimize_scalar

已被源码依赖,但requirements-web.txt尚未列入,属于部署清单缺口

PyYAML

读取模型与运行配置

项目实际依赖

Web

Python标准库http.server、线程、子进程、JSON;HTML/CSS/JavaScript

没有引入Flask、FastAPI、React或Node服务端

ROS

可选ROS 1任务桥

网页入口不依赖ROS Master;当前没有足够证据固定ROS发行版和版本号

v25附加层

Python标准库HTTPS/SSL、浏览器AudioWorklet、外部ASR与模型接口

候选实现;CA生成工具还依赖OpenSSL命令

另一个历史Linux离线验证环境记录了Python 3.10.21、PyTorch 2.5.1+cpu、OpenCV 4.10.0、NumPy 1.26.4。它用于推理回放,不能代替上表的真机环境,更不能据此声称机器人装有CUDA或GPU。

当前目录树

下面按入口和职责列出实际保留的核心文件,省略历史证据、备份和非运行教学材料。较旧版本号的模块仍可能是当前依赖,判断依据应是导入关系和发布清单,而不是名字新旧。

battery_grasp_ws/
├── README.md / README.en.md
├── requirements-web.txt
├── deployment/
│   ├── CURRENT_RELEASE.json
│   ├── run_visual_task_control_v24.py        当前网页启动入口
│   ├── visual_task_control_v24.py            HTTP、任务与状态
│   ├── visual_task_dashboard_v24.html        网页UI
│   ├── visual_live_camera_v24.py             相机唯一采集端与同帧服务
│   ├── visual_detection_confirm_v24.py       2秒可见性统计
│   ├── run_visual_pick_sort_live_v24.py      批次父进程
│   ├── visual_pick_sort_live_v24_vision.py   当前视觉采集入口
│   ├── known_cylinder_geometry*.py          黑壳/轴向几何
│   ├── known_cylinder_color_v23.py          红白轮廓
│   ├── visual_equal_height_plane.py         射线与工作面求交
│   ├── visual_pick_sort_v22_auto_height.py  两层高度判断
│   ├── visual_pick_sort_v22_source.py       near/far选择及目标映射
│   ├── visual_pick_sort_v23_worker.py       机械臂和手部动作
│   ├── hand_bus_startup.py                  末端通信初始化
│   ├── color_bin_adjustment_v23.json        投放修正与抬升配置
│   ├── task_control_ros_v24.py              可选ROS桥
│   ├── run_visual_task_control_v25.py       语音/文字/HTTPS候选入口
│   ├── voice_interaction_v25.py             任务意图与确认
│   ├── voice_web_server_v25.py              HTTPS访问层
│   ├── voice_panel_v25.js / voice_audio_worklet_v25.js
│   └── *-files.sha256                      运行文件校验
├── src/battery_grasp/
│   ├── scripts/yolo_worker.py              独立模型进程
│   ├── src/battery_grasp/jit_inference.py   TorchScript推理
│   ├── src/battery_grasp/inference_client.py
│   ├── config/yolo_v3_calibrated.yaml
│   └── models/                             本机模型;公开源码不附权重
├── calibration/                            运行机器专属资产,不公开发布
├── captures/                               原图、通信与会话结果,运行时产生
├── docs/                                   说明、进度、验收与维护记录
├── tools/release/                          精简发布与运行包构建
└── technical_blog/                         本文及可追溯附件

calibration/和captures/在这里表示运行资产目录,不表示公开仓库克隆后就自带这些数据。资产说明列出了权重、设备SDK、标定和绑定的恢复要求。

系统如何把图像交给动作

模块与数据流

持续运行的是相机采集、推理和Web状态服务;自动抓取需要用户发起任务。网页不直接下发关节角。任务父进程负责选择当前目标,动作子进程只接收已经生成并带有来源的请求。末端通信仍经机械臂控制器转发,不由浏览器接触RS485。

一轮完整业务流程

“工作区未再观察到目标”仍是视觉结论;“动作结果完成”是控制流程结论。当前缺少独立传感器确认每件物体确实入了正确盒,因此二者不能直接合并成工业分拣成功率。

目标检测:训练、阈值和推理边界

数据与模型的真实选择过程

运行模型来自YOLOv5s v3,历史记录选择的是epoch 27的last.pt。曾使用含v1字样的旧文件名,但文件内容哈希属于v3;后续部署导出为battery_v3_camera.torchscript。这也是保留文件哈希而不只记文件名的原因。

保留的训练库yolov5s.yaml使用Conv、C3、SPPF骨干及上采样、Concat融合,检测头输出P3/8、P4/16、P5/32三个尺度;深度和宽度倍率为0.33、0.50。该文件的nc: 80是通用模板,部署任务实际是下面列出的四类,不能照抄成80类电池识别。模板、训练协议和历史报告均随本文保留了原始副本,见证据索引。

v3协议记录从v1最佳权重初始化,学习率0.0005,最多60轮、patience 20;减少mosaic并进行亮度/饱和度增强。历史划分为118张训练、28张验证、4张测试,实际训练27轮。4张测试只含黑色和方形,初始化还见过部分旧验证图,因此早期零误检/漏检只能作为已有素材回归,不能代表独立泛化。部署选择last而非第7轮best,也涉及新增训练素材复核,选择过程的局限必须与结果一起保留。

历史v4试验并非没有训练。报告记录了289张训练图像、123张验证图像和424个验证目标;实际训练26轮,最佳模型在第1轮,采用v3权重微调。验证标注曾由模型建议后再修订,且画面来自相近工作台。即使没有完全相同图像同时进入训练和验证,仍不能把它称为独立场景的无偏泛化评估。

最终保留v3,理由是按部署阈值重新运行实际推理worker后,v3得到423 TP、7 FP、1 FN,而v4为423 TP、15 FP、1 FN。v4的某些总体训练指标略有提高,并没有转化为本场景各类别误检同时减少。完整历史材料保存在训练报告和阈值评估报告,它们是历史报告,不是本文新做的实验。

输入、模型输出与类别

源码 S02 · src/battery_grasp/src/battery_grasp/jit_inference.py · BatteryDetector.__init__ · L9–L17 · 完整函数;当前TorchScript加载。

    def __init__(self, repository, weights, device='cpu', confidence=.25, iou=.45, square_confidence=None, class_confidences=None):
        if device == 'auto': device='cuda:0' if torch.cuda.is_available() else 'cpu'
        if str(device).isdigit(): device='cuda:'+str(device)
        self.device=torch.device(device)
        self.model=torch.jit.load(str(weights),map_location=self.device).eval()
        self.confidence,self.iou=confidence,iou
        self.class_confidences=class_confidences or [confidence,confidence,confidence,square_confidence if square_confidence is not None else confidence]
        if len(self.class_confidences)!=4 or any(not confidence<=v<1 for v in self.class_confidences):
            raise ValueError('Invalid class thresholds')

构造函数将权重载入指定设备并切换到评估模式。auto会根据PyTorch实际可用情况选择CUDA或CPU;源码具有这个分支,不代表现场已经验证GPU推理。class_confidences必须有四项,并且不能低于基础置信度。

源码 S03 · src/battery_grasp/src/battery_grasp/jit_inference.py · BatteryDetector.detect · L19–L53 · 完整函数;当前推理与NMS。

    def detect(self,bgr):
        if bgr is None or bgr.dtype!=np.uint8 or bgr.ndim!=3 or bgr.shape[2]!=3: raise ValueError('Expected uint8 BGR image')
        h,w=bgr.shape[:2];r=min(640/h,640/w)
        nw,nh=round(w*r),round(h*r)
        dw,dh=(640-nw)%32/2,(640-nh)%32/2
        im=cv2.resize(bgr,(nw,nh)) if (nw,nh)!=(w,h) else bgr
        im=cv2.copyMakeBorder(im,round(dh-.1),round(dh+.1),round(dw-.1),round(dw+.1),cv2.BORDER_CONSTANT,value=(114,114,114))
        tensor=torch.from_numpy(np.ascontiguousarray(im.transpose(2,0,1)[::-1])).to(self.device).float().unsqueeze(0)/255
        with torch.inference_mode(): prediction=self.model(tensor)[0].cpu().numpy()
        prediction=prediction[prediction[:,4]>self.confidence]
        if not len(prediction): return []
        scores=prediction[:,5:]*prediction[:,4:5]
        classes=scores.argmax(1);conf=scores[np.arange(len(scores)),classes]
        valid=conf>self.confidence;prediction,classes,conf=prediction[valid],classes[valid],conf[valid]
        boxes=np.concatenate((prediction[:,:2]-prediction[:,2:4]/2,prediction[:,:2]+prediction[:,2:4]/2),axis=1)
        order=np.argsort(-conf,kind='stable')[:30000];keep=[]
        while len(order) and len(keep)<1000:
            i=order[0];keep.append(i);others=order[1:]
            lo=np.maximum(boxes[i,:2],boxes[others,:2]);hi=np.minimum(boxes[i,2:],boxes[others,2:])
            area=np.maximum(hi-lo,0).prod(1)
            overlap=area/((boxes[i,2:]-boxes[i,:2]).prod()+(boxes[others,2:]-boxes[others,:2]).prod(1)-area+1e-12)
            order=others[(classes[others]!=classes[i])|(overlap<=self.iou)]
        result=[]
        # Match YOLO scale_boxes: padding is computed from the actual tensor dimensions.
        gain=min(im.shape[0]/h,im.shape[1]/w)
        pad_x,pad_y=(im.shape[1]-w*gain)/2,(im.shape[0]-h*gain)/2
        for i in keep:
            c=int(classes[i]);confidence=float(conf[i])
            if confidence<self.class_confidences[c]: continue
            x1,y1,x2,y2=boxes[i]
            x1,x2=np.rint(np.clip((np.array([x1,x2])-pad_x)/gain,0,w)).tolist()
            y1,y2=np.rint(np.clip((np.array([y1,y2])-pad_y)/gain,0,h)).tolist()
            result.append(dict(class_id=c,class_name=NAMES[c],category=CATEGORIES[c],grasp_supported=c!=3,confidence=confidence,
                               u=(x1+x2)/2,v=(y1+y2)/2,bbox=[x1,y1,x2-x1,y2-y1]))
        return result

输入是uint8三通道BGR图像。代码按最长边640等比缩放,再以32的倍数约束补边,因此实际张量不必恰好640×640。颜色转为RGB、维度转成CHW后归一化到0~1。输出置信度由目标存在概率与类别概率相乘,随后执行按类别的贪心NMS,最后把框还原到原图坐标。

ID

模型类别

当前阈值

实际任务

0

black_cyl_battery

0.80

正常品盒

1

red_cyl_battery

0.55

废品盒

2

white_cyl_battery

0.70

与红色共用废品盒位姿

3

square_battery

0.30

只识别,不生成抓取动作

基础过滤阈值为0.25,NMS IoU为0.45。这里的颜色是外观类别,不能推导电池是否损坏、是否充电或应如何化学回收。

yolo_worker.py把模型放到独立Python进程中,父进程经JSON行协议发送PNG图像,接收检测结果。这样可以明确指定推理解释器,也把普通输出与协议输出分开。inference_client.py使用请求锁、读取线程和队列;纯推理子进程超时可以终止,但这不等于可以同样粗暴地杀死一个正在控制带载机械臂的进程。

为什么框稳定,定位仍可能不稳定

检测只回答“这个区域像哪类物体”。抓取定位还要恢复圆柱顶端和轴向,轮廓上的反光、标签、阴影和亚克力背景都可能改变拟合。框变化几像素可能使后续ROI截到不同边界;反过来,框几乎不动,也可能有顶缘的亚像素变化。

当前未把YOLO框中心直接作为抓取点。黑壳用圆柱顶端外缘及物体轮廓约束;红白增加彩色前景提取。定位检查失败时,调度器保存原图和原因,重新观察或轮换目标,而不是用上一件目标坐标补位。这个策略避免把坏测量发送给机械臂,但也带来了后文记录的“看得到却不抓”的可用性问题。

从RGB-D诊断到当前RGB定位

深度方法确实存在,但不是当前网页抓取的数据源

项目早期有深度预览与World坐标诊断。基本反投影关系为:

实现通过RealSense反投影接口处理相机模型,不应把上面的理想针孔公式当作绕过畸变参数的理由。深度图需要与选定RGB像素对齐,距离单位也必须从设备尺度转成米。

源码 S04 · deployment/depth_preview.py · measure · L5–L24 · 完整函数;保留的深度诊断函数,当前网页抓取未使用深度流。

def measure(depth, scale, u, v, intrinsics, deproject):
    result = dict(depth_valid=False, position_optical_m=None, execution_ready=False)
    h, w = depth.shape
    if not np.isfinite([scale, u, v]).all() or scale <= 0 or not (0 <= u < w and 0 <= v < h):
        return dict(result, depth_reason='Invalid pixel or depth scale')
    x, y = int(u), int(v)
    patch = depth[max(0,y-3):min(h,y+4), max(0,x-3):min(w,x+4)].astype(float)*scale
    valid = patch[np.isfinite(patch) & (patch >= .15) & (patch <= 3.0)]
    result['depth_valid_fraction'] = float(valid.size/patch.size)
    if valid.size < 5 or valid.size/patch.size < .5:
        return dict(result, depth_reason='Insufficient valid depth')
    z = float(np.median(valid))
    spread = float(np.percentile(valid,90)-np.percentile(valid,10))
    result.update(depth_m=z, depth_spread_m=spread)
    if spread > .04:
        return dict(result, depth_reason='Depth edge or unstable surface')
    point = [float(p) for p in deproject(intrinsics, [float(u),float(v)], z)]
    if not np.isfinite(point).all():
        return dict(result, depth_reason='Invalid deprojection')
    return dict(result, depth_valid=True, position_optical_m=point, depth_reason='')

这是depth_preview.py中的诊断函数,不属于当前抓取入口实际采集的深度流。它读取像素附近7×7区域,筛掉无效值和0.15~3m以外的数据,要求有效点数量及比例满足条件;用中位数取深度,并以P90-P10检查局部离散程度。返回中的execution_ready=False明确限制了用途:一个表面点没有自动成为TCP目标。

当前相机入口只启动颜色流

源码 S05 · deployment/visual_live_camera_v24.py · LiveCamera._capture · L32–L66 · 完整函数;当前相机采集与资源释放。

    def _capture(self):
        pipeline = None
        try:
            import numpy as np
            import pyrealsense2 as rs
            pipeline = rs.pipeline()
            config = rs.config()
            config.enable_device('344322075008')
            config.enable_stream(rs.stream.color, 1280, 720, rs.format.bgr8, 30)
            profile = pipeline.start(config)
            intr = profile.get_stream(rs.stream.color).as_video_stream_profile().get_intrinsics()
            with self.lock:
                self.intrinsics = dict(fx=intr.fx, fy=intr.fy, ppx=intr.ppx, ppy=intr.ppy,
                    coeffs=list(intr.coeffs), model=str(intr.model), width=intr.width,
                    height=intr.height, serial='344322075008')
                self.lock.notify_all()
            while not self.closing.is_set():
                color = pipeline.wait_for_frames(5000).get_color_frame()
                if not color:
                    continue
                image = np.asanyarray(color.get_data()).copy()
                with self.lock:
                    self.image, self.frame = image, int(color.get_frame_number())
                    self.timestamp_ms, self.captured = float(color.get_timestamp()), time.monotonic()
                    self.lock.notify_all()
        except Exception as exc:
            with self.lock:
                self.camera_error = repr(exc)
                self.lock.notify_all()
        finally:
            if pipeline is not None:
                try:
                    pipeline.stop()
                except Exception as exc:
                    self.camera_error = 'camera cleanup: ' + repr(exc)

LiveCamera._capture明确调用的是rs.stream.color。内参来自实际启动的颜色流,图像拷贝和单调时钟时间一起存入共享状态。异常会写入camera_error,退出时停止pipeline。保留的设备序列号是本机绑定信息,复现者应恢复自己相机与标定的匹配关系。

因此,不能把当前系统描述成“检测框中心读取D435深度后直接抓取”。现阶段采用的是已知圆柱尺寸、RGB轮廓、相机外参与两层支撑面约束。D435有深度能力,但当前链没有消费该深度流。

历史上对同一批六组位置,RGB-D路线只有1/6满足5mm判据,最大误差约7.498mm;图案PnP位置一致性为6/6,最大约3.431mm。复核记录没有证明深度误差的单一根因,也没有证明增加一个固定偏置就能修复。当前方案是约束任务模型的工程取舍,而不是已经解决了自由三维深度测量。

标定得到的究竟是什么

固定相机、运动标定板与未知安装偏置

相机在机器人头部,采样期间头部不动;ArUco板随机械臂末端移动。这属于眼在手外的安装关系。项目使用100mm、ID 0、DICT_4X4_50标记,记录相机看到的图案位姿与机械臂当前位姿。

完整六维手眼标定曾出现超差,之后保留的是位置候选。该候选优化相机旋转3个参数、平移3个参数及末端坐标系中的标记中心3个参数,总计9个自由参数。位置残差可以写成:

其中,PCM,i来自图像PnP;机械臂给出RWE,i,tWE,i;qEM​是未知但固定的标记中心偏置。支架安装不必与法兰轴恰好对齐,关键是采样期间板面平整、尺寸正确、与末端刚性连接。纸张鼓起、支架弯曲或采样中相对滑动,会破坏这个模型。

候选使用16组FIT,拟合最大位置残差约4.084mm;另有六组图案位置复核最大约3.431mm。候选参数与独立位置复核保留了来源。这里的“独立”是没有加入那16组拟合,不等于使用外部高精度测量仪建立了真值。

相机坐标到World坐标

保存的变换矩阵,以下仅显示便于阅读的舍入值,程序读取JSON中的完整精度:

平移单位为米,方向为相机点到World点:

当前几何入口读取并核对冻结候选、相机上下文与来源哈希,再变换候选顶端中心。它不允许把六组验证数据重新当作拟合数据,也不把曾失败的RGB-D结果改写成通过。坐标转换的诊断模块world_coordinates.py同样区分可见表面点和抓取TCP。

冻结候选文件仍保留full6D_handeye_pass=False、position_validation_pass=False和diagnostic_pass=False,后续六组图案位置的一致性资格由独立证据文件保存。当前入口核对的是这一组合条件,不能删掉旧失败字段后宣布完整标定通过。

源码 S06 · deployment/visual_pick_sort_live_v24_vision.py · main · L128–L132 · 连续截取,非完整函数;当前视觉入口的连续片段。

        k=np.array([[intr.fx,0,intr.ppx],[0,intr.fy,intr.ppy],[0,0,1.]],float)
        if (k.tolist()!=candidate['source_context']['K'] or list(intr.coeffs)!=candidate['source_context']['distortion']
                or str(intr.model)!=candidate['source_context']['distortion_model'] or any(intr.coeffs)):
            raise ValueError('Camera intrinsics changed; no assumed compensation')
        transform=np.asarray(candidate['world_from_camera'],float)

这段从当前网页视觉入口截取:实测颜色流内参、畸变模型必须与候选上下文一致,随后从JSON读取world_from_camera。它不是每次运行现场重新拟合一个矩阵。

源码 S07 · deployment/visual_pick_sort_live_v24_vision.py · main · L314–L326 · 连续截取,非完整函数;当前几何候选到World的连续片段。

                    item['geometry']=geometry
                    if geometry['geometry_candidate_available']:
                        chosen=geometry['selected_candidate'];world={}
                        for field in ('top_center','geometric_body_center'):
                            p=np.asarray(chosen[field+'_camera_m'])
                            q=transform[:3,:3]@p+transform[:3,3]
                            inside=all(sum(e[j]*p[j] for j in range(3))+e[3]<=.005 for e in candidate['fit_camera_hull_equations'])
                            world[field+'_world_m']=q.tolist();world[field+'_inside_FIT_support']=inside
                            world[field+'_maximum_FIT_face_violation_mm']=float(max(
                                (np.dot(e[:3],p)+e[3])/np.linalg.norm(e[:3])*1000
                                for e in candidate['fit_camera_hull_equations']))
                        world['axis_from_top_into_body_world']=(transform[:3,:3]@np.asarray(chosen['axis_from_top_into_body_camera'])).tolist()
                        item.update(world,geometry_candidate_available=True)

p是几何模块输出的相机坐标点,q才是World点;顶端和几何体中心分别保存。FIT凸包检查另存为来源覆盖诊断,不能将“变换矩阵可以计算”直接解释为所有新位置都已有验证数据覆盖。

这套位置候选仍然没有给出灵巧手任意姿态下的完整TCP和接触模型。实际抓取还需要成功姿态的任务绑定。头部俯仰、左右转动,或相机与基座安装改变后,旧TWCTWC​不能因为图像还能识别就继续当作正确外参。桌子移近移远本身不会改变相机与基座外参,但工作面、可达性和绑定的假设仍须重新核对。

两层工作面与实时抓取坐标

圆柱几何为什么需要已知尺寸

透视投影下,圆柱顶端的圆会呈椭圆。黑壳几何模块从真实轮廓拟合外缘,并以相机内参和已知半径约束空间圆。图像二次曲线CC可通过KTCKKTCK转到归一化相机坐标,再构造圆位姿候选。对称物体可能有多解,因此还需轴向、轮廓和投影尺寸检查。

红白实现使用扩展ROI、GrabCut前景与彩色种子,结合已确认的直立方向拟合顶缘。它没有把整个YOLO矩形都当作物体。拟合残差、完整外缘和身体投影检查是不同的约束:顶端拟合好,不代表侧面没有选错;检测分类正确,也不保证几何完整。

射线与支撑面求交

若圆柱直立且高度固定,其顶端应落在对应支撑面的等高面上。设相机在World中的原点为OO,某候选点给出的World射线方向为dd,平面由点P0P0​和法向nn定义:

源码 S08 · deployment/visual_equal_height_plane.py · project_observation · L49–L71 · 完整函数;当前射线平面求交。

def project_observation(frame, plane):
    if frame.get('geometry_candidate_available') is not True:
        raise ValueError('Original per-frame rim/body image gates must pass')
    chosen=frame['geometry']['selected_candidate']
    camera_point=np.asarray(chosen['top_center_camera_m'],float)
    transform=np.asarray(plane['world_from_camera'],float)
    normal=np.asarray(plane['axis_from_top_into_body_world'],float)
    origin=transform[:3,3]
    direction=transform[:3,:3]@camera_point
    denominator=float(normal@direction)
    if not np.isfinite(direction).all() or abs(denominator)<1e-9:
        raise ValueError('Camera ray parallel to task plane')
    scale=float(normal@(np.asarray(plane['plane_point_world_m'])-origin)/denominator)
    if not math.isfinite(scale) or scale<=0 or not .1<=scale*camera_point[2]<=2.:
        raise ValueError('Plane intersection behind camera or outside original0.1-2m Z range')
    point=origin+scale*direction
    raw=np.asarray(frame['top_center_world_m'],float)
    body=point+.5*float(frame['geometry']['total_height_mm'])/1000*normal
    return dict(top_center_world_m=point.tolist(),geometric_body_center_world_m=body.tolist(),
        ray_scale=scale,raw_free3D_to_plane_correction_mm=float(np.linalg.norm(point-raw)*1000),
        scope='same_upright_shell_equal_seated_top_plane_only',
        height_inferred_from_task_plane=True,independent_depth_measured=False,
        raw_free3D_position_replaced_in_source_record=False,motion_authorized=False,execution_ready=False)

代码中的方向由完整候选点变换而来,不要求预先归一化,因为比例由scale吸收。检查会拒绝近似平行、在相机后方或超出原范围的求交。返回同时保存原自由三维点到平面点的改变量,并明确independent_depth_measured=False。

工作面法向来自参考观测中的圆柱轴向,不是外部测量仪测得的板面法向。这样可以在限定任务内降低单目自由解的波动,但会把参考轴向和工作板固定的假设带入后续结果。

槽底和板顶的高度差是现场量出的9.6mm。板顶假设通过实际高度模型生成新的平面,每个像素射线重新求交,因此XY也可能变化;不能只把一个旧TCP的Z加9.6mm就称为完成视觉测高。

两层判断为何会拒绝一次观测

当前visual_pick_sort_v22_auto_height.py保留两套已测量平面模型,在每帧轮廓上分别拟合,比较像素证据、连续估高和跨帧一致性。采集要求至少8帧且约2秒,坐标重复性限值3mm,顶缘图像质量判据2px。采样上限15秒不包含单帧推理或取帧阻塞,所以不能把15秒当成整个函数的硬实时截止。

3mm描述的是这一组重复观测的离散程度,不是对外部真值的绝对误差。每帧都接近也可能共同偏移;内参、外参和工作面模型中的系统误差不会被重复采样自动消除。

开发中曾增加“整组模型分数”候选以减少单帧翻票,随后伴随其他回归回退到成功基线。本文调查的当前运行链不能被写成已经启用了那个候选规则。历史fix13的测试或日志,不能覆盖当前文件的逐帧判断事实。

视觉点怎样变成机械臂目标

当前映射使用一次实际成功抓起时保存的TCP,以及当时同一空壳的视觉顶端点。新目标采用相对平移:

源码 S09 · deployment/visual_pick_sort_v16_source.py · target_candidate · L23–L42 · 完整函数;当前调用的公共目标生成模块。

def target_candidate(point,anchor):
    accepted_anchor(anchor);top=point_checked(point)
    surface=point.get('support_surface')
    expected_plane,rise,digest=support_plane(anchor['equal_height_plane'],surface)
    if (point['binding_camera_context']!=anchor['camera_context']
            or point['equal_height_plane']!=expected_plane
            or point.get('measured_support_rise_mm')!=rise
            or point.get('support_height_model_sha256')!=digest):
        raise ValueError('Target support height/camera/plane differs from its retained image evidence')
    old=anchor['reference_pregrasp_tcp_pose_m_rad'];origin=anchor['reference_top_center_world_m']
    delta=[top[i]-origin[i] for i in range(3)]
    pose=[old[i]+delta[i] for i in range(3)]+old[3:];upper=pose[:];upper[2]+=.180
    return dict(scope='live_visual_translation_from_actual044001_pickup_measured_support',
        pregrasp_tcp_candidate_m_rad=pose,hover_tcp_candidate_m_rad=upper,
        delta_from_reference_world_mm=[v*1000 for v in delta],fixed_wrist_rpy_rad=old[3:],
        prepare_recipe=anchor['prepare_targets'][:],grip_recipe=anchor['grip_targets'][:],lift_mm=180,
        support_surface=surface,measured_support_rise_mm=rise,support_height_model_sha256=digest,
        every_live_ray_reintersected=True,z_only_TCP_offset_used=False,
        slot_lookup_used=False,grid_snap_used=False,old_offsets_applied=False,
        actual_finger_arrival_required=False,motion_authorized=False,execution_ready=False)

这个函数是当前被调用的公共目标生成模块。它验证相机上下文、支撑面来源和绑定,再按本轮视觉差值平移TCP;上方点提高180mm。slot_lookup_used=False和grid_snap_used=False对应的是抓取XYZ,而不是说系统完全没有工作区分区。

一个可追溯的数值例子来自四件批次的cycle002:accepted_candidate.delta_from_reference_world_mm为[1.041314, -0.543378, -0.020730],生成的TCP约为[183.739311, -296.810381, -180.848735] mm,姿态为[-2.144000, -0.006000, 2.166000] rad。同一worker的下降指令保存了相同目标。这里展示的是历史输入差值到动作目标的对应,不是让读者照抄这组坐标控制设备。

近远腕姿选择位于另一层:

源码 S10 · deployment/visual_pick_sort_v22_source.py · select_profile · L86–L98 · 完整函数;当前腕姿分区选择。

def select_profile(point,grid):
    h=grid_matrix(grid,point['binding_camera_context'])
    x,y=foot(point['measurement_bbox_px'])
    denominator=float(h[2,0]*x+h[2,1]*y+h[2,2])
    if abs(denominator)<1e-12:raise ValueError('Image region projection is singular')
    u=float((h[0,0]*x+h[0,1]*y+h[0,2])/denominator)
    v=float((h[1,0]*x+h[1,1]*y+h[1,2])/denominator)
    if not all(math.isfinite(q) for q in (u,v)):raise ValueError('Invalid image region coordinates')
    row=0 if v<.25 else 1 if v<.75 else 2
    col=0 if u<.25 else 1 if u<.75 else 2
    profile='near' if [row,col] in NEAR_CELLS else 'far'
    return profile,dict(row_from_robot_near= row+1,column_from_robot_image_left=col+1,
        image_region_uv=[u,v],profile=profile,XYZ_snapped_to_grid=False)

image_region_uv来自工作区四边形的映射;分区只决定使用哪套已记录腕姿和抓取绑定,不把坐标吸附到槽中心。当前近处区域覆盖最近横向三格及中间横向的两格,实际以配置的机器人视角为准。三维位置仍来自当前目标图像。

这让系统获得了“在限定工作面内根据当前位置抓”的能力,但没有获得所有位置的全局可达保证。红圈区域使用近处手姿时,现场曾报告J3限位;改用远处姿态是否能完成整条路线,仍是未验证的假设。

机械臂和灵巧手怎样完成一轮

六个通道不是六个角度

手部的通道顺序为拇指弯曲、食指、中指、无名指、小拇指、拇指对掌。发送的是0~65535的原始目标计数,不是角度,也没有被标定为夹持力。机械臂位姿位置使用米、姿态使用弧度,关节位置与限位则使用度;把这几套单位混在一起会直接影响运动。

下表取自当前读取的实际成功记录,近处与远处使用同一组手部目标,但机械臂参考姿态不同。它不是早期调试中曾出现的40000等候选值。

阶段

拇指

食指

中指

无名指

小拇指

对掌

下降后预抓

6001

6000

6001

32000

65535

65535

夹持

26001

16899

19100

32000

65535

65535

投放张开

0

0

0

0

0

保持65535

这些参数见grasp_success_044001/success_record.json和grasp_near_success_140429/success_record.json。它们属于具体空壳、手姿和现场安装,不可直接作为另一只手的通用配方。

成功记录还保存了六通道速度配置65535、电流上限1299mA和力目标读取值;自动周期主要写位置目标,没有实现基于实时电流调节握持力的外环。电流回读用于状态核对,原始速度计数也没有被换算成指尖线速度。位置、电流、速度三种字段应分别解释。

先下降,再预抓,再夹持提起

这次项目最重要的动作修正之一,是把预抓手型放在下降完成之后。无名指和小拇指在该姿态下已经弯曲,如果在高位就准备好再下降,扫掠形状与实测成功路径会不同。

源码 S11 · deployment/visual_pick_sort_v23_worker.py · main.write_shape · L509–L555 · 完整函数;当前成组手部命令。

    def write_shape(desired,before,label):
        nonlocal motion_poll
        motion_poll=None
        desired=targets(desired);current=targets(before)
        io=bus._io
        if io is None or io.broken or bus._logging_error:
            raise RuntimeError('Current grouped hand connection is unavailable')
        if label=='prepare_after_descent':
            if report['phase']!='preparing_after_descent_at_visual_target' or not report.get('qualified_descent_endpoint'):
                raise RuntimeError('PRE6 is allowed only after this actual visual descent')
        elif label=='grip_together':
            if report['phase']!='grouped_grip_then_immediate180mm_lift' or not report.get('prepare_after_descent_targets'):
                raise RuntimeError('GRIP3 requires this postdescent PRE6')
        elif label=='normal_bin_open':
            if report['phase']!='opening_five_flex_at_current_selected_bin' or not report.get('qualified_bin_endpoint'):
                raise RuntimeError('Five-flex release requires this actual final bin endpoint')
        elif label=='initial_stationary_open':
            if (mode not in ('park_empty','visual_cycle') or active_motion
                    or report['phase']!='opening_current_five_flex_before_arm_motion'
                    or request['scene_permission'].get('initial_stationary_group_open_authorized') is not True
                    or request['scene_permission'].get('initial_opening_and_inert_shell_drop_zone_clear') is not True):
                raise RuntimeError('Initial OPEN5 requires stationary arm and authorized clear opening/drop zone')
        elif label=='empty_travel_open':
            if mode not in ('park_empty','visual_cycle') or report.get('initial_open_posture',{}).get('qualified') is not True:
                raise RuntimeError('Travel requires fresh actual open-position qualification')
        else:raise RuntimeError('Unsupported hand phase')
        address,values=io.groups[label];count=len(values)
        if desired[:count]!=list(values) or any(abs(a-b)>2 for a,b in zip(desired[count:],current[count:])):
            raise RuntimeError('Grouped target values or retained channels differ')
        command=dict(label=label,address=address,num=count,channels=list(range(count)),
            targets=list(values),monotonic=time.monotonic(),attempted=False,acknowledged=False,
            one_group_packet=True,actual_arrival_waited=False)
        report['hand_commands'].append(command)
        if any(abs(a-b)>2 for a,b in zip(current,desired)):
            check_abort()
            if external_drag:raise RuntimeError('External teaching during automatic control')
            bus._serial+=1;io.grant_group(label,bus._serial)
            command['attempted']=True;report['hand_register_writes']+=1
            io.write_group(address,list(values));command['acknowledged']=True
            readback=io.read(1135,6);command['target_readback']=readback
            check_targets(readback,desired,'One complete grouped target write')
            hand_protection_read(label,desired)
        else:command['skipped_matching_targets']=True
        report[label+'_targets']=desired[:]
        report['current_hand_targets']=desired[:]
        append('hand',dict(event='grouped_shape_command',**command));save()
        return desired[:]

write_shape依据阶段选择整组寄存器写入:PRE6写六个通道,GRIP3把拇、食、中三个目标放在同一报文中,投放OPEN5同时打开五个弯曲通道。函数核对写入ACK和目标寄存器回读,但没有把接触后无法完全到达目标的手指强行判定为抓取失败。

这与“忽略全部硬件状态”仍有区别。通信失败、保护异常和执行阶段不合法会阻止继续;真实夹持会使实际位置与目标不同,不能仅凭位置未到达就认定软件有故障。另一方面,写入目标成功也不能证明夹紧,电流、工作状态和现场反馈仍须分别记录。

源码 S12 · deployment/visual_pick_sort_v23_worker.py · main.finish_prepared_pick · L804–L816 · 完整函数;当前夹持和连续提起。

    def finish_prepared_pick(after_prepare):
        report['qualified_prepared_current']=copy.deepcopy(after_prepare)
        phase('grouped_grip_then_immediate180mm_lift')
        write_shape(grip,prepare,'grip_together')
        fresh=qualify_own_hand_hold(report['qualified_descent_endpoint'],'grip Cartesian pose retained')
        upper_pose=fresh['pose'][:];upper_pose[2]+=.180
        upper=move('Movel_Cmd',upper_pose,fresh,drive,grip,'lifting_live_grip180mm')
        report['qualified_loaded_upper']=copy.deepcopy(upper)
        if request.get('wrist_profile')=='near':
            upper=move('Movej_Cmd',scan_reference['joints'][:],upper,drive,grip,
                'carrying_to_verified_common_upper')
            report['qualified_common_loaded_upper']=copy.deepcopy(upper)
        deliver(upper,drive,grip)

finish_prepared_pick先发夹持,再确认机械臂仍在本轮下降点,从当前位姿生成Z增加0.180m的提起目标。中间不要求操作者再按一次键,也不等待三个手指在接触状态下全部到达目标。手指驱动可以继续向其目标闭合,提起过程中接触关系随物体离槽而变化。近处姿态提起后,会先转到已经记录的共同高位再接转运。

这实现了夹持与提起紧接的流程,并不意味着已经具备力控制或滑移闭环。当前没有独立握持传感器确认“稳在手里”;实际成功记录中的holding_sensor_verified=False保留了这一点。

连贯转运需要处理ACK和完成通知

源码 S13 · deployment/visual_pick_sort_v23_worker.py · main.deliver · L755–L763 · 连续截取,非完整函数;当前连贯转运队列的连续片段。

        check_abort();active_motion=True
        for row,flag in zip(rows,[1,1,0]):
            check_abort()
            command=dict(method='Movej_P_Cmd',destination=row['pose'][:],v=TRANSFER_SPEED,
                trajectory_connect=flag,r=0,block=False,phase=row['phase'])
            report['motion_requests'].append(command);report['arm_actuator_writes']+=1;save()
            rc=call('Movej_P_Cmd',row['pose'][:],TRANSFER_SPEED,trajectory_connect=flag,r=0,block=False)
            connected['acknowledgements'].append(rc)
            if type(rc) is not int or rc!=0:raise RuntimeError('Connected transfer ACK refused; no retry/queue flush')

三个投放路径节点以trajectory_connect=[1,1,0]排入控制器,避免每个中间点都回到键盘等待。rc=0只是指令被接受。后续代码还检查完成通知顺序、trajectory_state、最终位姿和连续静稳回读,满足条件后才允许OPEN5。

r=0和block=False也不能写成“保证全程不停顿”。源码明确记录nonzero_corner_velocity_guaranteed=False:当前实现减少的是上层重复等待,没有证明控制器经过所有角点时保持非零速度,更没有完成最优时间轨迹规划。

投放修正与返回路径

黑色进入正常品盒,红白共用白色参考投放位姿。当前配置保存黑色原后移40mm再后移30mm;红白相对白色原位后移55mm、右移-35mm,也就是左移35mm,并把投放高度提高60mm。方向由固定头部视角投影到World XY,再作用于不可变的原始料盒位姿,不随每轮重复累加。

投放后黑色竖直抬80mm,红白抬40mm,再按记录的关节姿态返回。数值以当前color_bin_adjustment_v23.json为准,不把聊天中曾提出但没有进入当前基线的修正当作运行事实。该配置还保留physical_new_drop_acceptance=False,因此配置存在不等于每一处新落点均已实机验收。

源码 S14 · deployment/visual_pick_sort_v23_source.py · adjusted_bin · L93–L127 · 完整函数;当前投放偏移生成。

def adjusted_bin(rows,color,previous_offset):
    setting=json.loads((ROOT/'deployment/color_bin_adjustment_v23.json').read_bytes())
    if setting.get('user_confirmed_additional_not_replacement') is not True:
        raise ValueError('Drop adjustment must retain the confirmed additional-offset semantics')
    transform=json.loads((ROOT/'deployment/camera_position_candidate_225543.json').read_bytes())['world_from_camera']
    backward=[-float(transform[0][2]),-float(transform[1][2]),0.]
    right=[float(transform[0][0]),float(transform[1][0]),0.]
    for axis in (backward,right):
        length=math.hypot(axis[0],axis[1])
        if not math.isfinite(length) or length<1e-9:
            raise ValueError('Fixed robot-view horizontal direction unavailable')
        axis[0]/=length;axis[1]/=length
    current=setting[color]
    back_mm=current['additional_backward_mm'];right_mm=current['additional_right_mm']
    if any(type(v) not in (int,float) or not math.isfinite(v) for v in (back_mm,right_mm)):
        raise ValueError('Drop adjustment must contain finite millimetres')
    delta=[(back_mm*backward[i]+right_mm*right[i])/1000. for i in range(3)]
    up_mm=setting.get('red_white_additional_up_mm',0.) if color in ('red','white') else 0.
    if type(up_mm) not in (int,float) or not math.isfinite(up_mm):raise ValueError('Invalid drop height offset')
    delta[2]+=up_mm/1000.
    previous=rows[-1]['pose'][:]
    for i in range(3):rows[-1]['pose'][i]+=delta[i]
    old=previous_offset['delta_world_mm']
    return rows,dict(target_color=color,scope=setting['scope'],
        source_adjustment_sha256=hashlib.sha256((ROOT/'deployment/color_bin_adjustment_v23.json').read_bytes()).hexdigest(),
        previous_offset=previous_offset,previous_drop_pose_m_rad=previous,
        additional_backward_mm=back_mm,additional_right_mm=right_mm,
        additional_up_mm=up_mm,
        robot_view_backward_unit_World=backward,robot_view_right_unit_World=right,
        additional_delta_world_mm=[v*1000 for v in delta],
        total_delta_from_school_world_mm=[old[i]+delta[i]*1000 for i in range(3)],
        adjusted_drop_pose_m_rad=rows[-1]['pose'][:],
        height_and_orientation_unchanged=up_mm==0,orientation_unchanged=True,
        applied_once_from_immutable_source=True,
        physical_new_drop_acceptance=False)

adjusted_bin把相机视角的“后”和“右”投影成World XY单位方向,再将毫米转换成米。它还保存旧偏移、新增偏移和最终位姿,避免一次次调试后无法回答“这60mm是追加还是替换”。Z方向的提高独立处理,腕姿保持来源值。

高位返回曾被改成笛卡尔直线返回后再调整腕姿,结果出现不同逆解分支、J4逼近限位。当前回到了原成功版本的关节目标返回。这说明“TCP位置相同”不能推出“关节姿态相同”,关节余量也不能只在起点检查一次。

当前安全能力的实际范围

当前启动会读取设备状态,检查碰撞等级8、自碰撞开启、普通关节与驱动限位,以及现场授权条件。历史错误4109对应控制器碰撞保护;恢复软件任务不会自动清除它。3°普通限位余量是度数,不是毫米。

这里没有在线场景障碍地图、点云碰撞体、MoveIt、RRT或其他全局避障规划器。系统使用已记录腕姿、转运走廊、现场清空条件和运行时状态约束。控制器自碰撞功能也不能替代对篮筐、桌面、线缆及抓住物体的完整几何建模。

源码 S15 · deployment/visual_pick_sort_v23_worker.py · main · L1074–L1102 · 连续截取,非完整函数;当前异常处理及主要SDK清理,后续收尾未引用。

    except BaseException as exc:
        report['exceptions'].append(dict(error=repr(exc), traceback=traceback.format_exc(),
            phase=report.get('phase')))
        report.update(failed_phase=report.get('phase'), phase='fault',
            outcome='worker_not_completed_no_automatic_retry', physical_object_success=False)
        if active_motion and robot is not None and not stop_attempted:
            stop_attempted = True
            report['arm_stop_writes'] += 1
            try:
                report['fault_stop_raw'] = call('Move_Stop_Cmd', block=False)
            except BaseException as stop_exc:
                report['fault_stop_error'] = repr(stop_exc)
        save()
    finally:
        if bus is not None:
            try:
                report['hand_close'] = bus.close()
            except BaseException as exc:
                report['cleanup_errors'].append(dict(method='manual_hand_close', error=repr(exc)))
        if robot is not None:
            for name in ('Arm_Socket_Close', 'RM_API_UnInit'):
                try:
                    raw = encode(getattr(robot, name)())
                    report.setdefault('sdk_cleanup_results', []).append(dict(method=name, raw=raw))
                    if name == 'RM_API_UnInit' and (type(raw) is not int or raw != 0):
                        raise RuntimeError('API uninitialization returned nonzero/unknown status')
                except BaseException as exc:
                    report['cleanup_errors'].append(dict(method=name, error=repr(exc)))
            report['SDK_cleanup_finished'] = not report['cleanup_errors']

这段连续源码包含异常记录、一次非阻塞停止请求和主要清理逻辑,后续还有日志与文件锁收尾。Move_Stop_Cmd(block=False)返回、SDK关闭和程序退出都不能证明物理停止;当前基线故障分支仍缺少在断开前保存最终停稳状态的完整证据。故障后默认不自动张开,是因为悬空持物与由板承托时的释放后果不同。现场急停与软件请求的作用不能混用。

Web控制、视频和任务状态

持续画面与定位必须使用同一帧

v24把相机所有权集中到LiveCamera:一个采集线程持有D435,另一个推理线程取最新图像,模型仍在独立进程。网页预览一直更新,动作时也不关闭画面。

显示流是GET /live.mjpg的JPEG帧,压缩和标注只用于观看。几何采集经GET /api/sample取得原始BGR字节与X-Frame-Meta:帧号、单调时钟、内参、原图SHA256和该帧检测结果。SharedMeasurement.wait_for_frames检查哈希、帧号递增和采集时刻,再把同一帧交给几何算法。

如果把某一时刻的框画到另一时刻的图上,页面仍可能“看起来像识别到了”,但ROI和目标像素已经错配。这也是不能拿网页截图替代原始定位输入的原因。

控制按钮对应任务命令

源码 S16 · deployment/visual_task_control_v24.py · RealTaskControl.command · L186–L203 · 连续截取,非完整函数;当前启动命令分支的连续片段。

                elif command in ('START','START_AUTO','START_SINGLE'):
                    if not self.ready or self.busy:
                        raise ValueError('任务尚未就绪或仍在执行,不重复启动')
                    if status['state'] in ('PAUSED','STOPPED','INPUT_UNAVAILABLE','STARTUP_NOT_COMPLETED'):
                        raise ValueError('任务暂停;处理现场状态后可重置软件任务,不能自动重试')
                    cam=status['camera']
                    if not cam['measurement_ready'] or cam['frame_age_seconds'] is None or cam['frame_age_seconds']>1:
                        raise ValueError('实时相机/推理尚未就绪:'+str(cam.get('camera_error') or cam.get('inference_error') or '正在初始化'))
                    if command=='START_AUTO':self.mode='AUTO'
                    if command=='START_SINGLE':self.mode='MANUAL'
                    if self.stop_latch.exists():self.stop_latch.unlink()
                    self.ready=False
                    self.busy=True
                    self.phase='开始当前批次'
                    self.reason=''
                    self._send('a' if self.mode=='AUTO' else 'm')
                elif command=='RESET':
                    if self.busy or not self.ready:

HTTP层通过锁保护任务状态,将自动和单件命令分别转为原批次进程的a或m。忙碌时拒绝重复启动;相机测量数据未就绪或过期时不开始新任务。响应的accepted表示接口接受请求,不表示一轮已经完成。

源码 S17 · deployment/visual_task_control_v24.py · create_server.Handler.do_POST · L300–L320 · 完整函数;当前Web控制API。

        def do_POST(self):
            if urlsplit(self.path).path!='/api/command':
                self.reply(404,dict(error='Unknown route'))
                return
            origin=self.headers.get('Origin')
            if origin and urlsplit(origin).netloc!=self.headers.get('Host'):
                self.reply(403,dict(error='Same-origin commands only'))
                return
            try:
                length=int(self.headers.get('Content-Length','0'))
                if not 0<length<=2048 or self.headers.get('Transfer-Encoding'):
                    raise ValueError('Expected a small JSON command')
                if not self.headers.get('Content-Type','').startswith('application/json'):
                    raise ValueError('Content-Type application/json required')
                body=json.loads(self.rfile.read(length))
                if set(body)!={'command'}:
                    raise ValueError('Only command is accepted')
                value=control.command(body['command'])
                self.reply(value['http_status'],value)
            except (ValueError,TypeError) as exc:
                self.reply(400,dict(error=str(exc)))

真实API只接受/api/command的小型JSON请求,字段必须只有command,并核对来源。服务端不是一个允许任意传入Python、SDK方法名或坐标的执行接口。

页面操作

后台实际语义

自动工作

启动当前批次,循环选择合格目标并取放

单步工作

完成一件的整个取放流程,不是单关节运动

继续识别

使用自动任务入口重新观察;不是带载故障续投

停止工作

锁存软件停止请求,阻止后续执行;不自动松手

重置任务

清软件任务状态;不清控制器错误、不回臂

网页控制服务监听后台父进程输出,收集PHASE、就绪标记和结果路径,再提供GET /api/status。动作记录留在captures/,包括父进程结果、每轮request.json、worker_result.json、手部JSONL通信和相机压缩包。原图和原始回包用于排错,不能只保留一句“失败”。

“存在2秒才统计”与“采2秒做定位”是两件事

源码 S18 · deployment/visual_detection_confirm_v24.py · ConfirmedDetections.update · L37–L78 · 完整函数;当前显示统计确认。

    def update(self, detections, frame_number, captured):
        # Re-reading the same frame can never make a pending object mature.
        if frame_number<=self.last_frame:
            return self.snapshot
        if (self.last_capture is not None and
                (captured<=self.last_capture or captured-self.last_capture>self.maximum_gap_seconds)):
            self.tracks=[]
        valid=[]
        for index,detection in enumerate(detections):
            box=detection.get('bbox',[])
            category=detection.get('class_id')
            if (type(category) is not int or len(box)!=4
                    or any(type(v) not in (int,float) or not math.isfinite(v) for v in box)
                    or box[2]<=0 or box[3]<=0):
                continue
            valid.append(dict(detection_index=index,class_id=category,bbox=list(box)))
        candidates=[]
        references={}
        for detection in valid:
            options=[i for i,track in enumerate(self.tracks)
                if detection['class_id']==track['class_id']
                and overlap(detection['bbox'],track['bbox'])>=self.minimum_iou]
            candidates.append(options)
            for i in options:references[i]=references.get(i,0)+1
        tracks=[]
        for detection,options in zip(valid,candidates):
            # Ambiguous overlapping objects do not inherit another object's age.
            if len(options)==1 and references[options[0]]==1:
                previous=self.tracks[options[0]]
                identity,first,observations=previous['id'],previous['first_capture'],previous['observations']+1
            else:
                identity,first,observations=self.next_id,captured,1
                self.next_id+=1
            duration=max(0.,captured-first)
            tracks.append(dict(detection,id=identity,first_capture=first,
                observations=observations,visible_seconds=duration,
                confirmed=observations>=2 and duration>=self.required_seconds))
        # Unmatched targets disappear immediately; a later reappearance starts at zero.
        self.tracks=tracks
        self.last_frame,self.last_capture=frame_number,captured
        self.snapshot=self._snapshot(tracks)
        return self.snapshot

ConfirmedDetections.update只处理新采集帧;重复轮询同一帧不会让目标成熟。类别相同、框重叠并且一对一匹配时继承首见时刻;歧义匹配和消失后的重新出现重新计时。达到至少2秒才进入当前可见数量,短暂闪现不计入,也不逐帧累计。

这只影响展示统计。抓取仍要另外完成至少8帧、约2秒的几何采集与坐标检查;绿色确认框不是运动许可。当前统计也不是“今天总共分拣了多少件”的累计产量。

自动批次先按工作区和支持类别筛选;检测列表按图像框X、Y排序用于编号,但执行目标由VisualRecovery.choose决定:优先观测失败次数较少的目标,再按框底部像素Y较大、X较小的顺序选择,也就是图像中的靠前者优先。采集期间锁定本次ROI,保留每帧实际检测框供诊断,不逐帧把新检测框当成新的测量窗口。这里没有按类别价值或最短旅行距离做全局任务排序;这种简单策略保证流程可追溯,但还有效率优化空间。

一个仍未完成的交互缺口

图2:现场反馈中网页停在“收尾核对、等待指令”,后台实际为VISION_PENDING。截图只是日志可见性证据,不代表一轮成功。

2026年10月26日的记录里,相机连续检出一个红色目标,但三组几何采集失败,批次完成数为0。控制服务没有把具体轮廓失败原因完整呈现在主日志中;随后软件重置可以显示IDLE。识别框存在、界面恢复空闲、任务真正抓完,是三种不同状态。这一问题已进入维护计划,尚未修复。

v25:在任务层增加语音和文字

本地最新提交增加了v25候选:笔记本浏览器提供麦克风,经机器人上的HTTPS服务完成语音识别和文字交互,保留原v24画面、按钮和动作执行器。它不是重新写一套机械臂控制程序,也没有给语言模型直接发送关节或手指指令的权限。

浏览器音频与意图接口

浏览器使用AudioWorklet收集音频,重采样为单声道16kHz、PCM16小端数据。UI单句最长20秒,服务器音频限制为30秒;配置支持普通话与英语的ASR参数。后台调用百度ASR,再把非精确口令的文字交给配置的火山方舟Chat接口。实际模型由model_id决定,当前没有锁定可复现的模型修订号。

语言模型拿不到实时图像和设备测量值,只能输出白名单任务意图;它不能从“抓红色那个”生成项目尚未提供的按类别选目标能力。

源码 S19 · deployment/voice_interaction_v25.py · Interaction.execute · L128–L142 · 完整函数;v25候选,未真机验收。

    def execute(self, command, generation=None):
        with self.lock:
            if generation is not None and generation!=self.generation:
                raise InteractionError('This input was cancelled by a stop request; submit a new command')
            if command not in COMMANDS or command=='NONE':
                raise InteractionError('Unsupported command')
            if command not in ('STATUS','STOP') and self.cfg.get('enable_interaction_commands') is not True:
                raise InteractionError('Voice/text motion commands are disabled in the robot configuration')
            if command=='STOP':
                self.stop_generation()
            # Reuse every existing readiness/scene/busy/stop check / 复用原任务门控。
            outcome = self.control.command(command)
        self.log(dict(event='command',command=command,accepted=outcome.get('accepted'),http_status=outcome.get('http_status')))
        return dict(command=command,reply=outcome.get('message','状态已更新'),execution=outcome,
                    executed=bool(outcome.get('accepted')),physical_completion_verified=False)

这段execute最终仍调用self.control.command,复用忙碌、就绪、停止等检查。新增交互的运动命令默认关闭,查询和停止可用。模型提出动作后还有30秒、单次使用的确认;停止会递增取消代次,让迟到网络结果失效。它限制的是任务层权限,不能代替动作层的设备检查。

“停止”按钮直接走原控制接口,不等待ASR或模型。语音“停止”仍受录音、网络与识别延迟影响,不能作为现场硬件急停。

HTTPS、局域网与验证边界

候选层内部HTTP仅监听回环18081端口,外部HTTPS默认监听所有IPv4网卡的18082端口。0.0.0.0是监听含义,不是客户地址,也不代表证书匹配所有IP。证书SAN应包含实际访问的IP或域名,客户只安装管理员核对过的公开根证书;CA私钥、服务端私钥和云Key不进入源码包。

v25还增加HTTP Basic访问口令和同源检查,v24本身的普通HTTP入口不能因此被称为已经具备同样的认证层。两版复用同一个设备进程锁,不应并行启动。

已有验收文件记录了17项模拟接口检查、PCM处理、私有CA下的真实TLS连接验证和包CRC检查。但同一文件明确写着real_cloud=False、real_browser_microphone=False、robot_deployment=False、physical_acceptance=False。所以当前结论是候选源码及离线接口/TLS验证完成,真实云、客户浏览器和真机链路待验收。本文只读取这些既有结果,没有重新运行测试。

结果、指标与验证范围

功能状态矩阵

能力

实现位置

当前状态与证据

边界

RGB采集与电池检测

visual_live_camera_v24.py、TorchScript worker

历史检测与相机采集已验证;当前持续Web链已实现但现场验收不足

30fps是采集配置,不是实测端到端帧率

黑/红/白/方形分类

jit_inference.py、类别配置

有原图实际worker评估和现场分类记录

方形不抓;颜色不等于真实电池状态

两层空间定位

圆柱几何、自动测高和平面模块

限定工作面已有成功取放;仍有几何拒绝

不支持任意未知高度和任意姿态

左臂单件抓取

成功记录、动作worker

有实际提起和投放记录

没有自动握持力/滑移真值

连续多件黑壳分拣

四件批次原始结果及审阅

已确认4个动作周期,near两件、far两件;现场报告完成

不是九个槽位覆盖,不是长期成功率

三色分类投放

v23类别、投放及运行记录

有部分红白/黑色取放现场记录

未形成混合批次、全部区域、全部新落点的统一统计验收

Web任务与2秒统计

v24控制、相机、确认模块

已实现,有页面及后台现场问题记录

当前发布元数据仍为等待现场验收;拒绝原因展示有缺口

异常保存与软件停止

worker、控制层、JSONL

有失败记录、停止请求与清理证据

故障后的最终物理停稳证明仍不足

ROS任务桥

task_control_ros_v24.py

已实现但缺少本轮可靠实机桥接验收

可选,网页不依赖ROS Master

语音/文字/HTTPS

v25新增文件

候选代码及离线接口/TLS检查通过

实云、现场麦克风、真机部署未验收

右臂协作、任意物体、在线避障

无完整当前链

规划中

不因硬件有两臂或深度相机就自动具备

检测指标:先说数据口径,再给数字

Precision和Recall的定义为:

数据与阈值

TP / FP / FN

Precision

Recall

能说明什么

v3,123张原图、424个目标,部署类别阈值

423 / 7 / 1

98.37%

99.76%

保存的实际worker检测结果;ROS未参与

同一批标签对应的123张裁剪副本,重新推理

422 / 6 / 2

98.60%

99.53%

改变像素输入后的另一组结果,不能与原图混算

v4,同一原图集合、其选定类别阈值

423 / 15 / 1

96.58%

99.76%

在这套部署评估中误检更多,因此未替换v3

原图v3按类为:黑色293 TP / 2 FP / 0 FN,红色57 / 4 / 1,白色57 / 1 / 0,方形16 / 0 / 0。报告记录过红色窗帘、板孔和黑色杂物的误检,以及遮挡红色目标的漏检。裁剪改变了输入尺度和背景,不能简单从原图误检清单里删掉背景框就当作新的推理实验。

历史训练报告还保存了另一种口径:基础置信度0.25时,v3的P/R为83.60%/99.76%,mAP50为99.39%、mAP50–95为96.91%;v4分别为84.94%/99.76%、99.38%、97.28%。固定阈值P/R和完整PR曲线的mAP不是同一个统计量,也不同于上表采用类别阈值的结果。

上述验证集参与了阈值选择,标注也不是独立盲审真值。数字可以描述该集合中的检测表现,不能外推成所有光照条件的识别率,更不能外推成整机抓取成功率。

定位误差与机械误差不能互换

记录

数量与结果

正确解释

位置候选拟合

16组FIT,最大约4.084mm

拟合残差,不是独立目标抓取精度

图案PnP位置复核

6组,6/6满足5mm,最大约3.431mm

图案位置一致性;没有外部测量真值的绝对精度保证

对应RGB-D位置复核

6组,1/6满足5mm,最大约7.498mm

这条路线未达到判据;不能写成已通过

视觉采集3mm检查

至少8帧、约2秒

组内坐标重复性门限,不是系统定位精度

实际抓取记录提起

far约179.980mm,near约180.002mm的World Z变化

机械臂回读的提起量,不等于物体跟随量或绝对抓取误差

这里没有可靠的机械臂绝对定位精度测试,不能用厂家宣传值补成项目实测;也没有证据把所有5mm残差归因于肉眼不可见的机械抖动。图像估计、时序、标定和模型约束都可能贡献误差,需要不同实验分开定位。

四件批次与耗时

四件批次审阅确认四个visual_cycle完成,均无记录中的异常和清理错误,自动回观察位;最后一次扫描没有再观察到黑壳,操作者报告“非常完美”。来源包SHA256为6a31f5bd5f86bde3eff767d5dd117432c5d8be07c0a0217cea7d8203a33d2976。

这批记录使用关节移动15%、下降/提起和转运10%,不是当前30%/15%设置。父进程attempts记录的四个动作子进程elapsed_seconds分别为92.625、98.199、98.261、92.375秒,范围92.37~98.26秒。它包括动作进程启动、设备检查、取放和返回,不包含此前的视觉采集,不能叫完整单件端到端耗时;更不能据此按速度比例推算当前节拍。

仍缺少统一统计的指标包括:当前30%/15%版本端到端节拍、实测推理FPS和P95耗时、九槽全覆盖抓取率、混合颜色长批次结果、滑落率、错盒率、持续运行稳定性。没有这些记录的地方,本文不填估计值。

真正遇到的BUG及其处理

1. NumPy布尔值使结果打包崩溃

现象与条件:几何采集完成后,保存JSON时出现Object of type bool_ is not JSON serializable。前面已经采到A或B,并不代表最终结果一定能落盘。

原因与改动:NumPy计算得到的标量进入报告。当前公共记录模块先递归转换数组、标量、容器,再序列化;写文件采用临时文件替换,禁止NaN进入标准JSON。

源码 S20 · deployment/known_cylinder_records.py · native · L8–L21 · 完整函数;当前JSON原生类型转换。

def native(value):
    if value is None or type(value) in (bool, int, float, str):
        return value
    if isinstance(value, dict):
        if any(not isinstance(key, str) for key in value):
            raise TypeError('Record keys must be strings')
        return {key: native(item) for key, item in value.items()}
    if isinstance(value, (list, tuple)):
        return [native(item) for item in value]
    if type(value).__module__.split('.')[0] == 'numpy':
        # Scalars (including bool_) and ndarrays become explicit native values.
        converted = value.tolist() if hasattr(value, 'tolist') else value.item()
        return native(converted)
    raise TypeError('Unsupported record type: '+type(value).__name__)

这段是当前native函数的原样实现。tolist和item负责转回Python类型,嵌套容器继续递归;非有限浮点最终由encode的allow_nan=False拒绝。修复的是结果边界,不应为了让JSON通过而把几何失败改成成功。后续已有可读取的观测和批次报告,但本文没有重新运行该历史采集流程。

2. 机器人重启后,末端寄存器读不到

现象:首次身份读取返回read_state=false,界面只报“手部读取不完整或已过期”。发生在重启后,即使手为空也一样失败。

定位:手是否握物与通信是否配置成功是两件事。原始JSON表明请求还没有进入位置控制,失败在末端Modbus身份寄存器读取。

修复:hand_bus_startup.py在需要时配置控制器末端通信,再核对设备身份,而不是根据“看起来没电池”跳过读取。Git提交75d7ad7记录此修正。它处理配置丢失,不保证以后不会有晚到回包、权限锁存或真正断线。后续每批复用连接的候选又出现过晚到报文,最终仍须按原始事务归属排错。

3. 指令ACK成功,连贯转运仍失败

现象:三个Movej_P_Cmd都返回0,随后出现trajectory_state=false或完成通知不符,物体仍在手中、停在共同高位附近。

定位:ACK是队列受理,不是运动完成。原通知里存在控制器明确的轨迹失败,不能只把它当作“日志顺序不好看”。新增投放点和腕姿也可能超出实际规划能力。

处理:保留原始通知、最终状态和来源高位;红白共用白色位姿,并增加投放高度的候选修正。当前执行器检查1/1/0通知与实际终点后才释放。这个语义检查已经写入代码,但不能由此宣称任意新增投放位姿均可达;当前配置的新落点验收标志仍为false。

4. 为了让返回更好看,反而改变了逆解分支

现象:取放后先直线回观察位置再调腕,J4先接近-175.019°,停止请求之后的后续静态回读约-176.94°;后面恢复原版也在预检报余量不足。

证据:J4故障链复核区分了两个事实:fix14在新增笛卡尔腕姿阶段实际写过动作;后来的fix15和恢复fix11均为0次动作写入,继承了已经停下的残余状态。不能把多次预检拒绝写成多次自主旋转。

改动与边界:撤回固定TCP调腕候选,恢复成功版本记录的关节返回。非阻塞Stop后的最终停稳回读缺口也被单独记录。该缺口没有因为动作回退就自动消失;完整停止轨迹仍缺少数据。经验是优化返回路径时必须比较关节轨迹,不能只比较笛卡尔终点。

5. 0.1mm级机械臂回读变化也打断了流程

现象:下降后预抓阶段报“arm unchanged”不匹配,日志中的位置差约0.100mm,姿态约0.001rad、关节差很小。

定位与处理:原先比较过于精细,把实际回读的微小差异当作阶段变化。当前match_arm和match_cartesian_hold区分笛卡尔保持与关节姿态匹配,位置容差按已授权的1mm处理。它不是允许忽略任何关节越界、姿态变化或9.6mm支撑层选择错误;不同物理量不能共用“没超过1mm”的说法。

6. 标准输入失效后反复刷“任务暂停”

现象:终端循环出现input(): lost sys.stdin,程序保留界面但无法继续交互。

修复:4115500对应控制台输入收尾:把输入不可用作为一次明确状态处理,而不是在捕获异常后原地重复调用input()。后续网页通过受控父进程管道发送任务命令,仍需记录子进程是否退出、是否就绪;不能把进程存在视为设备可用。

7. 白壳被身体图像轴的保守门限拒绝

现象:同一白色圆柱的部分帧报Body image axis ambiguous; principal variance ratio below new conservative2:1 gate,其他帧可解,整组因此失败。

修正:透视、明亮侧面和标签影响了轮廓PCA方向;使用已确认直立任务的轴向基准,保留原顶缘质量检查,相关提交为c611494。此后有白色取放现场记录,但这不证明所有颜色轮廓问题都解决;红色ROI越界和身体轮廓不匹配仍在维护记录里。

8. 识别到红壳,三次重观测后仍没有动作

现象:网页出现识别框,但批次0件完成。相机记录分别报Colored foreground reaches expanded ROI; complete rim unavailable与body_silhouette_mismatch,重观测耗尽后保留一个待处理目标。

当前状态:未修复、已搁置。源码中彩色分割ROI和完整外缘门限是排查入口,但缺少本地收到的对应原始相机包,不能声称已经确认是哪一个背景像素或哪段边缘导致。UI没有显示完整原因也是另一个缺陷,应分别处理。

9. 图中某处使用近处腕姿触发J3限位

3:现场标记了一个近处腕姿疑似无法完成抓取的位置。图片没有关节读数或World坐标,不能作为远处腕姿安全可用的证明。

当前状态:已记录,未改运行分区。现场报告近处手姿触发第三关节限位,提出远处手姿可能适用;缺少触发阶段、J3实际角度、完整路径与逆解分支日志。下一步应比较两套腕姿从高位、下降、提起到返回的全链,而不是扩大限位或把整片区域直接换成另一姿态。

10. 候选语音HTTPS层中的慢握手问题

v25开发记录包含慢TLS握手阻塞服务受理的修复:握手移到请求线程并设置超时,避免未完成握手一直占住主受理路径。已有本地TLS检查证据,尚无客户浏览器、Wi-Fi与真机联合验收。这个问题属于新增候选网络层,不能与历史机械臂报错混为一个“都修好了”的结论。

版本演进与取舍

方面

学校参考实现

当前升级实现

还未获得的能力

抓取位置来源

索引、固定起点和行列间距

本轮视觉顶端点相对成功绑定生成TCP

不受工作面约束的自由三维抓取

类别与投放

参考自动流程含预设颜色位置

当前检测类别决定黑色或红白投放

化学类型、容量与安全状态检测

腕姿

预设抓取姿态

near/far分区及两套实际绑定

在线全工作区姿态优化与完整可达保证

手部执行

固定动作及分步流程

下降后预抓、成组手指命令、夹持后紧接提起

力与滑移闭环、自适应抓取不同形状

批次

按已知槽位顺序执行

自动检出、采集、不合格重观测/轮换、取放后再观察

任意复杂堆叠与被遮挡目标处理

交互

本地脚本与终端

持续相机Web控制;v25另加任务层交互候选

已完成现场验收的语音控制产品

证据

参考动作代码

原图、通信、请求、结果、清单哈希和本地验收Git

全过程外部真值与长期统计

Git可以确认下列演进节点,但不能证明每次命名为“验收通过”的提交都经过真机。提交描述的范围和证据必须一起读。

日期

提交

可以确认的变化与范围

2026-10-24

4b278ca

实际视觉周期证据、下降后预抓和成组手指执行

2026-10-24

7380e07

后续成功记录和v20自动批次交付

2026-10-24

5b2f477

四件黑壳结果,以及三色/30%与15%候选配置

2026-10-24

ba20876、c611494

三色参数缺项和白壳图像轴问题修正

2026-10-25

75d7ad7

重启后末端通信准备修正,fix11基线

2026-10-25

e96e0ba、0fb102d

整组高度与连接复用等候选;随后发生回归,不能当作当前全部启用

2026-10-26

6b9fe1e、4115500

恢复成功动作基线,处理终端输入失效

2026-10-26

8709255、af658d0

红白抬升40mm/黑色80mm;2秒可见性统计

2026-10-26

99f99de、0c887c8

公开说明、场景图、精简项目结构和发布整理

2026-10-26

1f2063b、bcad811

将视觉拒绝、近处J3与远处候选记录为待办,没有改动作

2026-10-27

56ad982、6b38ca2

交互教学与笔记本麦克风相关材料,不等于机器人语音验收

2026-10-28

c3e02ae

机器人网页语音/文字及私有CA HTTPS候选,离线接口/TLS范围

项目日期以这些实际记录为准。Git初始化时间不能自动当作立项日期,文件名中的日期也不能单独当作一次现场测试日期。

几次取舍影响了系统形态。RGB-D位置验证未达判据后,改用有明确任务假设的RGB圆柱和平面模型;一次抓取姿势不能覆盖近处区域后,保存独立近处绑定;提高返回轨迹观感引入逆解分支回归后,恢复记录的关节返回;整组高度模型和连接复用候选没有被包装成无条件升级,而是保留回退事实。工程进展需要体现在真实行为改善,不能只看版本号递增。

部署与复现

先区分源码复现与真机复现

公开源码可以用于理解架构和控制逻辑,但仓库不附模型权重、厂商SDK二进制、现场相机标定和成功腕姿绑定。它不是git clone后接上任意机械臂即可运行的通用产品。完整本地工程和公开精简目录也不是同一个仓库工作树。

现有机器人环境优先沿用。新Python环境安装命令原样来自项目README:

python3 -m venv --system-site-packages .venv
source .venv/bin/activate
python -m pip install -r requirements-web.txt

这几行只完成依赖清单安装,不证明设备SDK、SciPy、RealSense驱动、相机权限及TorchScript运行环境已满足。清单未锁定全部版本,且遗漏SciPy,复现者需要按实际源码补齐并记录环境;本文没有修改环境或执行安装。

源码获取命令也来自README:

git clone https://github.com/VincentCassano/vision-guided-robotic-sorting.git
cd vision-guided-robotic-sorting

恢复模型时,应核对docs/ASSETS.md、模型验证JSON、类别映射和权重哈希;恢复SDK时应匹配aarch64与Python接口;标定、near/far绑定、工作区和料盒位姿必须属于同一现场,不能拿本文矩阵直接用于另一台机器人。

当前v24网页入口

在真机部署已准备好、相机和控制器独占、现场整手与含物路线清空的条件下,README中的启动命令是:

/usr/bin/python3 deployment/run_visual_task_control_v24.py --host 0.0.0.0

该命令会启动相机和任务服务,点击任务按钮后才启动动作。不要为了阅读本文在没有设备条件时执行。默认网页地址为本机http://127.0.0.1:18081,局域网客户使用运行主机实际IP的18081端口;hostname -I可查询地址。监听所有网卡不意味着跨网段路由、防火墙和Wi-Fi客户互访必然可用。

默认尝试打开1440×940普通浏览器窗口,不全屏。只启动服务可加--no-browser。如果使用另一Python环境,需要同时指定该环境解释器及--inference-python,避免主服务可用而模型子进程缺库。

启动前会核对运行文件SHA256。修改源码却继续使用旧清单会被拒绝;这种文件完整性错误不是机械臂故障。不要为了跳过校验随便删清单,它同时约束当前动作代码和来源文件的一致性。

ROS桥是可选入口

下面两行同样来自README,仅在已经配置ROS 1环境时使用:

source ~/catkin_ws/devel/setup.bash
/usr/bin/python3 deployment/task_control_ros_v24.py

桥接器通过同一个任务服务控制设备,不应另起第二套SDK控制。历史终端出现过Unable to communicate with master!,它说明当时无法连接ROS Master,不说明相机或手部已经坏了;纯网页路径不依赖该Master。本文没有把ROS桥存在当作ROS联合实机验收。

v25候选的部署入口

v25依赖完整v24基线,不能只拿十个候选文件代替原工程。以下检查命令原样来自v25部署说明:

python3 deployment/run_visual_task_control_v25.py \
  --config "$HOME/.config/sortai-v25/voice.json" \
  --cert "$HOME/.config/sortai-v25/tls-initial/server_private/robot-server.crt" \
  --key "$HOME/.config/sortai-v25/tls-initial/server_private/robot-server.key" \
  --check-only

它只检查文件、私有配置和证书,不启动相机、SDK或动作,也不验证云Key有效性。初次生成CA、初始化私有配置、客户核对并信任公开根证书的完整步骤应按该说明操作;本文不附任何真实凭据。正式启动去掉--check-only之前,还要结束旧v24服务并完成候选层现场验收条件。

启动异常应按所在层定位

表现

首先核对

不能由此推断

权重加载失败

文件是否恢复、TorchScript格式与PyTorch环境

相机外参错误

相机不就绪

设备序列号、占用、权限、实际颜色流

已经允许执行抓取

手部read_state=false

末端通信配置、身份、原始请求与回复

只因手为空就可跳过

4109或关节余量不足

当前控制器状态、限位、触发阶段与原始回读

放宽阈值即可解决路径

看到框却不动作

观测组的具体几何错误、支撑层与最终坐标检查

检测模型一定没识别到

HTTPS证书/麦克风不可用

CA信任、SAN与实际地址、有效期、浏览器权限

监听0.0.0.0即可修复

退出浏览器不等于退出服务。服务终端的停止请求、SDK清理与现场硬件停止各自有边界;特别是在手中仍有物体时,不应把“重置”当作自动松手或回起点。

GitHub源码与许可证范围

项目名称为Vision-Guided Robotic Grasping and Sorting System,公开仓库为:

VincentCassano/vision-guided-robotic-sorting。

这个地址来自精简公开发布工作树的实际origin,不是根据项目名拼接猜测。本地主工程当前没有remote;归档的公开工作树本地HEAD为3c799dd0e344809e1dc6f7aa5139e158b6b7e882。本文调查基线则为本地主工程main的c3e02ae…。两者不同,本文没有重新查询远端当前HEAD,也没有执行推送,因此不能声称最新v25已经发布到GitHub。

公开目录保留源码、配置结构、中文README、英文说明和项目结构;模型、SDK、现场绑定及完整原始采集继续保留在本地资产或备份中。历史Git对象是本文取证来源,不保证所有历史证据文件也存在于精简公共仓库。

许可证需要单独说明:当前没有为整个项目授予统一开源许可证的根LICENSE。第三方说明明确表示没有在该说明中新增项目级许可。第三方材料的许可证不能自动覆盖自有代码和厂商SDK。更准确的表述是“已公开项目源码”,读者在复制、再发布或商业使用前仍需核对具体权利范围。

尚未完成的工作与可执行的改进

已发现的问题与尚未验证的风险

已发现的问题包括:红色目标分割误拒、部分位置近处腕姿的J3可达性、视觉待处理原因未完整进入Web日志、依赖清单遗漏、停止后最终状态证据不足。它们有实际文件、现场记录或源码依据。

另外一些是当前证据没有覆盖的风险:模型在陌生背景与光照下的泛化、长时间连续运行中的通信稳定性、不同摩擦表面上的夹持可靠性、改变电池规格后的几何适配。它们不能写成已经发生过的故障,也不能因为没有报告就视为通过。

优先级

具体目标

可执行路线

应取得的证据

P0

解决红色目标可见却不抓

收回对应原始RGB及每帧掩膜、顶缘点和ROI;定位被拒边界,分别检查分割与投影残差

相同冻结图像修复前后对比,加不同位置真机取放;不能只让失败标记变成true

P0

验证问题区域的腕姿

保存J3实际角度、触发阶段与全链关节轨迹;比较near/far完整路径

到达、下降、带载提起、转运和回程均通过,保留限位余量

P0

让网页显示真实暂停原因

将视觉结果的待处理数量、失败码与人可读原因纳入结构化任务事件

页面与后台同一会话状态一致;重置不篡改上批次结果

P1

把动作周期变成物理结果

提起后检查目标是否跟随,投放后检查指定盒内变化,并关联物体ID

空抓、滑落、错盒与成功分别计数;视觉缺失不能自动算成功

P1

提高三维定位可信度

分离标定、工作面与物体几何误差;用独立位置检查验证;若重启RGB-D路线,重新做对齐和深度实测

独立真值或明确的测量不确定度,不能只复用FIT残差

P1

改善夹持

记录电流、实际位置与短时握持结果;在允许硬件接口内研究力/滑移反馈

受控接触与持续过载的区分证据,不以异响作为成功传感器

P1

故障恢复与停止核对

停止请求后保存最终回读、明确承托/悬空恢复状态;分离只读重连与动作重试

停止ACK、编码器稳定和物理停止分别记录

P2

优化速度与观测效率

按阶段打时间戳,先测重复连接、读取、推理和真实运动占比,再做单变量改动

同版本前后节拍及成功/失败统计;不只报告速度百分比

P2

语音网页现场验收

验证客户CA、麦克风、实云ASR/模型、取消迟到结果与原任务接口

真实客户浏览器与机器人联合记录;保留独立硬件停止能力

P2

工程化部署

补SciPy,冻结主机/依赖/SDK与模型哈希;补全项目许可和设备资产清单

从干净但匹配的环境恢复,不覆盖现场配置

动态避障、更多规格和双臂协作需要新的状态估计、碰撞模型与控制验证,不能通过多加几个固定点自然获得。若引入规划框架,应先明确它接管哪一段路径、如何保持已有成功姿态和夹持条件,再讨论算法选择。

一个可复现的后续评估方案

以下是建议,没有在本文编写期间执行。

  1. 冻结代码、模型、相机参数、标定和动作配置哈希。记录运行主机的Python、PyTorch、OpenCV、SciPy、RealSense与SDK版本。

  2. 建立独立标注的检测集,按颜色、背景、遮挡、反光和区域分层;阈值在验证集选定,最终指标在独立测试集报告。

  3. 对定位另建测量表,逐点记录真值来源和不确定度,分别统计XYZ偏差、最大误差与重复性。两层不能混入同一个平均误差掩盖错层。

  4. 对实际取放逐件记录“检出、定位合格、抓取尝试、确实离面、保持、正确入盒、回观察位”。报告各阶段分母和失败原因,不能以SDK周期完成替代实际入盒。

  5. 从用户发起到物体入盒并返回记录完整节拍;相机、推理、几何、设备初始化、每段动作分别计时,报告样本数、中位数与P95。

  6. 最后进行约定时长的连续运行,记录重新连接、重复任务、资源占用和人工介入次数。长时稳定性应来自这份记录,不能来自一次演示视频。

这套评估能回答“检测模型是否好”“坐标是否准”“手是否抓住”“整批是否完成”四个不同问题。只有把分母和证据分开,后续提速才不会再次把可靠性回归藏在更流畅的画面后面。

这次开发留下的认识

这个项目已经跨过了单纯显示识别框的阶段:当前目标图像参与坐标生成,机械臂按生成结果完成过实际提起和分类投放,四件黑壳批次也保存了连续处理与最终复查记录。与此同时,它仍是受工作面、物体规格、腕姿和现场走廊约束的原型,不能因有了网页和语言模型就把这些约束抹掉。

最消耗开发时间的部分,是各模块对“成功”的定义不一致。视觉模块得到一个中心,动作模块需要完整TCP;手部确认目标寄存器,机械臂却需要物体确实离面;控制器接受一组指令,网页又可能把接口接收显示成任务完成。把这些语义明确下来,比再加一个功能按钮更能减少误判。

另一条经验来自回归:局部看起来更合理的返回直线,可能换了逆解分支;减少连接时间的候选,可能引入晚到报文;更保守的图像判据,也可能把本来可操作的目标长期拒绝。优化必须保留成功基线,并能对照相同条件下的证据说明到底改善了什么。

项目启动时保留了一句“世上无难事,只要肯登攀。”这句提醒最终应落在可追溯的工程工作里:能够解释某次动作为什么发生、某次失败停在哪一层、一次成功究竟覆盖了什么范围。这样的记录,才使下一次修改有可靠的起点。


阅读与取证入口:源码与证据索引、原图与历史材料、代码引用索引。本文全部项目代码片段按原文件连续行摘录,未改写变量、缩进和执行顺序;部署命令与目录树是明确标注的说明材料。文章未自动发布,本文档检查也不属于真机验收。