ykcheungab
b37c861254
- What: `docs/architecture/studio-architecture.md` 的数字与结论按当前源码重扫后刷新：
- 分层图/纯文本图：`app_window` 3044 → **2309 行 / fan-out 37**，并新增一层
"②b Studio 控制器"（session_controller 437 / replay_controller 641 / view_layout 398 /
display_prefs 227）；领域服务与共享层的行数一并更新（replay 291、calibration_service 194、
coordinator 619、camera 238、view 757、asset_source 256、gl_backend 870；
shared scene3d 4565 / acquisition 2627 / record 3008 / force 3057 / 基础设施 1507）。
- 边界规则：模块数 89（studio 32 + shared 57）→ **94（studio 37 + shared 57）**，环 0 个不变。
- 指标表：新增 `replay_controller`(641) 与 `session_controller`(437) 两行，并写明
"app_window 的 fan-out 仍是最高（37），因为它本来就是装配器——但规则已经不在它里面"。
- 生产面/验证面：studio 生产 14 655 行、shared 14 764、测试 15 639（shared 7226/334 项 +
studio 8413/310 项）、工具 4046（ui_check 3401）；验证面 19.7k > 生产面 14.7k。
- 评估第 1 条与"一句话结论"改写为：上帝对象已按职责拆开，并**诚实记账**留下的东西——
约 40 个过渡转发（给 tests/`ui_check` 的桥，属过渡层）、仍留在窗口的预览与 2D 渲染
（它们同时属于面板与相机），以及 fan-out 从 36 升到 37 的原因。
- 建议表第 1 条标记为已完成（写清五个去处与新增 41 项控制器单测），新增第 1b 条
"下次改动顺手删掉对应转发"，并补第 7 条"真机与 ARM 验收"（本机无设备/板卡，是当前最大空白）。
- What: `studio-architecture.svg` / `.png` 由 `.repro/make_studio_svg.py` 重新生成：
窗口框改为"2309 行 · 158 方法 · fan-out 37 · 装配 + 信号转发"，右侧四个控制器小框，
面板/服务/共享层/验证面的行数与测试项数同步；底部结论改为"已按职责拆开 + 剩下的胶水"。
顺带修好 `svg_to_png.py` 里写死的 1560×1180（现在读 SVG 自己的尺寸），否则海报加高后会被裁掉。
- Why: 这份报告是"判断组织是否合理"的依据，数字或结论一旦过期就会误导决策；
拆分改变最大的一处正是它第 1 条风险与第 1 条建议，必须同步。
- Verification: 图表脚本重跑无异常（SVG well-formed，PNG 1560×1210 已目视检查）；
同批源码的验证为 pytest 644 passed / 0 failed / 15 skipped（offscreen）、
tools/ui_check.py 587 项 0 失败、.repro/locale_check.py 0 缺失。
- Not in this change: 不改代码；不改 `.repro` 下的扫描脚本口径（仍以扫描输出为准）。
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.