@kubohiroya/turbowarp-camera-source 0.11.0 → 0.12.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.11.0/dist/camera-source.js
29
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-camera-source@0.12.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.11.0
35
+ pnpm add @kubohiroya/turbowarp-camera-source@0.12.0
36
36
  ```
37
37
 
38
38
  ## Quick start
@@ -55,6 +55,7 @@ stop shared camera [pose]
55
55
  <!-- BEGIN GENERATED BLOCKS -->
56
56
 
57
57
  - `start shared camera [CAMERA_ID] with device ID [DEVICE_ID]`: 名前付き共有カメラを開始します。
58
+ - `start shared camera [CAMERA_ID] requested by this page`: ページのクエリパラメータが指定するカメラを開始します。`cameraDeviceId`は厳密に、`cameraWidth`・`cameraHeight`・`cameraFrameRate`は理想値として要求します。指定がなければ、デバイスを指定しない`start shared camera`と同じです。複数のUSBカメラを使うアプリが、同じoriginの別のアプリ(レンズ校正アプリなど)をそのうち1台のために開くときの指定方法です。
58
59
  - `stop shared camera [CAMERA_ID]`: 名前付き共有カメラを停止し、MediaStreamTrackを解放します。
59
60
  - `shared camera [CAMERA_ID] is running?`: 指定した共有カメラが起動中かを返します。
60
61
  - `shared camera [CAMERA_ID] error code`: 直近の開始失敗コードを返します。開始成功後は空文字列です。
@@ -85,6 +86,9 @@ stop shared camera [pose]
85
86
  - `camera conditions generation for [CAMERA_ID]`: 幾何に影響する条件が変わるたびに増える整数を返します。frame rateでは動きません。
86
87
  - `save camera profile for [CAMERA_ID] to browser storage`: そのカメラに登録済みのプロファイルを、このoriginのブラウザストレージ(IndexedDB)へ保存し、同じoriginの他ウィンドウへ通知します。書き込み完了まで待ちます。結果は`saved`/`no-profile`/`unavailable`です。
87
88
  - `restore stored camera profile for [CAMERA_ID]`: 保存済みプロファイルのうち、現在のカメラ構成に`compatible`な最新のものをこのcamera IDで登録します。fail closedで、`undetermined`や`incompatible`なものは登録せず、既存の登録にも触れません。結果は`restored`/`none`/`incompatible`/`undetermined`/`unavailable`です。
89
+ - `restore stored camera profile calibrated on the device of [CAMERA_ID]`: `restore stored camera profile`と同じですが、このカメラが今動いているデバイスで校正したプロファイルだけを候補にします。同じ型番のカメラどうしで校正を取り違えません。device IDはブラウザストレージと同じくoriginとブラウザのプロファイルごとです。カメラが動いていなければ`undetermined`、`none`のときは他のデバイスのプロファイルが何件あったかを説明に含めます。
90
+ - `bind camera profile for [CAMERA_ID] to its current device`: 登録済みプロファイルに、このカメラが今動いているデバイスを記録します。ファイルから読んだものなど、操作者がこのカメラのものと指定したプロファイルのためのブロックです。現在のカメラに`compatible`なときだけ記録し、そうでなければ何も変えません。記録を残すには続けて保存します。
91
+ - `camera profile for [CAMERA_ID] belongs to its current device?`: 登録済みプロファイルが、このカメラが今動いているデバイスで校正された、または結び付けられたものかを返します。
88
92
  - `stored camera profile result for [CAMERA_ID]`: そのcamera IDで直近に行った保存または復元の結果を返します。未実行なら空文字列です。
89
93
  - `stored camera profile detail for [CAMERA_ID]`: 直近の保存・復元の説明を返します。保存・復元したプロファイル、またはどの保存済みプロファイルもカメラに適合しない理由です。
90
94
  - `stored camera profiles generation`: このウィンドウまたは同じoriginの他ウィンドウでプロファイルが保存されるたびに増えるカウンタです。プロジェクトを読み込んでも戻りません。
@@ -243,8 +247,12 @@ if <(stored camera profile result for [pose]) = [restored]> then
243
247
 
244
248
  `register camera profile [PROFILE_JSON] as [CAMERA_ID]`はファイルに対して同じ付け替えを行う。校正アプリで`default`として解いたプロファイルを、利用側の作品で`pose`として登録できる。
245
249
 
250
+ **同じ型番のカメラが2台あるとき。** 2台は同じラベルと同じ撮影条件を報告するので、互いの校正が`compatible`になる。`restore stored camera profile calibrated on the device of [CAMERA_ID]`は、記録されたdevice IDがそのカメラの今のデバイスと一致するプロファイルだけを候補にする。device IDはoriginとブラウザのプロファイルごとで、ストレージの範囲と同じである。ファイルから持ち込んだプロファイルには別のブラウザのdevice IDが入っているので、カメラに登録し、`bind camera profile for [CAMERA_ID] to its current device`(`compatible`なものだけを結び付ける)を実行してから保存する。1台のカメラのために校正アプリを開くアプリは、クエリパラメータ`cameraDeviceId`・`cameraWidth`・`cameraHeight`・`cameraFrameRate`でカメラと使うサイズを指定し、`start shared camera [CAMERA_ID] requested by this page`がそのとおりに開始する。
251
+
246
252
  ## 互換性
247
253
 
254
+ 0.12.0ではデバイスで絞る復元、`bind camera profile ... to its current device`、`camera profile ... belongs to its current device?`、`start shared camera [CAMERA_ID] requested by this page`を追加した。既存のブロックとcapabilityのメンバーは変えていない。
255
+
248
256
  0.11.0では校正ファイルをROSの`camera_info` YAMLで読み書きするようにした。`camera profile YAML`を追加し、`register camera profile`はYAMLも受け取り、処理だけを持つ関数を`./profile`で公開した。既存のブロックとcapabilityのメンバーは変えていない。
249
257
 
250
258
  0.10.0では校正プロファイルのブラウザストレージと`register camera profile as`を追加した。既存のブロックとcapabilityのメンバーは変えていない。
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.11.0/dist/camera-source.js
33
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-camera-source@0.12.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.11.0
39
+ pnpm add @kubohiroya/turbowarp-camera-source@0.12.0
40
40
  ```
41
41
 
42
42
  ## Quick Start
@@ -69,6 +69,16 @@ Starts or keeps a named shared MediaDevices camera stream.
69
69
  | `CAMERA_ID` | String, default: `default` |
70
70
  | `DEVICE_ID` | String, default: `` |
71
71
 
72
+ ### `start shared camera [CAMERA_ID] requested by this page`
73
+
74
+ Starts the camera the page's query parameters name: `cameraDeviceId` exactly, and `cameraWidth`, `cameraHeight` and `cameraFrameRate` as ideal values. Without them it behaves like `start shared camera` with no device. An app with several USB cameras opens another app on the same origin, such as the lens calibration app, for one of them this way.
75
+
76
+ | Property | Value |
77
+ |---|---|
78
+ | Type | Command |
79
+ | Opcode | `startRequestedSharedCamera` |
80
+ | `CAMERA_ID` | String, default: `default` |
81
+
72
82
  ### `stop shared camera [CAMERA_ID]`
73
83
 
74
84
  Stops a named shared camera stream and releases its tracks.
@@ -367,6 +377,36 @@ Registers the newest saved profile that is `compatible` with the camera as confi
367
377
  | Opcode | `restoreStoredCameraProfile` |
368
378
  | `CAMERA_ID` | String, default: `default` |
369
379
 
380
+ ### `restore stored camera profile calibrated on the device of [CAMERA_ID]`
381
+
382
+ Like `restore stored camera profile`, but considers only profiles calibrated on the device this camera is running on now, so two cameras of the same model never receive each other's calibration. Device IDs are scoped to the origin and browser profile, as browser storage is. A camera that is not running gives `undetermined`; `none` says how many saved profiles belong to other devices.
383
+
384
+ | Property | Value |
385
+ |---|---|
386
+ | Type | Command |
387
+ | Opcode | `restoreStoredCameraProfileForDevice` |
388
+ | `CAMERA_ID` | String, default: `default` |
389
+
390
+ ### `bind camera profile for [CAMERA_ID] to its current device`
391
+
392
+ Records the device this camera is running on in its registered profile, for a profile the operator has assigned to this camera, such as one loaded from a file. Only a profile `compatible` with the camera as it is now is bound; otherwise nothing changes. Save the profile afterwards to keep the binding.
393
+
394
+ | Property | Value |
395
+ |---|---|
396
+ | Type | Command |
397
+ | Opcode | `bindCameraProfileToDevice` |
398
+ | `CAMERA_ID` | String, default: `default` |
399
+
400
+ ### `camera profile for [CAMERA_ID] belongs to its current device?`
401
+
402
+ Whether the registered profile was calibrated on, or bound to, the device this camera is running on now.
403
+
404
+ | Property | Value |
405
+ |---|---|
406
+ | Type | Boolean |
407
+ | Opcode | `cameraProfileOnDevice` |
408
+ | `CAMERA_ID` | String, default: `default` |
409
+
370
410
  ### `stored camera profile result for [CAMERA_ID]`
371
411
 
372
412
  Returns the outcome of the last save or restore for the camera ID, or an empty string before either has run.
@@ -597,8 +637,22 @@ camera is left as it was. The result is `restored`, `none`, `incompatible`, `und
597
637
  `register camera profile [PROFILE_JSON] as [CAMERA_ID]` does the same rebinding for a file: a profile
598
638
  solved under `default` in a calibration app can be registered as `pose` in the app that uses it.
599
639
 
640
+ **Two cameras of the same model.** They report the same label and the same capture conditions, so
641
+ each one's calibration is `compatible` with the other. `restore stored camera profile calibrated on
642
+ the device of [CAMERA_ID]` only considers profiles whose recorded device ID is the one the camera is
643
+ running on. Device IDs are scoped to the origin and browser profile, which is also where the storage
644
+ lives. A profile brought in from a file carries another browser's device ID: register it for the
645
+ camera, `bind camera profile for [CAMERA_ID] to its current device` (which binds only a `compatible`
646
+ profile), and save it. An app that opens the calibration app for one camera names that camera and the size it uses in the
647
+ `cameraDeviceId`, `cameraWidth`, `cameraHeight` and `cameraFrameRate` query parameters, and
648
+ `start shared camera [CAMERA_ID] requested by this page` starts it that way.
649
+
600
650
  ## Compatibility
601
651
 
652
+ Version 0.12.0 adds device-scoped restore, `bind camera profile ... to its current device`,
653
+ `camera profile ... belongs to its current device?` and `start shared camera [CAMERA_ID] requested by this page`.
654
+ No existing block or capability member changes.
655
+
602
656
  Version 0.11.0 writes and reads calibration files as ROS `camera_info` YAML: `camera profile YAML`
603
657
  is new, `register camera profile` also accepts YAML, and the pure functions are published under
604
658
  `./profile`. No existing block or capability member changes.
@@ -35,6 +35,15 @@
35
35
  }
36
36
  }
37
37
  },
38
+ {
39
+ "opcode": "startRequestedSharedCamera",
40
+ "blockType": "COMMAND",
41
+ "text": "start shared camera [CAMERA_ID] requested by this page",
42
+ "arguments": { "CAMERA_ID": {
43
+ "type": "STRING",
44
+ "defaultValue": "default"
45
+ } }
46
+ },
38
47
  {
39
48
  "opcode": "stopSharedCamera",
40
49
  "blockType": "COMMAND",
@@ -306,6 +315,33 @@
306
315
  "defaultValue": "default"
307
316
  } }
308
317
  },
318
+ {
319
+ "opcode": "restoreStoredCameraProfileForDevice",
320
+ "blockType": "COMMAND",
321
+ "text": "restore stored camera profile calibrated on the device of [CAMERA_ID]",
322
+ "arguments": { "CAMERA_ID": {
323
+ "type": "STRING",
324
+ "defaultValue": "default"
325
+ } }
326
+ },
327
+ {
328
+ "opcode": "bindCameraProfileToDevice",
329
+ "blockType": "COMMAND",
330
+ "text": "bind camera profile for [CAMERA_ID] to its current device",
331
+ "arguments": { "CAMERA_ID": {
332
+ "type": "STRING",
333
+ "defaultValue": "default"
334
+ } }
335
+ },
336
+ {
337
+ "opcode": "cameraProfileOnDevice",
338
+ "blockType": "BOOLEAN",
339
+ "text": "camera profile for [CAMERA_ID] belongs to its current device?",
340
+ "arguments": { "CAMERA_ID": {
341
+ "type": "STRING",
342
+ "defaultValue": "default"
343
+ } }
344
+ },
309
345
  {
310
346
  "opcode": "storedCameraProfileResult",
311
347
  "blockType": "REPORTER",
@@ -2212,6 +2248,38 @@
2212
2248
  function normalizeId(value, fallback = defaultCameraId) {
2213
2249
  return String(value ?? "").trim() || fallback;
2214
2250
  }
2251
+ /**
2252
+ * The camera a page was opened for, from its query parameters.
2253
+ *
2254
+ * Returns only what was named, so a page opened without parameters starts a camera exactly as the
2255
+ * plain block does. A size or rate that is not a positive number is ignored rather than guessed.
2256
+ */
2257
+ function requestedCamera(search) {
2258
+ let parameters;
2259
+ try {
2260
+ parameters = new URLSearchParams(search);
2261
+ } catch {
2262
+ return {};
2263
+ }
2264
+ const deviceId = optionalText(parameters.get("cameraDeviceId"));
2265
+ const video = {};
2266
+ if (deviceId) video.deviceId = { exact: deviceId };
2267
+ const ideal = (name) => {
2268
+ const value = Number(parameters.get(name) ?? "");
2269
+ return Number.isFinite(value) && value > 0 ? value : void 0;
2270
+ };
2271
+ const width = ideal("cameraWidth");
2272
+ const height = ideal("cameraHeight");
2273
+ const frameRate = ideal("cameraFrameRate");
2274
+ if (width !== void 0) video.width = { ideal: width };
2275
+ if (height !== void 0) video.height = { ideal: height };
2276
+ if (frameRate !== void 0) video.frameRate = { ideal: frameRate };
2277
+ if (Object.keys(video).length === 0) return {};
2278
+ return {
2279
+ ...deviceId ? { deviceId } : {},
2280
+ video
2281
+ };
2282
+ }
2215
2283
  function optionalText(value) {
2216
2284
  return String(value ?? "").trim();
2217
2285
  }
@@ -2556,7 +2624,77 @@
2556
2624
  * so trying a candidate that loses never displaces the registered one even for a moment.
2557
2625
  */
2558
2626
  async restoreStoredCameraProfile(args = {}) {
2627
+ await this.restoreStoredProfile(normalizeId(args.CAMERA_ID), false);
2628
+ }
2629
+ /**
2630
+ * Like `restore stored camera profile`, but only from profiles calibrated on the device the camera
2631
+ * is running on now.
2632
+ *
2633
+ * Compatibility alone cannot tell two cameras of the same model apart: they report the same label
2634
+ * and the same capture conditions, so either one's calibration reads as `compatible` for the other.
2635
+ * What differs is the device id, which is scoped to this origin and browser profile. That scope is
2636
+ * exactly where browser storage lives, so a profile saved here and a camera opened here agree on it
2637
+ * for as long as the browser keeps both.
2638
+ *
2639
+ * A camera that is not running has no device id, and the answer is then `undetermined`. A profile
2640
+ * brought in from another browser carries another id and is never a candidate; register it with
2641
+ * the file and `bind camera profile ... to its current device` first.
2642
+ */
2643
+ async restoreStoredCameraProfileForDevice(args = {}) {
2644
+ await this.restoreStoredProfile(normalizeId(args.CAMERA_ID), true);
2645
+ }
2646
+ /**
2647
+ * Records the device the camera is running on in its registered profile.
2648
+ *
2649
+ * For the case where the operator has said which camera a profile belongs to, typically by loading
2650
+ * a file for it. Only a profile `compatible` with the camera as it is now is bound: a profile that
2651
+ * does not fit is not made more trustworthy by naming a device in it. A label the camera reports is
2652
+ * written too when the profile has none; one it already has has been compared and matched.
2653
+ */
2654
+ bindCameraProfileToDevice(args = {}) {
2559
2655
  const cameraId = normalizeId(args.CAMERA_ID);
2656
+ const profile = this.profiles.get(cameraId);
2657
+ if (!profile) return;
2658
+ const conditions = this.conditionsOf(cameraId);
2659
+ if (conditions.deviceId.length === 0) return;
2660
+ if (evaluateProfileCompatibility(profile, conditions).state !== "compatible") return;
2661
+ const document = JSON.parse(serializeCameraIntrinsicProfile(profile));
2662
+ const label = profile.device?.label ?? conditions.label;
2663
+ document["device"] = {
2664
+ ...label === void 0 ? {} : { label },
2665
+ deviceId: conditions.deviceId
2666
+ };
2667
+ this.profiles.register(document);
2668
+ }
2669
+ /** Whether the registered profile was calibrated on, or bound to, the device the camera runs on. */
2670
+ cameraProfileOnDevice(args = {}) {
2671
+ const cameraId = normalizeId(args.CAMERA_ID);
2672
+ const deviceId = this.profiles.get(cameraId)?.device?.deviceId;
2673
+ return deviceId !== void 0 && deviceId.length > 0 && deviceId === this.conditionsOf(cameraId).deviceId;
2674
+ }
2675
+ /**
2676
+ * Starts a camera the way the page's query parameters ask, or as `start shared camera` does when
2677
+ * they ask nothing.
2678
+ *
2679
+ * How one app hands a camera to another it opens on the same origin. An app running several USB
2680
+ * cameras opens the lens calibration app for one of them, and the calibration has to be solved on
2681
+ * that device at the size the app will use: a camera the browser picks may be the other camera of
2682
+ * the same model, and a profile solved at another size is `incompatible`.
2683
+ *
2684
+ * `cameraDeviceId` is required exactly. `cameraWidth`, `cameraHeight` and `cameraFrameRate` are
2685
+ * asked for as `ideal`, the way the opening app asked, so the camera settles on the same mode.
2686
+ */
2687
+ async startRequestedSharedCamera(args = {}) {
2688
+ const cameraId = normalizeId(args.CAMERA_ID);
2689
+ if (this.blockLeases.has(cameraId)) return;
2690
+ const lease = await this.acquireCamera({
2691
+ owner: "camera-source-block",
2692
+ cameraId,
2693
+ ...requestedCamera(globalThis.location?.search ?? "")
2694
+ });
2695
+ this.blockLeases.set(cameraId, lease);
2696
+ }
2697
+ async restoreStoredProfile(cameraId, sameDevice) {
2560
2698
  let records;
2561
2699
  try {
2562
2700
  records = await this.profileStore.list();
@@ -2568,14 +2706,26 @@
2568
2706
  return;
2569
2707
  }
2570
2708
  const conditions = this.conditionsOf(cameraId);
2709
+ if (sameDevice && conditions.deviceId.length === 0) {
2710
+ this.storedProfileOutcomes.set(cameraId, {
2711
+ state: "undetermined",
2712
+ detail: "The camera is not running, so the device a saved profile was calibrated on cannot be compared."
2713
+ });
2714
+ return;
2715
+ }
2571
2716
  let incompatible;
2572
2717
  let undetermined;
2718
+ let otherDevices = 0;
2573
2719
  for (const record of [...records].sort(newestFirst)) {
2574
2720
  const parsed = parseJson(record.document);
2575
2721
  if (!parsed.ok) continue;
2576
2722
  const document = rebindCameraId(parsed.value, cameraId);
2577
2723
  const result = readCameraProfileDocument(document);
2578
2724
  if (!result.ok) continue;
2725
+ if (sameDevice && result.profile.device?.deviceId !== conditions.deviceId) {
2726
+ otherDevices += 1;
2727
+ continue;
2728
+ }
2579
2729
  const report = evaluateProfileCompatibility(result.profile, conditions);
2580
2730
  if (report.state === "compatible") {
2581
2731
  this.profiles.register(document);
@@ -2591,7 +2741,7 @@
2591
2741
  const decisive = incompatible ?? undetermined;
2592
2742
  this.storedProfileOutcomes.set(cameraId, decisive === void 0 ? {
2593
2743
  state: "none",
2594
- detail: ""
2744
+ detail: otherDevices === 0 ? "" : `${otherDevices} saved profile(s) were calibrated on other devices and were not considered.`
2595
2745
  } : {
2596
2746
  state: decisive.state,
2597
2747
  detail: compatibilityDetail(decisive)
@@ -2,6 +2,16 @@
2
2
  "formatVersion": 1,
3
3
  "id": "kubohiroyacamerasource",
4
4
  "blocks": [
5
+ {
6
+ "opcode": "bindCameraProfileToDevice",
7
+ "blockType": "COMMAND",
8
+ "arguments": [
9
+ {
10
+ "id": "CAMERA_ID",
11
+ "type": "STRING"
12
+ }
13
+ ]
14
+ },
5
15
  {
6
16
  "opcode": "cameraConditionsGeneration",
7
17
  "blockType": "REPORTER",
@@ -167,6 +177,16 @@
167
177
  }
168
178
  ]
169
179
  },
180
+ {
181
+ "opcode": "cameraProfileOnDevice",
182
+ "blockType": "BOOLEAN",
183
+ "arguments": [
184
+ {
185
+ "id": "CAMERA_ID",
186
+ "type": "STRING"
187
+ }
188
+ ]
189
+ },
170
190
  {
171
191
  "opcode": "cameraProfileRegistered",
172
192
  "blockType": "BOOLEAN",
@@ -256,6 +276,16 @@
256
276
  }
257
277
  ]
258
278
  },
279
+ {
280
+ "opcode": "restoreStoredCameraProfileForDevice",
281
+ "blockType": "COMMAND",
282
+ "arguments": [
283
+ {
284
+ "id": "CAMERA_ID",
285
+ "type": "STRING"
286
+ }
287
+ ]
288
+ },
259
289
  {
260
290
  "opcode": "saveCameraProfile",
261
291
  "blockType": "COMMAND",
@@ -281,6 +311,16 @@
281
311
  }
282
312
  ]
283
313
  },
314
+ {
315
+ "opcode": "startRequestedSharedCamera",
316
+ "blockType": "COMMAND",
317
+ "arguments": [
318
+ {
319
+ "id": "CAMERA_ID",
320
+ "type": "STRING"
321
+ }
322
+ ]
323
+ },
284
324
  {
285
325
  "opcode": "startSharedCamera",
286
326
  "blockType": "COMMAND",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/turbowarp-camera-source",
3
- "version": "0.11.0",
3
+ "version": "0.12.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",