@kubohiroya/turbowarp-camera-source 0.9.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ja.md CHANGED
@@ -26,13 +26,13 @@ TurboWarp-Camera-Sourceは、MediaDevicesのカメラストリームを名前付
26
26
  次のURLをunsandboxed custom extensionとして読み込みます。
27
27
 
28
28
  ```text
29
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-camera-source@0.9.1/dist/camera-source.js
29
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-camera-source@0.10.0/dist/camera-source.js
30
30
  ```
31
31
 
32
32
  npm hostでは次を使います。
33
33
 
34
34
  ```bash
35
- pnpm add @kubohiroya/turbowarp-camera-source@0.9.1
35
+ pnpm add @kubohiroya/turbowarp-camera-source@0.10.0
36
36
  ```
37
37
 
38
38
  ## Quick start
@@ -70,6 +70,7 @@ stop shared camera [pose]
70
70
  - `camera device ID at [INDEX]`: 1始まりの位置でカメラdevice IDを返します。
71
71
  - `camera device label at [INDEX]`: 1始まりの位置でカメララベルを返します。
72
72
  - `register camera profile [PROFILE_JSON]`: 内部校正プロファイルを検証して登録します。現行の`twcs/camera-intrinsics`と、旧`twrmc/camera-calibration`のどちらの文書も受け取ります。
73
+ - `register camera profile [PROFILE_JSON] as [CAMERA_ID]`: 文書が持つcamera IDを指定したIDへ置き換えてから検証し、登録します。校正アプリで`default`として解いたプロファイルを`pose`として使う場合などに使います。camera profile errorの扱いは通常の登録ブロックと同じです。
73
74
  - `forget camera profile for [CAMERA_ID]`: 登録済みプロファイルを破棄します。
74
75
  - `camera [CAMERA_ID] is calibrated?`: プロファイルが登録されているかを返します。未登録は正常な状態です。
75
76
  - `camera profile JSON for [CAMERA_ID]`: 保存された文書をそのまま返します。表示や書き出し用であって、投影に使う数値ではありません。
@@ -81,6 +82,11 @@ stop shared camera [pose]
81
82
  - `camera intrinsics JSON for [CAMERA_ID]`: 現在のフレームに適合済みの内部行列を返します。適合していなければ空文字列です。
82
83
  - `camera conditions JSON for [CAMERA_ID]`: カメラが今報告している撮影条件を返します。
83
84
  - `camera conditions generation for [CAMERA_ID]`: 幾何に影響する条件が変わるたびに増える整数を返します。frame rateでは動きません。
85
+ - `save camera profile for [CAMERA_ID] to browser storage`: そのカメラに登録済みのプロファイルを、このoriginのブラウザストレージ(IndexedDB)へ保存し、同じoriginの他ウィンドウへ通知します。書き込み完了まで待ちます。結果は`saved`/`no-profile`/`unavailable`です。
86
+ - `restore stored camera profile for [CAMERA_ID]`: 保存済みプロファイルのうち、現在のカメラ構成に`compatible`な最新のものをこのcamera IDで登録します。fail closedで、`undetermined`や`incompatible`なものは登録せず、既存の登録にも触れません。結果は`restored`/`none`/`incompatible`/`undetermined`/`unavailable`です。
87
+ - `stored camera profile result for [CAMERA_ID]`: そのcamera IDで直近に行った保存または復元の結果を返します。未実行なら空文字列です。
88
+ - `stored camera profile detail for [CAMERA_ID]`: 直近の保存・復元の説明を返します。保存・復元したプロファイル、またはどの保存済みプロファイルもカメラに適合しない理由です。
89
+ - `stored camera profiles generation`: このウィンドウまたは同じoriginの他ウィンドウでプロファイルが保存されるたびに増えるカウンタです。プロジェクトを読み込んでも戻りません。
84
90
 
85
91
  <!-- END GENERATED BLOCKS -->
86
92
 
@@ -161,8 +167,26 @@ import type {CameraFrameSource, CameraLease} from "@kubohiroya/turbowarp-camera-
161
167
 
162
168
  **「判定できない」は「適合する」とは別の答え。** 適合性は`compatible`/`incompatible`/`undetermined`の3値で、不明が`compatible`へ格上げされることはない。プロファイルが現在の構成に適合していない限り内部行列は渡さない。渡してしまえば、利用側は別の構成の数値で投影し、**もっともらしく間違った幾何**を得ることになる。
163
169
 
170
+ ### ブラウザストレージ
171
+
172
+ プロファイルはブラウザ内に保持でき、次の作業や別ウィンドウでファイルを読み直さずに済む。`save camera profile for [CAMERA_ID] to browser storage`は登録済みプロファイルをIndexedDB(データベース`kubohiroya-camera-source`、object store`camera-profiles`、キーは`profileId`)へ書き込み、BroadcastChannel`kubohiroya-camera-source:camera-profiles`で保存を知らせる。`stored camera profiles generation`は、このウィンドウでも同じoriginの別ウィンドウでも保存のたびに増えるので、別ウィンドウの校正アプリを待つ作品はこの整数だけを見て、動いたら復元すればよい。
173
+
174
+ ```text
175
+ restore stored camera profile for [pose]
176
+ if <(stored camera profile result for [pose]) = [restored]> then
177
+ ... レンズ校正を省略 ...
178
+ ```
179
+
180
+ **これはキャッシュであってバックアップではない。** ストレージは1つのブラウザプロファイルの1つのoriginに属し、ホストやポートが違えば見えず、ブラウザが消すこともある。**書き出したプロファイルファイルが正本**なので、そちらを残しておくこと。
181
+
182
+ **復元はfail closedである。** 候補は`calibratedAt`の新しい順に、ブロックで指定したcamera IDへ付け替えたうえで、そのカメラの現在の構成と照合する。登録するのは`compatible`なものだけ。`undetermined`(たとえばカメラがまだフレームを届けていない)は弱いyesではなく、該当がなければそのカメラに登録済みのプロファイルはそのまま残る。結果は`restored`/`none`/`incompatible`/`undetermined`/`unavailable`、保存は`saved`/`no-profile`/`unavailable`を返す。
183
+
184
+ `register camera profile [PROFILE_JSON] as [CAMERA_ID]`はファイルに対して同じ付け替えを行う。校正アプリで`default`として解いたプロファイルを、利用側の作品で`pose`として登録できる。
185
+
164
186
  ## 互換性
165
187
 
188
+ 0.10.0では校正プロファイルのブラウザストレージと`register camera profile as`を追加した。既存のブロックとcapabilityのメンバーは変えていない。
189
+
166
190
  未リリースの変更は破壊的である。`CameraFrameSource.mirrored`は`previewFlip`へ置き換えた。軸を名指しでき、かつ「描画の話であって画素の話ではない」と言えるためである。previewブロックの`MIRRORED`引数は`PREVIEW_FLIP`へ置き換え、booleanはもう読まない。`acquireCamera`は`previewFlip`を受け取り、`mirrored`は受け付けない。frame sourceのinterfaceを手書きで持っている利用側は、公開した`./runtime`のimportへ移ること。そうしていればこの変更はビルド時に分かった。
167
191
 
168
192
  0.6.0ではcamera IDごとの開始失敗情報を公開し、inactive streamまたは終了したvideo trackを停止状態として
package/README.md CHANGED
@@ -30,13 +30,13 @@ or select separate cameras for separate roles.
30
30
  Load this URL as an unsandboxed custom extension:
31
31
 
32
32
  ```text
33
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-camera-source@0.9.1/dist/camera-source.js
33
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-camera-source@0.10.0/dist/camera-source.js
34
34
  ```
35
35
 
36
36
  For npm hosts:
37
37
 
38
38
  ```bash
39
- pnpm add @kubohiroya/turbowarp-camera-source@0.9.1
39
+ pnpm add @kubohiroya/turbowarp-camera-source@0.10.0
40
40
  ```
41
41
 
42
42
  ## Quick Start
@@ -218,6 +218,17 @@ Validates a twcs/camera-intrinsics version 1 document and stores it against the
218
218
  | Opcode | `registerCameraProfile` |
219
219
  | `PROFILE_JSON` | String, default: `{}` |
220
220
 
221
+ ### `register camera profile [PROFILE_JSON] as [CAMERA_ID]`
222
+
223
+ Registers a profile under the named camera ID, replacing the ID the document carries before it is validated. Use it when a profile was solved under another name, such as `default` in a calibration app. Sets or clears the camera profile error like the plain register block.
224
+
225
+ | Property | Value |
226
+ |---|---|
227
+ | Type | Command |
228
+ | Opcode | `registerCameraProfileAs` |
229
+ | `PROFILE_JSON` | String, default: `{}` |
230
+ | `CAMERA_ID` | String, default: `default` |
231
+
221
232
  ### `forget camera profile for [CAMERA_ID]`
222
233
 
223
234
  Removes the stored calibration profile for one camera.
@@ -326,6 +337,55 @@ Returns a number that increases whenever something affecting the geometry change
326
337
  | Opcode | `cameraConditionsGeneration` |
327
338
  | `CAMERA_ID` | String, default: `default` |
328
339
 
340
+ ### `save camera profile for [CAMERA_ID] to browser storage`
341
+
342
+ Saves the profile registered for the camera to this origin's browser storage (IndexedDB) and tells other windows on the same origin. Waits until the write commits. The result becomes `saved`, `no-profile` or `unavailable`.
343
+
344
+ | Property | Value |
345
+ |---|---|
346
+ | Type | Command |
347
+ | Opcode | `saveCameraProfile` |
348
+ | `CAMERA_ID` | String, default: `default` |
349
+
350
+ ### `restore stored camera profile for [CAMERA_ID]`
351
+
352
+ Registers the newest saved profile that is `compatible` with the camera as configured now, under this camera ID. Fails closed: an `undetermined` or `incompatible` profile is never registered and the current registration is left untouched. The result becomes `restored`, `none`, `incompatible`, `undetermined` or `unavailable`.
353
+
354
+ | Property | Value |
355
+ |---|---|
356
+ | Type | Command |
357
+ | Opcode | `restoreStoredCameraProfile` |
358
+ | `CAMERA_ID` | String, default: `default` |
359
+
360
+ ### `stored camera profile result for [CAMERA_ID]`
361
+
362
+ Returns the outcome of the last save or restore for the camera ID, or an empty string before either has run.
363
+
364
+ | Property | Value |
365
+ |---|---|
366
+ | Type | Reporter |
367
+ | Opcode | `storedCameraProfileResult` |
368
+ | `CAMERA_ID` | String, default: `default` |
369
+
370
+ ### `stored camera profile detail for [CAMERA_ID]`
371
+
372
+ Explains the last save or restore: which profile was saved or restored, or why no saved profile fits the camera.
373
+
374
+ | Property | Value |
375
+ |---|---|
376
+ | Type | Reporter |
377
+ | Opcode | `storedCameraProfileDetail` |
378
+ | `CAMERA_ID` | String, default: `default` |
379
+
380
+ ### `stored camera profiles generation`
381
+
382
+ A counter that increments whenever a profile is saved in this window or another window on the same origin. It is not reset by loading a project.
383
+
384
+ | Property | Value |
385
+ |---|---|
386
+ | Type | Reporter |
387
+ | Opcode | `storedCameraProfilesGeneration` |
388
+
329
389
  <!-- END GENERATED BLOCKS -->
330
390
 
331
391
  ## Runtime API
@@ -421,8 +481,41 @@ own repository and fails in a browser instead.
421
481
 
422
482
  **"Cannot tell" is a distinct answer from "fits".** Compatibility is `compatible`, `incompatible` or `undetermined`, and unknown never resolves upward. Intrinsics are withheld unless the profile actually fits the camera as configured now: handing them over regardless would let a consumer project with numbers from a different configuration and get plausible, wrong geometry back.
423
483
 
484
+ ### Browser storage
485
+
486
+ A profile can be kept in the browser so the next session, or another window, does not need the file
487
+ again. `save camera profile for [CAMERA_ID] to browser storage` writes the registered profile to
488
+ IndexedDB (database `kubohiroya-camera-source`, object store `camera-profiles`, keyed by `profileId`)
489
+ and announces the save on the `kubohiroya-camera-source:camera-profiles` BroadcastChannel.
490
+ `stored camera profiles generation` moves on every save, in this window or any other on the same
491
+ origin, so a project waiting for a calibration app in another window watches one number and restores
492
+ when it changes.
493
+
494
+ ```text
495
+ restore stored camera profile for [pose]
496
+ if <(stored camera profile result for [pose]) = [restored]> then
497
+ ... skip lens calibration ...
498
+ ```
499
+
500
+ **It is a cache, not a backup.** Storage belongs to one origin in one browser profile, a different
501
+ host or port sees none of it, and the browser may evict it. The exported profile file stays the
502
+ source of truth; keep it.
503
+
504
+ **Restoring fails closed.** Candidates are tried newest `calibratedAt` first, each rebound to the
505
+ camera ID the block names and judged against that camera as it is configured now. Only a
506
+ `compatible` one is registered. `undetermined` — for example because the camera has not delivered a
507
+ frame yet — is not a weaker yes, and when nothing qualifies the profile already registered for the
508
+ camera is left as it was. The result is `restored`, `none`, `incompatible`, `undetermined` or
509
+ `unavailable`; a save reports `saved`, `no-profile` or `unavailable`.
510
+
511
+ `register camera profile [PROFILE_JSON] as [CAMERA_ID]` does the same rebinding for a file: a profile
512
+ solved under `default` in a calibration app can be registered as `pose` in the app that uses it.
513
+
424
514
  ## Compatibility
425
515
 
516
+ Version 0.10.0 adds browser storage for calibration profiles and `register camera profile as`. No
517
+ existing block or capability member changes.
518
+
426
519
  Unreleased changes are breaking. `CameraFrameSource.mirrored` is replaced by `previewFlip`, which
427
520
  names the axis and says that it describes the drawing rather than the pixels. The preview block's
428
521
  `MIRRORED` argument is replaced by `PREVIEW_FLIP` and the boolean is no longer read. `acquireCamera`
@@ -171,6 +171,21 @@
171
171
  "defaultValue": "{}"
172
172
  } }
173
173
  },
174
+ {
175
+ "opcode": "registerCameraProfileAs",
176
+ "blockType": "COMMAND",
177
+ "text": "register camera profile [PROFILE_JSON] as [CAMERA_ID]",
178
+ "arguments": {
179
+ "PROFILE_JSON": {
180
+ "type": "STRING",
181
+ "defaultValue": "{}"
182
+ },
183
+ "CAMERA_ID": {
184
+ "type": "STRING",
185
+ "defaultValue": "default"
186
+ }
187
+ }
188
+ },
174
189
  {
175
190
  "opcode": "forgetCameraProfile",
176
191
  "blockType": "COMMAND",
@@ -263,6 +278,48 @@
263
278
  "type": "STRING",
264
279
  "defaultValue": "default"
265
280
  } }
281
+ },
282
+ {
283
+ "opcode": "saveCameraProfile",
284
+ "blockType": "COMMAND",
285
+ "text": "save camera profile for [CAMERA_ID] to browser storage",
286
+ "arguments": { "CAMERA_ID": {
287
+ "type": "STRING",
288
+ "defaultValue": "default"
289
+ } }
290
+ },
291
+ {
292
+ "opcode": "restoreStoredCameraProfile",
293
+ "blockType": "COMMAND",
294
+ "text": "restore stored camera profile for [CAMERA_ID]",
295
+ "arguments": { "CAMERA_ID": {
296
+ "type": "STRING",
297
+ "defaultValue": "default"
298
+ } }
299
+ },
300
+ {
301
+ "opcode": "storedCameraProfileResult",
302
+ "blockType": "REPORTER",
303
+ "text": "stored camera profile result for [CAMERA_ID]",
304
+ "arguments": { "CAMERA_ID": {
305
+ "type": "STRING",
306
+ "defaultValue": "default"
307
+ } }
308
+ },
309
+ {
310
+ "opcode": "storedCameraProfileDetail",
311
+ "blockType": "REPORTER",
312
+ "text": "stored camera profile detail for [CAMERA_ID]",
313
+ "arguments": { "CAMERA_ID": {
314
+ "type": "STRING",
315
+ "defaultValue": "default"
316
+ } }
317
+ },
318
+ {
319
+ "opcode": "storedCameraProfilesGeneration",
320
+ "blockType": "REPORTER",
321
+ "text": "stored camera profiles generation",
322
+ "arguments": {}
266
323
  }
267
324
  ],
268
325
  menus: { "flips": {
@@ -1022,6 +1079,88 @@
1022
1079
  }
1023
1080
  };
1024
1081
  //#endregion
1082
+ //#region src/calibration/store.ts
1083
+ /**
1084
+ * Profiles kept in the browser between sessions.
1085
+ *
1086
+ * A cache, not a backup. IndexedDB belongs to one origin in one browser profile, and the browser may
1087
+ * evict it; the exported file stays the thing an operator keeps. What this buys is the common case:
1088
+ * the calibration app and the app that uses its result are served from the same origin, so a solve
1089
+ * saved in one window can be picked up by the other without a file changing hands.
1090
+ *
1091
+ * The store holds documents and says nothing about whether one fits a camera. That is decided when
1092
+ * a profile is restored, against the camera as it is then, by the same validation and compatibility
1093
+ * rules every other way in goes through.
1094
+ */
1095
+ var cameraProfileDatabaseName = "kubohiroya-camera-source";
1096
+ var cameraProfileObjectStoreName = "camera-profiles";
1097
+ /** Other windows on the same origin hear about a save here. The message is `{profileId}`. */
1098
+ var cameraProfileChannelName = "kubohiroya-camera-source:camera-profiles";
1099
+ function isText(value) {
1100
+ return typeof value === "string";
1101
+ }
1102
+ /**
1103
+ * Whether a value read back has the shape of a record.
1104
+ *
1105
+ * The database outlives this build. Anything another version, or a developer console, left behind is
1106
+ * skipped here rather than handed on as if this build had written it.
1107
+ */
1108
+ function isStoredCameraProfile(value) {
1109
+ if (typeof value !== "object" || value === null) return false;
1110
+ const record = value;
1111
+ return isText(record["profileId"]) && isText(record["cameraId"]) && isText(record["calibratedAt"]) && isText(record["savedAt"]) && isText(record["document"]) && (record["deviceLabel"] === void 0 || isText(record["deviceLabel"]));
1112
+ }
1113
+ function settle(request) {
1114
+ return new Promise((resolve, reject) => {
1115
+ request.onsuccess = () => resolve(request.result);
1116
+ request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("IndexedDB request failed."));
1117
+ });
1118
+ }
1119
+ /**
1120
+ * The IndexedDB store.
1121
+ *
1122
+ * The database is opened on first use, not on construction: every project that loads this extension
1123
+ * would otherwise create it, including the ones that never save a profile. A failed open is not
1124
+ * remembered, so a later call gets another attempt instead of inheriting one bad moment for good.
1125
+ */
1126
+ function createIndexedDbCameraProfileStore(factory = globalThis.indexedDB) {
1127
+ let opening;
1128
+ const database = () => {
1129
+ if (!factory) return Promise.reject(/* @__PURE__ */ new Error("IndexedDB is not available."));
1130
+ if (!opening) {
1131
+ const request = factory.open(cameraProfileDatabaseName, 1);
1132
+ request.onupgradeneeded = () => {
1133
+ if (!request.result.objectStoreNames.contains("camera-profiles")) request.result.createObjectStore(cameraProfileObjectStoreName, { keyPath: "profileId" });
1134
+ };
1135
+ opening = settle(request).then((db) => {
1136
+ db.onversionchange = () => {
1137
+ db.close();
1138
+ opening = void 0;
1139
+ };
1140
+ return db;
1141
+ });
1142
+ opening.catch(() => {
1143
+ opening = void 0;
1144
+ });
1145
+ }
1146
+ return opening;
1147
+ };
1148
+ return {
1149
+ async list() {
1150
+ return (await settle((await database()).transaction(cameraProfileObjectStoreName, "readonly").objectStore(cameraProfileObjectStoreName).getAll())).filter(isStoredCameraProfile);
1151
+ },
1152
+ async put(record) {
1153
+ const transaction = (await database()).transaction(cameraProfileObjectStoreName, "readwrite");
1154
+ transaction.objectStore(cameraProfileObjectStoreName).put(record);
1155
+ await new Promise((resolve, reject) => {
1156
+ transaction.oncomplete = () => resolve();
1157
+ transaction.onerror = () => reject(transaction.error ?? /* @__PURE__ */ new Error("IndexedDB write failed."));
1158
+ transaction.onabort = () => reject(transaction.error ?? /* @__PURE__ */ new Error("IndexedDB write aborted."));
1159
+ });
1160
+ }
1161
+ };
1162
+ }
1163
+ //#endregion
1025
1164
  //#region src/runtime.ts
1026
1165
  /**
1027
1166
  * Where the extension instance puts itself on the VM runtime.
@@ -1316,6 +1455,49 @@
1316
1455
  function previewFlipOf(options) {
1317
1456
  return toFlip(options.previewFlip);
1318
1457
  }
1458
+ /** The document with its camera id replaced, or the value untouched when it is not an object. */
1459
+ function rebindCameraId(document, cameraId) {
1460
+ if (typeof document !== "object" || document === null || Array.isArray(document)) return document;
1461
+ return {
1462
+ ...document,
1463
+ cameraId
1464
+ };
1465
+ }
1466
+ function parseJson(text) {
1467
+ try {
1468
+ return {
1469
+ ok: true,
1470
+ value: JSON.parse(text)
1471
+ };
1472
+ } catch {
1473
+ return { ok: false };
1474
+ }
1475
+ }
1476
+ /** Which saved profile, in words an operator can match against the file they exported. */
1477
+ function describeStoredProfile(profile) {
1478
+ const label = profile.device?.label;
1479
+ return `Profile ${profile.profileId} calibrated at ${profile.calibratedAt}${label ? ` on ${label}` : ""}.`;
1480
+ }
1481
+ function compatibilityDetail(report) {
1482
+ const findings = decisiveFindings(report);
1483
+ if (findings.length === 0) return "The profile matches the camera as configured.";
1484
+ return findings.map((entry) => entry.detail).join(" ");
1485
+ }
1486
+ /**
1487
+ * Newest calibration first.
1488
+ *
1489
+ * Timestamps are compared as instants, so an offset other than `Z` still sorts where it belongs. One
1490
+ * that does not parse sorts last: it cannot be shown to be newer than anything.
1491
+ */
1492
+ function newestFirst(left, right) {
1493
+ const instant = (text) => {
1494
+ const value = Date.parse(text);
1495
+ return Number.isFinite(value) ? value : Number.NEGATIVE_INFINITY;
1496
+ };
1497
+ const byCalibration = instant(right.calibratedAt) - instant(left.calibratedAt);
1498
+ if (byCalibration !== 0 && !Number.isNaN(byCalibration)) return byCalibration;
1499
+ return instant(right.savedAt) - instant(left.savedAt) || 0;
1500
+ }
1319
1501
  function cameraFailure(error) {
1320
1502
  if (error instanceof Error) return {
1321
1503
  code: error.name || "Error",
@@ -1327,7 +1509,7 @@
1327
1509
  };
1328
1510
  }
1329
1511
  var CameraSourceExtension = class {
1330
- constructor() {
1512
+ constructor(options = {}) {
1331
1513
  this.sessions = /* @__PURE__ */ new Map();
1332
1514
  this.blockLeases = /* @__PURE__ */ new Map();
1333
1515
  this.blockPreviewLeases = /* @__PURE__ */ new Map();
@@ -1338,10 +1520,13 @@
1338
1520
  this.lastConditions = /* @__PURE__ */ new Map();
1339
1521
  this.assessments = /* @__PURE__ */ new Map();
1340
1522
  this.devices = [];
1523
+ this.storedProfileOutcomes = /* @__PURE__ */ new Map();
1524
+ this.storedProfilesGeneration = 0;
1341
1525
  this.dispose = () => {
1342
1526
  this.stopAllCameras();
1343
1527
  const runtime = Scratch.vm.runtime;
1344
1528
  if (runtime["kubohiroyaCameraSourceCapability"] === this.capability) delete runtime[cameraSourceCapabilityKey];
1529
+ this.profileChannel?.close();
1345
1530
  Scratch.vm.runtime.off?.("PROJECT_STOP_ALL", this.handleProjectBoundary);
1346
1531
  Scratch.vm.runtime.off?.("PROJECT_LOADED", this.handleProjectBoundary);
1347
1532
  Scratch.vm.runtime.off?.("RUNTIME_DISPOSED", this.dispose);
@@ -1349,7 +1534,10 @@
1349
1534
  this.handleProjectBoundary = () => {
1350
1535
  this.stopAllCameras();
1351
1536
  this.profileError = void 0;
1537
+ this.storedProfileOutcomes.clear();
1352
1538
  };
1539
+ this.profileStore = options.profileStore ?? createIndexedDbCameraProfileStore();
1540
+ this.profileChannel = this.openProfileChannel();
1353
1541
  Scratch.vm.runtime[cameraSourceRuntimeKey] = this;
1354
1542
  this.capability = createRuntimeCapability({
1355
1543
  registerProfile: (document) => this.profiles.register(document),
@@ -1505,20 +1693,132 @@
1505
1693
  this.blockPreviewLeases.clear();
1506
1694
  }
1507
1695
  registerCameraProfile(args = {}) {
1508
- const text = Scratch.Cast.toString(args.PROFILE_JSON ?? "");
1509
- let document;
1696
+ this.registerProfileText(args.PROFILE_JSON, (document) => document);
1697
+ }
1698
+ /**
1699
+ * Registers a profile under the camera id the project names, whatever id the document carries.
1700
+ *
1701
+ * The id in a document is the name the camera had where it was solved. A calibration app knows one
1702
+ * camera and calls it `default`; the app that uses the result may call the same camera `pose`.
1703
+ * Rebinding happens before validation, so the document is checked as the profile it is about to
1704
+ * become rather than as the one it was.
1705
+ */
1706
+ registerCameraProfileAs(args = {}) {
1707
+ const cameraId = normalizeId(args.CAMERA_ID);
1708
+ this.registerProfileText(args.PROFILE_JSON, (document) => rebindCameraId(document, cameraId));
1709
+ }
1710
+ /**
1711
+ * Writes the profile registered for a camera to browser storage.
1712
+ *
1713
+ * Only a registered profile can be saved, so whatever reaches storage has already passed
1714
+ * validation. Other windows on the origin are told once the write has committed, not before: a
1715
+ * window that went looking on the strength of an uncommitted write would find nothing and conclude
1716
+ * there was nothing to find.
1717
+ */
1718
+ async saveCameraProfile(args = {}) {
1719
+ const cameraId = normalizeId(args.CAMERA_ID);
1720
+ const profile = this.profiles.get(cameraId);
1721
+ if (!profile) {
1722
+ this.storedProfileOutcomes.set(cameraId, {
1723
+ state: "no-profile",
1724
+ detail: ""
1725
+ });
1726
+ return;
1727
+ }
1728
+ const label = profile.device?.label;
1729
+ const record = {
1730
+ profileId: profile.profileId,
1731
+ cameraId: profile.cameraId,
1732
+ calibratedAt: profile.calibratedAt,
1733
+ savedAt: (/* @__PURE__ */ new Date()).toISOString(),
1734
+ ...label === void 0 ? {} : { deviceLabel: label },
1735
+ document: serializeCameraIntrinsicProfile(profile)
1736
+ };
1510
1737
  try {
1511
- document = JSON.parse(text);
1738
+ await this.profileStore.put(record);
1512
1739
  } catch {
1513
- this.profileError = {
1514
- code: "not-an-object",
1515
- path: "",
1516
- message: "The profile is not valid JSON."
1517
- };
1740
+ this.storedProfileOutcomes.set(cameraId, {
1741
+ state: "unavailable",
1742
+ detail: ""
1743
+ });
1518
1744
  return;
1519
1745
  }
1520
- const result = this.profiles.register(document);
1521
- this.profileError = result.ok ? void 0 : result.error;
1746
+ this.storedProfilesGeneration += 1;
1747
+ this.storedProfileOutcomes.set(cameraId, {
1748
+ state: "saved",
1749
+ detail: describeStoredProfile(profile)
1750
+ });
1751
+ try {
1752
+ this.profileChannel?.postMessage({ profileId: profile.profileId });
1753
+ } catch {}
1754
+ }
1755
+ /**
1756
+ * Registers the newest saved profile that fits the camera as it is configured now.
1757
+ *
1758
+ * Fails closed. Only a `compatible` verdict registers anything; `undetermined` is not a weaker yes,
1759
+ * and a camera that has not delivered a frame yet cannot be shown to match any calibration. When
1760
+ * nothing qualifies, whatever is already registered for the camera stays exactly as it was: a
1761
+ * restore that found nothing usable has no business taking away a profile that was.
1762
+ *
1763
+ * Every candidate is judged against the conditions directly, without going through the registry,
1764
+ * so trying a candidate that loses never displaces the registered one even for a moment.
1765
+ */
1766
+ async restoreStoredCameraProfile(args = {}) {
1767
+ const cameraId = normalizeId(args.CAMERA_ID);
1768
+ let records;
1769
+ try {
1770
+ records = await this.profileStore.list();
1771
+ } catch {
1772
+ this.storedProfileOutcomes.set(cameraId, {
1773
+ state: "unavailable",
1774
+ detail: ""
1775
+ });
1776
+ return;
1777
+ }
1778
+ const conditions = this.conditionsOf(cameraId);
1779
+ let incompatible;
1780
+ let undetermined;
1781
+ for (const record of [...records].sort(newestFirst)) {
1782
+ const parsed = parseJson(record.document);
1783
+ if (!parsed.ok) continue;
1784
+ const document = rebindCameraId(parsed.value, cameraId);
1785
+ const result = readCameraProfileDocument(document);
1786
+ if (!result.ok) continue;
1787
+ const report = evaluateProfileCompatibility(result.profile, conditions);
1788
+ if (report.state === "compatible") {
1789
+ this.profiles.register(document);
1790
+ this.storedProfileOutcomes.set(cameraId, {
1791
+ state: "restored",
1792
+ detail: describeStoredProfile(result.profile)
1793
+ });
1794
+ return;
1795
+ }
1796
+ if (report.state === "incompatible") incompatible ?? (incompatible = report);
1797
+ else undetermined ?? (undetermined = report);
1798
+ }
1799
+ const decisive = incompatible ?? undetermined;
1800
+ this.storedProfileOutcomes.set(cameraId, decisive === void 0 ? {
1801
+ state: "none",
1802
+ detail: ""
1803
+ } : {
1804
+ state: decisive.state,
1805
+ detail: compatibilityDetail(decisive)
1806
+ });
1807
+ }
1808
+ storedCameraProfileResult(args = {}) {
1809
+ return this.storedProfileOutcomes.get(normalizeId(args.CAMERA_ID))?.state ?? "";
1810
+ }
1811
+ storedCameraProfileDetail(args = {}) {
1812
+ return this.storedProfileOutcomes.get(normalizeId(args.CAMERA_ID))?.detail ?? "";
1813
+ }
1814
+ /**
1815
+ * A counter that moves whenever a profile is saved, here or in another window on this origin.
1816
+ *
1817
+ * A project waiting for the calibration app compares this integer rather than polling storage: it
1818
+ * restores when the number moves, and the restore decides whether what arrived is usable.
1819
+ */
1820
+ storedCameraProfilesGeneration() {
1821
+ return this.storedProfilesGeneration;
1522
1822
  }
1523
1823
  forgetCameraProfile(args = {}) {
1524
1824
  this.profiles.forget(normalizeId(args.CAMERA_ID));
@@ -1545,10 +1845,7 @@
1545
1845
  cameraProfileCompatibilityDetail(args = {}) {
1546
1846
  const cameraId = normalizeId(args.CAMERA_ID);
1547
1847
  const assessment = this.assessmentOf(cameraId);
1548
- if (assessment === void 0) return "";
1549
- const findings = decisiveFindings(assessment.compatibility);
1550
- if (findings.length === 0) return "The profile matches the camera as configured.";
1551
- return findings.map((entry) => entry.detail).join(" ");
1848
+ return assessment === void 0 ? "" : compatibilityDetail(assessment.compatibility);
1552
1849
  }
1553
1850
  cameraProfileAdaptation(args = {}) {
1554
1851
  const cameraId = normalizeId(args.CAMERA_ID);
@@ -1565,6 +1862,38 @@
1565
1862
  cameraConditionsGeneration(args = {}) {
1566
1863
  return this.generationOf(normalizeId(args.CAMERA_ID));
1567
1864
  }
1865
+ registerProfileText(value, prepare) {
1866
+ const parsed = parseJson(Scratch.Cast.toString(value ?? ""));
1867
+ if (!parsed.ok) {
1868
+ this.profileError = {
1869
+ code: "not-an-object",
1870
+ path: "",
1871
+ message: "The profile is not valid JSON."
1872
+ };
1873
+ return;
1874
+ }
1875
+ const result = this.profiles.register(prepare(parsed.value));
1876
+ this.profileError = result.ok ? void 0 : result.error;
1877
+ }
1878
+ /**
1879
+ * Listens for saves made in other windows on this origin.
1880
+ *
1881
+ * Absent where the browser has no BroadcastChannel. The generation then moves only for saves made
1882
+ * here, and a project still finds another window's profile the next time it restores.
1883
+ */
1884
+ openProfileChannel() {
1885
+ const Channel = globalThis.BroadcastChannel;
1886
+ if (typeof Channel !== "function") return void 0;
1887
+ try {
1888
+ const channel = new Channel(cameraProfileChannelName);
1889
+ channel.onmessage = () => {
1890
+ this.storedProfilesGeneration += 1;
1891
+ };
1892
+ return channel;
1893
+ } catch {
1894
+ return;
1895
+ }
1896
+ }
1568
1897
  /** What the track reports about itself right now. Read only. */
1569
1898
  intrinsicsOf(cameraId) {
1570
1899
  const id = normalizeId(cameraId);
@@ -222,6 +222,40 @@
222
222
  }
223
223
  ]
224
224
  },
225
+ {
226
+ "opcode": "registerCameraProfileAs",
227
+ "blockType": "COMMAND",
228
+ "arguments": [
229
+ {
230
+ "id": "CAMERA_ID",
231
+ "type": "STRING"
232
+ },
233
+ {
234
+ "id": "PROFILE_JSON",
235
+ "type": "STRING"
236
+ }
237
+ ]
238
+ },
239
+ {
240
+ "opcode": "restoreStoredCameraProfile",
241
+ "blockType": "COMMAND",
242
+ "arguments": [
243
+ {
244
+ "id": "CAMERA_ID",
245
+ "type": "STRING"
246
+ }
247
+ ]
248
+ },
249
+ {
250
+ "opcode": "saveCameraProfile",
251
+ "blockType": "COMMAND",
252
+ "arguments": [
253
+ {
254
+ "id": "CAMERA_ID",
255
+ "type": "STRING"
256
+ }
257
+ ]
258
+ },
225
259
  {
226
260
  "opcode": "showCameraPreview",
227
261
  "blockType": "COMMAND",
@@ -260,6 +294,31 @@
260
294
  "type": "STRING"
261
295
  }
262
296
  ]
297
+ },
298
+ {
299
+ "opcode": "storedCameraProfileDetail",
300
+ "blockType": "REPORTER",
301
+ "arguments": [
302
+ {
303
+ "id": "CAMERA_ID",
304
+ "type": "STRING"
305
+ }
306
+ ]
307
+ },
308
+ {
309
+ "opcode": "storedCameraProfileResult",
310
+ "blockType": "REPORTER",
311
+ "arguments": [
312
+ {
313
+ "id": "CAMERA_ID",
314
+ "type": "STRING"
315
+ }
316
+ ]
317
+ },
318
+ {
319
+ "opcode": "storedCameraProfilesGeneration",
320
+ "blockType": "REPORTER",
321
+ "arguments": []
263
322
  }
264
323
  ],
265
324
  "menus": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/turbowarp-camera-source",
3
- "version": "0.9.1",
3
+ "version": "0.10.0",
4
4
  "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
5
5
  "description": "A TurboWarp capability extension for sharing one MediaDevices camera stream across extensions.",
6
6
  "type": "module",