@wandelbots/nova-js 4.2.0 → 4.3.0-pr.318.6592c26

package/dist/experimental/math/index.d.mts

@@ -0,0 +1,107 @@
+import { bc as Pose$1, t as Nova } from "../../Nova-DdbUm145.mjs";
+//#region src/lib/experimental/math/Pose.d.ts
+/**
+ * A `Pose` (position + axis-angle orientation) with methods for composing
+ * and inverting transforms. Instances are plain-data compatible with the
+ * wire-format `PoseData` type (own `position`/`orientation` properties only,
+ * no enumerable methods), so they can be passed directly back into API calls
+ * that expect a pose.
+ *
+ * Poses returned from `NovaAPIClient`/`Nova` are automatically upgraded to
+ * `Pose` instances; construct one directly only when you have a pose from
+ * elsewhere (e.g. a websocket message).
+ */
+declare class Pose implements Pose$1 {
+  readonly position: number[];
+  readonly orientation: number[];
+  constructor(position?: number[], orientation?: number[]);
+  static from(pose: Pose$1): Pose;
+  static identity(): Pose;
+  /**
+   * Compose this pose with `other`, treating `other` as being expressed in
+   * this pose's coordinate frame. Equivalent to the homogeneous transform
+   * product `this * other`: applying the result to a point is the same as
+   * applying `other` first, then `this`.
+   */
+  multiply(other: Pose$1): Pose;
+  /** The inverse transform, such that `pose.multiply(pose.inverse())` is the identity pose. */
+  inverse(): Pose;
+  /** Apply this pose's transform to a point, returning the transformed point. */
+  transformPoint(point: number[]): number[];
+  /** Compare to another pose within a tolerance, since floating-point pose math rarely produces exact equality. */
+  equals(other: Pose$1, epsilon?: number): boolean;
+  toJSON(): Pose$1;
+}
+//#endregion
+//#region src/lib/experimental/math/augmentMath.d.ts
+type PoseKeys = keyof Pose$1;
+type IsExactlyPoseData<T> = [Exclude<keyof T, PoseKeys>] extends [never] ? [Exclude<PoseKeys, keyof T>] extends [never] ? true : false : false;
+type MaxDepth = [unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown];
+type AugmentPosesCore<T, Depth extends readonly unknown[]> = Depth["length"] extends MaxDepth["length"] ? T : IsExactlyPoseData<T> extends true ? Pose : T extends readonly (infer U)[] ? DeepPoseAugmented<U, [...Depth, unknown]>[] : T extends object ? { [K in keyof T]: DeepPoseAugmented<T[K], [...Depth, unknown]>; } : T;
+/**
+ * Type-level counterpart to `augmentPoses`: recursively replaces any
+ * `PoseData`-shaped field with `Pose` (distributing over unions, e.g. so
+ * optional `Pose | undefined` fields keep the `| undefined`), so the static
+ * type matches what's actually returned at runtime.
+ */
+type DeepPoseAugmented<T, Depth extends readonly unknown[] = []> = T extends unknown ? AugmentPosesCore<T, Depth> : never;
+/**
+ * Recursively walks a parsed API response/request body, upgrading any
+ * `Pose`-shaped objects in place to `Pose` instances so they gain math
+ * methods (`multiply`, `inverse`, ...) while remaining JSON/wire-compatible.
+ * Used by `augmentMath` for `nova.api.*` responses; exported so it can also
+ * be applied manually to e.g. websocket messages.
+ */
+declare function augmentPoses<T>(value: T): DeepPoseAugmented<T>;
+type WithAugmentedPosesCore<T, Depth extends readonly unknown[]> = Depth["length"] extends MaxDepth["length"] ? T : T extends ((...args: infer A) => Promise<infer R>) ? (...args: A) => Promise<DeepPoseAugmented<R>> : T extends object ? { [K in keyof T]: WithAugmentedPosesCore<T[K], [...Depth, unknown]>; } : T;
+/**
+ * Recursively maps every method on `Nova["api"]` (and its nested API groups)
+ * so calls are typed as returning `DeepPoseAugmented` results, matching what
+ * `augmentMath` does at runtime.
+ */
+type WithAugmentedPoses<T> = WithAugmentedPosesCore<T, []>;
+type NovaWithMath = Omit<Nova, "api"> & {
+  readonly api: WithAugmentedPoses<Nova["api"]>;
+};
+/**
+ * Wraps a `Nova` instance so every `nova.api.*` call automatically upgrades
+ * `Pose`-shaped fields in its response to `Pose` instances (with math
+ * methods like `multiply`/`inverse`). Returns a new proxied view - does not
+ * mutate the original `nova` instance.
+ */
+declare function augmentMath(nova: Nova): NovaWithMath;
+//#endregion
+//#region src/lib/experimental/math/Quaternion.d.ts
+/**
+ * Internal quaternion helpers used to compose/invert the axis-angle
+ * `orientation` vectors used by the NOVA API's `Pose` type. Rotation vectors
+ * are converted to quaternions for composition (numerically stable, unlike
+ * composing axis-angle vectors directly) and converted back at the boundary.
+ */
+type Quaternion = {
+  w: number;
+  x: number;
+  y: number;
+  z: number;
+};
+/** Convert an axis-angle rotation vector [rx, ry, rz] to a unit quaternion. */
+declare function axisAngleToQuaternion(r: number[]): Quaternion;
+/**
+ * Convert a unit quaternion back to an axis-angle rotation vector [rx, ry, rz],
+ * matching wb-robotix's `Quaternion::toRotationVector()` (ported from
+ * QuaternionBasePlugin.h): using `atan2` rather than `acos` keeps the angle
+ * canonically within [0, pi] regardless of which of the two antipodal unit
+ * quaternions (q or -q) represents the rotation, rather than acos's [0, 2*pi]
+ * range - important since composed poses need to match the same canonical
+ * rotation vector the robot controller itself would report for a pose.
+ */
+declare function quaternionToAxisAngle(q: Quaternion): number[];
+/** Hamilton product: composes rotations so that applying `multiplyQuaternions(a, b)` to a vector equals applying `b` then `a`. */
+declare function multiplyQuaternions(a: Quaternion, b: Quaternion): Quaternion;
+/** Conjugate of a unit quaternion equals its inverse. */
+declare function conjugateQuaternion(q: Quaternion): Quaternion;
+/** Rotate a 3D vector by a unit quaternion. */
+declare function rotateVectorByQuaternion(q: Quaternion, v: number[]): number[];
+//#endregion
+export { type DeepPoseAugmented, type NovaWithMath, Pose, type Pose$1 as PoseData, type Quaternion, augmentMath, augmentPoses, axisAngleToQuaternion, conjugateQuaternion, multiplyQuaternions, quaternionToAxisAngle, rotateVectorByQuaternion };
+//# sourceMappingURL=index.d.mts.map

package/dist/experimental/math/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../src/lib/experimental/math/Pose.ts","../../../src/lib/experimental/math/augmentMath.ts","../../../src/lib/experimental/math/Quaternion.ts"],"mappings":";;;;;;;;;;;;;cAkCa,gBAAgB;WAClB;WACA;EAGP,YAAA,qBACA;SAMK,KAAK,MAAM,SAAW;SAUtB,YAAY;;;;;;;EAUnB,SAAS,OAAO,SAAW;;EAc3B,WAAW;;EAeX,eAAe;;EAMf,OAAO,OAAO,QAAU;EAcxB,UAAU;;;;KC/GP,iBAAiB;KAEjB,kBAAkB,MAAM,cAAc,GAAG,8BACzC,QAAQ,gBAAgB;KAOxB;KAaA,iBACH,GACA,oCACE,wBAAwB,qBACxB,IACA,kBAAkB,kBAChB,OACA,0BAA0B,OACxB,kBAAkB,OAAO,qBACzB,sBACK,WAAW,IAAI,kBAAkB,EAAE,QAAQ,sBAC9C;;;;;;;KAQE,kBACV,GACA,yCACE,oBAAoB,iBAAiB,GAAG;;;;;;;;iBA2D5B,aAAa,GAAG,OAAO,IAAI,kBAAkB;KAKxD,uBACH,GACA,oCACE,wBAAwB,qBACxB,IACA,eAAc,YAAY,MAAM,cAAc,UACxC,MAAM,MAAM,QAAQ,kBAAkB,MAC1C,sBACK,WAAW,IAAI,uBAAuB,EAAE,QAAQ,sBACnD;;;;;;KAOH,mBAAmB,KAAK,uBAAuB;KAExC,eAAe,KAAK;WACrB,KAAK,mBAAmB;;;;;;;;iBA6BnB,YAAY,MAAM,OAAO;;;;;;;;;KC1J7B;EAAe;EAAW;EAAW;EAAW;;;iBAK5C,sBAAsB,cAAc;;;;;;;;;;iBAuBpC,sBAAsB,GAAG;;iBAWzB,oBAAoB,GAAG,YAAY,GAAG,aAAa;;iBAUnD,oBAAoB,GAAG,aAAa;;iBAKpC,yBAAyB,GAAG,YAAY"}

package/dist/experimental/math/index.mjs

@@ -0,0 +1,226 @@
+//#region src/lib/experimental/math/Quaternion.ts
+const EPSILON = 1e-12;
+/** Convert an axis-angle rotation vector [rx, ry, rz] to a unit quaternion. */
+function axisAngleToQuaternion(r) {
+	const rx = r[0] ?? 0;
+	const ry = r[1] ?? 0;
+	const rz = r[2] ?? 0;
+	const angle = Math.sqrt(rx * rx + ry * ry + rz * rz);
+	if (angle < EPSILON) return {
+		w: 1,
+		x: 0,
+		y: 0,
+		z: 0
+	};
+	const half = angle / 2;
+	const s = Math.sin(half) / angle;
+	return {
+		w: Math.cos(half),
+		x: rx * s,
+		y: ry * s,
+		z: rz * s
+	};
+}
+/**
+* Convert a unit quaternion back to an axis-angle rotation vector [rx, ry, rz],
+* matching wb-robotix's `Quaternion::toRotationVector()` (ported from
+* QuaternionBasePlugin.h): using `atan2` rather than `acos` keeps the angle
+* canonically within [0, pi] regardless of which of the two antipodal unit
+* quaternions (q or -q) represents the rotation, rather than acos's [0, 2*pi]
+* range - important since composed poses need to match the same canonical
+* rotation vector the robot controller itself would report for a pose.
+*/
+function quaternionToAxisAngle(q) {
+	const vecNorm = Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z);
+	if (vecNorm < EPSILON) return [
+		0,
+		0,
+		0
+	];
+	const angle = 2 * Math.atan2(vecNorm, Math.abs(q.w));
+	const scale = (q.w >= 0 ? angle : -angle) / vecNorm;
+	return [
+		q.x * scale,
+		q.y * scale,
+		q.z * scale
+	];
+}
+/** Hamilton product: composes rotations so that applying `multiplyQuaternions(a, b)` to a vector equals applying `b` then `a`. */
+function multiplyQuaternions(a, b) {
+	return {
+		w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
+		x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+		y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+		z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w
+	};
+}
+/** Conjugate of a unit quaternion equals its inverse. */
+function conjugateQuaternion(q) {
+	return {
+		w: q.w,
+		x: -q.x,
+		y: -q.y,
+		z: -q.z
+	};
+}
+/** Rotate a 3D vector by a unit quaternion. */
+function rotateVectorByQuaternion(q, v) {
+	const vx = v[0] ?? 0;
+	const vy = v[1] ?? 0;
+	const vz = v[2] ?? 0;
+	const { w, x, y, z } = q;
+	const tx = 2 * (y * vz - z * vy);
+	const ty = 2 * (z * vx - x * vz);
+	const tz = 2 * (x * vy - y * vx);
+	return [
+		vx + w * tx + (y * tz - z * ty),
+		vy + w * ty + (z * tx - x * tz),
+		vz + w * tz + (x * ty - y * tx)
+	];
+}
+//#endregion
+//#region src/lib/experimental/math/Pose.ts
+const ZERO_VECTOR = [
+	0,
+	0,
+	0
+];
+function addVectors(a, b) {
+	return [
+		(a[0] ?? 0) + (b[0] ?? 0),
+		(a[1] ?? 0) + (b[1] ?? 0),
+		(a[2] ?? 0) + (b[2] ?? 0)
+	];
+}
+function negateVector(a) {
+	return [
+		-(a[0] ?? 0),
+		-(a[1] ?? 0),
+		-(a[2] ?? 0)
+	];
+}
+/**
+* A `Pose` (position + axis-angle orientation) with methods for composing
+* and inverting transforms. Instances are plain-data compatible with the
+* wire-format `PoseData` type (own `position`/`orientation` properties only,
+* no enumerable methods), so they can be passed directly back into API calls
+* that expect a pose.
+*
+* Poses returned from `NovaAPIClient`/`Nova` are automatically upgraded to
+* `Pose` instances; construct one directly only when you have a pose from
+* elsewhere (e.g. a websocket message).
+*/
+var Pose = class Pose {
+	position;
+	orientation;
+	constructor(position = ZERO_VECTOR, orientation = ZERO_VECTOR) {
+		this.position = position;
+		this.orientation = orientation;
+	}
+	static from(pose) {
+		if (pose instanceof Pose) return pose;
+		return new Pose(pose.position ?? ZERO_VECTOR, pose.orientation ?? ZERO_VECTOR);
+	}
+	static identity() {
+		return new Pose();
+	}
+	/**
+	* Compose this pose with `other`, treating `other` as being expressed in
+	* this pose's coordinate frame. Equivalent to the homogeneous transform
+	* product `this * other`: applying the result to a point is the same as
+	* applying `other` first, then `this`.
+	*/
+	multiply(other) {
+		const q1 = axisAngleToQuaternion(this.orientation);
+		const q2 = axisAngleToQuaternion(other.orientation ?? ZERO_VECTOR);
+		const position = addVectors(this.position, rotateVectorByQuaternion(q1, other.position ?? ZERO_VECTOR));
+		const orientation = quaternionToAxisAngle(multiplyQuaternions(q1, q2));
+		return new Pose(position, orientation);
+	}
+	/** The inverse transform, such that `pose.multiply(pose.inverse())` is the identity pose. */
+	inverse() {
+		const position = rotateVectorByQuaternion(conjugateQuaternion(axisAngleToQuaternion(this.orientation)), negateVector(this.position));
+		const orientation = negateVector(this.orientation);
+		return new Pose(position, orientation);
+	}
+	/** Apply this pose's transform to a point, returning the transformed point. */
+	transformPoint(point) {
+		const q = axisAngleToQuaternion(this.orientation);
+		return addVectors(this.position, rotateVectorByQuaternion(q, point));
+	}
+	/** Compare to another pose within a tolerance, since floating-point pose math rarely produces exact equality. */
+	equals(other, epsilon = 1e-9) {
+		const otherPosition = other.position ?? ZERO_VECTOR;
+		const otherOrientation = other.orientation ?? ZERO_VECTOR;
+		return this.position.every((v, i) => Math.abs(v - (otherPosition[i] ?? 0)) <= epsilon) && this.orientation.every((v, i) => Math.abs(v - (otherOrientation[i] ?? 0)) <= epsilon);
+	}
+	toJSON() {
+		return {
+			position: this.position,
+			orientation: this.orientation
+		};
+	}
+};
+//#endregion
+//#region src/lib/experimental/math/augmentMath.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Pose);
+}
+function isNumberTriple(value) {
+	return Array.isArray(value) && value.length === 3 && value.every((n) => typeof n === "number");
+}
+/**
+* Structural check for the wire shape of `Pose` (`{ position, orientation }`,
+* each a 3-number array, and nothing else). This API has no other type with
+* this exact shape, so it reliably identifies `Pose` values without needing
+* per-endpoint knowledge of which fields are poses.
+*/
+function isPoseShape(value) {
+	return Object.keys(value).length === 2 && isNumberTriple(value.position) && isNumberTriple(value.orientation);
+}
+function augmentPosesInPlace(value) {
+	if (Array.isArray(value)) {
+		for (const item of value) augmentPosesInPlace(item);
+		return;
+	}
+	if (isPlainObject(value)) if (isPoseShape(value)) Object.setPrototypeOf(value, Pose.prototype);
+	else for (const key of Object.keys(value)) augmentPosesInPlace(value[key]);
+}
+/**
+* Recursively walks a parsed API response/request body, upgrading any
+* `Pose`-shaped objects in place to `Pose` instances so they gain math
+* methods (`multiply`, `inverse`, ...) while remaining JSON/wire-compatible.
+* Used by `augmentMath` for `nova.api.*` responses; exported so it can also
+* be applied manually to e.g. websocket messages.
+*/
+function augmentPoses(value) {
+	augmentPosesInPlace(value);
+	return value;
+}
+function wrapWithPoseAugmentation(target) {
+	return new Proxy(target, { get(t, prop) {
+		const value = Reflect.get(t, prop, t);
+		if (typeof value === "function") return (...args) => {
+			const result = value.apply(t, args);
+			return result instanceof Promise ? result.then((data) => augmentPoses(data)) : result;
+		};
+		if (value !== null && typeof value === "object") return wrapWithPoseAugmentation(value);
+		return value;
+	} });
+}
+/**
+* Wraps a `Nova` instance so every `nova.api.*` call automatically upgrades
+* `Pose`-shaped fields in its response to `Pose` instances (with math
+* methods like `multiply`/`inverse`). Returns a new proxied view - does not
+* mutate the original `nova` instance.
+*/
+function augmentMath(nova) {
+	return new Proxy(nova, { get(target, prop) {
+		if (prop === "api") return wrapWithPoseAugmentation(target.api);
+		return Reflect.get(target, prop, target);
+	} });
+}
+//#endregion
+export { Pose, augmentMath, augmentPoses, axisAngleToQuaternion, conjugateQuaternion, multiplyQuaternions, quaternionToAxisAngle, rotateVectorByQuaternion };
+
+//# sourceMappingURL=index.mjs.map

package/dist/experimental/math/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/lib/experimental/math/Quaternion.ts","../../../src/lib/experimental/math/Pose.ts","../../../src/lib/experimental/math/augmentMath.ts"],"sourcesContent":["/**\n * Internal quaternion helpers used to compose/invert the axis-angle\n * `orientation` vectors used by the NOVA API's `Pose` type. Rotation vectors\n * are converted to quaternions for composition (numerically stable, unlike\n * composing axis-angle vectors directly) and converted back at the boundary.\n */\n\nexport type Quaternion = { w: number; x: number; y: number; z: number }\n\nconst EPSILON = 1e-12\n\n/** Convert an axis-angle rotation vector [rx, ry, rz] to a unit quaternion. */\nexport function axisAngleToQuaternion(r: number[]): Quaternion {\n  const rx = r[0] ?? 0\n  const ry = r[1] ?? 0\n  const rz = r[2] ?? 0\n\n  const angle = Math.sqrt(rx * rx + ry * ry + rz * rz)\n  if (angle < EPSILON) {\n    return { w: 1, x: 0, y: 0, z: 0 }\n  }\n  const half = angle / 2\n  const s = Math.sin(half) / angle\n  return { w: Math.cos(half), x: rx * s, y: ry * s, z: rz * s }\n}\n\n/**\n * Convert a unit quaternion back to an axis-angle rotation vector [rx, ry, rz],\n * matching wb-robotix's `Quaternion::toRotationVector()` (ported from\n * QuaternionBasePlugin.h): using `atan2` rather than `acos` keeps the angle\n * canonically within [0, pi] regardless of which of the two antipodal unit\n * quaternions (q or -q) represents the rotation, rather than acos's [0, 2*pi]\n * range - important since composed poses need to match the same canonical\n * rotation vector the robot controller itself would report for a pose.\n */\nexport function quaternionToAxisAngle(q: Quaternion): number[] {\n  const vecNorm = Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z)\n  if (vecNorm < EPSILON) {\n    return [0, 0, 0]\n  }\n  const angle = 2 * Math.atan2(vecNorm, Math.abs(q.w))\n  const scale = (q.w >= 0 ? angle : -angle) / vecNorm\n  return [q.x * scale, q.y * scale, q.z * scale]\n}\n\n/** Hamilton product: composes rotations so that applying `multiplyQuaternions(a, b)` to a vector equals applying `b` then `a`. */\nexport function multiplyQuaternions(a: Quaternion, b: Quaternion): Quaternion {\n  return {\n    w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,\n    x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,\n    y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,\n    z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,\n  }\n}\n\n/** Conjugate of a unit quaternion equals its inverse. */\nexport function conjugateQuaternion(q: Quaternion): Quaternion {\n  return { w: q.w, x: -q.x, y: -q.y, z: -q.z }\n}\n\n/** Rotate a 3D vector by a unit quaternion. */\nexport function rotateVectorByQuaternion(q: Quaternion, v: number[]): number[] {\n  const vx = v[0] ?? 0\n  const vy = v[1] ?? 0\n  const vz = v[2] ?? 0\n  const { w, x, y, z } = q\n\n  // t = 2 * cross(q.xyz, v)\n  const tx = 2 * (y * vz - z * vy)\n  const ty = 2 * (z * vx - x * vz)\n  const tz = 2 * (x * vy - y * vx)\n\n  // v' = v + w*t + cross(q.xyz, t)\n  return [\n    vx + w * tx + (y * tz - z * ty),\n    vy + w * ty + (z * tx - x * tz),\n    vz + w * tz + (x * ty - y * tx),\n  ]\n}\n","import type { Pose as PoseData } from \"@wandelbots/nova-api/v2\"\nimport {\n  axisAngleToQuaternion,\n  conjugateQuaternion,\n  multiplyQuaternions,\n  quaternionToAxisAngle,\n  rotateVectorByQuaternion,\n} from \"./Quaternion.ts\"\n\nconst ZERO_VECTOR = [0, 0, 0]\n\nfunction addVectors(a: number[], b: number[]): number[] {\n  return [\n    (a[0] ?? 0) + (b[0] ?? 0),\n    (a[1] ?? 0) + (b[1] ?? 0),\n    (a[2] ?? 0) + (b[2] ?? 0),\n  ]\n}\n\nfunction negateVector(a: number[]): number[] {\n  return [-(a[0] ?? 0), -(a[1] ?? 0), -(a[2] ?? 0)]\n}\n\n/**\n * A `Pose` (position + axis-angle orientation) with methods for composing\n * and inverting transforms. Instances are plain-data compatible with the\n * wire-format `PoseData` type (own `position`/`orientation` properties only,\n * no enumerable methods), so they can be passed directly back into API calls\n * that expect a pose.\n *\n * Poses returned from `NovaAPIClient`/`Nova` are automatically upgraded to\n * `Pose` instances; construct one directly only when you have a pose from\n * elsewhere (e.g. a websocket message).\n */\nexport class Pose implements PoseData {\n  readonly position: number[]\n  readonly orientation: number[]\n\n  constructor(\n    position: number[] = ZERO_VECTOR,\n    orientation: number[] = ZERO_VECTOR,\n  ) {\n    this.position = position\n    this.orientation = orientation\n  }\n\n  static from(pose: PoseData): Pose {\n    if (pose instanceof Pose) {\n      return pose\n    }\n    return new Pose(\n      pose.position ?? ZERO_VECTOR,\n      pose.orientation ?? ZERO_VECTOR,\n    )\n  }\n\n  static identity(): Pose {\n    return new Pose()\n  }\n\n  /**\n   * Compose this pose with `other`, treating `other` as being expressed in\n   * this pose's coordinate frame. Equivalent to the homogeneous transform\n   * product `this * other`: applying the result to a point is the same as\n   * applying `other` first, then `this`.\n   */\n  multiply(other: PoseData): Pose {\n    const q1 = axisAngleToQuaternion(this.orientation)\n    const q2 = axisAngleToQuaternion(other.orientation ?? ZERO_VECTOR)\n\n    const position = addVectors(\n      this.position,\n      rotateVectorByQuaternion(q1, other.position ?? ZERO_VECTOR),\n    )\n    const orientation = quaternionToAxisAngle(multiplyQuaternions(q1, q2))\n\n    return new Pose(position, orientation)\n  }\n\n  /** The inverse transform, such that `pose.multiply(pose.inverse())` is the identity pose. */\n  inverse(): Pose {\n    const q = axisAngleToQuaternion(this.orientation)\n    const qInverse = conjugateQuaternion(q)\n\n    const position = rotateVectorByQuaternion(\n      qInverse,\n      negateVector(this.position),\n    )\n    // Negating an axis-angle vector gives the inverse rotation directly.\n    const orientation = negateVector(this.orientation)\n\n    return new Pose(position, orientation)\n  }\n\n  /** Apply this pose's transform to a point, returning the transformed point. */\n  transformPoint(point: number[]): number[] {\n    const q = axisAngleToQuaternion(this.orientation)\n    return addVectors(this.position, rotateVectorByQuaternion(q, point))\n  }\n\n  /** Compare to another pose within a tolerance, since floating-point pose math rarely produces exact equality. */\n  equals(other: PoseData, epsilon = 1e-9): boolean {\n    const otherPosition = other.position ?? ZERO_VECTOR\n    const otherOrientation = other.orientation ?? ZERO_VECTOR\n\n    return (\n      this.position.every(\n        (v, i) => Math.abs(v - (otherPosition[i] ?? 0)) <= epsilon,\n      ) &&\n      this.orientation.every(\n        (v, i) => Math.abs(v - (otherOrientation[i] ?? 0)) <= epsilon,\n      )\n    )\n  }\n\n  toJSON(): PoseData {\n    return { position: this.position, orientation: this.orientation }\n  }\n}\n","import type { Pose as PoseData } from \"@wandelbots/nova-api/v2\"\nimport type { Nova } from \"../../Nova.ts\"\nimport { Pose } from \"./Pose.ts\"\n\ntype PoseKeys = keyof PoseData\n\ntype IsExactlyPoseData<T> = [Exclude<keyof T, PoseKeys>] extends [never]\n  ? [Exclude<PoseKeys, keyof T>] extends [never]\n    ? true\n    : false\n  : false\n\n// Depth cap avoids \"type instantiation is excessively deep\" on nova-api's\n// large (and possibly cyclic, e.g. compound colliders) generated type graph.\ntype MaxDepth = [\n  unknown,\n  unknown,\n  unknown,\n  unknown,\n  unknown,\n  unknown,\n  unknown,\n  unknown,\n  unknown,\n  unknown,\n]\n\ntype AugmentPosesCore<\n  T,\n  Depth extends readonly unknown[],\n> = Depth[\"length\"] extends MaxDepth[\"length\"]\n  ? T\n  : IsExactlyPoseData<T> extends true\n    ? Pose\n    : T extends readonly (infer U)[]\n      ? DeepPoseAugmented<U, [...Depth, unknown]>[]\n      : T extends object\n        ? { [K in keyof T]: DeepPoseAugmented<T[K], [...Depth, unknown]> }\n        : T\n\n/**\n * Type-level counterpart to `augmentPoses`: recursively replaces any\n * `PoseData`-shaped field with `Pose` (distributing over unions, e.g. so\n * optional `Pose | undefined` fields keep the `| undefined`), so the static\n * type matches what's actually returned at runtime.\n */\nexport type DeepPoseAugmented<\n  T,\n  Depth extends readonly unknown[] = [],\n> = T extends unknown ? AugmentPosesCore<T, Depth> : never\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    !Array.isArray(value) &&\n    !(value instanceof Pose)\n  )\n}\n\nfunction isNumberTriple(value: unknown): value is number[] {\n  return (\n    Array.isArray(value) &&\n    value.length === 3 &&\n    value.every((n) => typeof n === \"number\")\n  )\n}\n\n/**\n * Structural check for the wire shape of `Pose` (`{ position, orientation }`,\n * each a 3-number array, and nothing else). This API has no other type with\n * this exact shape, so it reliably identifies `Pose` values without needing\n * per-endpoint knowledge of which fields are poses.\n */\nfunction isPoseShape(value: Record<string, unknown>): boolean {\n  return (\n    Object.keys(value).length === 2 &&\n    isNumberTriple(value.position) &&\n    isNumberTriple(value.orientation)\n  )\n}\n\nfunction augmentPosesInPlace(value: unknown): void {\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      augmentPosesInPlace(item)\n    }\n    return\n  }\n\n  if (isPlainObject(value)) {\n    if (isPoseShape(value)) {\n      Object.setPrototypeOf(value, Pose.prototype)\n    } else {\n      for (const key of Object.keys(value)) {\n        augmentPosesInPlace(value[key])\n      }\n    }\n  }\n}\n\n/**\n * Recursively walks a parsed API response/request body, upgrading any\n * `Pose`-shaped objects in place to `Pose` instances so they gain math\n * methods (`multiply`, `inverse`, ...) while remaining JSON/wire-compatible.\n * Used by `augmentMath` for `nova.api.*` responses; exported so it can also\n * be applied manually to e.g. websocket messages.\n */\nexport function augmentPoses<T>(value: T): DeepPoseAugmented<T> {\n  augmentPosesInPlace(value)\n  return value as DeepPoseAugmented<T>\n}\n\ntype WithAugmentedPosesCore<\n  T,\n  Depth extends readonly unknown[],\n> = Depth[\"length\"] extends MaxDepth[\"length\"]\n  ? T\n  : T extends (...args: infer A) => Promise<infer R>\n    ? (...args: A) => Promise<DeepPoseAugmented<R>>\n    : T extends object\n      ? { [K in keyof T]: WithAugmentedPosesCore<T[K], [...Depth, unknown]> }\n      : T\n\n/**\n * Recursively maps every method on `Nova[\"api\"]` (and its nested API groups)\n * so calls are typed as returning `DeepPoseAugmented` results, matching what\n * `augmentMath` does at runtime.\n */\ntype WithAugmentedPoses<T> = WithAugmentedPosesCore<T, []>\n\nexport type NovaWithMath = Omit<Nova, \"api\"> & {\n  readonly api: WithAugmentedPoses<Nova[\"api\"]>\n}\n\nfunction wrapWithPoseAugmentation<T extends object>(target: T): T {\n  return new Proxy(target, {\n    get(t, prop) {\n      const value = Reflect.get(t, prop, t)\n      if (typeof value === \"function\") {\n        return (...args: unknown[]) => {\n          const result = (value as (...a: unknown[]) => unknown).apply(t, args)\n          return result instanceof Promise\n            ? result.then((data) => augmentPoses(data))\n            : result\n        }\n      }\n      if (value !== null && typeof value === \"object\") {\n        return wrapWithPoseAugmentation(value)\n      }\n      return value\n    },\n  }) as T\n}\n\n/**\n * Wraps a `Nova` instance so every `nova.api.*` call automatically upgrades\n * `Pose`-shaped fields in its response to `Pose` instances (with math\n * methods like `multiply`/`inverse`). Returns a new proxied view - does not\n * mutate the original `nova` instance.\n */\nexport function augmentMath(nova: Nova): NovaWithMath {\n  const proxy = new Proxy(nova, {\n    get(target, prop) {\n      if (prop === \"api\") {\n        return wrapWithPoseAugmentation(target.api)\n      }\n      // receiver is `target`, not the proxy, so `this` inside Nova's own\n      // methods stays bound to the original (un-proxied) instance.\n      return Reflect.get(target, prop, target)\n    },\n  })\n\n  return proxy as unknown as NovaWithMath\n}\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wandelbots/nova-js",
   "type": "module",
-  "version": "4.2.0",
+  "version": "4.3.0-pr.318.6592c26",
   "description": "Official JS client for the Wandelbots API",
   "sideEffects": false,
   "packageManager": "pnpm@11.9.0+sha512.bd682d5d03fe525ef7c9fd6780c6884d1e756ac4c9c9fe00c538782824310dcf90e3ddc4f53835f06dfaebd5085e41855e0bcbb3b60de2ac5bbab89e5036f03b",
@@ -20,6 +20,10 @@
     "./experimental/nats": {
       "types": "./dist/experimental/nats/index.d.mts",
       "default": "./dist/experimental/nats/index.mjs"
+    },
+    "./experimental/math": {
+      "types": "./dist/experimental/math/index.d.mts",
+      "default": "./dist/experimental/math/index.mjs"
     }
   },
   "main": "./dist/index.mjs",

package/src/experimental/math/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Experimental pose math helpers (`Pose`, `augmentMath`) for working with
+ * position + axis-angle orientation values from the NOVA API.
+ *
+ * This API is experimental and may change without a major version bump.
+ */
+export type { Pose as PoseData } from "@wandelbots/nova-api/v2"
+export {
+  augmentMath,
+  augmentPoses,
+} from "../../lib/experimental/math/augmentMath.ts"
+export type {
+  DeepPoseAugmented,
+  NovaWithMath,
+} from "../../lib/experimental/math/augmentMath.ts"
+export { Pose } from "../../lib/experimental/math/Pose.ts"
+export {
+  axisAngleToQuaternion,
+  conjugateQuaternion,
+  multiplyQuaternions,
+  quaternionToAxisAngle,
+  rotateVectorByQuaternion,
+} from "../../lib/experimental/math/Quaternion.ts"
+export type { Quaternion } from "../../lib/experimental/math/Quaternion.ts"

package/src/lib/experimental/math/Pose.ts

@@ -0,0 +1,119 @@
+import type { Pose as PoseData } from "@wandelbots/nova-api/v2"
+import {
+  axisAngleToQuaternion,
+  conjugateQuaternion,
+  multiplyQuaternions,
+  quaternionToAxisAngle,
+  rotateVectorByQuaternion,
+} from "./Quaternion.ts"
+
+const ZERO_VECTOR = [0, 0, 0]
+
+function addVectors(a: number[], b: number[]): number[] {
+  return [
+    (a[0] ?? 0) + (b[0] ?? 0),
+    (a[1] ?? 0) + (b[1] ?? 0),
+    (a[2] ?? 0) + (b[2] ?? 0),
+  ]
+}
+
+function negateVector(a: number[]): number[] {
+  return [-(a[0] ?? 0), -(a[1] ?? 0), -(a[2] ?? 0)]
+}
+
+/**
+ * A `Pose` (position + axis-angle orientation) with methods for composing
+ * and inverting transforms. Instances are plain-data compatible with the
+ * wire-format `PoseData` type (own `position`/`orientation` properties only,
+ * no enumerable methods), so they can be passed directly back into API calls
+ * that expect a pose.
+ *
+ * Poses returned from `NovaAPIClient`/`Nova` are automatically upgraded to
+ * `Pose` instances; construct one directly only when you have a pose from
+ * elsewhere (e.g. a websocket message).
+ */
+export class Pose implements PoseData {
+  readonly position: number[]
+  readonly orientation: number[]
+
+  constructor(
+    position: number[] = ZERO_VECTOR,
+    orientation: number[] = ZERO_VECTOR,
+  ) {
+    this.position = position
+    this.orientation = orientation
+  }
+
+  static from(pose: PoseData): Pose {
+    if (pose instanceof Pose) {
+      return pose
+    }
+    return new Pose(
+      pose.position ?? ZERO_VECTOR,
+      pose.orientation ?? ZERO_VECTOR,
+    )
+  }
+
+  static identity(): Pose {
+    return new Pose()
+  }
+
+  /**
+   * Compose this pose with `other`, treating `other` as being expressed in
+   * this pose's coordinate frame. Equivalent to the homogeneous transform
+   * product `this * other`: applying the result to a point is the same as
+   * applying `other` first, then `this`.
+   */
+  multiply(other: PoseData): Pose {
+    const q1 = axisAngleToQuaternion(this.orientation)
+    const q2 = axisAngleToQuaternion(other.orientation ?? ZERO_VECTOR)
+
+    const position = addVectors(
+      this.position,
+      rotateVectorByQuaternion(q1, other.position ?? ZERO_VECTOR),
+    )
+    const orientation = quaternionToAxisAngle(multiplyQuaternions(q1, q2))
+
+    return new Pose(position, orientation)
+  }
+
+  /** The inverse transform, such that `pose.multiply(pose.inverse())` is the identity pose. */
+  inverse(): Pose {
+    const q = axisAngleToQuaternion(this.orientation)
+    const qInverse = conjugateQuaternion(q)
+
+    const position = rotateVectorByQuaternion(
+      qInverse,
+      negateVector(this.position),
+    )
+    // Negating an axis-angle vector gives the inverse rotation directly.
+    const orientation = negateVector(this.orientation)
+
+    return new Pose(position, orientation)
+  }
+
+  /** Apply this pose's transform to a point, returning the transformed point. */
+  transformPoint(point: number[]): number[] {
+    const q = axisAngleToQuaternion(this.orientation)
+    return addVectors(this.position, rotateVectorByQuaternion(q, point))
+  }
+
+  /** Compare to another pose within a tolerance, since floating-point pose math rarely produces exact equality. */
+  equals(other: PoseData, epsilon = 1e-9): boolean {
+    const otherPosition = other.position ?? ZERO_VECTOR
+    const otherOrientation = other.orientation ?? ZERO_VECTOR
+
+    return (
+      this.position.every(
+        (v, i) => Math.abs(v - (otherPosition[i] ?? 0)) <= epsilon,
+      ) &&
+      this.orientation.every(
+        (v, i) => Math.abs(v - (otherOrientation[i] ?? 0)) <= epsilon,
+      )
+    )
+  }
+
+  toJSON(): PoseData {
+    return { position: this.position, orientation: this.orientation }
+  }
+}

package/src/lib/experimental/math/Quaternion.ts

@@ -0,0 +1,79 @@
+/**
+ * Internal quaternion helpers used to compose/invert the axis-angle
+ * `orientation` vectors used by the NOVA API's `Pose` type. Rotation vectors
+ * are converted to quaternions for composition (numerically stable, unlike
+ * composing axis-angle vectors directly) and converted back at the boundary.
+ */
+
+export type Quaternion = { w: number; x: number; y: number; z: number }
+
+const EPSILON = 1e-12
+
+/** Convert an axis-angle rotation vector [rx, ry, rz] to a unit quaternion. */
+export function axisAngleToQuaternion(r: number[]): Quaternion {
+  const rx = r[0] ?? 0
+  const ry = r[1] ?? 0
+  const rz = r[2] ?? 0
+
+  const angle = Math.sqrt(rx * rx + ry * ry + rz * rz)
+  if (angle < EPSILON) {
+    return { w: 1, x: 0, y: 0, z: 0 }
+  }
+  const half = angle / 2
+  const s = Math.sin(half) / angle
+  return { w: Math.cos(half), x: rx * s, y: ry * s, z: rz * s }
+}
+
+/**
+ * Convert a unit quaternion back to an axis-angle rotation vector [rx, ry, rz],
+ * matching wb-robotix's `Quaternion::toRotationVector()` (ported from
+ * QuaternionBasePlugin.h): using `atan2` rather than `acos` keeps the angle
+ * canonically within [0, pi] regardless of which of the two antipodal unit
+ * quaternions (q or -q) represents the rotation, rather than acos's [0, 2*pi]
+ * range - important since composed poses need to match the same canonical
+ * rotation vector the robot controller itself would report for a pose.
+ */
+export function quaternionToAxisAngle(q: Quaternion): number[] {
+  const vecNorm = Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z)
+  if (vecNorm < EPSILON) {
+    return [0, 0, 0]
+  }
+  const angle = 2 * Math.atan2(vecNorm, Math.abs(q.w))
+  const scale = (q.w >= 0 ? angle : -angle) / vecNorm
+  return [q.x * scale, q.y * scale, q.z * scale]
+}
+
+/** Hamilton product: composes rotations so that applying `multiplyQuaternions(a, b)` to a vector equals applying `b` then `a`. */
+export function multiplyQuaternions(a: Quaternion, b: Quaternion): Quaternion {
+  return {
+    w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
+    x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+    y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+    z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
+  }
+}
+
+/** Conjugate of a unit quaternion equals its inverse. */
+export function conjugateQuaternion(q: Quaternion): Quaternion {
+  return { w: q.w, x: -q.x, y: -q.y, z: -q.z }
+}
+
+/** Rotate a 3D vector by a unit quaternion. */
+export function rotateVectorByQuaternion(q: Quaternion, v: number[]): number[] {
+  const vx = v[0] ?? 0
+  const vy = v[1] ?? 0
+  const vz = v[2] ?? 0
+  const { w, x, y, z } = q
+
+  // t = 2 * cross(q.xyz, v)
+  const tx = 2 * (y * vz - z * vy)
+  const ty = 2 * (z * vx - x * vz)
+  const tz = 2 * (x * vy - y * vx)
+
+  // v' = v + w*t + cross(q.xyz, t)
+  return [
+    vx + w * tx + (y * tz - z * ty),
+    vy + w * ty + (z * tx - x * tz),
+    vz + w * tz + (x * ty - y * tx),
+  ]
+}

package/src/lib/experimental/math/augmentMath.ts

@@ -0,0 +1,175 @@
+import type { Pose as PoseData } from "@wandelbots/nova-api/v2"
+import type { Nova } from "../../Nova.ts"
+import { Pose } from "./Pose.ts"
+
+type PoseKeys = keyof PoseData
+
+type IsExactlyPoseData<T> = [Exclude<keyof T, PoseKeys>] extends [never]
+  ? [Exclude<PoseKeys, keyof T>] extends [never]
+    ? true
+    : false
+  : false
+
+// Depth cap avoids "type instantiation is excessively deep" on nova-api's
+// large (and possibly cyclic, e.g. compound colliders) generated type graph.
+type MaxDepth = [
+  unknown,
+  unknown,
+  unknown,
+  unknown,
+  unknown,
+  unknown,
+  unknown,
+  unknown,
+  unknown,
+  unknown,
+]
+
+type AugmentPosesCore<
+  T,
+  Depth extends readonly unknown[],
+> = Depth["length"] extends MaxDepth["length"]
+  ? T
+  : IsExactlyPoseData<T> extends true
+    ? Pose
+    : T extends readonly (infer U)[]
+      ? DeepPoseAugmented<U, [...Depth, unknown]>[]
+      : T extends object
+        ? { [K in keyof T]: DeepPoseAugmented<T[K], [...Depth, unknown]> }
+        : T
+
+/**
+ * Type-level counterpart to `augmentPoses`: recursively replaces any
+ * `PoseData`-shaped field with `Pose` (distributing over unions, e.g. so
+ * optional `Pose | undefined` fields keep the `| undefined`), so the static
+ * type matches what's actually returned at runtime.
+ */
+export type DeepPoseAugmented<
+  T,
+  Depth extends readonly unknown[] = [],
+> = T extends unknown ? AugmentPosesCore<T, Depth> : never
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !(value instanceof Pose)
+  )
+}
+
+function isNumberTriple(value: unknown): value is number[] {
+  return (
+    Array.isArray(value) &&
+    value.length === 3 &&
+    value.every((n) => typeof n === "number")
+  )
+}
+
+/**
+ * Structural check for the wire shape of `Pose` (`{ position, orientation }`,
+ * each a 3-number array, and nothing else). This API has no other type with
+ * this exact shape, so it reliably identifies `Pose` values without needing
+ * per-endpoint knowledge of which fields are poses.
+ */
+function isPoseShape(value: Record<string, unknown>): boolean {
+  return (
+    Object.keys(value).length === 2 &&
+    isNumberTriple(value.position) &&
+    isNumberTriple(value.orientation)
+  )
+}
+
+function augmentPosesInPlace(value: unknown): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      augmentPosesInPlace(item)
+    }
+    return
+  }
+
+  if (isPlainObject(value)) {
+    if (isPoseShape(value)) {
+      Object.setPrototypeOf(value, Pose.prototype)
+    } else {
+      for (const key of Object.keys(value)) {
+        augmentPosesInPlace(value[key])
+      }
+    }
+  }
+}
+
+/**
+ * Recursively walks a parsed API response/request body, upgrading any
+ * `Pose`-shaped objects in place to `Pose` instances so they gain math
+ * methods (`multiply`, `inverse`, ...) while remaining JSON/wire-compatible.
+ * Used by `augmentMath` for `nova.api.*` responses; exported so it can also
+ * be applied manually to e.g. websocket messages.
+ */
+export function augmentPoses<T>(value: T): DeepPoseAugmented<T> {
+  augmentPosesInPlace(value)
+  return value as DeepPoseAugmented<T>
+}
+
+type WithAugmentedPosesCore<
+  T,
+  Depth extends readonly unknown[],
+> = Depth["length"] extends MaxDepth["length"]
+  ? T
+  : T extends (...args: infer A) => Promise<infer R>
+    ? (...args: A) => Promise<DeepPoseAugmented<R>>
+    : T extends object
+      ? { [K in keyof T]: WithAugmentedPosesCore<T[K], [...Depth, unknown]> }
+      : T
+
+/**
+ * Recursively maps every method on `Nova["api"]` (and its nested API groups)
+ * so calls are typed as returning `DeepPoseAugmented` results, matching what
+ * `augmentMath` does at runtime.
+ */
+type WithAugmentedPoses<T> = WithAugmentedPosesCore<T, []>
+
+export type NovaWithMath = Omit<Nova, "api"> & {
+  readonly api: WithAugmentedPoses<Nova["api"]>
+}
+
+function wrapWithPoseAugmentation<T extends object>(target: T): T {
+  return new Proxy(target, {
+    get(t, prop) {
+      const value = Reflect.get(t, prop, t)
+      if (typeof value === "function") {
+        return (...args: unknown[]) => {
+          const result = (value as (...a: unknown[]) => unknown).apply(t, args)
+          return result instanceof Promise
+            ? result.then((data) => augmentPoses(data))
+            : result
+        }
+      }
+      if (value !== null && typeof value === "object") {
+        return wrapWithPoseAugmentation(value)
+      }
+      return value
+    },
+  }) as T
+}
+
+/**
+ * Wraps a `Nova` instance so every `nova.api.*` call automatically upgrades
+ * `Pose`-shaped fields in its response to `Pose` instances (with math
+ * methods like `multiply`/`inverse`). Returns a new proxied view - does not
+ * mutate the original `nova` instance.
+ */
+export function augmentMath(nova: Nova): NovaWithMath {
+  const proxy = new Proxy(nova, {
+    get(target, prop) {
+      if (prop === "api") {
+        return wrapWithPoseAugmentation(target.api)
+      }
+      // receiver is `target`, not the proxy, so `this` inside Nova's own
+      // methods stays bound to the original (un-proxied) instance.
+      return Reflect.get(target, prop, target)
+    },
+  })
+
+  return proxy as unknown as NovaWithMath
+}