| name | minemap-math-foundations |
| description | MineMap 数学基础规范。覆盖 `Vector2/3/4`、`Matrix3/4`、`Quaternion`、`HeadingPitchRoll`、`Cartographic`、以及角度弧度转换的实际用法。 |
MineMap Math Foundations
Quick Start
const position = minemap.Math.Vector3.fromDegrees(116.39, 39.9, 20);
const hpr = minemap.Math.HeadingPitchRoll.fromDegrees(0, 65, 0);
console.log(position, hpr);
Core Concepts
1) minemap.Math 是业务参数类型系统
高频公开对象包括：
Vector2Vector3Vector4CartographicMatrix2Matrix3Matrix4QuaternionHeadingPitchRollEulertoRadians(...)toDegrees(...)
这套对象在 MineMap 里不是底层细节，而是大量 API 的直接输入类型。
2) Vector3 是最常见核心类型
它高频用于：
如果在写 MineMap 代码，Vector3 基本是最常见对象之一。
3) fromDegrees* 系列是经纬高构造主路径
高频入口：
Vector3.fromDegrees(...)Vector3.fromDegreesArrayHeights(...)
适合：
4) 姿态不要总靠裸数组表达
当业务开始涉及：
应优先使用：
HeadingPitchRollQuaternionMatrix4
5) Math 与 Transforms 分工不同
Math：向量、矩阵、姿态对象本身Transforms：不同坐标系之间的转换
Demo-backed Patterns
模式 1：业务点位通常从 Vector3 开始
大量 demo 与现有 skill 都直接使用：
new minemap.Math.Vector3(...)Vector3.fromDegrees(...)Vector3.fromDegreesArrayHeights(...)
这说明 Vector3 是业务层主类型，而不是数学细枝末节。
模式 2：实例化姿态优先 HeadingPitchRoll.fromDegrees(...)
当前业务里只要姿态来自“度数”输入，就优先这样构造，能明显减少单位混淆。
模式 3：矩阵只在确实需要时接管
普通点位不必过早矩阵化。
但当你开始：
- 组合旋转
- 维护
modelMatrix
- 做局部坐标姿态
就应转向 Matrix4。
Practical Selection Guide
用 Vector2
用 Vector3
用 Vector4
用 HeadingPitchRoll
用 Quaternion
用 Matrix4
- 对象总变换
- 和
Transforms 联动
- 固定坐标矩阵表达
Strict Constraints
1. 不要混淆“经纬高”和“世界笛卡尔”
它们都可能看起来是三个数，但语义完全不同。
2. 批量几何优先 fromDegreesArrayHeights(...)
不要手工一组组 new 大量 Vector3。
3. 角度与弧度要显式区分
有的 API 吃度数，有的对象内部用弧度。不要裸写魔法数后忘记单位。
4. 不要在明显需要对象语义时继续只写数组
当接口已经明显是向量、姿态、矩阵语义时，优先显式使用 minemap.Math.* 类型。
Common Failure Cases
- 用经纬高数组冒充世界坐标
- 批量线面点位仍然手工 new 大量
Vector3
HeadingPitchRoll 与普通 [x, y, z] 旋转数组混着用- 进入矩阵工作流后仍用零散数值硬拼姿态
Demo References
demo/html/3DModelTransform.htmldemo/html/ModelTransformControl.htmldemo/html/PolylineAdaptTerrain.html
See Also
minemap-transformsminemap-scene-componentsminemap-primitives-and-materialsminemap-business-measurementminemap-business-roaming-and-tracking
