@eyepop.ai/eyepop 3.19.0 → 3.20.0

package/dist/eyepop.index.js

@@ -8677,6 +8677,7 @@ __export(index_exports, {
   EvaluationStatus: () => EvaluationStatus,
   ExportedBy: () => ExportedBy,
   EyePop: () => EyePop,
+  EyePopDataWebSocketError: () => EyePopDataWebSocketError,
   EyepopLineDecoder: () => EyepopLineDecoder,
   ForwardOperatorType: () => ForwardOperatorType,
   InferenceType: () => InferenceType,
@@ -8692,8 +8693,10 @@ __export(index_exports, {
   ModelTrainingStage: () => ModelTrainingStage,
   ModelType: () => ModelType,
   MotionModel: () => MotionModel,
+  PointCloud: () => PointCloud,
   PopComponentType: () => PopComponentType,
   PredictionVersion: () => PredictionVersion,
+  QUATERNION_TOLERANCE: () => QUATERNION_TOLERANCE,
   Semaphore: () => Semaphore,
   Stream: () => Stream,
   TaskMode: () => TaskMode,
@@ -8712,13 +8715,19 @@ __export(index_exports, {
   WorkflowPhase: () => WorkflowPhase,
   accessTokenCredential: () => accessTokenCredential,
   apiKeyCredential: () => apiKeyCredential,
+  cloudOfDepth: () => cloudOfDepth,
+  cloudOfObject: () => cloudOfObject,
+  cloudsOfPrediction: () => cloudsOfPrediction,
   decodeDepthMap: () => decodeDepthMap,
+  decodePointCloud: () => decodePointCloud,
   default: () => index_default,
   encodeMultipartFormData: () => encodeMultipartFormData,
   getBaseUrl: () => getBaseUrl,
   randomMultipartBoundary: () => randomMultipartBoundary,
   readableStreamFromString: () => readableStreamFromString,
-  resolveAuth: () => resolveAuth
+  resolveAuth: () => resolveAuth,
+  validateCamera: () => validateCamera,
+  validatePop: () => validatePop
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -9297,6 +9306,67 @@ Content-Disposition: form-data; name="${part.name}"\r
   });
 }
 
+// camera.ts
+var QUATERNION_TOLERANCE = 1e-3;
+function isFinite_(value) {
+  return value === void 0 || Number.isFinite(value);
+}
+function validateCamera(camera) {
+  if (camera.intrinsics !== void 0 && camera.hfovDegrees !== void 0) {
+    throw new Error("camera.intrinsics and camera.hfovDegrees are alternatives, supply one");
+  }
+  if (camera.intrinsics === void 0 && camera.hfovDegrees === void 0) {
+    throw new Error("camera requires either camera.intrinsics or camera.hfovDegrees");
+  }
+  if (camera.hfovDegrees !== void 0) {
+    if (!(camera.hfovDegrees > 0 && camera.hfovDegrees < 180)) {
+      throw new Error("camera.hfovDegrees must be a horizontal field of view in (0, 180) degrees");
+    }
+  } else {
+    const intrinsics = camera.intrinsics;
+    for (const [name, focal] of [
+      ["fx", intrinsics.fx],
+      ["fy", intrinsics.fy]
+    ]) {
+      if (!(focal > 0) || !Number.isFinite(focal)) {
+        throw new Error(`camera.intrinsics.${name} must be a positive, finite focal length`);
+      }
+    }
+    for (const [name, principal, extent] of [
+      ["cx", intrinsics.cx, "width"],
+      ["cy", intrinsics.cy, "height"]
+    ]) {
+      if (!(principal >= 0 && principal <= 1)) {
+        throw new Error(`camera.intrinsics.${name} must be within [0, 1] of the frame ${extent}`);
+      }
+    }
+  }
+  if (camera.distortion !== void 0) {
+    for (const name of ["k1", "k2", "p1", "p2", "k3"]) {
+      if (!isFinite_(camera.distortion[name])) {
+        throw new Error(`camera.distortion.${name} must be a finite number`);
+      }
+    }
+  }
+  if (camera.extrinsics !== void 0) {
+    const translation = camera.extrinsics.translation;
+    if (translation !== void 0) {
+      for (const axis of ["x", "y", "z"]) {
+        if (!Number.isFinite(translation[axis])) {
+          throw new Error(`camera.extrinsics.translation.${axis} must be a finite number`);
+        }
+      }
+    }
+    const rotation = camera.extrinsics.rotation;
+    if (rotation !== void 0) {
+      const norm = Math.sqrt(rotation.w ** 2 + rotation.x ** 2 + rotation.y ** 2 + rotation.z ** 2);
+      if (!(Math.abs(norm - 1) <= QUATERNION_TOLERANCE)) {
+        throw new Error("camera.extrinsics.rotation must be a unit quaternion");
+      }
+    }
+  }
+}
+
 // worker/worker_types.ts
 var PredictionVersion = /* @__PURE__ */ ((PredictionVersion3) => {
   PredictionVersion3[PredictionVersion3["V1"] = 1] = "V1";
@@ -9351,6 +9421,16 @@ var ContourType = /* @__PURE__ */ ((ContourType2) => {
   ContourType2["RECTANGLE"] = "rectangle";
   return ContourType2;
 })(ContourType || {});
+function validatePop(pop) {
+  if (pop.depthMap !== void 0) {
+    if (pop.depthMap.ability === void 0 === (pop.depthMap.abilityUuid === void 0)) {
+      throw new Error("depthMap requires exactly one of ability or abilityUuid");
+    }
+  }
+  if (pop.defaults?.camera !== void 0) {
+    validateCamera(pop.defaults.camera);
+  }
+}
 
 // worker/webrtc_whip.ts
 var import_uuid2 = require("uuid");
@@ -9841,7 +9921,7 @@ var UploadJob = class extends AbstractJob {
         }
       }
       const postUrl = `${session.baseUrl.replace(/\/+$/, "")}/pipelines/${session.pipelineId}/source?${queryParams.toString()}`;
-      if (this._params.componentParams || this._params.roi) {
+      if (this._params.componentParams || this._params.roi || this._params.camera) {
         const formData = new FormData();
         if (this._params.componentParams) {
           const blob = new Blob([JSON.stringify(this._params.componentParams)], { type: "application/json" });
@@ -9855,6 +9935,10 @@ var UploadJob = class extends AbstractJob {
           const blob = new Blob([JSON.stringify(this._params.fps)], { type: "application/json" });
           formData.append("fps", blob);
         }
+        if (this._params.camera) {
+          const blob = new Blob([JSON.stringify(this._params.camera)], { type: "application/json" });
+          formData.append("camera", blob);
+        }
         const fileBlob = await new Response(await this.uploadBody()).blob();
         formData.append("file", fileBlob);
         const headers = {
@@ -9936,7 +10020,7 @@ var UploadJob = class extends AbstractJob {
         }
       }
       const postUrl = `${session.baseUrl.replace(/\/+$/, "")}/pipelines/${session.pipelineId}/source?${queryParams.toString()}`;
-      if (this._params.componentParams || this._params.roi) {
+      if (this._params.componentParams || this._params.roi || this._params.camera) {
         const formData = new FormData();
         if (this._params.componentParams) {
           const blob = new Blob([JSON.stringify(this._params.componentParams)], { type: "application/json" });
@@ -9950,6 +10034,10 @@ var UploadJob = class extends AbstractJob {
           const blob = new Blob([JSON.stringify(this._params.fps)], { type: "application/json" });
           formData.append("fps", blob);
         }
+        if (this._params.camera) {
+          const blob = new Blob([JSON.stringify(this._params.camera)], { type: "application/json" });
+          formData.append("camera", blob);
+        }
         const fileBlob = await new Response(await this.uploadBody()).blob();
         formData.append("file", fileBlob);
         const headers = {
@@ -10006,6 +10094,7 @@ var LoadFromJob = class extends AbstractJob {
       params: this._params.componentParams,
       roi: this._params.roi,
       fps: this._params.fps,
+      camera: this._params.camera,
       version: this._version
     };
     if (this._params.motionDetect) {
@@ -10066,6 +10155,9 @@ var UploadGroupJob = class extends AbstractJob {
     if (this._params.fps) {
       parts.push({ name: "fps", contentType: "application/json", content: JSON.stringify(this._params.fps) });
     }
+    if (this._params.camera) {
+      parts.push({ name: "camera", contentType: "application/json", content: JSON.stringify(this._params.camera) });
+    }
     for (const source of this._sources) {
       parts.push({ name: "file", contentType: source.mimeType, content: source.stream });
     }
@@ -10113,6 +10205,9 @@ var LoadFromGroupJob = class extends AbstractJob {
     if (this._params.roi) {
       body["roi"] = this._params.roi;
     }
+    if (this._params.camera) {
+      body["camera"] = this._params.camera;
+    }
     if (this._params.motionDetect) {
       Object.assign(body, this._params.motionDetect);
     }
@@ -10151,6 +10246,7 @@ var LoadFromAssetUuidJob = class extends AbstractJob {
       params: this._params.componentParams,
       roi: this._params.roi,
       fps: this._params.fps,
+      camera: this._params.camera,
       version: this._version
     };
     if (this._params.motionDetect) {
@@ -10205,6 +10301,7 @@ var LoadMediaStreamJob = class extends AbstractJob {
       params: this._params.componentParams,
       roi: this._params.roi,
       fps: this._params.fps,
+      camera: this._params.camera,
       version: this._version
     };
     if (this._params.motionDetect) {
@@ -10816,6 +10913,7 @@ var _WorkerEndpoint = class _WorkerEndpoint extends Endpoint {
     return this.options().pop || null;
   }
   async changePop(pop) {
+    validatePop(pop);
     if (this.options().popId == "transient" /* Transient */) {
       await this.changeTransientPop(pop);
       return;
@@ -10888,7 +10986,22 @@ var _WorkerEndpoint = class _WorkerEndpoint extends Endpoint {
       return Promise.reject("unknown source type");
     }
   }
+  /**
+   * Reject a source's calibration before any work is started for it.
+   *
+   * Called by every entry point that takes ProcessParams rather than at the
+   * one boundary they share, because they have none: the group methods build
+   * their jobs directly instead of going through processV2. It runs before
+   * the concurrency limit is acquired, so a request that can never be sent
+   * does not hold a slot.
+   */
+  validateProcessParams(params) {
+    if (params.camera !== void 0) {
+      validateCamera(params.camera);
+    }
+  }
   async processV2(request) {
+    this.validateProcessParams(request);
     if (request.source.file !== void 0) {
       return this.uploadFile(request.source, request);
     } else if (request.source.stream !== void 0) {
@@ -10909,6 +11022,7 @@ var _WorkerEndpoint = class _WorkerEndpoint extends Endpoint {
     if (paths.length === 0) {
       throw new Error("upload group requires at least one path");
     }
+    this.validateProcessParams(params);
     if (!this._baseUrl || !this._pipelineId || !this._client || !this._limit) {
       throw new Error("endpoint not connected, use connect()");
     }
@@ -10947,6 +11061,7 @@ var _WorkerEndpoint = class _WorkerEndpoint extends Endpoint {
     if (mimeTypes !== void 0 && mimeTypes.length !== streams.length) {
       throw new Error("mimeTypes must have the same length as streams");
     }
+    this.validateProcessParams(params);
     if (!this._baseUrl || !this._pipelineId || !this._client || !this._limit) {
       throw new Error("endpoint not connected, use connect()");
     }
@@ -10975,6 +11090,7 @@ var _WorkerEndpoint = class _WorkerEndpoint extends Endpoint {
     if (urls.length === 0) {
       throw new Error("load from group requires at least one url");
     }
+    this.validateProcessParams(params);
     if (!this._baseUrl || !this._pipelineId || !this._client || !this._limit) {
       throw new Error("endpoint not connected, use connect()");
     }
@@ -11522,57 +11638,8 @@ if ("document" in globalThis && "implementation" in globalThis.document) {
   };
 }
 
-// ../../node_modules/url-join/lib/url-join.js
-function normalize(strArray) {
-  var resultArray = [];
-  if (strArray.length === 0) {
-    return "";
-  }
-  if (typeof strArray[0] !== "string") {
-    throw new TypeError("Url must be a string. Received " + strArray[0]);
-  }
-  if (strArray[0].match(/^[^/:]+:\/*$/) && strArray.length > 1) {
-    var first = strArray.shift();
-    strArray[0] = first + strArray[0];
-  }
-  if (strArray[0].match(/^file:\/\/\//)) {
-    strArray[0] = strArray[0].replace(/^([^/:]+):\/*/, "$1:///");
-  } else {
-    strArray[0] = strArray[0].replace(/^([^/:]+):\/*/, "$1://");
-  }
-  for (var i = 0; i < strArray.length; i++) {
-    var component = strArray[i];
-    if (typeof component !== "string") {
-      throw new TypeError("Url must be a string. Received " + component);
-    }
-    if (component === "") {
-      continue;
-    }
-    if (i > 0) {
-      component = component.replace(/^[\/]+/, "");
-    }
-    if (i < strArray.length - 1) {
-      component = component.replace(/[\/]+$/, "");
-    } else {
-      component = component.replace(/[\/]+$/, "/");
-    }
-    resultArray.push(component);
-  }
-  var str = resultArray.join("/");
-  str = str.replace(/\/(\?|&|#[^!])/g, "$1");
-  var parts = str.split("?");
-  str = parts.shift() + (parts.length > 0 ? "?" : "") + parts.join("&");
-  return str;
-}
-function urlJoin() {
-  var input;
-  if (typeof arguments[0] === "object") {
-    input = arguments[0];
-  } else {
-    input = [].slice.call(arguments);
-  }
-  return normalize(input);
-}
+// data/data_endpoint.ts
+var import_url_join = __toESM(require("url-join"));
 
 // data/data_types.ts
 var DataApiType = /* @__PURE__ */ ((DataApiType2) => {
@@ -11925,6 +11992,33 @@ var EvaluateDatasetJob = class {
 // data/data_endpoint.ts
 var WS_INITIAL_RECONNECT_DELAY = 1e3;
 var WS_MAX_RECONNECT_DELAY = 6e4;
+function ws_origin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}
+function ws_failure_reason(event, sourceError) {
+  if (sourceError instanceof Error) {
+    return sourceError.message;
+  }
+  if (typeof sourceError === "string") {
+    return sourceError;
+  }
+  return event?.message ?? "";
+}
+var EyePopDataWebSocketError = class extends Error {
+  constructor(url, event) {
+    const sourceError = event?.error ?? event;
+    const reason = ws_failure_reason(event, sourceError);
+    super(reason ? `EyePop Dataset event WebSocket connection failed: ${reason}` : "EyePop Dataset event WebSocket connection failed");
+    this.code = "DATA_WEBSOCKET_CONNECTION_FAILED";
+    this.name = "EyePopDataWebSocketError";
+    this.endpoint = ws_origin(url);
+    this.sourceError = sourceError;
+  }
+};
 function omit_nulls(_, value) {
   if (value === null) {
     return void 0;
@@ -11938,6 +12032,9 @@ var DataEndpoint = class extends Endpoint {
     this.vlmApiUrl = null;
     this._ws = null;
     this._ws_current_reconnect_delay = null;
+    this._ws_reconnect_timeout = null;
+    this._ws_reconnect_enabled = false;
+    this._ws_connecting = null;
     this._accountId = options.accountId || null;
     this._account_event_handlers = [];
     this._dataset_uuid_to_event_handlers = /* @__PURE__ */ new Map();
@@ -11961,14 +12058,15 @@ var DataEndpoint = class extends Endpoint {
     };
   }
   async disconnect(wait = true) {
+    this._ws_reconnect_enabled = false;
+    if (this._ws_reconnect_timeout) {
+      clearTimeout(this._ws_reconnect_timeout);
+      this._ws_reconnect_timeout = null;
+    }
     this.datasetApiUrl = null;
     this.vlmApiUrl = null;
     if (this._ws) {
-      try {
-        this._ws.close();
-      } catch (e) {
-        this._logger.warn("ignored exception", e);
-      }
+      this.close_ws(this._ws, "unsubscribe");
       this._ws = null;
     }
     await super.disconnect(wait);
@@ -12006,13 +12104,14 @@ var DataEndpoint = class extends Endpoint {
     const vlmApiUrl = new URL(config.vlm_api_url, this.eyepopUrl());
     this.vlmApiUrl = vlmApiUrl.toString();
     if (this.options().disableWs) {
+      this._ws_reconnect_enabled = false;
       this._logger.info("disabled ws connection");
     } else {
       await this.reconnect_ws();
     }
     if (this.options().useCookie) {
       const client = this._client;
-      const url = urlJoin(this.datasetApiUrl, "security", "check?set_cookie=true");
+      const url = (0, import_url_join.default)(this.datasetApiUrl, "security", "check?set_cookie=true");
       const headers2 = {
         Authorization: await this.authorizationHeader()
       };
@@ -12029,37 +12128,68 @@ var DataEndpoint = class extends Endpoint {
     return Promise.resolve(this);
   }
   async reconnect_ws() {
+    if (this._ws_connecting) {
+      return this._ws_connecting;
+    }
+    const connecting = this.open_ws();
+    this._ws_connecting = connecting;
+    try {
+      await connecting;
+    } finally {
+      this._ws_connecting = null;
+    }
+  }
+  async open_ws() {
     if (this._ws) {
-      this._ws.close();
+      this.close_ws(this._ws, "unsubscribe");
       this._ws = null;
     }
     const baseUrl = this.datasetApiUrl?.replace("https://", "wss://").replace("http://", "ws://");
     if (!baseUrl) {
       return;
     }
-    const ws_url = urlJoin(baseUrl, "events");
+    const ws_url = (0, import_url_join.default)(baseUrl, "events");
     this._requestLogger.debug("about to connect ws to: %s", ws_url);
     return new Promise((resolve, reject) => {
+      let settled = false;
+      const settle_ok = () => {
+        settled = true;
+        resolve();
+      };
+      const settle_err = (error) => {
+        settled = true;
+        reject(error);
+      };
       const ws = createWebSocket(ws_url);
       if (!ws) {
-        return resolve();
+        return settle_ok();
       }
       this._ws = ws;
-      ws.onopen = async () => {
-        const auth_header = await this.authorizationHeader();
-        let msg = JSON.stringify({ authorization: auth_header });
-        this._requestLogger.debug("ws send: %s", msg);
-        ws.send(msg);
-        msg = JSON.stringify({ subscribe: { account_uuid: this._accountId } });
-        this._requestLogger.debug("ws send: %s", msg);
-        ws.send(msg);
-        for (let dataset_uuid in this._dataset_uuid_to_event_handlers.keys()) {
-          const msg2 = JSON.stringify({ subscribe: { dataset_uuid } });
-          this._requestLogger.debug("ws send: %s", msg2);
-          ws.send(msg2);
-        }
-        this._ws_current_reconnect_delay = WS_INITIAL_RECONNECT_DELAY;
-        resolve();
+      ws.onopen = () => {
+        void this.authorizationHeader().then((auth_header) => {
+          if (this._ws !== ws) {
+            this.close_ws(ws, "unsubscribe");
+            settle_ok();
+            return;
+          }
+          let msg = JSON.stringify({ authorization: auth_header });
+          this._requestLogger.debug("ws send: %s", msg);
+          ws.send(msg);
+          msg = JSON.stringify({ subscribe: { account_uuid: this._accountId } });
+          this._requestLogger.debug("ws send: %s", msg);
+          ws.send(msg);
+          for (const dataset_uuid of this._dataset_uuid_to_event_handlers.keys()) {
+            const msg2 = JSON.stringify({ subscribe: { dataset_uuid } });
+            this._requestLogger.debug("ws send: %s", msg2);
+            ws.send(msg2);
+          }
+          this._ws_current_reconnect_delay = WS_INITIAL_RECONNECT_DELAY;
+          this._ws_reconnect_enabled = true;
+          settle_ok();
+        }).catch((error) => {
+          this.close_ws(ws, "authorization failed", 1011);
+          settle_err(error);
+        });
       };
       ws.onmessage = (event) => {
         const data = JSON.parse(event.data);
@@ -12070,24 +12200,54 @@ var DataEndpoint = class extends Endpoint {
       ws.onclose = (event) => {
         const { code, reason } = event;
         this._requestLogger.debug("ws closed: %d %s", code, reason);
-        if (reason !== "unsubscribe") {
-          if (!this._ws_current_reconnect_delay) {
-            this._ws_current_reconnect_delay = WS_INITIAL_RECONNECT_DELAY;
-          } else if (this._ws_current_reconnect_delay < WS_MAX_RECONNECT_DELAY) {
-            this._ws_current_reconnect_delay *= 1.5;
-          }
-          setTimeout(async () => {
-            await this.reconnect_ws();
-          }, this._ws_current_reconnect_delay);
+        if (!settled) {
+          settle_err(new EyePopDataWebSocketError(ws_url, new Error(`closed before the connection was established: ${code} ${reason}`)));
+        }
+        if (this._ws !== ws) {
+          return;
         }
+        this._ws = null;
+        this.schedule_ws_reconnect();
       };
       ws.onerror = (event) => {
-        this._logger.error(event);
-        reject(event);
+        const error = new EyePopDataWebSocketError(ws_url, event);
+        this._logger.error({ err: error }, "dataset event WebSocket connection failed");
+        settle_err(error);
         return null;
       };
     });
   }
+  close_ws(ws, reason, code = 1e3) {
+    try {
+      ws.close(code, reason);
+    } catch (e) {
+      this._logger.warn({ err: e }, "ignored exception closing the dataset event WebSocket");
+    }
+  }
+  schedule_ws_reconnect() {
+    if (!this._ws_reconnect_enabled || this._ws_reconnect_timeout) {
+      return;
+    }
+    if (!this._ws_current_reconnect_delay) {
+      this._ws_current_reconnect_delay = WS_INITIAL_RECONNECT_DELAY;
+    } else if (this._ws_current_reconnect_delay < WS_MAX_RECONNECT_DELAY) {
+      this._ws_current_reconnect_delay *= 1.5;
+    }
+    this._ws_reconnect_timeout = setTimeout(() => {
+      if (!this._ws_reconnect_enabled) {
+        this._ws_reconnect_timeout = null;
+        return;
+      }
+      void this.reconnect_ws().catch((error) => {
+        this._requestLogger.debug("dataset event WebSocket reconnect failed: %s", error);
+      }).finally(() => {
+        this._ws_reconnect_timeout = null;
+        if (!this._ws) {
+          this.schedule_ws_reconnect();
+        }
+      });
+    }, this._ws_current_reconnect_delay);
+  }
   options() {
     return this._options;
   }
@@ -12112,7 +12272,7 @@ var DataEndpoint = class extends Endpoint {
         body: options.body
       };
       this._requestLogger.debug("Request - " + ri.method + " " + path2 + " BODY: " + (ri.body ? ri.body : ""));
-      return await client.fetch(urlJoin(baseUrl ?? "", path2), ri);
+      return await client.fetch((0, import_url_join.default)(baseUrl ?? "", path2), ri);
     });
     if (response.status === 204) {
       return null;
@@ -12850,6 +13010,176 @@ function decodeDepthMap(depth) {
   return new DepthMap(depth.width, depth.height, values);
 }
 
+// point_cloud.ts
+var VALUES_PER_POINT = 3;
+var isLittleEndianPlatform2 = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
+function base64ToBytes2(base64) {
+  if (typeof Buffer !== "undefined") {
+    const buffer = Buffer.from(base64, "base64");
+    return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+var PointCloud = class {
+  constructor(width, height, points, box) {
+    this.width = width;
+    this.height = height;
+    this.points = points;
+    this.box = box;
+  }
+  /**
+   * The world point for pixel (i, j), or undefined where the worker placed none.
+   *
+   * (i, j) indexes the cloud's own grid - the mask bitmap, or the depth map
+   * for a scene cloud: i is the column, j is the row.
+   */
+  at(i, j) {
+    if (!(i >= 0 && i < this.width && j >= 0 && j < this.height)) {
+      throw new Error(`(${i}, ${j}) is outside a ${this.width}x${this.height} cloud`);
+    }
+    const offset = (j * this.width + i) * VALUES_PER_POINT;
+    const x = this.points[offset];
+    const y = this.points[offset + 1];
+    const z = this.points[offset + 2];
+    if (Number.isNaN(x) || Number.isNaN(y) || Number.isNaN(z)) {
+      return void 0;
+    }
+    return { x, y, z };
+  }
+  /**
+   * The world point for a source frame coordinate inside the cloud's box.
+   *
+   * Needs a cloud built with cloudOfObject(), or with cloudOfDepth() and the
+   * frame size: the grid covers a box, and nothing else knows where it sits.
+   */
+  atSource(x, y) {
+    if (this.box === void 0) {
+      throw new Error("atSource needs a box; build with cloudOfObject or cloudOfDepth");
+    }
+    if (!(this.box.width > 0) || !(this.box.height > 0)) {
+      throw new Error(`invalid bounding box extent: ${this.box.width}x${this.box.height}`);
+    }
+    const i = Math.min(Math.max(Math.floor((x - this.box.x) / this.box.width * this.width), 0), this.width - 1);
+    const j = Math.min(Math.max(Math.floor((y - this.box.y) / this.box.height * this.height), 0), this.height - 1);
+    return this.at(i, j);
+  }
+  isPlaced(i, j) {
+    return this.at(i, j) !== void 0;
+  }
+  /**
+   * Just the points the worker placed.
+   *
+   * The shape a scatter plot or an export wants: the grid with its NaN holes
+   * dropped, and no mask to apply first.
+   */
+  get placedPoints() {
+    const placed = [];
+    for (let offset = 0; offset < this.points.length; offset += VALUES_PER_POINT) {
+      const x = this.points[offset];
+      const y = this.points[offset + 1];
+      const z = this.points[offset + 2];
+      if (!Number.isNaN(x) && !Number.isNaN(y) && !Number.isNaN(z)) {
+        placed.push({ x, y, z });
+      }
+    }
+    return placed;
+  }
+  /**
+   * Per axis (min, max) in metres over the placed points, or undefined if none were.
+   *
+   * The counterpart to DepthMap's finiteMin/finiteMax, which are one axis
+   * because a depth map has one value per pixel.
+   */
+  get bounds() {
+    let found = false;
+    const min = { x: Number.POSITIVE_INFINITY, y: Number.POSITIVE_INFINITY, z: Number.POSITIVE_INFINITY };
+    const max = { x: Number.NEGATIVE_INFINITY, y: Number.NEGATIVE_INFINITY, z: Number.NEGATIVE_INFINITY };
+    for (let offset = 0; offset < this.points.length; offset += VALUES_PER_POINT) {
+      const x = this.points[offset];
+      const y = this.points[offset + 1];
+      const z = this.points[offset + 2];
+      if (Number.isNaN(x) || Number.isNaN(y) || Number.isNaN(z)) {
+        continue;
+      }
+      found = true;
+      min.x = Math.min(min.x, x);
+      min.y = Math.min(min.y, y);
+      min.z = Math.min(min.z, z);
+      max.x = Math.max(max.x, x);
+      max.y = Math.max(max.y, y);
+      max.z = Math.max(max.z, z);
+    }
+    return found ? { min, max } : void 0;
+  }
+};
+function decode(width, height, world, box) {
+  if (!Number.isSafeInteger(width) || width <= 0 || !Number.isSafeInteger(height) || height <= 0) {
+    throw new Error(`invalid point cloud dimensions: ${width}x${height}`);
+  }
+  const bytes = base64ToBytes2(world);
+  const count = width * height * VALUES_PER_POINT;
+  if (bytes.byteLength !== count * 4) {
+    throw new Error(`'world' holds ${bytes.byteLength} bytes, expected ${count * 4} for ${width}x${height} xyz float32`);
+  }
+  let points;
+  if (isLittleEndianPlatform2) {
+    const aligned = new Uint8Array(bytes);
+    points = new Float32Array(aligned.buffer, 0, count);
+  } else {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    points = new Float32Array(count);
+    for (let i = 0; i < count; i++) {
+      points[i] = view.getFloat32(i * 4, true);
+    }
+  }
+  return new PointCloud(width, height, points, box);
+}
+function decodePointCloud(mask, box) {
+  if (mask === void 0 || mask.world === void 0) {
+    return void 0;
+  }
+  return decode(mask.width, mask.height, mask.world, box);
+}
+function cloudOfObject(obj) {
+  if (obj === void 0 || obj.mask === void 0) {
+    return void 0;
+  }
+  return decodePointCloud(obj.mask, { x: obj.x, y: obj.y, width: obj.width, height: obj.height });
+}
+function cloudOfDepth(depth, sourceWidth, sourceHeight) {
+  if (depth === void 0 || depth.world === void 0) {
+    return void 0;
+  }
+  const box = sourceWidth && sourceHeight ? { x: 0, y: 0, width: sourceWidth, height: sourceHeight } : void 0;
+  return decode(depth.width, depth.height, depth.world, box);
+}
+function cloudsOfPrediction(prediction) {
+  const clouds = [];
+  if (prediction === void 0) {
+    return clouds;
+  }
+  const walk = (objects) => {
+    for (const obj of objects ?? []) {
+      const cloud = cloudOfObject(obj);
+      if (cloud !== void 0) {
+        clouds.push(cloud);
+      }
+      walk(obj.objects);
+    }
+  };
+  walk(prediction.objects);
+  const scene = cloudOfDepth(prediction.depth, prediction.source_width, prediction.source_height);
+  if (scene !== void 0) {
+    clouds.push(scene);
+  }
+  return clouds;
+}
+
 // worker/webrtc_whep.ts
 var WebrtcWhep = class extends WebrtcBase {
   constructor(ingressId, getSession, client, requestLogger) {
@@ -12954,6 +13284,9 @@ var EyePop;
   } : void 0;
   EyePop2.endpoint = workerEndpoint;
   function workerEndpoint(opts = {}) {
+    if (opts.pop !== void 0) {
+      validatePop(opts.pop);
+    }
     if (opts.isLocalMode === void 0) {
       opts.isLocalMode = stringToBooleanSafe(readEnv("EYEPOP_LOCAL_MODE"));
     }
@@ -13090,6 +13423,7 @@ var index_default = EyePop;
   EvaluationStatus,
   ExportedBy,
   EyePop,
+  EyePopDataWebSocketError,
   EyepopLineDecoder,
   ForwardOperatorType,
   InferenceType,
@@ -13105,8 +13439,10 @@ var index_default = EyePop;
   ModelTrainingStage,
   ModelType,
   MotionModel,
+  PointCloud,
   PopComponentType,
   PredictionVersion,
+  QUATERNION_TOLERANCE,
   Semaphore,
   Stream,
   TaskMode,
@@ -13125,12 +13461,18 @@ var index_default = EyePop;
   WorkflowPhase,
   accessTokenCredential,
   apiKeyCredential,
+  cloudOfDepth,
+  cloudOfObject,
+  cloudsOfPrediction,
   decodeDepthMap,
+  decodePointCloud,
   encodeMultipartFormData,
   getBaseUrl,
   randomMultipartBoundary,
   readableStreamFromString,
-  resolveAuth
+  resolveAuth,
+  validateCamera,
+  validatePop
 });
 /*! Bundled license information: