@eyepop.ai/eyepop 3.19.1 → 3.20.0

package/dist/eyepop.index.js

@@ -8693,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,
@@ -8713,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);
 
@@ -9298,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";
@@ -9352,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");
@@ -9842,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" });
@@ -9856,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 = {
@@ -9937,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" });
@@ -9951,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 = {
@@ -10007,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) {
@@ -10067,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 });
     }
@@ -10114,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);
     }
@@ -10152,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) {
@@ -10206,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) {
@@ -10817,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;
@@ -10889,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) {
@@ -10910,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()");
     }
@@ -10948,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()");
     }
@@ -10976,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()");
     }
@@ -12895,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) {
@@ -12999,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"));
     }
@@ -13151,8 +13439,10 @@ var index_default = EyePop;
   ModelTrainingStage,
   ModelType,
   MotionModel,
+  PointCloud,
   PopComponentType,
   PredictionVersion,
+  QUATERNION_TOLERANCE,
   Semaphore,
   Stream,
   TaskMode,
@@ -13171,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: