@realsee/dnalogel 3.69.12 → 3.69.13-alpha-2

package/dist/shared-utils/math/quaternionUtils.d.ts

@@ -0,0 +1,333 @@
+import * as THREE from 'three';
+/**
+ * 四元数相关的工具函数
+ */
+/**
+ * 计算从原始四元数到目标四元数的差值四元数
+ * @param originQuaternion 原始四元数
+ * @param targetQuaternion 目标四元数
+ * @returns 差值四元数，满足 originQuaternion * result = targetQuaternion
+ *
+ * @example
+ * ```typescript
+ * const q1 = new THREE.Quaternion(0, 0, 0, 1) // 初始旋转
+ * const q2 = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), Math.PI / 4) // 绕Y轴旋转45度
+ * const qDiff = calculateQuaternionDifference(q1, q2)
+ *
+ * // 验证：q1 * qDiff 应该等于 q2
+ * const result = q1.clone().multiply(qDiff)
+ * console.log('验证结果:', result.equals(q2)) // 应该为 true
+ * ```
+ */
+export declare function calculateQuaternionDifference(originQuaternion: THREE.Quaternion, targetQuaternion: THREE.Quaternion): THREE.Quaternion;
+/**
+ * 将四元数差值应用到对象上
+ * @param object3D 要旋转的对象
+ * @param quaternionDiff 差值四元数
+ * @param rotateCenter 旋转中心点（可选，如果不提供则以对象中心旋转）
+ *
+ * @example
+ * ```typescript
+ * const mesh = new THREE.Mesh(geometry, material)
+ * const qDiff = calculateQuaternionDifference(currentQuat, targetQuat)
+ * applyQuaternionDifference(mesh, qDiff, new THREE.Vector3(0, 0, 0))
+ * ```
+ */
+export declare function applyQuaternionDifference(object3D: THREE.Object3D, quaternionDiff: THREE.Quaternion, rotateCenter?: THREE.Vector3): void;
+/**
+ * 从原始四元数旋转到目标四元数的完整操作
+ * @param object3D 要旋转的对象
+ * @param targetQuaternion 目标四元数
+ * @param rotateCenter 旋转中心点（可选）
+ * @returns 应用的差值四元数
+ *
+ * @example
+ * ```typescript
+ * const mesh = new THREE.Mesh(geometry, material)
+ * const targetQuat = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), Math.PI / 2)
+ * const appliedDiff = rotateToQuaternion(mesh, targetQuat)
+ * ```
+ */
+export declare function rotateToQuaternion(object3D: THREE.Object3D, targetQuaternion: THREE.Quaternion, rotateCenter?: THREE.Vector3): THREE.Quaternion;
+/**
+ * 验证四元数计算是否正确
+ * @param originQuaternion 原始四元数
+ * @param targetQuaternion 目标四元数
+ * @param quaternionDiff 计算得到的差值四元数
+ * @param tolerance 容差值（默认为 1e-6）
+ * @returns 验证是否通过
+ */
+export declare function verifyQuaternionDifference(originQuaternion: THREE.Quaternion, targetQuaternion: THREE.Quaternion, quaternionDiff: THREE.Quaternion, tolerance?: number): boolean;
+/**
+ * 获取四元数之间的角度差（弧度）
+ * @param q1 第一个四元数
+ * @param q2 第二个四元数
+ * @returns 角度差（弧度）
+ */
+export declare function getQuaternionAngleDifference(q1: THREE.Quaternion, q2: THREE.Quaternion): number;
+/**
+ * 从四元数和原始向量反推目标向量
+ * @param quaternion 通过setFromUnitVectors(p1, p2)创建的四元数
+ * @param p1 原始向量（已知）
+ * @returns 目标向量p2
+ *
+ * @description
+ * 当四元数是通过 setFromUnitVectors(p1, p2) 创建时，
+ * 可以使用此函数从已知的四元数和p1向量反推出p2向量
+ *
+ * @example
+ * ```typescript
+ * // 已知两个向量
+ * const p1 = new THREE.Vector3(1, 0, 0).normalize()
+ * const p2 = new THREE.Vector3(0, 1, 0).normalize()
+ *
+ * // 创建四元数
+ * const quaternion = new THREE.Quaternion().setFromUnitVectors(p1, p2)
+ *
+ * // 反推p2（已知quaternion和p1）
+ * const reconstructedP2 = reverseVectorFromQuaternion(quaternion, p1)
+ *
+ * // 验证结果
+ * console.log('原始p2:', p2)
+ * console.log('反推p2:', reconstructedP2)
+ * console.log('是否相等:', p2.distanceTo(reconstructedP2) < 0.0001)
+ * ```
+ */
+export declare function reverseVectorFromQuaternion(quaternion: THREE.Quaternion, p1: THREE.Vector3): THREE.Vector3;
+/**
+ * 验证向量反推的准确性
+ * @param originalP1 原始向量p1
+ * @param originalP2 原始向量p2
+ * @param reconstructedP2 反推得到的p2
+ * @param tolerance 容差值（默认为 1e-6）
+ * @returns 验证是否通过
+ *
+ * @example
+ * ```typescript
+ * const p1 = new THREE.Vector3(1, 0, 0).normalize()
+ * const p2 = new THREE.Vector3(0, 1, 0).normalize()
+ * const quaternion = new THREE.Quaternion().setFromUnitVectors(p1, p2)
+ * const reconstructedP2 = reverseVectorFromQuaternion(quaternion, p1)
+ *
+ * const isValid = verifyVectorReconstruction(p1, p2, reconstructedP2)
+ * console.log('反推验证结果:', isValid)
+ * ```
+ */
+export declare function verifyVectorReconstruction(originalP1: THREE.Vector3, originalP2: THREE.Vector3, reconstructedP2: THREE.Vector3, tolerance?: number): boolean;
+/**
+ * 修改四元数的转动角度并反推计算新的目标向量
+ * @param quaternion 原始四元数（从startVector到currentVector的转动）
+ * @param startVector 起始向量
+ * @param newAngleRadians 新的转动角度（弧度）
+ * @returns 新的目标向量
+ *
+ * @description
+ * 这个函数用于修改一个四元数的转动角度，同时保持转动轴不变，
+ * 然后计算应用新四元数后startVector会转动到的新位置
+ *
+ * @example
+ * ```typescript
+ * // 已知从startVector到currentVector的转动四元数
+ * const startVector = new THREE.Vector3(1, 0, 0).normalize()
+ * const currentVector = new THREE.Vector3(0, 1, 0).normalize()
+ * const quaternion = new THREE.Quaternion().setFromUnitVectors(startVector, currentVector)
+ *
+ * // 修改转动角度为60度（原来可能是90度）
+ * const newAngle = Math.PI / 3 // 60度
+ * const newCurrentVector = modifyQuaternionAngleAndReversVector(quaternion, startVector, newAngle)
+ *
+ * console.log('新的目标向量:', newCurrentVector)
+ * ```
+ */
+export declare function modifyQuaternionAngleAndReversVector(quaternion: THREE.Quaternion, startVector: THREE.Vector3, newAngleRadians: number): THREE.Vector3;
+/**
+ * 从四元数中提取转动轴
+ * @param quaternion 四元数
+ * @returns 归一化的转动轴向量
+ *
+ * @description
+ * 根据四元数的数学定义：q = [cos(θ/2), sin(θ/2) * axis]
+ * 其中 axis 是转动轴的单位向量，θ 是转动角度
+ */
+export declare function extractAxisFromQuaternion(quaternion: THREE.Quaternion): THREE.Vector3;
+/**
+ * 从四元数中提取转动角度
+ * @param quaternion 四元数
+ * @returns 转动角度（弧度）
+ *
+ * @description
+ * 根据四元数的数学定义：q = [cos(θ/2), sin(θ/2) * axis]
+ * 角度 θ = 2 * acos(|w|)
+ */
+export declare function extractAngleFromQuaternion(quaternion: THREE.Quaternion): number;
+/**
+ * 修改四元数的转动角度（保持轴不变）
+ * @param quaternion 原始四元数
+ * @param newAngleRadians 新的转动角度（弧度）
+ * @returns 新的四元数
+ *
+ * @example
+ * ```typescript
+ * const originalQuat = new THREE.Quaternion().setFromAxisAngle(
+ *   new THREE.Vector3(0, 1, 0),
+ *   Math.PI / 2 // 90度
+ * )
+ *
+ * // 修改为60度，保持转动轴不变
+ * const newQuat = modifyQuaternionAngle(originalQuat, Math.PI / 3)
+ * ```
+ */
+export declare function modifyQuaternionAngle(quaternion: THREE.Quaternion, newAngleRadians: number): THREE.Quaternion;
+/**
+ * 获取四元数的详细信息（轴和角度）
+ * @param quaternion 四元数
+ * @returns 包含轴向量和角度的对象
+ *
+ * @example
+ * ```typescript
+ * const quat = new THREE.Quaternion().setFromAxisAngle(
+ *   new THREE.Vector3(0, 1, 0),
+ *   Math.PI / 4
+ * )
+ *
+ * const info = getQuaternionInfo(quat)
+ * console.log('转动轴:', info.axis)
+ * console.log('转动角度（度）:', info.angleDegrees)
+ * console.log('转动角度（弧度）:', info.angleRadians)
+ * ```
+ */
+export declare function getQuaternionInfo(quaternion: THREE.Quaternion): {
+    axis: THREE.Vector3;
+    angleRadians: number;
+    angleDegrees: number;
+};
+/**
+ * 获取向量在指定轴方向旋转为0的向量
+ * @param startVec 起始向量
+ * @param axis 轴向量
+ * @returns 移除了在axis方向旋转分量的向量
+ *
+ * @description
+ * 这个函数通过向量投影的方法，移除startVec在axis轴方向上的旋转分量，
+ * 返回垂直于axis的投影向量。数学原理：
+ * 1. 计算startVec在axis上的投影：projection = axis * (startVec · axis)
+ * 2. 从startVec中减去投影得到垂直分量：perpendicular = startVec - projection
+ * 3. 垂直分量就是在axis方向旋转为0的向量
+ *
+ * @example
+ * ```typescript
+ * // 示例：将一个倾斜的向量投影到垂直于Y轴的平面上
+ * const startVec = new THREE.Vector3(1, 1, 1).normalize()
+ * const axis = new THREE.Vector3(0, 1, 0) // Y轴
+ *
+ * const result = getVectorWithZeroRotationOnAxis(startVec, axis)
+ * console.log('原始向量:', startVec)
+ * console.log('轴向量:', axis)
+ * console.log('移除Y轴旋转后的向量:', result)
+ *
+ * // 验证结果向量与轴垂直
+ * const dotProduct = result.dot(axis)
+ * console.log('垂直验证(应该接近0):', dotProduct)
+ * ```
+ */
+export declare function getVectorWithZeroRotationOnAxis(startVec: THREE.Vector3, axis: THREE.Vector3): THREE.Vector3;
+/**
+ * 验证向量是否与指定轴垂直
+ * @param vector 要验证的向量
+ * @param axis 轴向量
+ * @param tolerance 容差值（默认为 1e-6）
+ * @returns 是否垂直
+ *
+ * @example
+ * ```typescript
+ * const startVec = new THREE.Vector3(1, 1, 1)
+ * const axis = new THREE.Vector3(0, 1, 0)
+ * const result = getVectorWithZeroRotationOnAxis(startVec, axis)
+ *
+ * const isVertical = isVectorPerpendicularToAxis(result, axis)
+ * console.log('是否垂直:', isVertical) // 应该为 true
+ * ```
+ */
+export declare function isVectorPerpendicularToAxis(vector: THREE.Vector3, axis: THREE.Vector3, tolerance?: number): boolean;
+/**
+ * 获取四元数在某个轴向量的旋转角度
+ * @param quaternion 四元数
+ * @param axis 指定的轴向量
+ * @returns 旋转角度（弧度）
+ *
+ * @description
+ * 这个函数计算四元数在指定轴方向上的旋转分量。
+ * 通过将四元数分解为轴角表示，然后计算该轴在指定轴上的投影角度。
+ *
+ * 数学原理：
+ * 1. 从四元数中提取转动轴和角度
+ * 2. 计算转动轴与指定轴的夹角
+ * 3. 根据投影关系计算在指定轴上的旋转角度
+ *
+ * @example
+ * ```typescript
+ * // 创建一个绕Y轴旋转45度的四元数
+ * const quat = new THREE.Quaternion().setFromAxisAngle(
+ *   new THREE.Vector3(0, 1, 0),
+ *   Math.PI / 4 // 45度
+ * )
+ *
+ * // 获取在Y轴上的旋转角度
+ * const yAxisAngle = getQuaternionAngleOnAxis(quat, new THREE.Vector3(0, 1, 0))
+ * console.log('Y轴旋转角度（弧度）:', yAxisAngle)
+ * console.log('Y轴旋转角度（度）:', (yAxisAngle * 180) / Math.PI)
+ *
+ * // 获取在X轴上的旋转角度（应该接近0）
+ * const xAxisAngle = getQuaternionAngleOnAxis(quat, new THREE.Vector3(1, 0, 0))
+ * console.log('X轴旋转角度（度）:', (xAxisAngle * 180) / Math.PI)
+ *
+ * // 获取在Z轴上的旋转角度（应该接近0）
+ * const zAxisAngle = getQuaternionAngleOnAxis(quat, new THREE.Vector3(0, 0, 1))
+ * console.log('Z轴旋转角度（度）:', (zAxisAngle * 180) / Math.PI)
+ * ```
+ */
+export declare function getQuaternionAngleOnAxis(quaternion: THREE.Quaternion, axis: THREE.Vector3): number;
+/**
+ * 获取四元数在某个轴向量的旋转角度（度）
+ * @param quaternion 四元数
+ * @param axis 指定的轴向量
+ * @returns 旋转角度（度）
+ *
+ * @example
+ * ```typescript
+ * const quat = new THREE.Quaternion().setFromAxisAngle(
+ *   new THREE.Vector3(0, 1, 0),
+ *   Math.PI / 4
+ * )
+ *
+ * const yAxisAngleDegrees = getQuaternionAngleOnAxisDegrees(quat, new THREE.Vector3(0, 1, 0))
+ * console.log('Y轴旋转角度（度）:', yAxisAngleDegrees) // 应该接近45度
+ * ```
+ */
+export declare function getQuaternionAngleOnAxisDegrees(quaternion: THREE.Quaternion, axis: THREE.Vector3): number;
+/**
+ * 获取四元数在多个轴上的旋转角度
+ * @param quaternion 四元数
+ * @param axes 轴向量数组
+ * @returns 包含各轴旋转角度的对象
+ *
+ * @example
+ * ```typescript
+ * const quat = new THREE.Quaternion().setFromAxisAngle(
+ *   new THREE.Vector3(0, 1, 0),
+ *   Math.PI / 4
+ * )
+ *
+ * const axes = [
+ *   new THREE.Vector3(1, 0, 0), // X轴
+ *   new THREE.Vector3(0, 1, 0), // Y轴
+ *   new THREE.Vector3(0, 0, 1)  // Z轴
+ * ]
+ *
+ * const angles = getQuaternionAnglesOnAxes(quat, axes)
+ * console.log('X轴角度:', angles[0], '度')
+ * console.log('Y轴角度:', angles[1], '度')
+ * console.log('Z轴角度:', angles[2], '度')
+ * ```
+ */
+export declare function getQuaternionAnglesOnAxes(quaternion: THREE.Quaternion, axes: THREE.Vector3[]): number[];