# 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, logging
- `apps/studio/config/` — locales, default prefs, editable `sensors/` copies
- `apps/studio/outputs/` — generated logs and calibration exports (gitignored)
- `build/` — Windows PyInstaller packaging (`build/studio/build.ps1`)

## Run (studio shell)

```powershell
cd D:\repo\orisys-app
python -m pip install -e .\shared -e .\apps\studio
python .\apps\studio\run.py
```

Or without install:

```powershell
$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.1 wheel does not include it). When working from a repo
checkout, install the SDK from source instead of from an index:

```powershell
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:

```powershell
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:

```powershell
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`](apps/studio/docs/ui-palette.md) for the
colour system, its relationship to the UI design spec, and every deliberate
deviation from 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 declares `REQUIRES_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.