ykcheungab
cf45e654e1
- What:
1. `docs/architecture/studio-3d-stages.md` 新增三节：**阶段 7**（二维图像后端统一与回放入口收口，含起因、
做法、验收表格）、**阶段 8 第一批**（能力控件/真实色标/复位语义/命名）、**阶段 9 上半**（限速、真实统计、
无位移复用几何、保护包密钥），并新开一节「尚未完成」把两项写清楚：阶段 8 第二批（画布布局与曲线量程）与
阶段 9 的门禁运行（GUI 2 小时长时 + 两块 ARM 板的探针/性能/长时报告），外加阶段 6 遗留的真机验证项。
文首进度与依赖关系图同步。
2. `docs/architecture/studio-3d-contracts.pyi`：新增 `SceneCapabilities`；`RenderStats` 增
`paint_calls`/`scale_lower`/`scale_upper`/`scale_mode` 并注明 `displayed_frames` 是"按帧身份的唯一帧"
而不是绘制次数；`RenderFrame` 增 `compose_ms`。
3. `tools/scene_assets/README.md`：新增「Studio 应用侧的配置」——`scene3d_verify_key`/
`scene3d_content_key_file` + `scene3d_content_key_id`/`scene3d_require_signature` 的用法、为什么没有验签
公钥就打不开签名包、以及"密钥文件缺失是状态而非崩溃、记录里只留布尔与路径"。
- Why: 规格 §13 要求每阶段同时交出实现、测试、输入样例、失败样例、兼容说明与平台诊断报告；阶段 6 的文档提交
之后又落了阶段 7/8/9 的接口改动，骨架文件必须跟上，否则下一阶段会照着过期文档实现。同时把"没做完的两项"
写在文档里（而不是留在对话里），下一个接手的人不需要猜。
- Verification: 文档改动本身不执行测试；其中的数字全部来自本仓可复现的命令：`pytest`（shared+apps 同一次
运行 588 项 0 失败 15 跳过）、真 GL 冒烟 14 项 0 失败、`ui_check.py` 587 项 0 失败、`locale_check.py`
0 缺失、`bench_scene.py --cpu-only`（20k 顶点 1.03 ms / 真实包 0.17 ms）、`validate_scene.py`（重编包
全项 ok）与两份 `.repro/probe_stage6_*.json`。
- Not in this change: 不改代码；阶段 8 第二批与阶段 9 门禁仍未做（见文档「尚未完成」一节）；ARM 板卡报告
按用户先前的意思仍是暂缓项。
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.