@kubohiroya/turbowarp-camera-source 0.10.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 +74 -4
- package/README.md +148 -4
- package/dist/calibration/camera-info.d.ts +32 -0
- package/dist/calibration/camera-info.d.ts.map +1 -0
- package/dist/calibration/camera-info.js +336 -0
- package/dist/calibration/camera-info.js.map +1 -0
- package/dist/calibration/profile-text.d.ts +10 -0
- package/dist/calibration/profile-text.d.ts.map +1 -0
- package/dist/calibration/profile-text.js +25 -0
- package/dist/calibration/profile-text.js.map +1 -0
- package/dist/calibration/profile.d.ts +47 -0
- package/dist/calibration/profile.d.ts.map +1 -0
- package/dist/calibration/profile.js +479 -0
- package/dist/calibration/profile.js.map +1 -0
- package/dist/calibration/yaml.d.ts +21 -0
- package/dist/calibration/yaml.d.ts.map +1 -0
- package/dist/calibration/yaml.js +441 -0
- package/dist/calibration/yaml.js.map +1 -0
- package/dist/camera-source.js +967 -10
- package/dist/extension-manifest.json +50 -0
- package/dist/profile.d.ts +21 -0
- package/dist/profile.d.ts.map +1 -0
- package/dist/profile.js +18 -0
- package/dist/profile.js.map +1 -0
- package/package.json +5 -1
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.
|
|
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.
|
|
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`: 直近の開始失敗コードを返します。開始成功後は空文字列です。
|
|
@@ -69,11 +70,12 @@ stop shared camera [pose]
|
|
|
69
70
|
- `camera device count`: 更新済みカメラデバイス数を返します。
|
|
70
71
|
- `camera device ID at [INDEX]`: 1始まりの位置でカメラdevice IDを返します。
|
|
71
72
|
- `camera device label at [INDEX]`: 1始まりの位置でカメララベルを返します。
|
|
72
|
-
- `register camera profile [PROFILE_JSON]`:
|
|
73
|
+
- `register camera profile [PROFILE_JSON]`: 内部校正プロファイルを検証して登録します。校正アプリが書き出すROSの`camera_info` YAML(`turbowarp_camera_source`の項目付き)と、`twcs/camera-intrinsics`のJSON、旧`twrmc/camera-calibration`のJSONを受け取ります。
|
|
73
74
|
- `register camera profile [PROFILE_JSON] as [CAMERA_ID]`: 文書が持つcamera IDを指定したIDへ置き換えてから検証し、登録します。校正アプリで`default`として解いたプロファイルを`pose`として使う場合などに使います。camera profile errorの扱いは通常の登録ブロックと同じです。
|
|
74
75
|
- `forget camera profile for [CAMERA_ID]`: 登録済みプロファイルを破棄します。
|
|
75
76
|
- `camera [CAMERA_ID] is calibrated?`: プロファイルが登録されているかを返します。未登録は正常な状態です。
|
|
76
|
-
- `camera profile JSON for [CAMERA_ID]`:
|
|
77
|
+
- `camera profile JSON for [CAMERA_ID]`: 登録された文書を`twcs/camera-intrinsics`のJSONで返します。表示や保存用であって、投影に使う数値ではありません。ファイルとして渡すには`camera profile YAML`を使います。
|
|
78
|
+
- `camera profile YAML for [CAMERA_ID]`: 登録された文書をROSの`camera_info` YAMLで返します。ファイルへの書き出しやQRコードにはこの形を使います。標準の部分はROSやOpenCV系のツールがそのまま読み、`turbowarp_camera_source`の項目に適合判定に要る校正日時と撮影条件が入ります。
|
|
77
79
|
- `camera profile error`: 直近の登録失敗のコードを返します。成功後は空文字列です。
|
|
78
80
|
- `camera profile error detail`: 直近の登録失敗の位置と理由を返します。
|
|
79
81
|
- `camera profile compatibility for [CAMERA_ID]`: `compatible`/`incompatible`/`undetermined`を返します。
|
|
@@ -84,6 +86,9 @@ stop shared camera [pose]
|
|
|
84
86
|
- `camera conditions generation for [CAMERA_ID]`: 幾何に影響する条件が変わるたびに増える整数を返します。frame rateでは動きません。
|
|
85
87
|
- `save camera profile for [CAMERA_ID] to browser storage`: そのカメラに登録済みのプロファイルを、このoriginのブラウザストレージ(IndexedDB)へ保存し、同じoriginの他ウィンドウへ通知します。書き込み完了まで待ちます。結果は`saved`/`no-profile`/`unavailable`です。
|
|
86
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?`: 登録済みプロファイルが、このカメラが今動いているデバイスで校正された、または結び付けられたものかを返します。
|
|
87
92
|
- `stored camera profile result for [CAMERA_ID]`: そのcamera IDで直近に行った保存または復元の結果を返します。未実行なら空文字列です。
|
|
88
93
|
- `stored camera profile detail for [CAMERA_ID]`: 直近の保存・復元の説明を返します。保存・復元したプロファイル、またはどの保存済みプロファイルもカメラに適合しない理由です。
|
|
89
94
|
- `stored camera profiles generation`: このウィンドウまたは同じoriginの他ウィンドウでプロファイルが保存されるたびに増えるカウンタです。プロジェクトを読み込んでも戻りません。
|
|
@@ -167,6 +172,65 @@ import type {CameraFrameSource, CameraLease} from "@kubohiroya/turbowarp-camera-
|
|
|
167
172
|
|
|
168
173
|
**「判定できない」は「適合する」とは別の答え。** 適合性は`compatible`/`incompatible`/`undetermined`の3値で、不明が`compatible`へ格上げされることはない。プロファイルが現在の構成に適合していない限り内部行列は渡さない。渡してしまえば、利用側は別の構成の数値で投影し、**もっともらしく間違った幾何**を得ることになる。
|
|
169
174
|
|
|
175
|
+
### 校正ファイル
|
|
176
|
+
|
|
177
|
+
PCの外へ出る校正(ファイルやQRコード)は、ROSの`camera_info` YAMLで書く。ROSの`camera_calibration_parsers`が読み書きする形式で、OpenCV系の処理、ROS/ROS 2のドライバ、SLAMツールがそのまま読める。`camera profile YAML for [CAMERA_ID]`は登録済みのプロファイルをこの形で返し、`register camera profile`はプロファイルJSONと同じようにこれを読む。
|
|
178
|
+
|
|
179
|
+
```yaml
|
|
180
|
+
image_width: 1280
|
|
181
|
+
image_height: 720
|
|
182
|
+
camera_name: stage-left
|
|
183
|
+
camera_matrix:
|
|
184
|
+
rows: 3
|
|
185
|
+
cols: 3
|
|
186
|
+
data: [940.25, 0, 639.5, 0, 939.5, 359.5, 0, 0, 1]
|
|
187
|
+
distortion_model: plumb_bob
|
|
188
|
+
distortion_coefficients:
|
|
189
|
+
rows: 1
|
|
190
|
+
cols: 5
|
|
191
|
+
data: [-0.32, 0.11, 0.0002, -0.0003, -0.018]
|
|
192
|
+
rectification_matrix:
|
|
193
|
+
rows: 3
|
|
194
|
+
cols: 3
|
|
195
|
+
data: [1, 0, 0, 0, 1, 0, 0, 0, 1]
|
|
196
|
+
projection_matrix:
|
|
197
|
+
rows: 3
|
|
198
|
+
cols: 4
|
|
199
|
+
data: [940.25, 0, 639.5, 0, 0, 939.5, 359.5, 0, 0, 0, 1, 0]
|
|
200
|
+
turbowarp_camera_source:
|
|
201
|
+
schema: "twcs/camera-intrinsics"
|
|
202
|
+
version: 1
|
|
203
|
+
profileId: "run-2026-09-15-a"
|
|
204
|
+
calibratedAt: "2026-09-15T04:05:06Z"
|
|
205
|
+
producer: "chessboard calibration"
|
|
206
|
+
undistorted: false
|
|
207
|
+
capture:
|
|
208
|
+
resizeMode: "none"
|
|
209
|
+
zoom: 1
|
|
210
|
+
focusMode: "manual"
|
|
211
|
+
quality:
|
|
212
|
+
sampleCount: 24
|
|
213
|
+
reprojectionErrorPx: 0.28
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
**標準の部分はROSのキーと形そのままである。** 歪みモデルは、`brown-conrady`の5係数(4係数は`k3 = 0`を足して書く)⇔`plumb_bob`、8係数⇔`rational_polynomial`、`kannala-brandt`⇔`equidistant`と対応する。ROSには「歪みなし」のモデルが無いので、歪みの無い画像は5つの0の`plumb_bob`で書き、読むと`none`に戻る。
|
|
217
|
+
|
|
218
|
+
**ROSに置き場の無い情報は`turbowarp_camera_source`の下に入れる。** 校正日時、どの校正か、適合判定に使う撮影条件は、プロファイルがまだ使えるかを決めるのに要る。項目名はプロファイルのもので、撮影条件は`MediaTrackSettings`の名前である。ROSの読み込み処理はキーを名前で引くだけでこの項目を見ないので、ファイルはROSでもそのまま読める。この項目の無い素のROSファイルは`missing-field`で拒否する。校正日時を捏造すれば「分からない」が記録に化けるからである。
|
|
219
|
+
|
|
220
|
+
**読み込みはJSONと同じくfail closedである。** ほかのトップレベルのキー、単位行列でない平行化行列(ステレオの組のもの)、ビニングや切り出した関心領域、固定値の違う内部行列、ROSが定めていない係数の数は、該当する項目を示して拒否する。値そのものはJSONと同じ検証器を通る。読めるYAMLはyaml-cppとPyYAMLが書くもの(ブロックとフローのコレクション、引用符、コメント)で、アンカー、エイリアス、タグ、ブロックスカラー、複数文書は推測せずに拒否する。
|
|
221
|
+
|
|
222
|
+
同じ規則を、TurboWarpの外のコード(校正アプリが書いたファイルを確かめるテストなど)のために関数として公開している。
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
import {
|
|
226
|
+
readProfileText,
|
|
227
|
+
readCameraProfileDocument,
|
|
228
|
+
serializeCameraInfoYaml,
|
|
229
|
+
evaluateProfileCompatibility,
|
|
230
|
+
readCameraConditions
|
|
231
|
+
} from "@kubohiroya/turbowarp-camera-source/profile";
|
|
232
|
+
```
|
|
233
|
+
|
|
170
234
|
### ブラウザストレージ
|
|
171
235
|
|
|
172
236
|
プロファイルはブラウザ内に保持でき、次の作業や別ウィンドウでファイルを読み直さずに済む。`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の別ウィンドウでも保存のたびに増えるので、別ウィンドウの校正アプリを待つ作品はこの整数だけを見て、動いたら復元すればよい。
|
|
@@ -183,8 +247,14 @@ if <(stored camera profile result for [pose]) = [restored]> then
|
|
|
183
247
|
|
|
184
248
|
`register camera profile [PROFILE_JSON] as [CAMERA_ID]`はファイルに対して同じ付け替えを行う。校正アプリで`default`として解いたプロファイルを、利用側の作品で`pose`として登録できる。
|
|
185
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
|
+
|
|
186
252
|
## 互換性
|
|
187
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
|
+
|
|
256
|
+
0.11.0では校正ファイルをROSの`camera_info` YAMLで読み書きするようにした。`camera profile YAML`を追加し、`register camera profile`はYAMLも受け取り、処理だけを持つ関数を`./profile`で公開した。既存のブロックとcapabilityのメンバーは変えていない。
|
|
257
|
+
|
|
188
258
|
0.10.0では校正プロファイルのブラウザストレージと`register camera profile as`を追加した。既存のブロックとcapabilityのメンバーは変えていない。
|
|
189
259
|
|
|
190
260
|
未リリースの変更は破壊的である。`CameraFrameSource.mirrored`は`previewFlip`へ置き換えた。軸を名指しでき、かつ「描画の話であって画素の話ではない」と言えるためである。previewブロックの`MIRRORED`引数は`PREVIEW_FLIP`へ置き換え、booleanはもう読まない。`acquireCamera`は`previewFlip`を受け取り、`mirrored`は受け付けない。frame sourceのinterfaceを手書きで持っている利用側は、公開した`./runtime`のimportへ移ること。そうしていればこの変更はビルド時に分かった。
|
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.
|
|
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.
|
|
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.
|
|
@@ -210,7 +220,7 @@ Returns the one-based camera device label at the requested index when the browse
|
|
|
210
220
|
|
|
211
221
|
### `register camera profile [PROFILE_JSON]`
|
|
212
222
|
|
|
213
|
-
Validates a twcs/camera-intrinsics version 1
|
|
223
|
+
Validates a calibration and stores it against the camera it names. Accepts a ROS camera_info YAML file carrying the turbowarp_camera_source mapping, as the calibration app writes it, as well as twcs/camera-intrinsics version 1 JSON and the legacy twrmc/camera-calibration JSON. Nothing is stored unless the whole document passes, and the profile in force for that camera is replaced.
|
|
214
224
|
|
|
215
225
|
| Property | Value |
|
|
216
226
|
|---|---|
|
|
@@ -251,7 +261,7 @@ Reports whether a calibration profile is stored for the camera. An uncalibrated
|
|
|
251
261
|
|
|
252
262
|
### `camera profile JSON for [CAMERA_ID]`
|
|
253
263
|
|
|
254
|
-
Returns the stored profile as JSON, or an empty string when the camera has none.
|
|
264
|
+
Returns the stored profile as twcs/camera-intrinsics JSON, or an empty string when the camera has none. For a file to hand to another machine or tool, use camera profile YAML.
|
|
255
265
|
|
|
256
266
|
| Property | Value |
|
|
257
267
|
|---|---|
|
|
@@ -259,6 +269,16 @@ Returns the stored profile as JSON, or an empty string when the camera has none.
|
|
|
259
269
|
| Opcode | `cameraProfileJson` |
|
|
260
270
|
| `CAMERA_ID` | String, default: `default` |
|
|
261
271
|
|
|
272
|
+
### `camera profile YAML for [CAMERA_ID]`
|
|
273
|
+
|
|
274
|
+
Returns the stored profile as a ROS camera_info YAML document, or an empty string when the camera has none. This is the form to write to a file or show as a QR code: ROS and OpenCV-based tools read the standard part as it is, and the turbowarp_camera_source mapping carries the calibration time and camera settings compatibility needs.
|
|
275
|
+
|
|
276
|
+
| Property | Value |
|
|
277
|
+
|---|---|
|
|
278
|
+
| Type | Reporter |
|
|
279
|
+
| Opcode | `cameraProfileYaml` |
|
|
280
|
+
| `CAMERA_ID` | String, default: `default` |
|
|
281
|
+
|
|
262
282
|
### `camera profile error`
|
|
263
283
|
|
|
264
284
|
Returns the code of the last rejected profile document, or an empty string when the last one was accepted.
|
|
@@ -357,6 +377,36 @@ Registers the newest saved profile that is `compatible` with the camera as confi
|
|
|
357
377
|
| Opcode | `restoreStoredCameraProfile` |
|
|
358
378
|
| `CAMERA_ID` | String, default: `default` |
|
|
359
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
|
+
|
|
360
410
|
### `stored camera profile result for [CAMERA_ID]`
|
|
361
411
|
|
|
362
412
|
Returns the outcome of the last save or restore for the camera ID, or an empty string before either has run.
|
|
@@ -481,6 +531,82 @@ own repository and fails in a browser instead.
|
|
|
481
531
|
|
|
482
532
|
**"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.
|
|
483
533
|
|
|
534
|
+
### Calibration files
|
|
535
|
+
|
|
536
|
+
A calibration that leaves the PC — a file, or a QR code — is a ROS `camera_info` YAML document, the
|
|
537
|
+
format ROS's `camera_calibration_parsers` reads and writes and that OpenCV-based pipelines, ROS and
|
|
538
|
+
ROS 2 drivers and SLAM tools load as it is. `camera profile YAML for [CAMERA_ID]` renders the
|
|
539
|
+
registered profile that way, and `register camera profile` reads it back as well as profile JSON.
|
|
540
|
+
|
|
541
|
+
```yaml
|
|
542
|
+
image_width: 1280
|
|
543
|
+
image_height: 720
|
|
544
|
+
camera_name: stage-left
|
|
545
|
+
camera_matrix:
|
|
546
|
+
rows: 3
|
|
547
|
+
cols: 3
|
|
548
|
+
data: [940.25, 0, 639.5, 0, 939.5, 359.5, 0, 0, 1]
|
|
549
|
+
distortion_model: plumb_bob
|
|
550
|
+
distortion_coefficients:
|
|
551
|
+
rows: 1
|
|
552
|
+
cols: 5
|
|
553
|
+
data: [-0.32, 0.11, 0.0002, -0.0003, -0.018]
|
|
554
|
+
rectification_matrix:
|
|
555
|
+
rows: 3
|
|
556
|
+
cols: 3
|
|
557
|
+
data: [1, 0, 0, 0, 1, 0, 0, 0, 1]
|
|
558
|
+
projection_matrix:
|
|
559
|
+
rows: 3
|
|
560
|
+
cols: 4
|
|
561
|
+
data: [940.25, 0, 639.5, 0, 0, 939.5, 359.5, 0, 0, 0, 1, 0]
|
|
562
|
+
turbowarp_camera_source:
|
|
563
|
+
schema: "twcs/camera-intrinsics"
|
|
564
|
+
version: 1
|
|
565
|
+
profileId: "run-2026-09-15-a"
|
|
566
|
+
calibratedAt: "2026-09-15T04:05:06Z"
|
|
567
|
+
producer: "chessboard calibration"
|
|
568
|
+
undistorted: false
|
|
569
|
+
capture:
|
|
570
|
+
resizeMode: "none"
|
|
571
|
+
zoom: 1
|
|
572
|
+
focusMode: "manual"
|
|
573
|
+
quality:
|
|
574
|
+
sampleCount: 24
|
|
575
|
+
reprojectionErrorPx: 0.28
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
**The standard part is ROS's, key for key.** Distortion models map as `brown-conrady` with five
|
|
579
|
+
coefficients (four are written with `k3 = 0`) ⇔ `plumb_bob`, eight ⇔ `rational_polynomial`, and
|
|
580
|
+
`kannala-brandt` ⇔ `equidistant`. A lens-free image is `plumb_bob` with five zeros, since ROS has no
|
|
581
|
+
model for none, and reads back as `none`.
|
|
582
|
+
|
|
583
|
+
**What ROS has no place for travels under `turbowarp_camera_source`.** When the camera was
|
|
584
|
+
calibrated, which run it was, and the capture settings compatibility is decided on are required to
|
|
585
|
+
tell whether a profile still fits; their member names are the profile's, and the capture members
|
|
586
|
+
are `MediaTrackSettings` names. ROS's reader looks keys up by name and ignores this one, so the file
|
|
587
|
+
still loads in ROS. A plain ROS file without it is refused with `missing-field`: inventing a
|
|
588
|
+
calibration time would turn "unknown" into a record.
|
|
589
|
+
|
|
590
|
+
**Reading fails closed, like JSON.** Other top-level keys, a rectification other than identity (a
|
|
591
|
+
stereo pair's), binning or a cropped region of interest, a calibration matrix whose fixed entries are
|
|
592
|
+
wrong, and a coefficient count ROS does not define are refused with the member that failed. The
|
|
593
|
+
values themselves then go through the same validator as JSON. The reader takes the YAML that
|
|
594
|
+
yaml-cpp and PyYAML write — block and flow collections, quotes, comments — and refuses anchors,
|
|
595
|
+
aliases, tags, block scalars and multiple documents rather than guessing.
|
|
596
|
+
|
|
597
|
+
The same rules are published as plain functions for code outside TurboWarp, such as a test that checks
|
|
598
|
+
a file a calibration app wrote:
|
|
599
|
+
|
|
600
|
+
```ts
|
|
601
|
+
import {
|
|
602
|
+
readProfileText,
|
|
603
|
+
readCameraProfileDocument,
|
|
604
|
+
serializeCameraInfoYaml,
|
|
605
|
+
evaluateProfileCompatibility,
|
|
606
|
+
readCameraConditions
|
|
607
|
+
} from "@kubohiroya/turbowarp-camera-source/profile";
|
|
608
|
+
```
|
|
609
|
+
|
|
484
610
|
### Browser storage
|
|
485
611
|
|
|
486
612
|
A profile can be kept in the browser so the next session, or another window, does not need the file
|
|
@@ -511,8 +637,26 @@ camera is left as it was. The result is `restored`, `none`, `incompatible`, `und
|
|
|
511
637
|
`register camera profile [PROFILE_JSON] as [CAMERA_ID]` does the same rebinding for a file: a profile
|
|
512
638
|
solved under `default` in a calibration app can be registered as `pose` in the app that uses it.
|
|
513
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
|
+
|
|
514
650
|
## Compatibility
|
|
515
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
|
+
|
|
656
|
+
Version 0.11.0 writes and reads calibration files as ROS `camera_info` YAML: `camera profile YAML`
|
|
657
|
+
is new, `register camera profile` also accepts YAML, and the pure functions are published under
|
|
658
|
+
`./profile`. No existing block or capability member changes.
|
|
659
|
+
|
|
516
660
|
Version 0.10.0 adds browser storage for calibration profiles and `register camera profile as`. No
|
|
517
661
|
existing block or capability member changes.
|
|
518
662
|
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { CameraIntrinsicProfileV1, ProfileError } from './types.js';
|
|
2
|
+
/** The top-level key holding the members ROS has no place for. */
|
|
3
|
+
export declare const CAMERA_INFO_EXTENSION_KEY = "turbowarp_camera_source";
|
|
4
|
+
export type CameraInfoReadResult = {
|
|
5
|
+
readonly ok: true;
|
|
6
|
+
readonly document: Record<string, unknown>;
|
|
7
|
+
} | {
|
|
8
|
+
readonly ok: false;
|
|
9
|
+
readonly error: ProfileError;
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* Renders a profile as a ROS `camera_info` YAML document.
|
|
13
|
+
*
|
|
14
|
+
* The layout follows what `camera_calibration_parsers` writes, key for key and in the same order, so
|
|
15
|
+
* the file reads like one ROS produced. The projection matrix is the calibration matrix with a zero
|
|
16
|
+
* fourth column, which is what a monocular camera with no rectification has; binning and region of
|
|
17
|
+
* interest are left out, as ROS treats them as optional.
|
|
18
|
+
*
|
|
19
|
+
* Strings in the extra mapping are always double-quoted. A timestamp left plain is read as a date
|
|
20
|
+
* by YAML 1.1 readers such as PyYAML, and an id made only of digits as a number.
|
|
21
|
+
*/
|
|
22
|
+
export declare function serializeCameraInfoYaml(profile: CameraIntrinsicProfileV1): string;
|
|
23
|
+
/**
|
|
24
|
+
* Turns a ROS `camera_info` YAML document into a profile document, ready to be validated.
|
|
25
|
+
*
|
|
26
|
+
* Only the shape ROS defines is checked here -- matrix sizes, the fixed entries of the calibration
|
|
27
|
+
* matrix, a rectification that does nothing, a distortion model ROS names. Everything the profile
|
|
28
|
+
* contract says about the values themselves is left to the profile validator, so there is one
|
|
29
|
+
* place that decides whether a calibration is acceptable.
|
|
30
|
+
*/
|
|
31
|
+
export declare function readCameraInfoYaml(text: string): CameraInfoReadResult;
|
|
32
|
+
//# sourceMappingURL=camera-info.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"camera-info.d.ts","sourceRoot":"","sources":["../../src/calibration/camera-info.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAC,wBAAwB,EAAmB,YAAY,EAAC,MAAM,YAAY,CAAC;AAGxF,kEAAkE;AAClE,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AA+BnE,MAAM,MAAM,oBAAoB,GAC5B;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAC,GAC/D;IAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;CAAC,CAAC;AAYvD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CA2CjF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAgBrE"}
|