ykcheungab
d06e116c15
- What:
1. `ThreeDCoordinator` 新增 **epoch**（显示声明代次）与 `_Inflight` 记录：`work()` 不再直接写
`_composed` mailbox，只 `return` 合成好的帧；结果在 GUI 线程的 `_collect_inflight()` 里被接受，
且必须同时满足 `item.epoch == self._epoch` 与 `_identity_is_current(identity)` 才会入队。
`activate()`/`begin_session()`/`set_visible(False)`/`show_rest()`/`close()` 统一走新的
`_invalidate()`：epoch+1、清空两块 mailbox、清 `_last_request_id`/`_last_composed_identity`/
`_last_field_frame`/`_settings_dirty`，并**尝试**取消 future。
2. **未成功取消的 future 仍占用唯一合成槽**：`_inflight` 只在 `future.done()` 时由 `_collect_inflight()`
释放，所以反复隐藏/显示不会在线程池里排起第二个合成；`CancelledError` 单独吞掉（取消不是失败，
不产生诊断），其它异常仍记成 `field_unavailable` 诊断（文案由 "compose raised" 回到 "compose failed"）。
3. **request_id 单调**：`submit()` 拒绝小于本 epoch 已见值的 request_id（>0 时）并计 `stale` + 给
`stale_frame` 诊断；`_identity_is_current()` 同样比较，所以"晚到的旧结果"也进不了屏幕。
4. 新增 `ThreeDCoordinator.epoch` 与 `last_presented()`（帧号 + 单调时刻，供后续面板帧计数用）；
构造参数新增关键字 `clock`（默认 `time.monotonic`）与 `stale_grace_s`（默认 1.0，本提交尚未使用）。
- Why: 审查报告 P1/R1 的第一条。`Future.cancel()` 无法中断已经开始运行的函数，而旧代码在
`_cancel_inflight()` 里就把 `_inflight` 置空并只比较 generation —— 于是"停止显示"之后旧 work 结束仍然
`offer` 进 `_composed`，下一次 tick 取到它并把状态改回 live（审查用可控后台任务复现：
`valid_after_show_rest=false` → 放行旧 compose → `valid_after_old_worker_finishes=true`、`state=live`）。
同一个洞也适用于"停止重算后定时器仍继续 tick"的场景。把接受点移到 GUI 线程后，"发布前校验"和
"接收时校验"是同一处代码，epoch 让"这一刻的显示声明"成为可比较的事实。
- Verification:
· `test_scene3d_coordinator.py` +7（24 通过）：合成已进入后被 `show_rest`/`set_visible(False)`/
`begin_session` 撤销 → 旧结果永不 present 且 state 不为 live、epoch 递增、槽位在 work 真正结束后释放；
`ManualExecutor` 复现"提交后立即取消" → `CancelledError` 不产生诊断且槽位可复用；
20 轮 begin_session→submit→tick→show_rest 循环里最后一个画面上永远没有有效测量、`max_in_flight==1`；
request_id 逆序在入口被拒（`stale` + `stale_frame`）且画面停在较新的请求上，
"较旧请求的结果晚到"也在接收侧被丢弃。
· 审查复现脚本对照（`.repro/probe_stage6_r1.py` → `probe_stage6_r1.json`）：
`stopped_frame_returns` 由 `{valid_after_old_worker_finishes: true, state: "live"}` 变为
`{false, "no_data", epoch_bumped: true, slot_free_again: true}`；
`request_id_not_checked` 由 `{old_submit: "accepted", shown_request: 1}` 变为
`{old_submit: "stale", shown_request: 2, diagnostic: "stale_frame"}`。
· apps/studio 全量 pytest 退出码 0（含真 GL 冒烟用例）。
- Not in this change: `stale_grace_s`/`clock` 只落地参数与 `last_presented()` 的记录，**失效状态的迁移
（`stale` 状态、宽限到期回参考模型）留给下一提交**；adapter 侧的字段级有效性、设备几何身份、
资产加载请求号、二维后端统一均未动；审查报告里那句"用 `coordinator._inflight` 当 Future 用"的复现
脚本无法再原样运行（槽位现在是 `_Inflight` 记录），改用上面那份等价探针。
orisys-app
Desktop applications that consume the Orisys SDK.
| App | Status |
|---|---|
apps/studio |
Scaffold shell (theme / locale / prefs / logging) |
apps/internal |
Stub for future calibration & automated testing |
Layout
shared/— common paths, prefs, theme, i18n, loggingapps/studio/config/— locales, default prefs, editablesensors/copiesapps/studio/outputs/— generated logs and calibration exports (gitignored)build/— Windows PyInstaller packaging (build/studio/build.ps1)
Run (studio shell)
cd D:\repo\orisys-app
python -m pip install -e .\shared -e .\apps\studio
python .\apps\studio\run.py
Or without install:
$env:PYTHONPATH = "D:\repo\orisys-app\shared\src;D:\repo\orisys-app\apps\studio\src"
python D:\repo\orisys-app\apps\studio\run.py
Local orisys SDK
orisys_app_shared.force imports orisys.calibration at module scope, so the
studio app cannot start against an SDK build that predates that module
(the published 0.5.2 wheel does not include it). When working from a repo
checkout, install the SDK from source instead of from an index:
python -m pip install .\..\orisys-sdk # same checkout that built this app
If a pip build is blocked by the environment, the equivalent manual install is
to copy orisys-sdk/src/orisys/**/*.py over site-packages/orisys/ and delete
the stale __init__.cp310-win_amd64.pyd (an extension module shadows the
package __init__.py, which hides sibling modules such as calibration.py).
Verifying UI changes
Both tools render the real main window with the offscreen Qt platform — no display, camera or sensor hardware required:
python .\apps\studio\tools\ui_check.py # layout/theme assertions
python .\apps\studio\tools\ui_snapshot.py --theme light --demo `
--sensor finger --panels cal,3d --size 1600x900 --out shot.png
ui_check.py needs only the runtime dependencies. The pytest suite in
shared/tests and apps/studio/tests covers the same ground plus locale and
preference-schema parity:
pip install pytest
python -m pytest
On Windows the offscreen platform finds no fonts unless QT_QPA_FONTDIR points
at C:\Windows\Fonts; both tools set it automatically.
ui_check.py also runs the palette rules (WCAG contrast, colour separation,
ramp monotonicity) that guard the brand tokens; see
apps/studio/docs/ui-palette.md for the
colour system, its relationship to the UI design spec, and every deliberate
deviation from it.
ui_check.py includes a record channel section as well; see
apps/studio/docs/record-channel.md for
why recording and calibration sampling no longer hang off the UI refresh timer,
and for the data-reliability fixes that came with it.
Branding
Window / EXE icon: shared/resources/branding/logo.png
Top bar / About: shared/resources/branding/logo_topbar.png
Dark mode is the default. Logos currently sit on a black tile; a transparent (or light) variant may be needed for polished light mode later.
Versioning
- Studio app version (
orisys_studio.__version__) — shown in Help → About and used for releases. - Shared package version (
orisys_app_shared.__version__) — internal library version. - Shared API (
orisys_app_shared.API_VERSION) — compatibility tag. Studio declaresREQUIRES_SHARED_API; startup logs a warning on mismatch.
Deferred
Run/Stop pipeline, arrow/force plots, units, calibration capture, Open3D finger mesh, sync-from-wheel for config/sensors, PyInstaller packaging, and the internal app.