CycleGUI

概述 / Overview

CycleGUI 是 MDCS 自研的 回合式 GUI 框架：算法代码可以在任何线程、任何时间 cast 一个协程到 GUI 主线程；协程仅在 需要刷新界面时被唤醒。这种"按需协程"模型让算法核心可以无负担地嵌入实时调试与可视化代码。

CycleGUI is MDCS's homegrown cyclic-coroutine GUI framework. Algorithm code on any thread can cast a coroutine onto the GUI thread; the coroutine wakes only when its visuals need refreshing. The "lazy coroutine" model lets the algorithm core embed live-debug code without performance cost.

设计动机 / Why

机器人算法（SLAM、规划、运动控制）需要 频繁、灵活地可视化中间状态。
传统 GUI 框架要求把算法搬到 GUI 主线程或用观察者模式回调 —— 都侵入性强。
CycleGUI 反转控制：算法在原线程跑，GUI 框架托管协程，只在 GUI 需要重绘时调用协程。
让 调试代码与 算法代码几乎无成本共存。

Robotics algorithms (SLAM, planning, motion) need to visualise intermediate state often and flexibly.
Conventional GUI frameworks force the algorithm onto the UI thread or use observer callbacks — both invasive.
CycleGUI inverts control: the algorithm stays on its thread; the GUI framework hosts the coroutine and pulls it only on repaint.
Debug code and algorithm code coexist with near-zero cost.

使用模型 / Usage model

 算法代码 (任意线程)
      │
      ▼
  UI.GetPainter("topic1")
      │
      ▼
  painter.DrawDot3D(color, position);  ← 任意时刻调用
  painter.DrawLine3D(...);
      │
      ▼
 CycleGUI 主线程（按需）
      │
      ▼
  渲染到屏幕

详见如何使用CycleGUI快速开发UI界面的具体 API。 For specific APIs see the usage guide.

核心抽象 / Core abstractions

Painter — 一个命名的绘制目标（topic）；多次 `DrawXxx` 累积到同一画面。
Layer — 多个 Painter 组合成一层；可控可见性。
Cyclic coroutine — 一段被框架托管的 `IEnumerable<Cycle>`，每次 帧重绘被执行一次。
Two-way binding — UI 控件（按钮、滑条、输入框）通过协程的 `yield return WaitForXxx` 与算法同步。

在 MDCS 中的应用 / Use within MDCS

Detour: 可视化 SLAM 中间状态（关键帧、闭环候选、协方差椭圆）。
Clumsy: 在 Movement 内部可视化 lidar 帧、检测器输出、目标姿态。
SimpleComposer: CAD 工具 + 调度时的车流可视化。
仿真 / 回放: 把回放数据投射到同一套 CycleGUI 视图。

实现位置 / Where

源码：`D:\src\CycleGUI\`（独立仓库）。MDCS 通过 NuGet 引用。 Source: `D:\src\CycleGUI\` (standalone repo); MDCS depends via NuGet.

关键特性 / Key features

零侵入: 不强制让算法上 GUI 线程。
跨进程: 一个 GUI 可以同时呈现多个进程的画面。
可录制: 所有 Painter 调用可序列化 → 离线回放。
Web 版（实验）: 把绘制指令转 WebGL，浏览器查看。

Zero-intrusion — algorithm doesn't migrate to the UI thread.
Cross-process — one GUI can render from multiple processes.
Recordable — all Painter calls serialise; replay off-line.
Web flavour (experimental) — render commands → WebGL, view in browser.

与其它框架的对比 / Comparison

项 / Item	CycleGUI	ImGui	Qt
协程模型 / Coroutine	是（按需唤醒）/ Yes (lazy)	否（每帧重画）	否（事件驱动）
跨进程 / Cross-process	内建	需 RPC	复杂
GUI 主线程要求 / UI-thread req	无（cast 自动派发）	有	有
学习曲线 / Curve	中	低	高