Add new Quaternion nodes to flow graph and glTF interactivity (#16739)

See
KhronosGroup/glTF@b8e8a5a
for the glTF interactivity spec updates.

Author: bghgary

packages/dev/core/src/FlowGraph/Blocks/Data/Math/flowGraphMathBlocks.ts

@@ -12,7 +12,7 @@ import type { FlowGraphDataConnection } from "core/FlowGraph/flowGraphDataConnec
 import type { FlowGraphContext } from "core/FlowGraph/flowGraphContext";
 import { FlowGraphMatrix2D, FlowGraphMatrix3D } from "core/FlowGraph/CustomTypes/flowGraphMatrix";
 import type { FlowGraphMathOperationType, FlowGraphNumber } from "core/FlowGraph/utils";
-import { _AreSameIntegerClass, _AreSameMatrixClass, _AreSameVectorClass, _GetClassNameOf, getNumericValue, isNumeric } from "core/FlowGraph/utils";
+import { _AreSameIntegerClass, _AreSameMatrixClass, _AreSameVectorOrQuaternionClass, _GetClassNameOf, getNumericValue, isNumeric } from "core/FlowGraph/utils";
 
 /**
  * A configuration interface  for math blocks
@@ -58,12 +58,9 @@ export class FlowGraphAddBlock extends FlowGraphBinaryOperationBlock<FlowGraphMa
     private _polymorphicAdd(a: FlowGraphMathOperationType, b: FlowGraphMathOperationType) {
         const aClassName = _GetClassNameOf(a);
         const bClassName = _GetClassNameOf(b);
-        if (_AreSameVectorClass(aClassName, bClassName) || _AreSameMatrixClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName)) {
+        if (_AreSameVectorOrQuaternionClass(aClassName, bClassName) || _AreSameMatrixClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName)) {
             // cast to vector3, but any other cast will be fine
             return (a as Vector3).add(b as Vector3);
-        } else if (aClassName === FlowGraphTypes.Quaternion || bClassName === FlowGraphTypes.Quaternion) {
-            // this is a simple add, and should be also supported between Quat and Vector4. Therefore -
-            return (a as Quaternion).add(b as Quaternion);
         } else {
             // at this point at least one of the variables is a number.
             if (this.config?.preventIntegerFloatArithmetic && typeof a !== typeof b) {
@@ -97,11 +94,9 @@ export class FlowGraphSubtractBlock extends FlowGraphBinaryOperationBlock<FlowGr
     private _polymorphicSubtract(a: FlowGraphMathOperationType, b: FlowGraphMathOperationType) {
         const aClassName = _GetClassNameOf(a);
         const bClassName = _GetClassNameOf(b);
-        if (_AreSameVectorClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName) || _AreSameMatrixClass(aClassName, bClassName)) {
+        if (_AreSameVectorOrQuaternionClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName) || _AreSameMatrixClass(aClassName, bClassName)) {
+            // cast to vector3, but it can be casted to any vector type
             return (a as Vector3).subtract(b as Vector3);
-        } else if (aClassName === FlowGraphTypes.Quaternion || bClassName === FlowGraphTypes.Quaternion) {
-            // this is a simple subtract, and should be also supported between Quat and Vector4. Therefore -
-            return (a as Quaternion).subtract(b as Quaternion);
         } else {
             // at this point at least one of the variables is a number.
             if (this.config?.preventIntegerFloatArithmetic && typeof a !== typeof b) {
@@ -132,16 +127,9 @@ export class FlowGraphMultiplyBlock extends FlowGraphBinaryOperationBlock<FlowGr
     private _polymorphicMultiply(a: FlowGraphMathOperationType, b: FlowGraphMathOperationType) {
         const aClassName = _GetClassNameOf(a);
         const bClassName = _GetClassNameOf(b);
-        if (_AreSameVectorClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName)) {
+        if (_AreSameVectorOrQuaternionClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName)) {
+            // cast to vector3, but it can be casted to any vector type
             return (a as Vector3).multiply(b as Vector3);
-        } else if (aClassName === FlowGraphTypes.Quaternion || bClassName === FlowGraphTypes.Quaternion) {
-            // this is a simple multiply (per component!), and should be also supported between Quat and Vector4. Therefore -
-            const aClone = (a as Quaternion).clone();
-            aClone.x *= (b as Quaternion).x;
-            aClone.y *= (b as Quaternion).y;
-            aClone.z *= (b as Quaternion).z;
-            aClone.w *= (b as Quaternion).w;
-            return aClone;
         } else if (_AreSameMatrixClass(aClassName, bClassName)) {
             if (this.config?.useMatrixPerComponent) {
                 // this is the definition of multiplication of glTF interactivity
@@ -195,7 +183,7 @@ export class FlowGraphDivideBlock extends FlowGraphBinaryOperationBlock<FlowGrap
     private _polymorphicDivide(a: FlowGraphMathOperationType, b: FlowGraphMathOperationType) {
         const aClassName = _GetClassNameOf(a);
         const bClassName = _GetClassNameOf(b);
-        if (_AreSameVectorClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName)) {
+        if (_AreSameVectorOrQuaternionClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName)) {
             // cast to vector3, but it can be casted to any vector type
             return (a as Vector3).divide(b as Vector3);
         } else if (aClassName === FlowGraphTypes.Quaternion || bClassName === FlowGraphTypes.Quaternion) {
@@ -710,7 +698,7 @@ export class FlowGraphEqualityBlock extends FlowGraphBinaryOperationBlock<FlowGr
         if (typeof a !== typeof b) {
             return false;
         }
-        if (_AreSameVectorClass(aClassName, bClassName) || _AreSameMatrixClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName)) {
+        if (_AreSameVectorOrQuaternionClass(aClassName, bClassName) || _AreSameMatrixClass(aClassName, bClassName) || _AreSameIntegerClass(aClassName, bClassName)) {
             return (a as Vector3).equals(b as Vector3);
         } else {
             return a === b;

packages/dev/core/src/FlowGraph/Blocks/Data/Math/flowGraphVectorMathBlocks.ts

@@ -1,4 +1,4 @@
-import type { IFlowGraphBlockConfiguration } from "core/FlowGraph/flowGraphBlock";
+import { FlowGraphBlock, type IFlowGraphBlockConfiguration } from "core/FlowGraph/flowGraphBlock";
 import {
     RichTypeVector3,
     FlowGraphTypes,
@@ -8,16 +8,25 @@ import {
     RichTypeMatrix,
     getRichTypeByFlowGraphType,
     RichTypeQuaternion,
+    RichTypeBoolean,
 } from "core/FlowGraph/flowGraphRichTypes";
 import { RegisterClass } from "core/Misc/typeStore";
 import { FlowGraphBlockNames } from "../../flowGraphBlockNames";
 import { FlowGraphBinaryOperationBlock } from "../flowGraphBinaryOperationBlock";
 import { FlowGraphUnaryOperationBlock } from "../flowGraphUnaryOperationBlock";
-import { Vector3, Vector4 } from "core/Maths/math.vector";
-import type { Matrix, Quaternion, Vector2 } from "core/Maths/math.vector";
+import { Quaternion, Vector3, Vector4 } from "core/Maths/math.vector";
+import type { Matrix, Vector2 } from "core/Maths/math.vector";
 import type { FlowGraphMatrix2D, FlowGraphMatrix3D } from "core/FlowGraph/CustomTypes";
 import type { FlowGraphMatrix, FlowGraphVector } from "core/FlowGraph/utils";
 import { _GetClassNameOf } from "core/FlowGraph/utils";
+import type { FlowGraphDataConnection } from "../../../flowGraphDataConnection";
+import type { FlowGraphContext } from "../../../flowGraphContext";
+import { GetAngleBetweenQuaternions, GetQuaternionFromDirections } from "../../../../Maths/math.vector.functions";
+import type { Nullable } from "../../../../types";
+
+const AxisCacheName = "cachedOperationAxis";
+const AngleCacheName = "cachedOperationAngle";
+const CacheExecIdName = "cachedExecutionId";
 
 /**
  * Vector length block.
@@ -200,3 +209,111 @@ export class FlowGraphTransformCoordinatesBlock extends FlowGraphBinaryOperation
 }
 
 RegisterClass(FlowGraphBlockNames.TransformCoordinates, FlowGraphTransformCoordinatesBlock);
+
+/**
+ * Conjugate the quaternion.
+ */
+export class FlowGraphConjugateBlock extends FlowGraphUnaryOperationBlock<Quaternion, Quaternion> {
+    constructor(config?: IFlowGraphBlockConfiguration) {
+        super(RichTypeQuaternion, RichTypeQuaternion, (a) => a.conjugate(), FlowGraphBlockNames.Conjugate, config);
+    }
+}
+
+RegisterClass(FlowGraphBlockNames.Conjugate, FlowGraphConjugateBlock);
+
+/**
+ * Get the angle between two quaternions.
+ */
+export class FlowGraphAngleBetweenBlock extends FlowGraphBinaryOperationBlock<Quaternion, Quaternion, number> {
+    constructor(config?: IFlowGraphBlockConfiguration) {
+        super(RichTypeQuaternion, RichTypeQuaternion, RichTypeNumber, (a, b) => GetAngleBetweenQuaternions(a, b), FlowGraphBlockNames.AngleBetween, config);
+    }
+}
+
+RegisterClass(FlowGraphBlockNames.AngleBetween, FlowGraphAngleBetweenBlock);
+
+/**
+ * Get the quaternion from an axis and an angle.
+ */
+export class FlowGraphQuaternionFromAxisAngleBlock extends FlowGraphBinaryOperationBlock<Vector3, number, Quaternion> {
+    constructor(config?: IFlowGraphBlockConfiguration) {
+        super(RichTypeVector3, RichTypeNumber, RichTypeQuaternion, (a, b) => Quaternion.RotationAxis(a, b), FlowGraphBlockNames.QuaternionFromAxisAngle, config);
+    }
+}
+
+RegisterClass(FlowGraphBlockNames.QuaternionFromAxisAngle, FlowGraphQuaternionFromAxisAngleBlock);
+
+/**
+ * Get the axis and angle from a quaternion.
+ */
+export class FlowGraphAxisAngleFromQuaternionBlock extends FlowGraphBlock {
+    /**
+     * The input of this block.
+     */
+    public readonly a: FlowGraphDataConnection<Quaternion>;
+
+    /**
+     * The output axis of rotation.
+     */
+    public readonly axis: FlowGraphDataConnection<Vector3>;
+
+    /**
+     * The output angle of rotation.
+     */
+    public readonly angle: FlowGraphDataConnection<number>;
+
+    /**
+     * Output connection: Whether the value is valid.
+     */
+    public readonly isValid: FlowGraphDataConnection<boolean>;
+
+    constructor(config?: IFlowGraphBlockConfiguration) {
+        super(config);
+
+        this.a = this.registerDataInput("a", RichTypeQuaternion);
+
+        this.axis = this.registerDataOutput("axis", RichTypeVector3);
+        this.angle = this.registerDataOutput("angle", RichTypeNumber);
+
+        this.isValid = this.registerDataOutput("isValid", RichTypeBoolean);
+    }
+
+    /** @override */
+    public override _updateOutputs(context: FlowGraphContext) {
+        const cachedExecutionId = context._getExecutionVariable(this, CacheExecIdName, -1);
+        const cachedAxis = context._getExecutionVariable<Nullable<Vector3>>(this, AxisCacheName, null);
+        const cachedAngle = context._getExecutionVariable<Nullable<number>>(this, AngleCacheName, null);
+        if (cachedAxis !== undefined && cachedAxis !== null && cachedAngle !== undefined && cachedAngle !== null && cachedExecutionId === context.executionId) {
+            this.axis.setValue(cachedAxis, context);
+            this.angle.setValue(cachedAngle, context);
+        } else {
+            try {
+                const { axis, angle } = this.a.getValue(context).toAxisAngle();
+                context._setExecutionVariable(this, AxisCacheName, axis);
+                context._setExecutionVariable(this, AngleCacheName, angle);
+                context._setExecutionVariable(this, CacheExecIdName, context.executionId);
+                this.axis.setValue(axis, context);
+                this.angle.setValue(angle, context);
+                this.isValid.setValue(true, context);
+            } catch (e) {
+                this.isValid.setValue(false, context);
+            }
+        }
+    }
+
+    /** @override */
+    public override getClassName(): string {
+        return FlowGraphBlockNames.AxisAngleFromQuaternion;
+    }
+}
+
+RegisterClass(FlowGraphBlockNames.AxisAngleFromQuaternion, FlowGraphAxisAngleFromQuaternionBlock);
+
+/**
+ * Get the quaternion from two direction vectors.
+ */
+export class FlowGraphQuaternionFromDirectionsBlock extends FlowGraphBinaryOperationBlock<Vector3, Vector3, Quaternion> {
+    constructor(config?: IFlowGraphBlockConfiguration) {
+        super(RichTypeVector3, RichTypeVector3, RichTypeQuaternion, (a, b) => GetQuaternionFromDirections(a, b), FlowGraphBlockNames.QuaternionFromDirections, config);
+    }
+}

packages/dev/core/src/FlowGraph/Blocks/flowGraphBlockFactory.ts

@@ -254,6 +254,16 @@ export function blockFactory(blockName: FlowGraphBlockNames | string): () => Pro
             return async () => (await import("./Data/Math/flowGraphVectorMathBlocks")).FlowGraphTransformBlock;
         case FlowGraphBlockNames.TransformCoordinates:
             return async () => (await import("./Data/Math/flowGraphVectorMathBlocks")).FlowGraphTransformCoordinatesBlock;
+        case FlowGraphBlockNames.Conjugate:
+            return async () => (await import("./Data/Math/flowGraphVectorMathBlocks")).FlowGraphConjugateBlock;
+        case FlowGraphBlockNames.AngleBetween:
+            return async () => (await import("./Data/Math/flowGraphVectorMathBlocks")).FlowGraphAngleBetweenBlock;
+        case FlowGraphBlockNames.QuaternionFromAxisAngle:
+            return async () => (await import("./Data/Math/flowGraphVectorMathBlocks")).FlowGraphQuaternionFromAxisAngleBlock;
+        case FlowGraphBlockNames.AxisAngleFromQuaternion:
+            return async () => (await import("./Data/Math/flowGraphVectorMathBlocks")).FlowGraphAxisAngleFromQuaternionBlock;
+        case FlowGraphBlockNames.QuaternionFromDirections:
+            return async () => (await import("./Data/Math/flowGraphVectorMathBlocks")).FlowGraphQuaternionFromDirectionsBlock;
         case FlowGraphBlockNames.MatrixDecompose:
             return async () => (await import("./Data/Math/flowGraphMatrixMathBlocks")).FlowGraphMatrixDecomposeBlock;
         case FlowGraphBlockNames.MatrixCompose:

packages/dev/core/src/FlowGraph/Blocks/flowGraphBlockNames.ts

@@ -127,6 +127,11 @@ export const enum FlowGraphBlockNames {
     ExtractMatrix3D = "FlowGraphExtractMatrix3DBlock",
     TransformVector = "FlowGraphTransformVectorBlock",
     TransformCoordinates = "FlowGraphTransformCoordinatesBlock",
+    Conjugate = "FlowGraphConjugateBlock",
+    AngleBetween = "FlowGraphAngleBetweenBlock",
+    QuaternionFromAxisAngle = "FlowGraphQuaternionFromAxisAngleBlock",
+    AxisAngleFromQuaternion = "FlowGraphAxisAngleFromQuaternionBlock",
+    QuaternionFromDirections = "FlowGraphQuaternionFromDirectionsBlock",
     MatrixDecompose = "FlowGraphMatrixDecompose",
     MatrixCompose = "FlowGraphMatrixCompose",
     BooleanToFloat = "FlowGraphBooleanToFloat",

packages/dev/core/src/FlowGraph/utils.ts

@@ -32,13 +32,16 @@ export function _GetClassNameOf(v: any) {
 
 /**
  * @internal
- * Check if two classname are the same and are vector classes.
+ * Check if two classname are the same and are vector or quaternion classes.
  * @param className the first class name
  * @param className2 the second class name
- * @returns whether the two class names are the same and are vector classes.
+ * @returns whether the two class names are the same and are vector or quaternion classes.
  */
-export function _AreSameVectorClass(className: string, className2: string) {
-    return className === className2 && (className === FlowGraphTypes.Vector2 || className === FlowGraphTypes.Vector3 || className === FlowGraphTypes.Vector4);
+export function _AreSameVectorOrQuaternionClass(className: string, className2: string) {
+    return (
+        className === className2 &&
+        (className === FlowGraphTypes.Vector2 || className === FlowGraphTypes.Vector3 || className === FlowGraphTypes.Vector4 || className === FlowGraphTypes.Quaternion)
+    );
 }
 
 /**

packages/dev/core/src/Maths/math.vector.functions.ts

@@ -1,4 +1,7 @@
-import type { Vector2, Vector3, Vector4 } from "./math.vector";
+import type { DeepImmutable } from "../types";
+import { Clamp } from "./math.scalar.functions";
+import type { Vector2, Vector4 } from "./math.vector";
+import { Quaternion, Vector3 } from "./math.vector";
 
 /**
  * Creates a string representation of the Vector2
@@ -29,3 +32,39 @@ export function Vector3ToFixed(vector: Vector3, decimalCount: number): string {
 export function Vector4ToFixed(vector: Vector4, decimalCount: number): string {
     return `{X: ${vector.x.toFixed(decimalCount)} Y: ${vector.y.toFixed(decimalCount)} Z: ${vector.z.toFixed(decimalCount)} W: ${vector.w.toFixed(decimalCount)}}`;
 }
+
+/**
+ * Returns the angle in radians between two quaternions
+ * @param q1 defines the first quaternion
+ * @param q2 defines the second quaternion
+ * @returns the angle in radians between the two quaternions
+ */
+export function GetAngleBetweenQuaternions(q1: DeepImmutable<Quaternion>, q2: DeepImmutable<Quaternion>): number {
+    return Math.acos(Clamp(Quaternion.Dot(q1, q2))) * 2;
+}
+
+/**
+ * Creates a quaternion from two direction vectors
+ * @param a defines the first direction vector
+ * @param b defines the second direction vector
+ * @returns the target quaternion
+ */
+export function GetQuaternionFromDirections<T extends Vector3>(a: T, b: T): Quaternion {
+    const result = new Quaternion();
+    GetQuaternionFromDirectionsToRef(a, b, result);
+    return result;
+}
+
+/**
+ * Creates a quaternion from two direction vectors
+ * @param a defines the first direction vector
+ * @param b defines the second direction vector
+ * @param result defines the target quaternion
+ * @returns the target quaternion
+ */
+export function GetQuaternionFromDirectionsToRef<T extends Vector3, ResultT extends Quaternion>(a: T, b: T, result: ResultT): ResultT {
+    const axis = Vector3.Cross(a, b);
+    const angle = Math.acos(Clamp(Vector3.Dot(a, b), -1, 1));
+    Quaternion.RotationAxisToRef(axis, angle, result);
+    return result;
+}

packages/dev/core/src/Maths/math.vector.ts

@@ -5311,6 +5311,37 @@ export class Quaternion implements Tensor<Tuple<number, 4>, Quaternion>, IQuater
         return this._x * other._x + this._y * other._y + this._z * other._z + this._w * other._w;
     }
 
+    /**
+     * Converts the current quaternion to an axis angle representation
+     * @returns the axis and angle in radians
+     */
+    public toAxisAngle(): { axis: Vector3; angle: number } {
+        const axis = Vector3.Zero();
+        const angle = this.toAxisAngleToRef(axis);
+        return { axis, angle };
+    }
+
+    /**
+     * Converts the current quaternion to an axis angle representation
+     * @param axis defines the target axis vector
+     * @returns the angle in radians
+     */
+    public toAxisAngleToRef<T extends Vector3>(axis: T): number {
+        let angle = 0;
+        const sinHalfAngle = Math.sqrt(this._x * this._x + this._y * this._y + this._z * this._z);
+        const cosHalfAngle = this._w;
+
+        if (sinHalfAngle > 0) {
+            angle = 2 * Math.atan2(sinHalfAngle, cosHalfAngle);
+            axis.set(this._x / sinHalfAngle, this._y / sinHalfAngle, this._z / sinHalfAngle);
+        } else {
+            angle = 0;
+            axis.set(1, 0, 0);
+        }
+
+        return angle;
+    }
+
     // Statics
 
     /**