场景管理模块（sceneManager.ts）

模块路径：web_rviz/src/visualization/sceneManager.ts

用途

维护 Three.js 场景、机器人姿态、TF 缓存、主题联动的视口样式、规划轨迹预览、运动采样位姿计算与点云显示。

公开类型

SceneTheme

• dark

• light

TfNode

• frame：当前坐标系名称。

• parent：父坐标系名称。

• translation：平移向量。

• rotation：旋转四元数。

RobotJointConnection

• name：URDF 中的关节名称。

• parent：父 link 名称。

• child：子 link 名称。

• type：URDF 关节类型，例如 fixed、revolute。

RobotTransformDetail

• xyz：平移，单位为米。

• rpy：滚转、俯仰、偏航，单位为弧度。

RobotInertiaDetail

• ixx / ixy / ixz / iyy / iyz / izz：若存在则返回惯量张量分量。

RobotLinkDetail

• name：link 名称。

• parentJoint：父 joint 名称；基座 link 时为 null。

• childJoints：子 joint 名称列表。

• visualCount / collisionCount：URDF 中 visual 与 collision 元素数量。

• materialNames：visual 中引用的材质名称列表。

• mass：若存在则返回惯性质量。

• inertialOrigin / inertia：从 URDF 解析出的惯性原点与惯量信息。

• pose：当前相对固定坐标系的位姿。

RobotJointDetail

• name / type：joint 名称与 URDF 类型。

• parentLink / childLink：连接的父子 link。

• axis：关节轴；未提供时为 null。

• origin：URDF joint 原点。

• limit：若存在则包含上下限、力矩和速度限制。

• dynamics：若存在则包含阻尼和摩擦参数。

• mimic：若存在则包含 mimic 源关节、倍数和偏移。

• currentValue：运行时当前关节值数组。

SceneManager 核心方法

• setTargetFps(value)：设置渲染目标帧率。

• resetView()：恢复默认相机位置与 OrbitControls 视角状态。

• setTheme(theme)：根据界面主题更新背景、网格、光照和主题相关的场景样式。

• setPlannedTrajectoryVisible(visible)：切换 MoveIt 规划轨迹预览的显示状态。

• setPlannedTrajectoryPath(points, startPose?, endPose?)：渲染规划轨迹折线，并可选显示 TCP 起点/终点姿态标记。

• clearPlannedTrajectory()：清除规划轨迹折线及起终点姿态标记。

• setFixedFrame(frame) / getFixedFrame()：设置和读取固定坐标系。

• getRobotBaseFrame()：获取当前机器人基座坐标系。

• setEndEffectorFrame(frame)：设置末端执行器坐标系。

• setShowOnlyEndEffector(show)：切换末端预览模式。

• setVisibleTfFrames(frames)：限制可见 TF 坐标轴集合；传入 null 可恢复不过滤状态。

• getDefaultEndEffectorFrame()：根据已加载的机器人模型推断默认末端坐标系。

• getLinkList() / getFrameList()：获取机器人 link 列表与已知 frame 列表。

• getRobotJointConnections()：返回按父子 link 排序的关节连接关系，适合 TF 树或结构视图复用。

• getTfSnapshot() / getTfNodes()：读取 TF 图快照信息。

• clearTfRecords()：清空 TF 记录并刷新显示。

• getRelativeTransform(frame)：获取相对固定坐标系的位姿，优先使用实时 TF。

• getRobotRelativeTransform(frame)：直接从机器人模型求取相对位姿，不依赖实时 TF。

• getRobotLinkDetail(linkName)：返回 TF 详情弹窗使用的 link 结构化信息。

• getRobotJointDetail(jointName)：返回 TF 详情弹窗使用的 joint 结构化信息。

• setRobot(robot, baseFrame)：设置或更新机器人模型。

• updateJointStates(message)：将关节状态应用到机器人模型。

• upsertTfMessage(message)：增量更新 TF 缓存。

• setPointCloud(pointCloud)：更新点云渲染对象。

• dispose()：释放渲染资源与监听器。

使用建议

• 页面卸载前应调用 dispose()，避免 WebGL 资源泄漏。

• 主题切换时应同步调用 setTheme()，确保视口背景与网格颜色和界面风格一致。

• 需要按需显示 TF 时，优先使用 setVisibleTfFrames()，而不是直接改动 TF 树文本数据。

• 使用关节采样来预览规划轨迹，或根据 MoveIt 关节轨迹点换算 TCP 曲线时，优先调用 getRobotRelativeTransform()，避免把预览轨迹和实时 TF 混在一起。

• 使用 setPlannedTrajectoryPath() 时可同时传入 startPose 和 endPose，在预览路径的同时显示 TCP 起终点姿态。

• 高频点云场景下，建议配合 maxPoints 与 targetFps 控制性能。