[WIP] Add clear comments and documentation for key code

[Copilot]

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.

Original prompt

目标：在仓库中为关键代码添加清晰、准确的注释与文档说明，主要澄清 T_WC 的语义（camera -> world），三种运行模式（INIT / TRACKING / RELOC）的职责，以及后端基于关键帧构建因子图并做局部/全局优化的流程，方便维护者和阅读者理解代码执行逻辑。

需要修改/添加注释的文件（建议）：

• mast3r_slam/frame.py

  • 在 Frame dataclass 和 SharedKeyframes/SharedStates 定义处添加注释：明确说明字段 T_WC 的语义是 Sim3 表示的 camera->world（相机坐标到世界坐标的变换），以及其数据类型（lietorch.Sim3，保存在共享内存时为 embedded data）。
  • 在 create_frame() 和 set_frame()/get_frame() 处补充注释，说明共享内存交互的细节与为何用 Sim3.data。

• main.py

  • 在主循环、INIT/TRACKING/RELOC 分支处添加注��，解释每个模式的触发条件和主要步骤（比如：INIT做单目推理并初始化关键帧；TRACKING用FrameTracker跟踪并决定关键帧；RELOC做检索并由后端尝试重定位）。
  • 在 run_backend 和 relocalization 函数添加注释，说明后台如何接收任务、构建因子图、调用优化器以及把优化结果写回共享 keyframes。标注与 shared states 的同步点（锁/队列）。

• mast3r_slam/global_opt.py

  • 在 solve_GN_rays 和 solve_GN_calib 函数上方添加说明：列出这两种求解器的输入、残差类型（ray+dist vs pixel+log-depth）、以及在优化完成后如何写回 keyframe.T_WC（并说明 pin 的含义）。

• mast3r_slam/evaluate.py

  • 在 save_traj 和 save_reconstruction 处添加注释，解释写出的 traj 文本是基于 T_WC 转为 SE3 的位置和四元数，重建点云是通过 keyframe.T_WC.act(X_canon) 得到世界坐标点，注意 Sim3 -> SE3 转换将丢弃 scale 信息的影响。

• mast3r_slam/visualization.py

  • 在可视化中关于 frustum 和 follow_cam 的地方注释：说明渲染需要 world->camera 视图矩阵，因此代码对保存的 camera->world 取逆用于渲染/相机控制。

• mast3r_slam/tracker.py

  • 在 track() 与 get_points_poses() 等关键函数处注释：解释输入/输出语义（例如 T_WCf/T_WCk 是 camera->world），以及点与度量是如何变换以构造残差并优化位姿。

具体变更要求：

• 注释使用简洁中文（或中英对照），准确说明变量类型与含义，避免改变任何运行逻辑。
• 在每个修改文件的开头或关键函数处增加 3-8 行注释/文档字符串，必要时在行内加入单行注释以提高可读性。
• 保持代码风格一致，注释长度适中以便后续维护。

产物（PR 说明）：

• 一个新的分支（自动由 Copilot agent 创建）并包含对上述文件的注释修改。
• PR 标题：与 problem_title 相同。
• PR 描述���说明所做修改的目的、受影响文件列表及示例代码片段解释（例如：展示 pW = T_WC.act(X) 表明 camera->world、在可视化处对 T_WC 取逆用于视图矩阵等）。
• 不修改任何算法逻辑或测试，仅添加注释/文档。

请创建一个 Pull Request 来实现这些注释更新，变更要尽量小且局部化，只改注释和文档字符串。

This pull request was created as a result of the following prompt from Copilot chat.

目标：在仓库中为关键代码添加清晰、准确的注释与文档说明，主要澄清 T_WC 的语义（camera -> world），三种运行模式（INIT / TRACKING / RELOC）的职责，以及后端基于关键帧构建因子图并做局部/全局优化的流程，方便维护者和阅读者理解代码执行逻辑。

需要修改/添加注释的文件（建议）：

• mast3r_slam/frame.py

  • 在 Frame dataclass 和 SharedKeyframes/SharedStates 定义处添加注释：明确说明字段 T_WC 的语义是 Sim3 表示的 camera->world（相机坐标到世界坐标的变换），以及其数据类型（lietorch.Sim3，保存在共享内存时为 embedded data）。
  • 在 create_frame() 和 set_frame()/get_frame() 处补充注释，说明共享内存交互的细节与为何用 Sim3.data。

• main.py

  • 在主循环、INIT/TRACKING/RELOC 分支处添加注��，解释每个模式的触发条件和主要步骤（比如：INIT做单目推理并初始化关键帧；TRACKING用FrameTracker跟踪并决定关键帧；RELOC做检索并由后端尝试重定位）。
  • 在 run_backend 和 relocalization 函数添加注释，说明后台如何接收任务、构建因子图、调用优化器以及把优化结果写回共享 keyframes。标注与 shared states 的同步点（锁/队列）。

• mast3r_slam/global_opt.py

  • 在 solve_GN_rays 和 solve_GN_calib 函数上方添加说明：列出这两种求解器的输入、残差类型（ray+dist vs pixel+log-depth）、以及在优化完成后如何写回 keyframe.T_WC（并说明 pin 的含义）。

• mast3r_slam/evaluate.py

  • 在 save_traj 和 save_reconstruction 处添加注释，解释写出的 traj 文本是基于 T_WC 转为 SE3 的位置和四元数，重建点云是通过 keyframe.T_WC.act(X_canon) 得到世界坐标点，注意 Sim3 -> SE3 转换将丢弃 scale 信息的影响。

• mast3r_slam/visualization.py

  • 在可视化中关于 frustum 和 follow_cam 的地方注释：说明渲染需要 world->camera 视图矩阵，因此代码对保存的 camera->world 取逆用于渲染/相机控制。

• mast3r_slam/tracker.py

  • 在 track() 与 get_points_poses() 等关键函数处注释：解释输入/输出语义（例如 T_WCf/T_WCk 是 camera->world），以及点与度量是如何变换以构造残差并优化位姿。

具体变更要求：

• 注释使用简洁中文（或中英对照），准确说明变量类型与含义，避免改变任何运行逻辑。
• 在每个修改文件的开头或关键函数处增加 3-8 行注释/文档字符串，必要时在行内加入单行注释以提高可读性。
• 保持代码风格一致，注释长度适中以便后续维护。

产物（PR 说明）：

• 一个新的分支（自动由 Copilot agent 创建）并包含对上述文件的注释修改。
• PR 标题：与 problem_title 相同。
• PR 描述���说明所做修改的目的、受影响文件列表及示例代码片段解释（例如：展示 pW = T_WC.act(X) 表明 camera->world、在可视化处对 T_WC 取逆用于视图矩阵等）。
• 不修改任何算法逻辑或测试，仅添加注释/文档。

请创建一个 Pull Request 来实现这些注释更新，变更要尽量小且局部化，只改注释和文档字符串。

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.