feat(studio-3d): 能力控件、真实色标与复位语义 —— 只提供数据源真正喂得出来的控制(阶段 8 第一批)
- What:
1. **能力声明**:`contracts.SceneCapabilities`(quantity/unit/displacement_available/
displacement_quality/source_kind);两个适配器都声明 `displacement_available = False`(它们只把标量
画在表面上,从不发布位移);`Scene3DView.capabilities()` 从**实际绑定的适配器**读出并推给面板。
`ThreeDPanel.set_capabilities()` 因此把"放大形变"/增益置灰并给出原因(新键 `scene3d.deform_unavailable`),
`settings()` 在能力缺失时**强制** `deform_enabled=False`(否则持久化的增益会悄悄作用在没有东西可放大的源上);
禁用状态在 `set_enabled`/`apply_settings` 之后仍然成立(原来 `apply_settings` 只按复选框状态使能增益)。
2. **真实色标**:`GLRenderer` 记录并暴露本次绘制**真正使用的**上下限与模式(`effective_scale()`),
写进 `RenderStats.scale_lower/scale_upper/scale_mode`;`_scalar_range` 在 `release()` 与
`upload_scene()` 重置(原来换场景/重建 context 后首个自动范围沿用旧场景);面板新增 `ColorScaleBar`
(用 `gl_backend.lut_rgba` 的同一张 256×1 表绘制),图例改为
`{quantity} [{unit}] · {自动|固定}色标 {lower} – {upper} · {quality}`(新键 `scene3d.legend_effective`/
`legend_auto`/`legend_fixed`),自动模式下不再让被禁用的输入框冒充"当前范围"。
3. **文案**:`scene3d.quantity_flow_magnitude`="光流幅值"/`quantity_depth_response`,preset "default" 显示为
"默认视角"(数据仍是资产里的真名),`scene3d.stats` 的"丢弃"改为"显示跳帧"(与录像丢帧区分)。
4. **复位语义**:`Scene3DView.reset_view()` 改为回到**资产自己的默认视角**(`camera_presets[0]`),
与首次显示一致;只有在没有 preset 时才退回 `OrbitCamera.reset()`。原来它把 yaw/pitch 清零并 refit,
与首帧呈现的 preset 视角不是同一个画面。
5. `describe()` 记录 `capabilities`(含 `displacement_available`)与 `effective_scale`(实际上下限与模式),
这样一条录像能说明"当时的颜色代表什么",而不是只留下操作者输入框里的数字。
- Why: 审查报告 R6:`FingerFrameAdapter` 只输出光流幅值、`displacement_sensor_m` 始终为 None,而面板仍允许
"放大形变"和 0×..500×——用户能操作一个没有真实输入的功能;自动色标每帧按实际范围变化,但面板范围输入框
仍是保存的 0..1,没有把颜色和数值联系起来的图例;`reset_view()` 与首次显示用的资产 preset 语义不一致。
报告明确要求"由 SceneCapabilities / 当前 FieldDescriptor 控制控件可用性""新增独立 effective_scale 输出"
"复位也应统一语义"。
- Verification:
· `test_scene3d_view.py` +3:无位移源 → 形变控件禁用且带原因、`settings().deform_enabled` 仍为 False、
`describe()["capabilities"]["displacement_available"] is False`;图例显示实际上下限(0.25–7.5)与"自动"、
不再出现内部键、`describe()["effective_scale"]` 三项一致;复位后的相机矩阵等于
`apply_preset(camera_presets[0])` 的结果(先 orbit+zoom 离开再复位)。
· `test_scene3d_skeleton.py` 的图例断言改为"不含内部键、含操作者语言的名字"。
· 全量:apps/studio 240 项 0 失败 14 跳过;真 GL 冒烟 14 项 0 失败 0 跳过;ui_check 587 项 0 失败;
locale_check 0 缺失。
- Not in this change: **画布布局(2D/3D 页签容器、参数收进"显示设置"抽屉、窄窗口回退)留作阶段 8 的第二批**
(需要同时改 `ui_check` 的布局断言与截图对比,风险与工作量都更大,独立提交更易审阅);曲线量程的
"可见区间自动/固定"开关(报告建议项)也留到第二批;诊断抽屉的结构调整同理;阶段 9(限速、真实耗时统计、
保护包密钥注入、ARM 与 2 小时门禁)未开始。
This commit is contained in:
@@ -509,6 +509,25 @@ class ColorScale:
|
||||
mode: Literal["fixed", "automatic"] = "fixed"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class SceneCapabilities:
|
||||
"""What the *data source* can put into a frame — not what the pane can draw.
|
||||
|
||||
The panel needs this to offer only the controls that can do something: today's
|
||||
adapters colour a scalar in place and never publish a displacement, so an
|
||||
"exaggerate the deformation" control would be operating on an input that does not
|
||||
exist. Recording it (rather than inferring it from a setting) is also what lets a
|
||||
recording say which controls were meaningful.
|
||||
"""
|
||||
|
||||
quantity: str = ""
|
||||
unit: str = ""
|
||||
#: Whether the source can ever publish ``displacement_sensor_m``.
|
||||
displacement_available: bool = False
|
||||
displacement_quality: Optional[Quality] = None
|
||||
source_kind: str = "live"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class DisplaySettings:
|
||||
"""Display-only settings. None of these reach the camera or the recording."""
|
||||
@@ -575,6 +594,13 @@ class RenderStats:
|
||||
upload_ms: float = 0.0
|
||||
paint_ms: float = 0.0
|
||||
estimated_gpu_bytes: int = 0
|
||||
#: The colour-scale bounds the shader was *actually* given for the frame on screen,
|
||||
#: and whether they came from the data ("automatic") or from the operator ("fixed").
|
||||
#: Without these the panel could only show the spin boxes, which in automatic mode
|
||||
#: are disabled and hold values nobody is using.
|
||||
scale_lower: float = 0.0
|
||||
scale_upper: float = 0.0
|
||||
scale_mode: str = ""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
|
||||
Reference in New Issue
Block a user