@kubohiroya/turbowarp-camera-source 0.6.0 → 0.7.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.
@@ -17,6 +17,10 @@
17
17
  license: "MPL-2.0",
18
18
  unsandboxed: true
19
19
  };
20
+ //#endregion
21
+ //#region config/feature-flags.ts
22
+ var overrides = globalThis.__TWCS_FEATURE_FLAGS__;
23
+ var featureFlags = Object.freeze({ calibrationProfilesV1: overrides?.calibrationProfilesV1 === true });
20
24
  var block_definitions_default = {
21
25
  extensionName: "Camera Source",
22
26
  blocks: [
@@ -24,7 +28,6 @@
24
28
  "opcode": "startSharedCamera",
25
29
  "blockType": "COMMAND",
26
30
  "text": "start shared camera [CAMERA_ID] with device ID [DEVICE_ID]",
27
- "description": "Starts or keeps a named shared MediaDevices camera stream.",
28
31
  "arguments": {
29
32
  "CAMERA_ID": {
30
33
  "type": "STRING",
@@ -40,7 +43,6 @@
40
43
  "opcode": "stopSharedCamera",
41
44
  "blockType": "COMMAND",
42
45
  "text": "stop shared camera [CAMERA_ID]",
43
- "description": "Stops a named shared camera stream and releases its tracks.",
44
46
  "arguments": { "CAMERA_ID": {
45
47
  "type": "STRING",
46
48
  "defaultValue": "default"
@@ -50,7 +52,6 @@
50
52
  "opcode": "isCameraRunning",
51
53
  "blockType": "BOOLEAN",
52
54
  "text": "shared camera [CAMERA_ID] is running?",
53
- "description": "Reports whether a named shared camera stream is active.",
54
55
  "arguments": { "CAMERA_ID": {
55
56
  "type": "STRING",
56
57
  "defaultValue": "default"
@@ -60,7 +61,6 @@
60
61
  "opcode": "cameraErrorCode",
61
62
  "blockType": "REPORTER",
62
63
  "text": "shared camera [CAMERA_ID] error code",
63
- "description": "Returns the latest camera failure code, or an empty string after a successful start.",
64
64
  "arguments": { "CAMERA_ID": {
65
65
  "type": "STRING",
66
66
  "defaultValue": "default"
@@ -70,7 +70,6 @@
70
70
  "opcode": "cameraError",
71
71
  "blockType": "REPORTER",
72
72
  "text": "shared camera [CAMERA_ID] error",
73
- "description": "Returns the latest camera failure message, or an empty string after a successful start.",
74
73
  "arguments": { "CAMERA_ID": {
75
74
  "type": "STRING",
76
75
  "defaultValue": "default"
@@ -80,7 +79,6 @@
80
79
  "opcode": "cameraDeviceIdReporter",
81
80
  "blockType": "REPORTER",
82
81
  "text": "shared camera [CAMERA_ID] device ID",
83
- "description": "Returns the active device ID for a named shared camera when available.",
84
82
  "arguments": { "CAMERA_ID": {
85
83
  "type": "STRING",
86
84
  "defaultValue": "default"
@@ -89,16 +87,16 @@
89
87
  {
90
88
  "opcode": "showCameraPreview",
91
89
  "blockType": "COMMAND",
92
- "text": "show shared camera [CAMERA_ID] preview mirrored [MIRRORED]",
93
- "description": "Shows the named shared camera with the GPU-backed stage preview.",
90
+ "text": "show shared camera [CAMERA_ID] preview flipped [PREVIEW_FLIP]",
94
91
  "arguments": {
95
92
  "CAMERA_ID": {
96
93
  "type": "STRING",
97
94
  "defaultValue": "default"
98
95
  },
99
- "MIRRORED": {
96
+ "PREVIEW_FLIP": {
100
97
  "type": "STRING",
101
- "defaultValue": "true"
98
+ "defaultValue": "horizontal",
99
+ "menu": "flips"
102
100
  }
103
101
  }
104
102
  },
@@ -106,7 +104,6 @@
106
104
  "opcode": "hideCameraPreview",
107
105
  "blockType": "COMMAND",
108
106
  "text": "hide shared camera [CAMERA_ID] preview",
109
- "description": "Hides the block-owned preview without stopping leases owned by other consumers.",
110
107
  "arguments": { "CAMERA_ID": {
111
108
  "type": "STRING",
112
109
  "defaultValue": "default"
@@ -116,7 +113,6 @@
116
113
  "opcode": "cameraFrameWidth",
117
114
  "blockType": "REPORTER",
118
115
  "text": "shared camera [CAMERA_ID] frame width",
119
- "description": "Returns the active video frame width in pixels, or zero while the camera is not running.",
120
116
  "arguments": { "CAMERA_ID": {
121
117
  "type": "STRING",
122
118
  "defaultValue": "default"
@@ -126,7 +122,6 @@
126
122
  "opcode": "cameraFrameHeight",
127
123
  "blockType": "REPORTER",
128
124
  "text": "shared camera [CAMERA_ID] frame height",
129
- "description": "Returns the active video frame height in pixels, or zero while the camera is not running.",
130
125
  "arguments": { "CAMERA_ID": {
131
126
  "type": "STRING",
132
127
  "defaultValue": "default"
@@ -136,7 +131,6 @@
136
131
  "opcode": "cameraFrameRate",
137
132
  "blockType": "REPORTER",
138
133
  "text": "shared camera [CAMERA_ID] frame rate",
139
- "description": "Returns the active video track frame rate, or zero when it is unavailable.",
140
134
  "arguments": { "CAMERA_ID": {
141
135
  "type": "STRING",
142
136
  "defaultValue": "default"
@@ -146,21 +140,18 @@
146
140
  "opcode": "refreshCameraDevices",
147
141
  "blockType": "COMMAND",
148
142
  "text": "refresh camera devices",
149
- "description": "Refreshes the browser camera device list.",
150
143
  "arguments": {}
151
144
  },
152
145
  {
153
146
  "opcode": "cameraDeviceCount",
154
147
  "blockType": "REPORTER",
155
148
  "text": "camera device count",
156
- "description": "Returns the number of known camera devices after refresh.",
157
149
  "arguments": {}
158
150
  },
159
151
  {
160
152
  "opcode": "cameraDeviceIdAt",
161
153
  "blockType": "REPORTER",
162
154
  "text": "camera device ID at [INDEX]",
163
- "description": "Returns the one-based camera device ID at the requested index.",
164
155
  "arguments": { "INDEX": {
165
156
  "type": "STRING",
166
157
  "defaultValue": "1"
@@ -170,15 +161,937 @@
170
161
  "opcode": "cameraDeviceLabelAt",
171
162
  "blockType": "REPORTER",
172
163
  "text": "camera device label at [INDEX]",
173
- "description": "Returns the one-based camera device label at the requested index when the browser exposes it.",
174
164
  "arguments": { "INDEX": {
175
165
  "type": "STRING",
176
166
  "defaultValue": "1"
177
167
  } }
168
+ },
169
+ {
170
+ "opcode": "registerCameraProfile",
171
+ "feature": "calibrationProfilesV1",
172
+ "blockType": "COMMAND",
173
+ "text": "register camera profile [PROFILE_JSON]",
174
+ "arguments": { "PROFILE_JSON": {
175
+ "type": "STRING",
176
+ "defaultValue": "{}"
177
+ } }
178
+ },
179
+ {
180
+ "opcode": "forgetCameraProfile",
181
+ "feature": "calibrationProfilesV1",
182
+ "blockType": "COMMAND",
183
+ "text": "forget camera profile for [CAMERA_ID]",
184
+ "arguments": { "CAMERA_ID": {
185
+ "type": "STRING",
186
+ "defaultValue": "default"
187
+ } }
188
+ },
189
+ {
190
+ "opcode": "cameraProfileRegistered",
191
+ "feature": "calibrationProfilesV1",
192
+ "blockType": "BOOLEAN",
193
+ "text": "camera [CAMERA_ID] is calibrated?",
194
+ "arguments": { "CAMERA_ID": {
195
+ "type": "STRING",
196
+ "defaultValue": "default"
197
+ } }
198
+ },
199
+ {
200
+ "opcode": "cameraProfileJson",
201
+ "feature": "calibrationProfilesV1",
202
+ "blockType": "REPORTER",
203
+ "text": "camera profile JSON for [CAMERA_ID]",
204
+ "arguments": { "CAMERA_ID": {
205
+ "type": "STRING",
206
+ "defaultValue": "default"
207
+ } }
208
+ },
209
+ {
210
+ "opcode": "cameraProfileError",
211
+ "feature": "calibrationProfilesV1",
212
+ "blockType": "REPORTER",
213
+ "text": "camera profile error",
214
+ "arguments": {}
215
+ },
216
+ {
217
+ "opcode": "cameraProfileErrorDetail",
218
+ "feature": "calibrationProfilesV1",
219
+ "blockType": "REPORTER",
220
+ "text": "camera profile error detail",
221
+ "arguments": {}
222
+ },
223
+ {
224
+ "opcode": "cameraProfileCompatibility",
225
+ "feature": "calibrationProfilesV1",
226
+ "blockType": "REPORTER",
227
+ "text": "camera profile compatibility for [CAMERA_ID]",
228
+ "arguments": { "CAMERA_ID": {
229
+ "type": "STRING",
230
+ "defaultValue": "default"
231
+ } }
232
+ },
233
+ {
234
+ "opcode": "cameraProfileCompatibilityDetail",
235
+ "feature": "calibrationProfilesV1",
236
+ "blockType": "REPORTER",
237
+ "text": "camera profile compatibility detail for [CAMERA_ID]",
238
+ "arguments": { "CAMERA_ID": {
239
+ "type": "STRING",
240
+ "defaultValue": "default"
241
+ } }
242
+ },
243
+ {
244
+ "opcode": "cameraProfileAdaptation",
245
+ "feature": "calibrationProfilesV1",
246
+ "blockType": "REPORTER",
247
+ "text": "camera profile adaptation for [CAMERA_ID]",
248
+ "arguments": { "CAMERA_ID": {
249
+ "type": "STRING",
250
+ "defaultValue": "default"
251
+ } }
252
+ },
253
+ {
254
+ "opcode": "cameraProfileIntrinsicsJson",
255
+ "feature": "calibrationProfilesV1",
256
+ "blockType": "REPORTER",
257
+ "text": "camera intrinsics JSON for [CAMERA_ID]",
258
+ "arguments": { "CAMERA_ID": {
259
+ "type": "STRING",
260
+ "defaultValue": "default"
261
+ } }
262
+ },
263
+ {
264
+ "opcode": "cameraConditionsJson",
265
+ "feature": "calibrationProfilesV1",
266
+ "blockType": "REPORTER",
267
+ "text": "camera conditions JSON for [CAMERA_ID]",
268
+ "arguments": { "CAMERA_ID": {
269
+ "type": "STRING",
270
+ "defaultValue": "default"
271
+ } }
272
+ },
273
+ {
274
+ "opcode": "cameraConditionsGeneration",
275
+ "feature": "calibrationProfilesV1",
276
+ "blockType": "REPORTER",
277
+ "text": "camera conditions generation for [CAMERA_ID]",
278
+ "arguments": { "CAMERA_ID": {
279
+ "type": "STRING",
280
+ "defaultValue": "default"
281
+ } }
178
282
  }
179
- ]
283
+ ],
284
+ menus: { "flips": {
285
+ "acceptReporters": true,
286
+ "items": [
287
+ "none",
288
+ "horizontal",
289
+ "vertical",
290
+ "both"
291
+ ]
292
+ } }
293
+ };
294
+ //#endregion
295
+ //#region src/calibration/conditions.ts
296
+ function positiveNumber(value) {
297
+ return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
298
+ }
299
+ function nonNegativeNumber(value) {
300
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
301
+ }
302
+ function nonEmptyText(value) {
303
+ if (typeof value !== "string") return void 0;
304
+ const text = value.trim();
305
+ return text.length === 0 ? void 0 : text;
306
+ }
307
+ function pixelCount(value) {
308
+ return Number.isFinite(value) && value > 0 ? Math.round(value) : 0;
309
+ }
310
+ /**
311
+ * Builds the conditions record.
312
+ *
313
+ * Frame size comes from the delivered frame rather than from the track settings: a track can report
314
+ * a requested size that the browser then satisfies with something else, and the number a consumer
315
+ * has to match its intrinsics against is the size of the image it is actually handed.
316
+ */
317
+ function readCameraConditions(frame, settings = {}) {
318
+ const label = nonEmptyText(frame.label);
319
+ const frameRate = positiveNumber(settings.frameRate);
320
+ const facingMode = nonEmptyText(settings.facingMode);
321
+ const resizeMode = nonEmptyText(settings.resizeMode);
322
+ const zoom = positiveNumber(settings.zoom);
323
+ const focusMode = nonEmptyText(settings.focusMode);
324
+ const focusDistance = nonNegativeNumber(settings.focusDistance);
325
+ return {
326
+ width: pixelCount(frame.width),
327
+ height: pixelCount(frame.height),
328
+ deviceId: nonEmptyText(frame.deviceId) ?? nonEmptyText(settings.deviceId) ?? "",
329
+ previewFlip: frame.previewFlip,
330
+ ...label === void 0 ? {} : { label },
331
+ ...frameRate === void 0 ? {} : { frameRate },
332
+ ...facingMode === void 0 ? {} : { facingMode },
333
+ ...resizeMode === void 0 ? {} : { resizeMode },
334
+ ...zoom === void 0 ? {} : { zoom },
335
+ ...focusMode === void 0 ? {} : { focusMode },
336
+ ...focusDistance === void 0 ? {} : { focusDistance }
337
+ };
338
+ }
339
+ //#endregion
340
+ //#region src/calibration/compatibility.ts
341
+ /** Zoom readings are device-reported floats; compare them with a tolerance rather than exactly. */
342
+ var ZOOM_TOLERANCE = 1e-6;
343
+ var FOCUS_DISTANCE_TOLERANCE = 1e-6;
344
+ function finding(code, state, decisive, detail) {
345
+ return {
346
+ code,
347
+ state,
348
+ decisive,
349
+ detail
350
+ };
351
+ }
352
+ function describe(value) {
353
+ return value === void 0 ? "not reported" : String(value);
354
+ }
355
+ /**
356
+ * Compares one optical member.
357
+ *
358
+ * Absent on both sides is agreement, not ignorance: the device reported no such control when the
359
+ * calibration was solved and reports none now. Present on one side only is a change nobody can
360
+ * quantify, so it is left unknown rather than guessed in either direction.
361
+ */
362
+ function compareMember(code, name, recorded, observed, equal) {
363
+ if (recorded === void 0 && observed === void 0) return finding(code, "matched", true, `Neither the profile nor the camera reports ${name}.`);
364
+ if (recorded === void 0 || observed === void 0) return finding(code, "unknown", true, `${name} is ${describe(recorded)} in the profile and ${describe(observed)} now, so the two cannot be compared.`);
365
+ const same = equal(recorded, observed);
366
+ return finding(code, same ? "matched" : "mismatched", true, same ? `${name} is ${describe(observed)} in both.` : `${name} was ${describe(recorded)} at calibration and is ${describe(observed)} now.`);
367
+ }
368
+ var sameText = (left, right) => left === right;
369
+ var nearlyEqual = (tolerance) => (left, right) => Math.abs(left - right) <= tolerance;
370
+ function captureFindings(capture, conditions) {
371
+ return [
372
+ compareMember("resize-mode", "Resize mode", capture.resizeMode, conditions.resizeMode, sameText),
373
+ compareMember("zoom", "Zoom", capture.zoom, conditions.zoom, nearlyEqual(ZOOM_TOLERANCE)),
374
+ compareMember("focus-mode", "Focus mode", capture.focusMode, conditions.focusMode, sameText),
375
+ compareMember("focus-distance", "Focus distance", capture.focusDistance, conditions.focusDistance, nearlyEqual(FOCUS_DISTANCE_TOLERANCE))
376
+ ];
377
+ }
378
+ function imageSizeFinding(profile, conditions) {
379
+ const expected = `${profile.image.width}x${profile.image.height}`;
380
+ if (conditions.width === 0 || conditions.height === 0) return finding("image-size", "unknown", true, `The camera has delivered no frame yet, so its size cannot be compared with the calibrated ${expected}.`);
381
+ const actual = `${conditions.width}x${conditions.height}`;
382
+ return actual === expected ? finding("image-size", "matched", true, `The frame is ${actual}, as calibrated.`) : finding("image-size", "mismatched", true, `The calibration was solved at ${expected} and the camera now delivers ${actual}.`);
383
+ }
384
+ function deviceFindings(profile, conditions) {
385
+ const recordedLabel = profile.device?.label;
386
+ const observedLabel = conditions.label;
387
+ const label = recordedLabel !== void 0 && observedLabel !== void 0 ? finding("device-label", recordedLabel === observedLabel ? "matched" : "mismatched", true, recordedLabel === observedLabel ? `The camera still reports itself as ${observedLabel}.` : `The profile was solved on ${recordedLabel} and the camera now reports ${observedLabel}.`) : finding("device-label", "unknown", false, "A device label is missing on one side, which is normal before the browser grants camera permission.");
388
+ const recordedId = profile.device?.deviceId;
389
+ const observedId = conditions.deviceId.length === 0 ? void 0 : conditions.deviceId;
390
+ return [label, finding("device-id", recordedId !== void 0 && observedId !== void 0 && recordedId === observedId ? "matched" : "unknown", false, "A device id is scoped to one browser and profile, so it changes without the camera changing. It is a hint for ordering candidates, never proof of identity.")];
391
+ }
392
+ /**
393
+ * Judges a profile against the conditions a camera reports.
394
+ *
395
+ * The verdict is `incompatible` when any decisive finding mismatched, `undetermined` when any
396
+ * decisive finding could not be settled, and `compatible` only when every decisive finding matched.
397
+ * Unknown never resolves upward into `compatible`.
398
+ */
399
+ function evaluateProfileCompatibility(profile, conditions) {
400
+ const findings = [imageSizeFinding(profile, conditions)];
401
+ if (profile.image.undistorted) findings.push(finding("undistorted-frames", "unknown", true, "The profile describes already undistorted images. This extension hands over the camera frames as captured and cannot confirm that something upstream corrects them."));
402
+ if (profile.capture === void 0) findings.push(finding("capture-conditions", "unknown", true, "The profile records no capture conditions, so whether the optics are configured as they were at calibration cannot be decided."));
403
+ else findings.push(...captureFindings(profile.capture, conditions));
404
+ findings.push(finding("frame-rate", "matched", false, `Frame rate was ${describe(profile.capture?.frameRate)} at calibration and is ${describe(conditions.frameRate)} now. It does not change how the lens projects.`), finding("facing-mode", "matched", false, `Facing mode was ${describe(profile.capture?.facingMode)} at calibration and is ${describe(conditions.facingMode)} now.`), ...deviceFindings(profile, conditions));
405
+ const decisive = findings.filter((entry) => entry.decisive);
406
+ return {
407
+ state: decisive.some((entry) => entry.state === "mismatched") ? "incompatible" : decisive.some((entry) => entry.state === "unknown") ? "undetermined" : "compatible",
408
+ findings
409
+ };
410
+ }
411
+ /** The findings that decided the verdict, in the order they were made. */
412
+ function decisiveFindings(report) {
413
+ return report.findings.filter((entry) => entry.decisive && entry.state !== "matched");
414
+ }
415
+ //#endregion
416
+ //#region src/calibration/adaptation.ts
417
+ /** Aspect ratios are compared with a tolerance; reported sizes are whole pixels. */
418
+ var ASPECT_TOLERANCE = .001;
419
+ function adaptProfileToConditions(profile, conditions) {
420
+ const { width: calibratedWidth, height: calibratedHeight } = profile.image;
421
+ const { width, height } = conditions;
422
+ if (width === 0 || height === 0) return {
423
+ state: "unavailable",
424
+ code: "no-frame",
425
+ width,
426
+ height,
427
+ scale: 1,
428
+ detail: "The camera has delivered no frame yet, so there is no size to adapt to."
429
+ };
430
+ if (width === calibratedWidth && height === calibratedHeight) return {
431
+ state: "exact",
432
+ code: "exact",
433
+ intrinsics: profile.intrinsics,
434
+ width,
435
+ height,
436
+ scale: 1,
437
+ detail: `The frame is ${width}x${height}, as calibrated.`
438
+ };
439
+ if (profile.image.undistorted) return {
440
+ state: "unavailable",
441
+ code: "undistorted-frames",
442
+ width,
443
+ height,
444
+ scale: 1,
445
+ detail: "The profile describes already undistorted images, so it cannot be re-expressed for a different frame size here."
446
+ };
447
+ if (profile.capture?.resizeMode === "crop-and-scale") return {
448
+ state: "unavailable",
449
+ code: "cropped",
450
+ width,
451
+ height,
452
+ scale: 1,
453
+ detail: "The track was calibrated with crop-and-scale resizing, so a different frame size may be a crop rather than a scale and the principal point cannot be placed."
454
+ };
455
+ const scaleX = width / calibratedWidth;
456
+ const scaleY = height / calibratedHeight;
457
+ if (Math.abs(scaleX - scaleY) > ASPECT_TOLERANCE) return {
458
+ state: "unavailable",
459
+ code: "aspect-changed",
460
+ width,
461
+ height,
462
+ scale: 1,
463
+ detail: `The calibrated ${calibratedWidth}x${calibratedHeight} and the current ${width}x${height} have different aspect ratios, so the difference is not a scale.`
464
+ };
465
+ const scale = (scaleX + scaleY) / 2;
466
+ return {
467
+ state: "scaled",
468
+ code: "uniform-scale",
469
+ intrinsics: scaleIntrinsics(profile.intrinsics, scale),
470
+ width,
471
+ height,
472
+ scale,
473
+ detail: `The calibrated ${calibratedWidth}x${calibratedHeight} has been scaled by ${scale} to the current ${width}x${height}.`
474
+ };
475
+ }
476
+ function scaleIntrinsics(intrinsics, scale) {
477
+ return {
478
+ fx: intrinsics.fx * scale,
479
+ fy: intrinsics.fy * scale,
480
+ cx: intrinsics.cx * scale,
481
+ cy: intrinsics.cy * scale,
482
+ skew: intrinsics.skew
483
+ };
484
+ }
485
+ /**
486
+ * The intrinsics to use, if there are any.
487
+ *
488
+ * Both conditions have to hold, and they are different questions. Compatibility asks whether this
489
+ * profile describes this camera as it is configured now; adaptation asks whether the numbers can be
490
+ * expressed for the frame size in front of us. A profile can fit the camera and still have no usable
491
+ * form — a crop, say — and it can adapt cleanly while belonging to a different camera entirely.
492
+ *
493
+ * Returning undefined rather than the stored numbers is the whole point. Intrinsics from another
494
+ * configuration do not fail visibly: they project, and the geometry that comes back looks like a
495
+ * slightly different camera pose rather than like a mistake.
496
+ */
497
+ function usableIntrinsics(compatibility, adaptation) {
498
+ if (compatibility.state !== "compatible") return void 0;
499
+ if (adaptation.intrinsics === void 0) return void 0;
500
+ return {
501
+ ...adaptation.intrinsics,
502
+ width: adaptation.width,
503
+ height: adaptation.height,
504
+ scale: adaptation.scale,
505
+ adaptation: adaptation.state
506
+ };
507
+ }
508
+ //#endregion
509
+ //#region src/calibration/profile.ts
510
+ var CAMERA_INTRINSIC_PROFILE_SCHEMA = "twcs/camera-intrinsics";
511
+ /** The application-specific format this contract replaces. Read for migration, never written. */
512
+ var LEGACY_CALIBRATION_SCHEMA = "twrmc/camera-calibration";
513
+ var IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
514
+ var UTC_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?Z$/;
515
+ var MAXIMUM_IMAGE_EDGE = 16384;
516
+ var MAXIMUM_PIXEL_MAGNITUDE = 1e7;
517
+ var MAXIMUM_DISTORTION_MAGNITUDE = 1e4;
518
+ var MAXIMUM_SAMPLE_COUNT = 1e4;
519
+ var MAXIMUM_REPROJECTION_ERROR_PX = 1e4;
520
+ var MAXIMUM_TEXT_LENGTH = 256;
521
+ var MAXIMUM_FRAME_RATE = 1e3;
522
+ var MAXIMUM_ZOOM = 1e3;
523
+ var MAXIMUM_FOCUS_DISTANCE = 1e4;
524
+ var MAXIMUM_SCAN_DEPTH = 16;
525
+ var AFFINE_ROW_TOLERANCE = 1e-6;
526
+ var DISTORTION_MODELS = [
527
+ "none",
528
+ "brown-conrady",
529
+ "kannala-brandt"
530
+ ];
531
+ var RESIZE_MODES = ["none", "crop-and-scale"];
532
+ var FOCUS_MODES = [
533
+ "none",
534
+ "manual",
535
+ "single-shot",
536
+ "continuous"
537
+ ];
538
+ /**
539
+ * Coefficient counts each model accepts.
540
+ *
541
+ * The Brown-Conrady lengths are the OpenCV sets that consumers already handle: four, the usual five
542
+ * with k3, and eight for the rational model. Longer OpenCV vectors (thin prism, tilted sensor) are
543
+ * rejected rather than carried, because no consumer in this family implements them and a profile
544
+ * that is accepted but only partly applied is worse than one that is refused.
545
+ */
546
+ var DISTORTION_COEFFICIENT_LENGTHS = {
547
+ none: [0],
548
+ "brown-conrady": [
549
+ 4,
550
+ 5,
551
+ 8
552
+ ],
553
+ "kannala-brandt": [4]
554
+ };
555
+ /**
556
+ * Key names that carry pairing or authentication material.
557
+ *
558
+ * Signaling data is short-lived session state and a calibration profile is a document operators keep
559
+ * and copy between venues. Rejecting the whole document is deliberate: a profile that reached here
560
+ * carrying an SDP is evidence that something upstream is mixing the two, and quietly stripping the
561
+ * key would hide that.
562
+ */
563
+ var FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
564
+ "accesstoken",
565
+ "answer",
566
+ "apikey",
567
+ "authorization",
568
+ "candidate",
569
+ "credential",
570
+ "credentials",
571
+ "ice",
572
+ "icecandidate",
573
+ "offer",
574
+ "passphrase",
575
+ "password",
576
+ "secret",
577
+ "sdp",
578
+ "token"
579
+ ]);
580
+ var ProfileRejection = class extends Error {
581
+ constructor(detail) {
582
+ super(detail.message);
583
+ this.name = "ProfileRejection";
584
+ this.detail = detail;
585
+ }
586
+ };
587
+ function reject(code, path, message) {
588
+ throw new ProfileRejection({
589
+ code,
590
+ path,
591
+ message
592
+ });
593
+ }
594
+ function isRecord(value) {
595
+ return typeof value === "object" && value !== null && !Array.isArray(value);
596
+ }
597
+ function member(path, name) {
598
+ return path.length === 0 ? name : `${path}.${name}`;
599
+ }
600
+ /** Normalizes a key so `ICE-Candidate`, `iceCandidate` and `ice_candidate` all match one entry. */
601
+ function comparableKey(key) {
602
+ return key.toLowerCase().replace(/[^a-z0-9]/g, "");
603
+ }
604
+ function assertNoForbiddenKeys(value, path, depth, seen) {
605
+ if (depth > MAXIMUM_SCAN_DEPTH) reject("invalid-value", path, "The document is nested more deeply than a profile ever is.");
606
+ if (typeof value !== "object" || value === null) return;
607
+ if (seen.has(value)) reject("invalid-value", path, "The document contains a cycle.");
608
+ seen.add(value);
609
+ if (Array.isArray(value)) {
610
+ value.forEach((item, index) => assertNoForbiddenKeys(item, `${path}[${index}]`, depth + 1, seen));
611
+ return;
612
+ }
613
+ for (const [key, child] of Object.entries(value)) {
614
+ if (FORBIDDEN_KEYS.has(comparableKey(key))) reject("forbidden-field", member(path, key), "Pairing and authentication material must not travel inside a calibration profile.");
615
+ assertNoForbiddenKeys(child, member(path, key), depth + 1, seen);
616
+ }
617
+ }
618
+ function requireRecord(value, path) {
619
+ if (!isRecord(value)) reject(path.length === 0 ? "not-an-object" : "invalid-type", path, "Expected an object.");
620
+ return value;
621
+ }
622
+ /** Rejects unknown members as well as missing ones, so an unrecognized field is never ignored. */
623
+ function requireExactKeys(record, path, required, optional = []) {
624
+ const known = /* @__PURE__ */ new Set([...required, ...optional]);
625
+ for (const key of Object.keys(record)) if (!known.has(key)) reject("unexpected-field", member(path, key), "Unknown member.");
626
+ for (const key of required) if (!(key in record)) reject("missing-field", member(path, key), "Required member is missing.");
627
+ }
628
+ function requireText(value, path) {
629
+ if (typeof value !== "string") reject("invalid-type", path, "Expected a string.");
630
+ if (value.length === 0 || value.length > MAXIMUM_TEXT_LENGTH) reject("out-of-range", path, `Expected between 1 and ${MAXIMUM_TEXT_LENGTH} characters.`);
631
+ return value;
632
+ }
633
+ function requireIdentifier(value, path) {
634
+ const text = requireText(value, path);
635
+ if (!IDENTIFIER_PATTERN.test(text)) reject("invalid-value", path, "Expected letters, digits, dot, underscore, colon or hyphen.");
636
+ return text;
637
+ }
638
+ function requireUtcTimestamp(value, path) {
639
+ const text = requireText(value, path);
640
+ if (!UTC_TIMESTAMP_PATTERN.test(text) || !Number.isFinite(Date.parse(text))) reject("invalid-value", path, "Expected an RFC 3339 timestamp in UTC, such as 2026-09-15T04:05:06Z.");
641
+ return text;
642
+ }
643
+ function requireBoolean(value, path) {
644
+ if (typeof value !== "boolean") reject("invalid-type", path, "Expected a boolean.");
645
+ return value;
646
+ }
647
+ function requireFinite(value, path) {
648
+ if (typeof value !== "number") reject("invalid-type", path, "Expected a number.");
649
+ if (!Number.isFinite(value)) reject("invalid-value", path, "Expected a finite number.");
650
+ return value;
651
+ }
652
+ function requireInteger(value, path, minimum, maximum) {
653
+ const numeric = requireFinite(value, path);
654
+ if (!Number.isInteger(numeric)) reject("invalid-value", path, "Expected an integer.");
655
+ if (numeric < minimum || numeric > maximum) reject("out-of-range", path, `Expected between ${minimum} and ${maximum}.`);
656
+ return numeric;
657
+ }
658
+ function requireBounded(value, path, minimum, maximum) {
659
+ const numeric = requireFinite(value, path);
660
+ if (numeric < minimum || numeric > maximum) reject("out-of-range", path, `Expected between ${minimum} and ${maximum}.`);
661
+ return numeric;
662
+ }
663
+ function requireLiteral(value, path, expected, code) {
664
+ if (value !== expected) reject(code, path, `Expected ${JSON.stringify(expected)}.`);
665
+ return expected;
666
+ }
667
+ function readImage(value, path) {
668
+ const record = requireRecord(value, path);
669
+ requireExactKeys(record, path, [
670
+ "width",
671
+ "height",
672
+ "undistorted"
673
+ ]);
674
+ return {
675
+ width: requireInteger(record["width"], member(path, "width"), 1, MAXIMUM_IMAGE_EDGE),
676
+ height: requireInteger(record["height"], member(path, "height"), 1, MAXIMUM_IMAGE_EDGE),
677
+ undistorted: requireBoolean(record["undistorted"], member(path, "undistorted"))
678
+ };
679
+ }
680
+ /**
681
+ * Reads the pinhole parameters.
682
+ *
683
+ * The principal point is allowed to sit outside the frame — a cropped or shifted sensor puts it
684
+ * there legitimately — but not arbitrarily far, because a principal point far outside the image is
685
+ * the signature of values given in the wrong unit rather than of an unusual lens.
686
+ */
687
+ function readIntrinsics(value, path, image) {
688
+ const record = requireRecord(value, path);
689
+ requireExactKeys(record, path, [
690
+ "fx",
691
+ "fy",
692
+ "cx",
693
+ "cy",
694
+ "skew"
695
+ ]);
696
+ return {
697
+ fx: requireBounded(record["fx"], member(path, "fx"), Number.MIN_VALUE, MAXIMUM_PIXEL_MAGNITUDE),
698
+ fy: requireBounded(record["fy"], member(path, "fy"), Number.MIN_VALUE, MAXIMUM_PIXEL_MAGNITUDE),
699
+ cx: requireBounded(record["cx"], member(path, "cx"), -image.width, image.width * 2),
700
+ cy: requireBounded(record["cy"], member(path, "cy"), -image.height, image.height * 2),
701
+ skew: requireBounded(record["skew"], member(path, "skew"), -1e7, MAXIMUM_PIXEL_MAGNITUDE)
702
+ };
703
+ }
704
+ function readDistortion(value, path) {
705
+ const record = requireRecord(value, path);
706
+ requireExactKeys(record, path, ["model", "coefficients"]);
707
+ const modelPath = member(path, "model");
708
+ const rawModel = record["model"];
709
+ if (typeof rawModel !== "string" || !DISTORTION_MODELS.includes(rawModel)) reject("invalid-distortion", modelPath, `Expected one of ${DISTORTION_MODELS.join(", ")}.`);
710
+ const model = rawModel;
711
+ const coefficientsPath = member(path, "coefficients");
712
+ const rawCoefficients = record["coefficients"];
713
+ if (!Array.isArray(rawCoefficients)) reject("invalid-type", coefficientsPath, "Expected an array.");
714
+ const allowed = DISTORTION_COEFFICIENT_LENGTHS[model];
715
+ if (!allowed.includes(rawCoefficients.length)) reject("invalid-distortion", coefficientsPath, `The ${model} model takes ${allowed.join(" or ")} coefficients, not ${rawCoefficients.length}.`);
716
+ return {
717
+ model,
718
+ coefficients: rawCoefficients.map((coefficient, index) => requireBounded(coefficient, `${coefficientsPath}[${index}]`, -1e4, MAXIMUM_DISTORTION_MAGNITUDE))
719
+ };
720
+ }
721
+ function requireEnum(value, path, allowed) {
722
+ const text = requireText(value, path);
723
+ if (!allowed.includes(text)) reject("invalid-value", path, `Expected one of ${allowed.join(", ")}.`);
724
+ return text;
725
+ }
726
+ function readCapture(value, path) {
727
+ const record = requireRecord(value, path);
728
+ requireExactKeys(record, path, [], [
729
+ "frameRate",
730
+ "facingMode",
731
+ "resizeMode",
732
+ "zoom",
733
+ "focusMode",
734
+ "focusDistance"
735
+ ]);
736
+ const read = (name, reader) => name in record ? reader(record[name], member(path, name)) : void 0;
737
+ const frameRate = read("frameRate", (raw, at) => requireBounded(raw, at, Number.MIN_VALUE, MAXIMUM_FRAME_RATE));
738
+ const facingMode = read("facingMode", requireText);
739
+ const resizeMode = read("resizeMode", (raw, at) => requireEnum(raw, at, RESIZE_MODES));
740
+ const zoom = read("zoom", (raw, at) => requireBounded(raw, at, Number.MIN_VALUE, MAXIMUM_ZOOM));
741
+ const focusMode = read("focusMode", (raw, at) => requireEnum(raw, at, FOCUS_MODES));
742
+ const focusDistance = read("focusDistance", (raw, at) => requireBounded(raw, at, 0, MAXIMUM_FOCUS_DISTANCE));
743
+ return {
744
+ ...frameRate === void 0 ? {} : { frameRate },
745
+ ...facingMode === void 0 ? {} : { facingMode },
746
+ ...resizeMode === void 0 ? {} : { resizeMode },
747
+ ...zoom === void 0 ? {} : { zoom },
748
+ ...focusMode === void 0 ? {} : { focusMode },
749
+ ...focusDistance === void 0 ? {} : { focusDistance }
750
+ };
751
+ }
752
+ function readQuality(value, path) {
753
+ const record = requireRecord(value, path);
754
+ requireExactKeys(record, path, ["sampleCount", "reprojectionErrorPx"]);
755
+ return {
756
+ sampleCount: requireInteger(record["sampleCount"], member(path, "sampleCount"), 1, MAXIMUM_SAMPLE_COUNT),
757
+ reprojectionErrorPx: requireBounded(record["reprojectionErrorPx"], member(path, "reprojectionErrorPx"), 0, MAXIMUM_REPROJECTION_ERROR_PX)
758
+ };
759
+ }
760
+ function readDevice(value, path) {
761
+ const record = requireRecord(value, path);
762
+ requireExactKeys(record, path, [], ["label", "deviceId"]);
763
+ const label = "label" in record ? requireText(record["label"], member(path, "label")) : void 0;
764
+ const deviceId = "deviceId" in record ? requireText(record["deviceId"], member(path, "deviceId")) : void 0;
765
+ return {
766
+ ...label === void 0 ? {} : { label },
767
+ ...deviceId === void 0 ? {} : { deviceId }
768
+ };
769
+ }
770
+ function readProfile(input) {
771
+ assertNoForbiddenKeys(input, "", 0, /* @__PURE__ */ new WeakSet());
772
+ const record = requireRecord(input, "");
773
+ requireLiteral(record["schema"], "schema", CAMERA_INTRINSIC_PROFILE_SCHEMA, "unsupported-schema");
774
+ requireLiteral(record["version"], "version", 1, "unsupported-version");
775
+ requireExactKeys(record, "", [
776
+ "schema",
777
+ "version",
778
+ "profileId",
779
+ "cameraId",
780
+ "calibratedAt",
781
+ "producer",
782
+ "cameraModel",
783
+ "image",
784
+ "intrinsics",
785
+ "distortion"
786
+ ], [
787
+ "capture",
788
+ "quality",
789
+ "device"
790
+ ]);
791
+ const image = readImage(record["image"], "image");
792
+ const distortion = readDistortion(record["distortion"], "distortion");
793
+ if (image.undistorted && distortion.model !== "none") reject("inconsistent-profile", "distortion.model", "A profile for an already undistorted image cannot also carry distortion coefficients.");
794
+ const capture = "capture" in record ? readCapture(record["capture"], "capture") : void 0;
795
+ const quality = "quality" in record ? readQuality(record["quality"], "quality") : void 0;
796
+ const device = "device" in record ? readDevice(record["device"], "device") : void 0;
797
+ return {
798
+ schema: CAMERA_INTRINSIC_PROFILE_SCHEMA,
799
+ version: 1,
800
+ profileId: requireIdentifier(record["profileId"], "profileId"),
801
+ cameraId: requireIdentifier(record["cameraId"], "cameraId"),
802
+ calibratedAt: requireUtcTimestamp(record["calibratedAt"], "calibratedAt"),
803
+ producer: requireText(record["producer"], "producer"),
804
+ cameraModel: requireLiteral(record["cameraModel"], "cameraModel", "pinhole", "invalid-value"),
805
+ image,
806
+ intrinsics: readIntrinsics(record["intrinsics"], "intrinsics", image),
807
+ distortion,
808
+ ...capture === void 0 ? {} : { capture },
809
+ ...quality === void 0 ? {} : { quality },
810
+ ...device === void 0 ? {} : { device }
811
+ };
812
+ }
813
+ function toResult(read) {
814
+ try {
815
+ return {
816
+ ok: true,
817
+ profile: read()
818
+ };
819
+ } catch (error) {
820
+ if (error instanceof ProfileRejection) return {
821
+ ok: false,
822
+ error: error.detail
823
+ };
824
+ throw error;
825
+ }
826
+ }
827
+ /**
828
+ * Reads whichever profile format a document is written in.
829
+ *
830
+ * An operator holding a file does not know, and should not have to know, which of two schemas it
831
+ * uses; they know they calibrated this camera once and kept the result. Dispatching on the document
832
+ * itself means one entry point accepts both, and the profile that comes out records where it came
833
+ * from in `producer`, so nothing about the conversion is hidden.
834
+ *
835
+ * Only the declared schema decides. A document that says nothing recognizable is refused by the
836
+ * current parser, which names what it expected.
837
+ */
838
+ function readCameraProfileDocument(input) {
839
+ if (isRecord(input) && input["schema"] === "twrmc/camera-calibration") return adoptLegacyCameraCalibration(input);
840
+ return parseCameraIntrinsicProfile(input);
841
+ }
842
+ /** Validates a parsed document and returns a normalized profile, or the reason it was refused. */
843
+ function parseCameraIntrinsicProfile(input) {
844
+ return toResult(() => readProfile(input));
845
+ }
846
+ /**
847
+ * Renders a profile as JSON with a fixed member order.
848
+ *
849
+ * Stable output means the same profile always produces the same bytes, so a file can be compared or
850
+ * hashed to tell whether two machines really hold the same calibration.
851
+ */
852
+ function orderedCapture(capture) {
853
+ const members = [
854
+ ["frameRate", capture.frameRate],
855
+ ["facingMode", capture.facingMode],
856
+ ["resizeMode", capture.resizeMode],
857
+ ["zoom", capture.zoom],
858
+ ["focusMode", capture.focusMode],
859
+ ["focusDistance", capture.focusDistance]
860
+ ];
861
+ return Object.fromEntries(members.filter((entry) => entry[1] !== void 0));
862
+ }
863
+ function serializeCameraIntrinsicProfile(profile) {
864
+ const ordered = {
865
+ schema: profile.schema,
866
+ version: profile.version,
867
+ profileId: profile.profileId,
868
+ cameraId: profile.cameraId,
869
+ calibratedAt: profile.calibratedAt,
870
+ producer: profile.producer,
871
+ cameraModel: profile.cameraModel,
872
+ image: {
873
+ width: profile.image.width,
874
+ height: profile.image.height,
875
+ undistorted: profile.image.undistorted
876
+ },
877
+ intrinsics: {
878
+ fx: profile.intrinsics.fx,
879
+ fy: profile.intrinsics.fy,
880
+ cx: profile.intrinsics.cx,
881
+ cy: profile.intrinsics.cy,
882
+ skew: profile.intrinsics.skew
883
+ },
884
+ distortion: {
885
+ model: profile.distortion.model,
886
+ coefficients: [...profile.distortion.coefficients]
887
+ },
888
+ ...profile.capture === void 0 ? {} : { capture: orderedCapture(profile.capture) },
889
+ ...profile.quality === void 0 ? {} : { quality: {
890
+ sampleCount: profile.quality.sampleCount,
891
+ reprojectionErrorPx: profile.quality.reprojectionErrorPx
892
+ } },
893
+ ...profile.device === void 0 ? {} : { device: {
894
+ ...profile.device.label === void 0 ? {} : { label: profile.device.label },
895
+ ...profile.device.deviceId === void 0 ? {} : { deviceId: profile.device.deviceId }
896
+ } }
897
+ };
898
+ return `${JSON.stringify(ordered, null, 2)}\n`;
899
+ }
900
+ function readLegacyMatrixRow(matrix, offset, expected) {
901
+ expected.forEach((value, index) => {
902
+ const actual = requireFinite(matrix[offset + index], `intrinsicMatrix[${offset + index}]`);
903
+ if (Math.abs(actual - value) > AFFINE_ROW_TOLERANCE) reject("inconsistent-profile", `intrinsicMatrix[${offset + index}]`, `Expected ${value} in the intrinsic matrix; the value read as ${actual}.`);
904
+ });
905
+ }
906
+ /**
907
+ * Converts a `twrmc/camera-calibration` v1 document into this contract.
908
+ *
909
+ * The world pose the old format carried is deliberately dropped. It was the extrinsic of whichever
910
+ * calibration sample happened to be last, so treating it as a placement in a shared world frame puts
911
+ * a camera somewhere it has never been. Placement belongs to whoever solves it against a common
912
+ * reference, and a profile that simply lacks it is honest about what it knows.
913
+ *
914
+ * Quality is dropped for the same reason: the old format recorded none, and inventing a sample count
915
+ * or a reprojection error would turn "unknown" into a measurement.
916
+ */
917
+ function adoptLegacyCameraCalibration(input) {
918
+ return toResult(() => {
919
+ assertNoForbiddenKeys(input, "", 0, /* @__PURE__ */ new WeakSet());
920
+ const record = requireRecord(input, "");
921
+ requireLiteral(record["schema"], "schema", LEGACY_CALIBRATION_SCHEMA, "unsupported-schema");
922
+ requireLiteral(record["version"], "version", 1, "unsupported-version");
923
+ requireExactKeys(record, "", [
924
+ "schema",
925
+ "version",
926
+ "calibrationId",
927
+ "cameraId",
928
+ "imageWidth",
929
+ "imageHeight",
930
+ "intrinsicMatrix",
931
+ "distortionCoefficients",
932
+ "calibratedAt"
933
+ ], ["worldFromCameraMatrix", "worldUnit"]);
934
+ const matrix = record["intrinsicMatrix"];
935
+ if (!Array.isArray(matrix) || matrix.length !== 9) reject("invalid-value", "intrinsicMatrix", "Expected nine numbers in row-major order.");
936
+ readLegacyMatrixRow(matrix, 3, [0]);
937
+ readLegacyMatrixRow(matrix, 6, [
938
+ 0,
939
+ 0,
940
+ 1
941
+ ]);
942
+ const rawCoefficients = record["distortionCoefficients"];
943
+ if (!Array.isArray(rawCoefficients)) reject("invalid-type", "distortionCoefficients", "Expected an array.");
944
+ const model = rawCoefficients.length === 0 ? "none" : "brown-conrady";
945
+ return readProfile({
946
+ schema: CAMERA_INTRINSIC_PROFILE_SCHEMA,
947
+ version: 1,
948
+ profileId: record["calibrationId"],
949
+ cameraId: record["cameraId"],
950
+ calibratedAt: record["calibratedAt"],
951
+ producer: `${LEGACY_CALIBRATION_SCHEMA} v1`,
952
+ cameraModel: "pinhole",
953
+ image: {
954
+ width: record["imageWidth"],
955
+ height: record["imageHeight"],
956
+ undistorted: false
957
+ },
958
+ intrinsics: {
959
+ fx: matrix[0],
960
+ fy: matrix[4],
961
+ cx: matrix[2],
962
+ cy: matrix[5],
963
+ skew: matrix[1]
964
+ },
965
+ distortion: {
966
+ model,
967
+ coefficients: rawCoefficients
968
+ }
969
+ });
970
+ });
971
+ }
972
+ //#endregion
973
+ //#region src/calibration/registry.ts
974
+ /**
975
+ * The profiles this runtime knows about.
976
+ *
977
+ * Producer-agnostic by construction: a profile arrives as a document that
978
+ * either passes validation or does not, and nothing here can tell chessboard
979
+ * calibration from an operator pasting JSON. Naming a producing extension would
980
+ * undo the split that keeps this package free of runtime dependencies.
981
+ *
982
+ * Registration is keyed by `cameraId`, not by `profileId`: a camera has one
983
+ * calibration in force at a time, and a fresh solve replaces the previous one
984
+ * rather than accumulating beside it.
985
+ */
986
+ var CameraProfileRegistry = class {
987
+ constructor() {
988
+ this.profiles = /* @__PURE__ */ new Map();
989
+ }
990
+ /**
991
+ * Validates a document and, only if it passes, stores it.
992
+ *
993
+ * Both the current contract and the `twrmc/camera-calibration` file an operator may still be
994
+ * carrying are accepted; the second is converted on the way in, dropping the world pose it
995
+ * carried rather than letting a stale extrinsic arrive as a placement.
996
+ *
997
+ * Nothing is written before the document has been checked. A half-registered
998
+ * profile would be indistinguishable from a good one at the point of use.
999
+ */
1000
+ register(document) {
1001
+ const result = readCameraProfileDocument(document);
1002
+ if (!result.ok) return result;
1003
+ this.profiles.set(result.profile.cameraId, result.profile);
1004
+ return result;
1005
+ }
1006
+ forget(cameraId) {
1007
+ return this.profiles.delete(cameraId.trim());
1008
+ }
1009
+ clear() {
1010
+ this.profiles.clear();
1011
+ }
1012
+ get(cameraId) {
1013
+ return this.profiles.get(cameraId.trim());
1014
+ }
1015
+ has(cameraId) {
1016
+ return this.profiles.has(cameraId.trim());
1017
+ }
1018
+ cameraIds() {
1019
+ return [...this.profiles.keys()].sort();
1020
+ }
1021
+ /**
1022
+ * The profile for a camera, judged against how that camera is configured now.
1023
+ *
1024
+ * Absent when the camera has never been calibrated. Callers that need one say so themselves.
1025
+ */
1026
+ assess(cameraId, conditions) {
1027
+ const profile = this.get(cameraId);
1028
+ if (!profile) return void 0;
1029
+ const compatibility = evaluateProfileCompatibility(profile, conditions);
1030
+ const adaptation = adaptProfileToConditions(profile, conditions);
1031
+ const usable = usableIntrinsics(compatibility, adaptation);
1032
+ return {
1033
+ profile,
1034
+ compatibility,
1035
+ adaptation,
1036
+ ...usable === void 0 ? {} : { usable }
1037
+ };
1038
+ }
180
1039
  };
181
1040
  //#endregion
1041
+ //#region src/runtime-capability.ts
1042
+ var runtimeCapabilityKey = "kubohiroyaCameraSourceCapability";
1043
+ function createRuntimeCapability(host) {
1044
+ const capability = {
1045
+ version: 1,
1046
+ requireVersion(version) {
1047
+ if (version !== 1) throw new Error(`Unsupported Camera Source runtime capability version: ${version}; this build provides 1.`);
1048
+ return capability;
1049
+ },
1050
+ registerProfile: (document) => host.registerProfile(document),
1051
+ forgetProfile: (cameraId) => host.forgetProfile(cameraId),
1052
+ profileFor: (cameraId) => host.profileFor(cameraId),
1053
+ calibratedCameras: () => host.calibratedCameras(),
1054
+ assessProfile: (cameraId) => host.assessProfile(cameraId),
1055
+ intrinsicsFor: (cameraId) => host.intrinsicsFor(cameraId),
1056
+ conditionsFor: (cameraId) => host.conditionsFor(cameraId),
1057
+ conditionsGeneration: (cameraId) => host.conditionsGeneration(cameraId)
1058
+ };
1059
+ return Object.freeze(capability);
1060
+ }
1061
+ //#endregion
1062
+ //#region src/flip.ts
1063
+ var FLIPS = [
1064
+ "none",
1065
+ "horizontal",
1066
+ "vertical",
1067
+ "both"
1068
+ ];
1069
+ function isFlip(value) {
1070
+ return typeof value === "string" && FLIPS.includes(value);
1071
+ }
1072
+ /** Reads a flip, accepting the boolean the older API used for left-right. */
1073
+ function toFlip(value, fallback = "none") {
1074
+ if (isFlip(value)) return value;
1075
+ if (value === true) return "horizontal";
1076
+ if (value === false) return "none";
1077
+ return fallback;
1078
+ }
1079
+ function flipsHorizontally(flip) {
1080
+ return flip === "horizontal" || flip === "both";
1081
+ }
1082
+ function flipsVertically(flip) {
1083
+ return flip === "vertical" || flip === "both";
1084
+ }
1085
+ //#endregion
1086
+ //#region src/runtime.ts
1087
+ /**
1088
+ * Where the extension instance puts itself on the VM runtime.
1089
+ *
1090
+ * Present as soon as the extension is registered. Absent means Camera Source is not loaded, which a
1091
+ * consumer has to handle whatever else it does.
1092
+ */
1093
+ var cameraSourceRuntimeKey = "ext_kubohiroyacamerasource";
1094
+ //#endregion
182
1095
  //#region src/video-preview.ts
183
1096
  var videoLayer = "video";
184
1097
  var haveCurrentData = 2;
@@ -272,13 +1185,13 @@
272
1185
  function assertRenderer(renderer) {
273
1186
  if (!renderer || !Array.isArray(renderer._allSkins) || !Number.isInteger(renderer._nextSkinId) || typeof renderer.createDrawable !== "function" || typeof renderer.destroyDrawable !== "function" || typeof renderer.destroySkin !== "function" || typeof renderer.getNativeSize !== "function") throw new Error("Camera preview requires a compatible TurboWarp renderer.");
274
1187
  }
275
- function createVideoPreview(renderer, video, mirrored, requestRedraw) {
1188
+ function createVideoPreview(renderer, video, flip, requestRedraw) {
276
1189
  assertRenderer(renderer);
277
1190
  const VideoSkin = videoSkinClass(renderer);
278
1191
  const skinId = renderer._nextSkinId++;
279
1192
  let drawableId;
280
1193
  let disposed = false;
281
- let previewMirrored = mirrored;
1194
+ let previewFlip = flip;
282
1195
  let lastLayout = "";
283
1196
  const updateLayout = () => {
284
1197
  if (drawableId === void 0 || video.videoWidth === 0 || video.videoHeight === 0) return;
@@ -288,11 +1201,11 @@
288
1201
  video.videoHeight,
289
1202
  stageWidth,
290
1203
  stageHeight,
291
- previewMirrored
1204
+ previewFlip
292
1205
  ].join(":");
293
1206
  if (layout === lastLayout) return;
294
1207
  const scale = Math.max(stageWidth / video.videoWidth, stageHeight / video.videoHeight) * 100;
295
- renderer.updateDrawableScale(drawableId, [previewMirrored ? -scale : scale, scale]);
1208
+ renderer.updateDrawableScale(drawableId, [flipsHorizontally(previewFlip) ? -scale : scale, flipsVertically(previewFlip) ? -scale : scale]);
296
1209
  lastLayout = layout;
297
1210
  };
298
1211
  const skin = new VideoSkin(skinId, renderer, video, (metricsChanged) => {
@@ -320,9 +1233,9 @@
320
1233
  throw error;
321
1234
  }
322
1235
  return Object.freeze({
323
- setMirrored: (nextMirrored) => {
324
- if (disposed || previewMirrored === nextMirrored) return;
325
- previewMirrored = nextMirrored;
1236
+ setFlip: (nextFlip) => {
1237
+ if (disposed || previewFlip === nextFlip) return;
1238
+ previewFlip = nextFlip;
326
1239
  updateLayout();
327
1240
  requestRedraw();
328
1241
  },
@@ -344,6 +1257,7 @@
344
1257
  //#endregion
345
1258
  //#region src/extension.ts
346
1259
  var blockDefinitions = block_definitions_default.blocks;
1260
+ var menuDefinitions = block_definitions_default.menus;
347
1261
  var defaultCameraId = "default";
348
1262
  function mediaDevices() {
349
1263
  const devices = globalThis.navigator?.mediaDevices;
@@ -374,6 +1288,20 @@
374
1288
  video: options.video ?? true
375
1289
  };
376
1290
  }
1291
+ /**
1292
+ * The flip a `show preview` block asked for.
1293
+ *
1294
+ * The menu accepts reporters, so the value can arrive as any string a project computed. Anything
1295
+ * outside the vocabulary falls back to horizontal rather than silently drawing the preview
1296
+ * unflipped: a project that asked for a flip and got none would look like the camera was wrong.
1297
+ */
1298
+ function requestedPreviewFlip(args) {
1299
+ return toFlip(args.PREVIEW_FLIP, "horizontal");
1300
+ }
1301
+ /** The preview flip a consumer asked for through the runtime API. */
1302
+ function previewFlipOf(options) {
1303
+ return toFlip(options.previewFlip);
1304
+ }
377
1305
  function cameraFailure(error) {
378
1306
  if (error instanceof Error) return {
379
1307
  code: error.name || "Error",
@@ -391,17 +1319,38 @@
391
1319
  this.blockPreviewLeases = /* @__PURE__ */ new Map();
392
1320
  this.blockPreviewRevisions = /* @__PURE__ */ new Map();
393
1321
  this.cameraFailures = /* @__PURE__ */ new Map();
1322
+ this.profiles = new CameraProfileRegistry();
1323
+ this.generations = /* @__PURE__ */ new Map();
1324
+ this.lastConditions = /* @__PURE__ */ new Map();
1325
+ this.assessments = /* @__PURE__ */ new Map();
1326
+ this.calibrationEnabled = featureFlags.calibrationProfilesV1;
394
1327
  this.devices = [];
395
1328
  this.dispose = () => {
396
1329
  this.stopAllCameras();
1330
+ const runtime = Scratch.vm.runtime;
1331
+ if (runtime["kubohiroyaCameraSourceCapability"] === this.capability) delete runtime[runtimeCapabilityKey];
397
1332
  Scratch.vm.runtime.off?.("PROJECT_STOP_ALL", this.handleProjectBoundary);
398
1333
  Scratch.vm.runtime.off?.("PROJECT_LOADED", this.handleProjectBoundary);
399
1334
  Scratch.vm.runtime.off?.("RUNTIME_DISPOSED", this.dispose);
400
1335
  };
401
1336
  this.handleProjectBoundary = () => {
402
1337
  this.stopAllCameras();
1338
+ this.profileError = void 0;
403
1339
  };
404
- Scratch.vm.runtime.ext_kubohiroyacamerasource = this;
1340
+ Scratch.vm.runtime[cameraSourceRuntimeKey] = this;
1341
+ this.capability = this.calibrationEnabled ? createRuntimeCapability({
1342
+ registerProfile: (document) => this.profiles.register(document),
1343
+ forgetProfile: (cameraId) => this.profiles.forget(cameraId),
1344
+ profileFor: (cameraId) => this.profiles.get(cameraId),
1345
+ calibratedCameras: () => this.profiles.cameraIds(),
1346
+ assessProfile: (cameraId) => {
1347
+ return this.assessmentOf(cameraId);
1348
+ },
1349
+ intrinsicsFor: (cameraId) => this.intrinsicsOf(cameraId),
1350
+ conditionsFor: (cameraId) => this.conditionsOf(cameraId),
1351
+ conditionsGeneration: (cameraId) => this.generationOf(cameraId)
1352
+ }) : void 0;
1353
+ if (this.capability) Scratch.vm.runtime[runtimeCapabilityKey] = this.capability;
405
1354
  Scratch.vm.runtime.on?.("PROJECT_STOP_ALL", this.handleProjectBoundary);
406
1355
  Scratch.vm.runtime.on?.("PROJECT_LOADED", this.handleProjectBoundary);
407
1356
  Scratch.vm.runtime.on?.("RUNTIME_DISPOSED", this.dispose);
@@ -410,7 +1359,11 @@
410
1359
  return {
411
1360
  id: extensionConfig.id,
412
1361
  name: Scratch.translate(block_definitions_default.extensionName),
413
- blocks: blockDefinitions.map((block) => this.toScratchBlock(block))
1362
+ blocks: blockDefinitions.filter((block) => block.feature === void 0 || this.calibrationEnabled).map((block) => this.toScratchBlock(block)),
1363
+ menus: Object.fromEntries(Object.entries(menuDefinitions).map(([id, menu]) => [id, {
1364
+ acceptReporters: menu.acceptReporters,
1365
+ items: [...menu.items]
1366
+ }]))
414
1367
  };
415
1368
  }
416
1369
  isCameraRunning(args = {}) {
@@ -461,14 +1414,14 @@
461
1414
  session.leases.add(token);
462
1415
  try {
463
1416
  if (options.preview === true) {
464
- session.previewLeases.set(token, options.mirrored === true);
1417
+ session.previewLeases.set(token, previewFlipOf(options));
465
1418
  this.ensurePreview(session);
466
- session.preview?.setMirrored(this.previewMirrored(session));
1419
+ session.preview?.setFlip(this.previewFlip(session));
467
1420
  }
468
1421
  } catch (error) {
469
1422
  session.leases.delete(token);
470
1423
  session.previewLeases.delete(token);
471
- if (session.leases.size === 0) this.stopCameraSession(session.cameraId);
1424
+ this.stopWhenUnused(session);
472
1425
  this.cameraFailures.set(cameraId, cameraFailure(error));
473
1426
  throw error;
474
1427
  }
@@ -483,21 +1436,21 @@
483
1436
  if (session.previewLeases.size === 0) {
484
1437
  session.preview?.dispose();
485
1438
  session.preview = null;
486
- } else session.preview?.setMirrored(this.previewMirrored(session));
487
- if (session.leases.size === 0) this.stopCameraSession(session.cameraId);
1439
+ } else session.preview?.setFlip(this.previewFlip(session));
1440
+ this.stopWhenUnused(session);
488
1441
  }
489
1442
  });
490
1443
  }
491
1444
  async showCameraPreview(args = {}) {
492
1445
  const cameraId = normalizeId(args.CAMERA_ID);
493
- const mirrored = Scratch.Cast.toBoolean(args.MIRRORED ?? true);
494
- if (this.blockPreviewLeases.get(cameraId)?.mirrored === mirrored) return;
1446
+ const flip = requestedPreviewFlip(args);
1447
+ if (this.blockPreviewLeases.get(cameraId)?.flip === flip) return;
495
1448
  const revision = this.nextPreviewBlockRevision(cameraId);
496
1449
  const lease = await this.acquireCamera({
497
1450
  owner: "camera-source-preview-block",
498
1451
  cameraId,
499
1452
  preview: true,
500
- mirrored
1453
+ previewFlip: flip
501
1454
  });
502
1455
  if (this.blockPreviewRevisions.get(cameraId) !== revision) {
503
1456
  await lease.release();
@@ -506,7 +1459,7 @@
506
1459
  const current = this.blockPreviewLeases.get(cameraId);
507
1460
  this.blockPreviewLeases.set(cameraId, {
508
1461
  lease,
509
- mirrored
1462
+ flip
510
1463
  });
511
1464
  await current?.lease.release();
512
1465
  }
@@ -538,6 +1491,163 @@
538
1491
  this.blockLeases.clear();
539
1492
  this.blockPreviewLeases.clear();
540
1493
  }
1494
+ registerCameraProfile(args = {}) {
1495
+ const text = Scratch.Cast.toString(args.PROFILE_JSON ?? "");
1496
+ let document;
1497
+ try {
1498
+ document = JSON.parse(text);
1499
+ } catch {
1500
+ this.profileError = {
1501
+ code: "not-an-object",
1502
+ path: "",
1503
+ message: "The profile is not valid JSON."
1504
+ };
1505
+ return;
1506
+ }
1507
+ const result = this.profiles.register(document);
1508
+ this.profileError = result.ok ? void 0 : result.error;
1509
+ }
1510
+ forgetCameraProfile(args = {}) {
1511
+ this.profiles.forget(normalizeId(args.CAMERA_ID));
1512
+ }
1513
+ cameraProfileRegistered(args = {}) {
1514
+ return this.profiles.has(normalizeId(args.CAMERA_ID));
1515
+ }
1516
+ cameraProfileJson(args = {}) {
1517
+ const profile = this.profiles.get(normalizeId(args.CAMERA_ID));
1518
+ return profile ? serializeCameraIntrinsicProfile(profile) : "";
1519
+ }
1520
+ cameraProfileError() {
1521
+ return this.profileError?.code ?? "";
1522
+ }
1523
+ cameraProfileErrorDetail() {
1524
+ if (!this.profileError) return "";
1525
+ const { path, message } = this.profileError;
1526
+ return path ? `${path}: ${message}` : message;
1527
+ }
1528
+ cameraProfileCompatibility(args = {}) {
1529
+ const cameraId = normalizeId(args.CAMERA_ID);
1530
+ return this.assessmentOf(cameraId)?.compatibility.state ?? "";
1531
+ }
1532
+ cameraProfileCompatibilityDetail(args = {}) {
1533
+ const cameraId = normalizeId(args.CAMERA_ID);
1534
+ const assessment = this.assessmentOf(cameraId);
1535
+ if (assessment === void 0) return "";
1536
+ const findings = decisiveFindings(assessment.compatibility);
1537
+ if (findings.length === 0) return "The profile matches the camera as configured.";
1538
+ return findings.map((entry) => entry.detail).join(" ");
1539
+ }
1540
+ cameraProfileAdaptation(args = {}) {
1541
+ const cameraId = normalizeId(args.CAMERA_ID);
1542
+ return this.assessmentOf(cameraId)?.adaptation.state ?? "";
1543
+ }
1544
+ cameraProfileIntrinsicsJson(args = {}) {
1545
+ const cameraId = normalizeId(args.CAMERA_ID);
1546
+ const usable = this.intrinsicsOf(cameraId);
1547
+ return usable === void 0 ? "" : JSON.stringify(usable);
1548
+ }
1549
+ cameraConditionsJson(args = {}) {
1550
+ return JSON.stringify(this.conditionsOf(normalizeId(args.CAMERA_ID)));
1551
+ }
1552
+ cameraConditionsGeneration(args = {}) {
1553
+ return this.generationOf(normalizeId(args.CAMERA_ID));
1554
+ }
1555
+ /** What the track reports about itself right now. Read only. */
1556
+ intrinsicsOf(cameraId) {
1557
+ const id = normalizeId(cameraId);
1558
+ return this.assessmentOf(id)?.usable;
1559
+ }
1560
+ conditionsOf(cameraId) {
1561
+ const id = normalizeId(cameraId);
1562
+ const session = this.sessions.get(id);
1563
+ if (!session?.stream) return {
1564
+ width: 0,
1565
+ height: 0,
1566
+ deviceId: "",
1567
+ previewFlip: "none"
1568
+ };
1569
+ const track = session.stream.getVideoTracks()[0];
1570
+ let settings = {};
1571
+ try {
1572
+ settings = track?.getSettings() ?? {};
1573
+ } catch {
1574
+ settings = {};
1575
+ }
1576
+ const device = this.devices.find((entry) => entry.deviceId === session.activeDeviceId);
1577
+ return readCameraConditions({
1578
+ width: session.video?.videoWidth ?? 0,
1579
+ height: session.video?.videoHeight ?? 0,
1580
+ deviceId: session.activeDeviceId,
1581
+ previewFlip: this.previewFlip(session),
1582
+ ...device?.label ? { label: device.label } : {}
1583
+ }, settings);
1584
+ }
1585
+ /**
1586
+ * A counter that moves when the geometry does.
1587
+ *
1588
+ * Derived by comparing the members that affect projection, so it advances on
1589
+ * a resolution change or a zoom and stays put for a frame rate change. A
1590
+ * consumer holding a placement solved from these conditions compares one
1591
+ * number rather than re-checking each of them.
1592
+ */
1593
+ /**
1594
+ * The conditions that decide geometry, as one comparable string.
1595
+ *
1596
+ * The preview flip is not among them. It changes how the stage draws the frame and nothing about
1597
+ * how the lens projects, so folding it in would advance the generation and invalidate consumers'
1598
+ * work every time an operator turned the preview over.
1599
+ */
1600
+ conditionsSignature(conditions) {
1601
+ return JSON.stringify([
1602
+ conditions.width,
1603
+ conditions.height,
1604
+ conditions.resizeMode ?? null,
1605
+ conditions.zoom ?? null,
1606
+ conditions.focusMode ?? null,
1607
+ conditions.focusDistance ?? null,
1608
+ conditions.deviceId
1609
+ ]);
1610
+ }
1611
+ /**
1612
+ * The assessment for a camera, reusing the last one while nothing it depends on has changed.
1613
+ *
1614
+ * The conditions are read on every call, so this cannot answer with a stale view of the camera.
1615
+ * What is skipped is the derivation: judging compatibility builds a finding for every member it
1616
+ * compares, each with its own sentence, and these reporters are read from blocks that a project
1617
+ * can evaluate on every frame. Reusing the result while the inputs are identical keeps that off
1618
+ * the frame budget without putting a staleness window in its place.
1619
+ */
1620
+ assessmentOf(cameraId) {
1621
+ const id = normalizeId(cameraId);
1622
+ const conditions = this.conditionsOf(id);
1623
+ const signature = this.conditionsSignature(conditions);
1624
+ const profile = this.profiles.get(id);
1625
+ const cached = this.assessments.get(id);
1626
+ if (cached && cached.signature === signature && cached.profile === profile) return cached.assessment;
1627
+ const assessment = this.profiles.assess(id, conditions);
1628
+ this.assessments.set(id, {
1629
+ signature,
1630
+ profile,
1631
+ assessment
1632
+ });
1633
+ return assessment;
1634
+ }
1635
+ generationOf(cameraId) {
1636
+ const id = normalizeId(cameraId);
1637
+ const conditions = this.conditionsOf(id);
1638
+ const signature = this.conditionsSignature(conditions);
1639
+ const previous = this.lastConditions.get(id);
1640
+ if (previous === void 0) {
1641
+ this.lastConditions.set(id, signature);
1642
+ this.generations.set(id, 0);
1643
+ return 0;
1644
+ }
1645
+ if (previous === signature) return this.generations.get(id) ?? 0;
1646
+ const next = (this.generations.get(id) ?? 0) + 1;
1647
+ this.lastConditions.set(id, signature);
1648
+ this.generations.set(id, next);
1649
+ return next;
1650
+ }
541
1651
  session(cameraId) {
542
1652
  const existing = this.sessions.get(cameraId);
543
1653
  if (existing) return existing;
@@ -550,14 +1660,12 @@
550
1660
  video: null,
551
1661
  preview: null,
552
1662
  startPromise: null,
553
- mirrored: false,
554
1663
  activeDeviceId: ""
555
1664
  };
556
1665
  this.sessions.set(cameraId, session);
557
1666
  return session;
558
1667
  }
559
1668
  async start(session, options) {
560
- session.mirrored = options.mirrored === true;
561
1669
  session.startPromise = (async () => {
562
1670
  const stream = await mediaDevices().getUserMedia(videoConstraints(options));
563
1671
  let video = null;
@@ -614,10 +1722,17 @@
614
1722
  ensurePreview(session) {
615
1723
  if (session.preview || !session.video) return;
616
1724
  const runtime = Scratch.vm.runtime;
617
- session.preview = createVideoPreview(runtime.renderer, session.video, this.previewMirrored(session), () => runtime.requestRedraw?.());
1725
+ session.preview = createVideoPreview(runtime.renderer, session.video, this.previewFlip(session), () => runtime.requestRedraw?.());
618
1726
  }
619
- previewMirrored(session) {
620
- return [...session.previewLeases.values()].some(Boolean);
1727
+ /**
1728
+ * How the preview is shown for a camera several consumers may be watching.
1729
+ *
1730
+ * Any consumer asking for a flipped preview flips it for everyone, which is
1731
+ * the same rule the previous boolean followed.
1732
+ */
1733
+ previewFlip(session) {
1734
+ for (const flip of session.previewLeases.values()) if (flip !== "none") return flip;
1735
+ return "none";
621
1736
  }
622
1737
  getFrameSource(session) {
623
1738
  if (!session.video || !session.stream) throw new Error("Shared camera is not running.");
@@ -626,10 +1741,14 @@
626
1741
  element: session.video,
627
1742
  width: session.video.videoWidth,
628
1743
  height: session.video.videoHeight,
629
- mirrored: session.mirrored,
1744
+ previewFlip: this.previewFlip(session),
630
1745
  deviceId: session.activeDeviceId
631
1746
  });
632
1747
  }
1748
+ stopWhenUnused(session) {
1749
+ if (this.sessions.get(session.cameraId) !== session) return;
1750
+ if (session.leases.size === 0) this.stopCameraSession(session.cameraId);
1751
+ }
633
1752
  stopCameraSession(cameraId) {
634
1753
  const session = this.sessions.get(cameraId);
635
1754
  if (!session) return;
@@ -648,6 +1767,7 @@
648
1767
  this.sessions.delete(cameraId);
649
1768
  this.blockLeases.delete(cameraId);
650
1769
  this.blockPreviewLeases.delete(cameraId);
1770
+ this.assessments.delete(cameraId);
651
1771
  }
652
1772
  toScratchBlock(block) {
653
1773
  return {
@@ -656,7 +1776,8 @@
656
1776
  text: Scratch.translate(block.text),
657
1777
  arguments: Object.fromEntries(Object.entries(block.arguments).map(([name, argument]) => [name, {
658
1778
  type: Scratch.ArgumentType[argument.type],
659
- defaultValue: argument.defaultValue
1779
+ defaultValue: argument.defaultValue,
1780
+ ...argument.menu === void 0 ? {} : { menu: argument.menu }
660
1781
  }]))
661
1782
  };
662
1783
  }