ykcheungab
278 lines
16 KiB
Markdown
278 lines
16 KiB
Markdown
# Studio — UI review: logic, look and information clarity (2026-10)
|
||
|
||
Status (2026-10-18): L1, L2 (rail hint and empty-state copy), L3 and A1 are implemented
|
||
in the reviewed `orisys-app` worktree; see [Implemented](#implemented-2026-10-18). Everything else below
|
||
is still a proposal. A touch-screen audit is in [section D](#d-touch-screen-readiness).
|
||
|
||
Maintenance moved to `apps/studio/docs` on 2026-10-18. This move preserves the dated review;
|
||
current implementation and commit status must be rechecked before starting an item.
|
||
Source history: workspace commit `5ab0beb`, same filename.
|
||
|
||
This review covers live, replay and calibration UI. An operator
|
||
meeting it cold cannot tell *what to do next* or *why a control is grey*. The biggest wins are not
|
||
visual polish: they are (1) making the next action obvious, (2) removing engineering vocabulary
|
||
from operator-facing text, and (3) fixing one regression of the September customer feedback that is
|
||
still visible in the default configuration (see L1).
|
||
|
||
Evidence: Six screenshots of the source build (`apps/studio/run.py`, 2026-10-18, dark theme,
|
||
`zh_CN`, sensor `finger`, no device attached): live view, 绘图设置, 三维显示设置, 手指 2D 显示方向,
|
||
传感器与标定, and the 标定 view. Copies are in workspace-root `.scratch/studio-ui-review-claude/shots/`
|
||
(disposable). Findings were checked against `orisys-app` `main` at `dc5a6f8`.
|
||
Not covered: the replay view, the light theme, a running session with live data, and the
|
||
`en_US` locale — each needs its own pass.
|
||
|
||
Severity: **P1** misleads or blocks the operator · **P2** slows or confuses · **P3** polish.
|
||
|
||
---
|
||
|
||
## Top priorities
|
||
|
||
| # | finding | sev | effort |
|
||
|---|---|---|---|
|
||
| L1 | FN curve still sits on the FX frame and has no 0 label by default | P1 | S |
|
||
| L2 | Nothing says *why* 运行 is disabled, and the rail offers no way to pick the video it waits for | P1 | S |
|
||
| L3 | Enabled and disabled buttons look almost the same, so the whole rail reads as "off" | P1 | S |
|
||
| C1 | 传感器与标定 shows internal state (`degraded`, `shipped`, absolute paths, an English SDK warning) | P1 | S–M |
|
||
| L4 | Calibration lives in two places with overlapping buttons (dialog and 标定 view) | P2 | M |
|
||
| A1 | Checked checkboxes are a filled square with no tick | P2 | S |
|
||
|
||
---
|
||
|
||
## A. UI logic
|
||
|
||
### L1 — the "no origin / FN on the FX frame" bug is still the default (P1)
|
||
|
||
The September review
|
||
items 5 and 19 were closed by making the FN lower bound configurable, but both defaults are `0.0`
|
||
(`ui/plot_settings_dialog.py:43,48`) and the N-mode floor was then deliberately fixed at 0
|
||
(`92e6de6`, 2026-10-07). With the view ending exactly at 0, pyqtgraph does not draw the 0 label and
|
||
the idle FN trace lies on the border it shares with FX (first screenshot).
|
||
*Done:* the configured range and ticks are unchanged (the 0 N decision stands); the *view* gets an
|
||
8 % margin beyond each bound (`force_plots._display_range`), never crossing zero when the range
|
||
excludes it, and bound labels may draw past the axis end.
|
||
|
||
### L2 — disabled 运行 never explains itself (P1)
|
||
|
||
The rail shows `使用摄像机`, which is the
|
||
*video-mode* group (`toolbar.py:193-200`): the current source is a video file, none is chosen, so 运行
|
||
is disabled. The only hint is a tooltip (`run_disabled_video`). The video group contains no
|
||
"choose video" button; that lives only in 文件 → 打开视频…. The 2D empty state says
|
||
"请选择视频或摄像机后点击「运行」" but nothing near it does either.
|
||
*Suggest:* show the source on the rail as one segmented control **摄像机 | 视频文件** followed by
|
||
the camera id or the file name with a `选择…` button. Put the disabled reason as visible text next
|
||
to 运行 (e.g. "未选择视频"), and make the 2D empty state contain the two actions as buttons.
|
||
|
||
### L3 — state is not legible on the rail (P1)
|
||
|
||
`QPushButton#primaryButton:disabled` uses
|
||
`panel_border` fill and muted text (`theme/qss.py:243`), which on `#0E1320` looks the same as an
|
||
enabled neutral button. In the screenshot 开始记录, 运行, 停止 and 重置传感器 are all disabled, and
|
||
it is not obvious.
|
||
*Suggest:* disabled = no fill, dashed or 40 % opacity border. Only one filled accent button at a
|
||
time — 运行 when idle, 停止 while running. Move 开始记录 after 运行 (you can only record a running
|
||
session) and keep it hidden or clearly inert until a session runs.
|
||
|
||
### L4 — two calibration homes (P2)
|
||
|
||
导出系数… and 应用到设备 appear both in the 传感器与标定 dialog and
|
||
at the bottom of the 标定 view; the dialog also has 保存, whose relation to 应用到设备 is unclear.
|
||
*Suggest:* the dialog chooses *which* calibration to use; the 标定 view *produces* one. Remove
|
||
export/apply from the dialog, or replace them with a link to the 标定 view.
|
||
|
||
### L5 — calibration workflow has no order (P2)
|
||
|
||
The 标定 view presents everything at once:
|
||
channel, weight (default `0.0000` N, a value that can never be valid), duration, 记录, a 0 %
|
||
progress bar, an empty table, 序列号, five row actions and four file actions.
|
||
*Suggest:* a three-step layout — ① channel + weight + capture, ② the point table with "fit needs
|
||
≥ 2 points (current 0)", ③ serial number + save/export/apply. Disable row actions until a row is
|
||
selected; separate 全部清空 from the others and confirm it. Rename 记录 to **采集样本** so it is not
|
||
confused with the session 开始记录 on the rail.
|
||
|
||
### L6 — inconsistent apply models (P2)
|
||
|
||
绘图设置 has 确定/取消; 三维显示设置 applies live and has
|
||
only 关闭; 传感器与标定 has 保存 and no cancel. Pick one rule: live-apply dialogs get 关闭 only and
|
||
say "更改立即生效"; deferred dialogs get 确定/取消.
|
||
|
||
### L7 — controls that live in the wrong place (P3)
|
||
|
||
显示三维视图 sits inside the 3D view's own
|
||
settings (it belongs in 视图 menu / layout); 复位视角 appears both as ↻ in the pane header and as a
|
||
button in the dialog; the settings toggle on the rail (设置), the ⚙ on every pane and the 视图 menu
|
||
are three entry points with no rule for which holds what.
|
||
|
||
### L8 — disabled fields without a reason (P2)
|
||
|
||
In 绘图设置, FN 上限 / 剪切上限 / 归零阈值（N）are
|
||
greyed because the sensor is uncalibrated; in 三维显示设置, 色标 and 范围 are greyed. Add one line
|
||
under each group, e.g. "牛顿量程需要先选择标定".
|
||
|
||
---
|
||
|
||
## B. Information clarity
|
||
|
||
### C1 — internal vocabulary in the sensor dialog (P1)
|
||
|
||
The header block shows
|
||
`配置档案 orisys.finger.r01 · 描述符配置包 · 来源 shipped`, an absolute path, `SDK 校验: degraded`,
|
||
and an untranslated SDK message `no calibration selected — calibrated force is unavailable; raw
|
||
force is available`. *Suggest:* one status line for operators ("可以运行 · 未标定，只能显示原始力"),
|
||
with the descriptor, root path and SDK check behind a 详情 expander. Map SDK warning codes to locale
|
||
strings instead of passing text through.
|
||
|
||
### C2 — terminology drift (P2)
|
||
|
||
One quantity has several names:
|
||
|
||
| concept | names seen | suggest |
|
||
|---|---|---|
|
||
| shear force | 切向力 (cards), 剪切 (绘图设置) | 切向力 everywhere |
|
||
| uncalibrated unit | `raw` (cards, badge), 原始 (settings) | 原始 in `zh_CN` |
|
||
| calibration for live use | 直播用标定 ("live-stream") | 实时采集用标定 |
|
||
| 3D pane | 三维网格 (title), 三维表面视图 (empty state) | 三维表面 |
|
||
| capture a calibration sample | 记录 | 采集样本 |
|
||
|
||
Also word order: "FN 原始上限" vs "原始剪切上限".
|
||
|
||
### C3 — numbers that are hard to read (P2)
|
||
|
||
Raw axes print `750000`, `-250000`; use `750k` or
|
||
thousands separators. The x-axis has no unit (s). 全程总览 is a label *below* an empty 0–1.0
|
||
overview; hide the overview until there is data, and title it above.
|
||
|
||
### C4 — the rail summarises the wrong things (P3)
|
||
|
||
`FINGER · sensor.json` shows a file name; an
|
||
operator needs the sensor and the calibration ("Finger · 未标定"). `使用摄像机` reads as a status
|
||
("using the camera") although it is an action to switch to the camera.
|
||
|
||
### C5 — explanation in a title bar (P3)
|
||
|
||
"手指 2D 显示方向（只影响 2D 画面：3D 视图仍用设计坐标系）" is
|
||
truncated as a window title. Title "2D 显示方向"; move the note into the dialog body.
|
||
|
||
### C6 — developer telemetry in an operator dialog (P3)
|
||
|
||
"已显示 1 · 未赶上显示的帧 0 · 合成 0.0 ms ·
|
||
绘制 1.8 ms" belongs in 帮助 → 诊断 or behind `show_fps`.
|
||
|
||
---
|
||
|
||
## C. Aesthetic
|
||
|
||
### A1 — checkbox and radio states (P2)
|
||
|
||
`QCheckBox::indicator:checked` paints a solid accent square
|
||
with no tick (`qss.py:481-484`); at 15 px it reads as "disabled" or "indeterminate". Add a tick
|
||
image, as the spin-box arrows already do (`_arrow_image`). In the 标定 view the selected FN radio
|
||
renders as a large rounded square ring, unlike the circles beside it.
|
||
|
||
### A2 — too much chrome, weak primary navigation (P2)
|
||
|
||
Menu bar + brand bar + rail use about
|
||
130 px of a 745 px window. The brand bar repeats the product name (ORISYS left, Orisys Studio right),
|
||
while the actual mode switch 实时 / 回放 / 标定 is the smallest text on screen. *Suggest:* merge
|
||
brand and tabs into one row, drop the right-hand name, and make the tabs ≥ 13 px with a filled
|
||
selected state.
|
||
|
||
### A3 — 3D pane (P2)
|
||
|
||
The header background stops at about 160 px, leaving a two-tone strip; the
|
||
pane is flush with the window edge while the other panes have margins; an empty strip sits under
|
||
the view. The idle mesh is a flat grey silhouette with no shading, outline or axis indicator, so it
|
||
reads as a placeholder blob. Add basic lighting or an edge outline and a small orientation gizmo.
|
||
|
||
### A4 — chart styling (P3)
|
||
|
||
Subplot left axes and frames are bright white and heavier than the
|
||
grid, and adjacent subplots draw double borders. Use one muted axis colour, a single separator
|
||
between subplots, and an accent zero line (now the reference line of the chart). The four
|
||
icon-only buttons in the chart header (→|, ⛶, ⬚, ⚙) need either labels or a grouped "视图" menu.
|
||
|
||
### A5 — focus looks like selection (P3)
|
||
|
||
The 2D mode combo and the 时间窗口 field open with an
|
||
accent border that is the keyboard focus ring; it suggests they are selected or in error. Use a
|
||
subtler ring, or do not give initial focus to fields.
|
||
|
||
### A6 — alignment and density (P3)
|
||
|
||
In 三维显示设置 labels wrap ("深度显示阈值") and spin boxes are
|
||
narrower than combos; in 标定 the "砝码重量 (N)" and "采集时长" labels are not on one edge. Use a
|
||
two-column form layout with fixed label width. In 绘图设置 split the fields into two columns,
|
||
**牛顿** and **原始**, so the disabled half is self-evident.
|
||
|
||
---
|
||
|
||
## D. Touch-screen readiness
|
||
|
||
Measured from the stylesheet and widgets; target ≈ 40 px for primary touch targets.
|
||
|
||
| # | finding | where | suggestion |
|
||
|---|---|---|---|
|
||
| T1 | Rail buttons are ~24 px tall; nav tabs 18 px with 11 px text; unit chip 18 px | `qss.py` `[rail="true"]`, `#navButton`, `#unitBadge` | a **touch density** preference (`compact`/`touch`) that raises these to 36–40 px; `ui_check`'s `top_area_limit = 78` would need a per-density limit — a product decision, not a bug |
|
||
| T2 | Essential information lives in tooltips (full source path, chart-header icon meaning, disabled reasons) — no hover on touch | `toolbar.py`, `force_plots.py` | visible text or a tap-to-reveal info button; the run reason is now on the rail (done) |
|
||
| T3 | Chart and 3D zoom are mouse-wheel only; no pinch | `force_plots.py` (`setMouseEnabled`), `scene3d/widget.py` `wheelEvent` | `QPinchGesture`, or on-screen +/− and fit buttons |
|
||
| T4 | No kinetic scrolling in scroll areas, tables or the sensor-dialog text | no `QScroller` use in `apps/studio` / `shared` | `QScroller.grabGesture(viewport, TouchGesture)` on each scroll area |
|
||
| T5 | Splitter handles are 6 px | `qss.py` `QSplitter::handle` | ≥ 12 px handles in touch density |
|
||
| T6 | Spin-box arrows are two half-height targets (~20 px) | `QAbstractSpinBox` | in touch density: side-by-side −/+ buttons, or rely on the numeric keyboard |
|
||
|
||
*Done in this change:* checkbox/radio indicators 18 px with taller rows, spin arrows 22 px wide,
|
||
scrollbars 12 px, menu rows +4 px, combo-popup rows ≥ 30 px.
|
||
|
||
---
|
||
|
||
## Implemented (2026-10-18)
|
||
|
||
| item | change |
|
||
|---|---|
|
||
| L1 | `force_plots._display_range`: 8 % view margin, zero-safe; labels may extend past the axis end |
|
||
| L2 | rail `run_hint` shows the blocking reason in acquire views (replay keeps its empty-state text); live + video reason no longer asks for a file; 2D empty state rewritten |
|
||
| L3 | disabled buttons: no fill, dashed outline (all four button styles) |
|
||
| A1 | checkbox tick image; checked radios keep their 20 px outer size (border no longer grows them into rounded squares) |
|
||
| — | `en_US` `panels.replay_empty` named a button label that does not exist; `ui_check` stub worker updated to the real `start()` keywords |
|
||
|
||
Verification: Linux offscreen (PySide6 6.12) against an untouched HEAD copy with the same stub fix —
|
||
studio suite fails exactly HEAD's set minus one (the replay-text test now passes), shared identical,
|
||
`ui_check` 631 checks with the same 2 failures as HEAD (one is Linux font metrics; "replay view is
|
||
not the live arrangement" is pre-existing and also fails on Windows). Windows run of the targeted
|
||
tests: App-root `.scratch/studio-ui-quick-fixes/`.
|
||
|
||
---
|
||
|
||
## Carried-forward requirements and remaining work
|
||
|
||
The [September plan](../../../../docs/archive/studio/orisys-studio-fix-plan.md) records these
|
||
customer decisions; they remain requirements, not newly verified implementation claims:
|
||
|
||
- Pause computation and display while keeping the camera connected.
|
||
- Keep `finger-mems` configuration in Studio, derived from box without calibration; no SDK addition.
|
||
- Keep camera preferences in `config/`, use app-local discovery and scan at start-up.
|
||
- Keep force settings per channel and separate device/tracker reset from view reset.
|
||
- Treat housing as a separate part, hidden by default while debugging.
|
||
|
||
| remaining item | status and acceptance boundary |
|
||
|---|---|
|
||
| September C: camera list and auto-pick | Previously not started; reconfirm current code. Persist names/preferences, scan off the GUI thread and avoid scans while a camera is in use. Stubbed tests must cover selection, missing stored IDs and UI responsiveness. |
|
||
| September display requests | Recheck valid-mask boundary stability, palette/LUT parity, per-axis unit labels and 2D/3D arrow appearance before dispatch; do not infer completion from the old plan. |
|
||
| Device registration and orientation | September items 8, 14, 15 and 17 still need device evidence. A device session needs the equipment, bounds and stop conditions required by workspace rules. |
|
||
| Latency | Item 9 needs paired input/configuration and frame-identity evidence for packet-to-paint delay. Synthetic or offscreen checks alone do not establish live-device latency. |
|
||
|
||
Current contracts: [layout](ui-layout.md), [palette](ui-palette.md), [bundles](sensor-bundles.md)
|
||
and [recording](record-channel.md). Inspect the current [window/controller](../src/orisys_studio/app_window.py)
|
||
and relevant [UI tests](../tests/test_ui_smoke.py), [pause tests](../tests/test_pause_controls.py)
|
||
and [UI checker](../tools/ui_check.py) before changing them. These are owners and check entry points,
|
||
not evidence that this migration exercised the UI or hardware.
|
||
|
||
## Suggested order
|
||
|
||
1. ~~L1, L2, L3, A1~~ — done.
|
||
2. C1, C2 — one locale sweep plus an SDK-code → message map.
|
||
3. L4, L5 — calibration restructure; needs a short agreement on the workflow first.
|
||
4. A2–A6, L6–L8, C3–C6 — polish, batchable with `ui_check.py` assertions (rail elision at
|
||
1280×720 still applies to any rail change).
|
||
|
||
Historical sources: [end-user comments](../../../../docs/archive/studio/orisys-studio-enduser-comments.md)
|
||
and [fix plan](../../../../docs/archive/studio/orisys-studio-fix-plan.md).
|