# Workspace 场景、Viewport 和 Painter

## 颜色契约

CycleGUI 公开颜色字段统一使用 `System.Drawing.Color`。不要把 ARGB `uint` 直接塞给颜色字段；旧 wire-format 用 `Extensions.FromRgba8(uint)` 转回 `Color`。

## 模型加载和实例

```csharp
Workspace.AddProp(new LoadModel
{
    name = "robot_class",
    detail = new Workspace.ModelDetail(File.ReadAllBytes("robot.glb"))
    {
        Scale = 0.01f,
        Center = Vector3.Zero,
    }
});

Workspace.AddProp(new PutModelObject
{
    name = "robot_1",
    clsName = "robot_class",
    newPosition = new Vector3(1, 0, 0),
    newQuaternion = Quaternion.Identity,
});
```

用 `TransformObject` 更新位置和姿态：

```csharp
Workspace.AddProp(new TransformObject
{
    name = "robot_1",
    pos = new Vector3(2, 0, 0),
    quat = Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI / 4),
    timeMs = 500,
});
```

## 点云

```csharp
Workspace.AddProp(new PutPointCloud
{
    name = "scan",
    xyzSzs = points.Select(p => new Vector4(p, 3f)).ToArray(),
    colors = points.Select(_ => Color.White).ToArray(),
    newPosition = Vector3.Zero,
});
```

`xyzSzs` 的 `Vector4.W` 是点大小。颜色数组使用 `Color[]`。

## 线、文本和对象删除

常用 prop 可在 `api-signatures.md` 查询。删除对象可保留 prop 引用调用 `Remove()`，或使用 name pattern 删除。

```csharp
myProp.Remove();
WorkspaceProp.RemoveNamePattern("robot_*");
```

name pattern 是 glob，不是 regex。

## 相机和外观

```csharp
new SetCamera
{
    lookAt = Vector3.Zero,
    azimuth = -MathF.PI / 2,
    altitude = MathF.PI / 4,
    distance = 10f,
    fov = 45f,
    projectionMode = SetCamera.ProjectionMode.Perspective,
}.IssueToAllTerminals();
```

```csharp
new SetAppearance
{
    useEDL = true,
    useSSAO = true,
    useGround = true,
    drawGroundGrid = true,
    drawGuizmo = true,
    useDefaultSky = true,
}.IssueToDefault();
```

## Viewport

```csharp
var vp = GUI.PromptWorkspaceViewport(
    panel => panel.ShowTitle("Aux View"),
    closeEvent: () => true);

vp.OnClosing(() => true);
```

不传 `closeEvent` 时不显示关闭按钮。

## Painter

Painter 用于调试绘制，数据按帧刷新，不持久化为业务对象。

```csharp
var p = Painter.GetPainter("debug");
p.Clear();
p.DrawDot(Color.Red, new Vector3(1, 0, 0), size: 3f);
p.DrawLine(Color.Yellow, start, end, width: 2f, arrow: Painter.ArrowType.End);
p.DrawVector(origin, direction, Color.Green, width: 1f, pixels: 20);
p.DrawText(Color.White, new Vector3(0, 0, 1), "Label");
p.DrawRegion3D(Color.Blue, center);
```

同名 Painter 复用同一层。需要限定终端时设置 `painter.terminal = terminal`。

## 填充多边形

```csharp
p.DrawPolygonFilled(points2D, translation, rotation,
    borderColor: Color.White,
    fillColor: Color.FromArgb(128, Color.Blue),
    thickness: 0.1f);
```

更多 prop 和 Painter 签名见 `api-signatures.md`。