Artheru：Initial bilingual draft (auto-published)

2026-05-16T11:43:04Z

Initial bilingual draft (auto-published)

新页面

<languages/>

== 概述 / Overview ==
[[Special:MyLanguage/CycleGUI|CycleGUI]] 是 MDCS 自研的 ''按需协程''GUI 框架。本页给开发者一份 ''最小学习路径''：开一个画面、画一点云、加一个按钮、读一个输入。

[[Special:MyLanguage/CycleGUI|CycleGUI]] is MDCS's lazy-coroutine GUI framework. This page is the minimum learning path: open a panel, draw a cloud, add a button, accept an input.

== 1. 开一个画面 / Open a panel ==
<syntaxhighlight lang="csharp">
using CycleGUI;

// 任何线程都可以 / from any thread
var painter = UI.GetPainter("my-debug");
painter.DrawText("Hello from algorithm thread");
</syntaxhighlight>

`UI.GetPainter(name)` 拿到一个 ''命名画板''；后续所有 `painter.DrawXxx` 累积到同一画面。
`UI.GetPainter(name)` returns a ''named painter''; subsequent `DrawXxx` calls accumulate into the same view.

== 2. 画点云 / Draw a point cloud ==
<syntaxhighlight lang="csharp">
var painter = UI.GetPainter("lidar-frame");
foreach (var pt in cachedLidar)
{
var c = pt.intensity > 0.8 ? Color.Red : Color.White;
painter.DrawDot3D(c,
new Vector3((float)(pt.d * Math.Cos(pt.th)),
(float)(pt.d * Math.Sin(pt.th)),
0));
}
</syntaxhighlight>

CycleGUI 把所有 `Draw` 命令存到 ''当前画面''；在 GUI 主线程下一次重绘时一次性渲染。
CycleGUI buffers all `Draw` commands for the current frame and renders them when the UI thread next repaints.

== 3. 加一个按钮 / Add a button ==
按钮 + 通用 UI 控件用 ''协程''风格 —— 把 UI 逻辑写成 `IEnumerable<Cycle>` 由框架托管：
Buttons and other widgets use coroutines:

<syntaxhighlight lang="csharp">
UI.CastCoroutine(MyControl());

IEnumerable<Cycle> MyControl()
{
while (true)
{
var panel = UI.GetPanel("control");
if (panel.Button("Start scan"))
{
StartScan(); // 调用算法
}
if (panel.Button("Stop"))
{
StopScan();
}
yield return Cycle.Next; // 等下一帧
}
}
</syntaxhighlight>

`UI.CastCoroutine` 把一个 `IEnumerable<Cycle>` 投递给 GUI 主线程；它只在需要重绘时被推进。
`UI.CastCoroutine` posts a coroutine to the UI thread; it advances only on repaint.

== 4. 读一个输入 / Read an input ==
<syntaxhighlight lang="csharp">
IEnumerable<Cycle> ConfigPanel()
{
int speed = 600;
while (true)
{
var p = UI.GetPanel("config");
speed = p.IntInput("speed (mm/s)", speed, min: 0, max: 2000);
p.Text($"Current speed = {speed}");

if (p.Button("Apply"))
{
Configuration.conf.basicSpeed = speed;
}
yield return Cycle.Next;
}
}
</syntaxhighlight>

== 5. 等用户输入 / Wait for user input ==
有时算法要等用户点确认才继续 —— 用 `yield return WaitForButton(...)`：

Sometimes the algorithm has to wait for user confirmation:

<syntaxhighlight lang="csharp">
IEnumerable<Cycle> ApprovalFlow()
{
while (true)
{
var p = UI.GetPanel("approve");
p.Text("Pending: cart approach to station-17");

yield return p.WaitForButton("Approve"); // 阻塞协程直到点击
ConfirmApproach();

yield return Cycle.Seconds(1);
}
}
</syntaxhighlight>

== 6. 跨线程 / 跨进程 / Cross-thread / cross-process ==
* CycleGUI 自动把任意线程的 `Draw` 调用 ''marshal''到 UI 主线程。
* 同一 CycleGUI 服务可被多个进程连接；每个进程独立维护自己的 painter，UI 端可同时显示。

CycleGUI auto-marshals `Draw` calls onto the UI thread from any thread. Multiple processes can connect to one CycleGUI server simultaneously; each has its own painter, all visible together.

== 7. 录制与回放 / Record & replay ==
<syntaxhighlight lang="csharp">
UI.StartRecording("session.cgr");
// ... 跑算法 + 各种 Draw ...
UI.StopRecording();

// 离线回放
UI.Replay("session.cgr");
</syntaxhighlight>

== 最佳实践 / Best practices ==
* '''命名 painter / panel''' 反映 ''数据来源''（如 `lidar-front`、`slam-map`），不要根据 UI 位置命名。
* '''协程内不要 sleep'''；改用 `yield return Cycle.Seconds(N)` 让框架调度。
* '''重命名 painter 会丢历史''' —— 如果用户在多次会话间想保留视图开关状态，名称保持稳定。
* '''数据多时考虑节流''' —— 即便是协程按需调用，每帧画百万点云仍会卡；用空间下采样或频率限制。

== 与 Detour / Clumsy / SimpleComposer 的集成 / Integration ==
* Detour: SLAM 中间状态默认在 `detour-slam` painter；可在 Detour UI 中开关。
* Clumsy: Movement 内部可调 `UI.GetPainter("movement-debug")` 加自定义可视化。
* SimpleComposer: CAD 画布本身就是一个 CycleGUI 实例，自定义工具通过协程加新的 layer。

== 相关页面 / See also ==
* [[Special:MyLanguage/CycleGUI|CycleGUI]]
* [[Special:MyLanguage/开发手册 - SimpleComposer界面开发 - CAD工具|开发手册 - SimpleComposer界面开发 - CAD工具]]
* [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]]

[[Category:二次开发相关说明]]

如何使用CycleGUI快速开发UI界面 - 版本历史

Artheru：​Initial bilingual draft (auto-published)

Artheru：Initial bilingual draft (auto-published)