UC3DStudio 多 ROI 管理与定位关联（自动跟随）

数据来源：《UC3DStudio 用户说明书》V1.38 §8.1「多 ROI 管理」、§8.1.1「ROI 定位关联（自动跟随）」。

在轮廓上绘制 ROI（感兴趣区域），自动编号 T001、T002…。每个检测项绑定一个 ROI；也可以留空表示「全区域检测」。

绘制必须由右键菜单发起

在轮廓图空白处右键 → 添加矩形ROI / 添加圆形ROI，此时进入「待绘制」态（画布左上角出现蓝色提示横幅），再按左键拖拽落笔。想中途放弃按 Esc。

⚠️ 左键在空白处拖动不会再画出 ROI —— 这是为了防止拖动视图时误建。

矩形 ROI：按住左键拖拽绘制矩形区域。
圆形 ROI：按住左键拖拽设置圆心与半径（拖动距离 = 半径）；绘制完成后可拖动整体移动圆心，或拖边缘调整半径。

ROI 管理面板操作

操作	方法	说明
新建（手绘）	轮廓图空白处右键 → 添加矩形ROI / 添加圆形ROI → 左键拖拽落笔	左键空白处不再直接起框
新建（精确输入）	点添加 → 在对话框选矩形 / 圆形并填写参数 → 确定	矩形填 X 起止 / Z 起止 / 旋转角度；圆形填圆心 X / Z / 半径。默认值取当前视图中央 40% 尺寸；确定后自动在列表中选中该 ROI 并进入编辑态
进入编辑态	在 ROI 列表单击某项	只有处于编辑态的 ROI 响应画布拖拽与把手（其余 ROI 完全不响应，避免误改）
改坐标 / 角度	双击列表项	矩形：X 起止 / Z 起止 / 旋转角度；圆形：圆心 X / Z / 半径。确定即生效并刷新视图与测量范围
旋转矩形	编辑态下拖拽顶边中点的圆形旋转把手	绕中心逆时针旋转，0.1° 步进，角度归一化到 ±180°；拖拽中按右键取消并恢复原角度
移动 / 缩放	编辑态下拖内部 / 拖 8 个边角把手	旋转矩形的缩放已按局部坐标系换算，不会因旋转而「跑偏」
删除 / 清空	删除 / 清空按钮	同步清除编辑态

ROI 列表高度随数量自适应，不再被固定高度压住而截行或出现内部滚动条。
对话框按钮已统一为「确定 / 取消」。

ROI 右键菜单

菜单项	出现条件	作用
添加矩形ROI / 添加圆形ROI	总是	进入待绘制态，随后左键拖拽落笔
取消绘制 (Esc)	仅待绘制态	退出待绘制态
选择 ROI(编辑点)	在 ROI 上右键	令该 ROI 进入编辑态（可拖移 / 缩放 / 旋转），并同步高亮列表行
编辑 ROI...	在 ROI 上右键	直接打开编辑对话框（含「定位关联」分组）
删除 ROI	在 ROI 上右键	删除该 ROI（含其跟随配置与叠加层）
添加测量类型 ▸	在 ROI 上右键 / 空白处右键	在 ROI 上右键 → 关联该 ROI 新建检测项；在空白处右键 → 新建全区域检测（不限制 ROI）

区域检测语义

测量前软件按参与测量的 ROI 计算 X 范围包络：矩形取外接矩形 X、圆形取外接矩形 X [cx−radius, cx+radius]。

旋转 ROI 的测量范围按旋转后的外接矩形（AABB）计算，与视图所见一致；旋转角度随 .uc3dproj 持久化。

定位关联（自动跟随）

工件在产线上存在平移或旋转漂移时，固定 ROI 会逐渐脱离被测特征。开启定位关联后，ROI 可跟随某个检测项的测量结果自动校正中心（矩形还可校正角度）。

入口：双击 ROI 列表项（或在 ROI 上右键 → 编辑 ROI...）→ 对话框内「定位关联」分组。

参数	说明
启用跟随	勾选后生效；取消勾选 ROI 恢复静止，叠加层消失
跟随方式	相对基准（默认）：以示教基准时的位置为基准，跟随源值的增量；绝对定位：直接用源值作为 ROI 中心（不绘制基准虚影）
X 源 / Z 源	选择跟随所依据的检测项与输出项。常用：位置检测的 `位置X` / `位置Z`、角度工具的 `交点X` / `交点Z`
角度源（仅矩形）	角度工具「单直线倾斜」的 `角度` 输出。跟随角度时该角度项必须使用角度范围 = 0（即 [0,180) 模式），否则角度回绕会把 ROI 转飞
死区 X/Z/角度	默认 `0.02 / 0.02 / 0.10` mm(°)。源值相对上次已应用值的偏差小于死区时 ROI 完全静止，跨过死区才步进一次。死区必须大于源值自身的离散误差
限位 X/Z/角度	默认 `5 / 2 / 5` mm(°)。相对基准的累计偏移超过限位时钳位，防止误跟飞
示教基准 / 回基准 / 清除基准	仅「相对基准」模式可见。示教基准 = 把当前位置记为基准；回基准 = ROI 复位到基准虚影；清除基准 = 撤销示教，下次开始测量时由首帧重新自动捕获基准

视觉反馈（轮廓图上叠加绘制）

元素	表现
基准虚影	灰色虚线框 + 中心小圆（相对基准模式下的示教位置；绝对定位模式不绘制）
中心十字	ROI 当前实际中心
状态串	相对基准显示 ΔX/ΔZ/Δθ；绝对定位显示 X/Z/θ

状态串颜色：正常浅灰、越限橙色、源失效红色并附「源失效(保持)」字样。

使用步骤

先在轮廓上建好源 ROI（如位置检测用的小 ROI）与目标 ROI（要跟随的测量 ROI），两 ROI 不得是同一个（自引用会被拒绝并告警）。
双击目标 ROI → 勾选启用跟随 → 选好 X/Z 源 → 确定。
开始测量，确认状态串有数值；此时点 示教基准 记录基准（轮廓图上虚线基准框即时更新）。
移动 / 旋转工件，目标 ROI 应每帧贴住特征（延迟 1 帧，为帧末统一应用所换取的结果确定性）。

⚠️ 源 ROI 必须比预期漂移范围更宽。源值只在源 ROI 的捕获范围内有效——过窄的源 ROI 在工件漂移出界后不会报错，而是静默输出错误位置，表现为 ROI「越跟越偏」。

⚠️ 连续测量链路暂不支持旋转 ROI：连续（高速）测量走独立的数据过滤路径，目前不感知 ROI 旋转角。若跟随会改变 ROI 角度，请以单次测量 / 检测流程链路为准。

持久化：跟随配置随 .uc3dproj 保存；旧工程无该属性时默认关闭跟随，行为与升级前一致。