unison.math3d — 数学工具

完整的 3D 数学库，包含向量、矩阵、四元数、颜色、射线、包围盒等。

使用方式

python

from unison import math3d

常量

常量	值	说明
`math3d.PI`	3.14159...	圆周率
`math3d.HALF_PI`	PI/2	半圆周率
`math3d.TWO_PI`	2*PI	两倍圆周率
`math3d.EPSILON`	极小值	浮点比较容差
`math3d.DEG_TO_RAD`	PI/180	角度转弧度系数
`math3d.RAD_TO_DEG`	180/PI	弧度转角度系数

快速构造函数

python

# 向量
v2 = math3d.vector2(x, y)         # Vector2
v3 = math3d.vector(x, y, z)       # Vector3
v4 = math3d.vector4(x, y, z, w)   # Vector4

# 旋转
q = math3d.rotation(x, y, z, w)           # Quaternion
q = math3d.euler_rotation(x, y, z)        # 从欧拉角创建
q = math3d.axis_rotation(axis, angle)     # 从轴角创建

# 颜色
c = math3d.color(r, g, b, a=1.0)
c = math3d.color_hex("#FF0000")

# 碰撞检测
r = math3d.ray(origin, direction)
p = math3d.plane(normal, distance)
b = math3d.bounds(center, size)

Vector2 — 二维向量

python

v = math3d.Vector2(1.0, 2.0)

属性

属性	类型	说明
`x`	float	X 分量
`y`	float	Y 分量

方法

方法	说明
`dot(other)`	点积
`cross(other)`	叉积（返回 float）
`length()`	向量长度
`length_squared()`	长度平方
`normalize()`	返回归一化向量
`perpendicular()`	返回垂直向量
`rotate(angle)`	旋转向量

静态方法

方法	说明
`Vector2.zero()`	(0, 0)
`Vector2.one()`	(1, 1)
`Vector2.up()`	(0, 1)
`Vector2.down()`	(0, -1)
`Vector2.left()`	(-1, 0)
`Vector2.right()`	(1, 0)
`Vector2.distance(a, b)`	两点距离
`Vector2.lerp(a, b, t)`	线性插值

运算符

支持 + - * / == -v（取反）。

Vector3 — 三维向量

python

v = math3d.Vector3(1.0, 2.0, 3.0)

属性

属性	类型	说明
`x`	float	X 分量
`y`	float	Y 分量
`z`	float	Z 分量

方法

方法	说明
`dot(other)`	点积
`cross(other)`	叉积
`length()`	向量长度
`length_squared()`	长度平方
`normalize()`	归一化
`reflect(normal)`	反射向量
`project(onto)`	投影到另一向量

静态方法

方法	说明
`Vector3.zero()`	(0, 0, 0)
`Vector3.one()`	(1, 1, 1)
`Vector3.up()` / `down()`	(0, 1, 0) / (0, -1, 0)
`Vector3.left()` / `right()`	(-1, 0, 0) / (1, 0, 0)
`Vector3.forward()` / `back()`	(0, 0, 1) / (0, 0, -1)
`Vector3.distance(a, b)`	两点距离
`Vector3.distance_squared(a, b)`	距离平方
`Vector3.lerp(a, b, t)`	线性插值
`Vector3.slerp(a, b, t)`	球面插值
`Vector3.min(a, b)`	逐分量取最小
`Vector3.max(a, b)`	逐分量取最大

运算符

支持 + - * / == -v。

Vector4 — 四维向量

python

v = math3d.Vector4(1.0, 2.0, 3.0, 4.0)
v = math3d.Vector4(v3, w)  # 从 Vector3 + w 分量

属性/方法	说明
`x, y, z, w`	分量属性
`dot(other)`	点积
`length()`	长度
`normalize()`	归一化
`xyz()`	返回前三个分量 (Vector3)

Quaternion — 四元数

python

q = math3d.Quaternion(0, 0, 0, 1)  # 单位四元数
q = math3d.Quaternion.from_euler(0, 90, 0)
q = math3d.Quaternion.from_axis_angle(math3d.Vector3.up(), 45 * math3d.DEG_TO_RAD)

属性

属性	类型
`x, y, z, w`	float

方法

方法	说明
`to_euler()`	转换为欧拉角 (Vector3)
`dot(other)`	点积
`length()`	长度
`normalize()`	归一化
`conjugate()`	共轭
`inverse()`	逆

静态方法

方法	说明
`Quaternion.identity()`	单位四元数
`Quaternion.from_euler(x, y, z)`	从欧拉角创建
`Quaternion.from_axis_angle(axis, angle)`	从轴角创建
`Quaternion.lerp(a, b, t)`	线性插值
`Quaternion.slerp(a, b, t)`	球面插值

运算符

支持 + *。

Matrix — 变换矩阵

python

m = math3d.Matrix()  # 单位矩阵

静态方法

方法	说明
`Matrix.identity()`	单位矩阵
`Matrix.zero()`	零矩阵
`Matrix.translation(v)`	平移矩阵
`Matrix.scale(v)`	缩放矩阵
`Matrix.rotationX(angle)`	绕 X 轴旋转
`Matrix.rotationY(angle)`	绕 Y 轴旋转
`Matrix.rotationZ(angle)`	绕 Z 轴旋转
`Matrix.rotationAxis(axis, angle)`	绕任意轴旋转
`Matrix.lookAt(eye, target, up)`	观察矩阵
`Matrix.perspective(fov, aspect, near, far)`	透视投影
`Matrix.ortho(l, r, b, t, n, f)`	正交投影

方法

方法	说明
`transform_point(point)`	变换点（带平移）
`transform_vector(vec)`	变换向量（不带平移）
`transpose()`	转置
`determinant()`	行列式

运算符

支持 *。

Color — 颜色

python

c = math3d.Color(1.0, 0.0, 0.0, 1.0)  # 红色
c = math3d.Color.red()

属性

r, g, b, a (float, 0~1)。

静态方法（预设颜色）

white(), black(), red(), green(), blue(), yellow(), cyan(), magenta(), gray(), transparent()

其他静态方法

方法	说明
`Color.lerp(a, b, t)`	颜色线性插值
`Color.from_hex(hex_str)`	从十六进制字符串创建

运算符

支持 + *。

Ray — 射线

python

r = math3d.Ray(origin, direction)

属性/方法	说明
`origin`	射线起点 (Vector3)
`direction`	射线方向 (Vector3)
`get_point(distance)`	获取射线上的点

Plane — 平面

python

p = math3d.Plane(normal, distance)

属性/方法	说明
`normal`	平面法线 (Vector3)
`distance`	到原点的距离 (float)
`distance_to_point(point)`	点到平面距离
`closest_point(point)`	平面上最近点

Bounds — 包围盒

python

b = math3d.Bounds(center, extents)

属性/方法	说明
`center`	中心点 (Vector3)
`extents`	半尺寸 (Vector3)
`get_min()`	最小点
`get_max()`	最大点
`get_size()`	尺寸 (2*extents)
`contains(point)`	是否包含点
`intersects(other)`	与另一包围盒是否相交

工具函数

python

math3d.clamp(value, min_val, max_val)       # 钳制
math3d.lerp(a, b, t)                         # 线性插值
math3d.smooth_step(edge0, edge1, x)          # 平滑步进
math3d.inverse_lerp(a, b, value)             # 反向插值
math3d.remap(iMin, iMax, oMin, oMax, value)  # 值域重映射
math3d.degrees(radians)   # 弧度→角度
math3d.radians(degrees)   # 角度→弧度

# 数学函数
math3d.sqrt(x)      math3d.pow(base, exp)
math3d.exp(x)       math3d.log(x)   math3d.log2(x)  math3d.log10(x)
math3d.sin(r)       math3d.cos(r)   math3d.tan(r)
math3d.asin(x)      math3d.acos(x)  math3d.atan(x)  math3d.atan2(y, x)
math3d.abs(x)       math3d.floor(x) math3d.ceil(x)
math3d.round(x)     math3d.sign(x)  math3d.fract(x)  math3d.mod(a, b)
math3d.min(a,b)     math3d.max(a,b)  math3d.min_int(a,b)  math3d.max_int(a,b)

# 随机
math3d.random_range(min, max)           # 随机浮点
math3d.random_range_int(min, max)       # 随机整数

unison.math3d — 数学工具 ​

使用方式 ​

常量 ​

快速构造函数 ​

Vector2 — 二维向量 ​

属性 ​

方法 ​

静态方法 ​

运算符 ​

Vector3 — 三维向量 ​

属性 ​

方法 ​

静态方法 ​

运算符 ​

Vector4 — 四维向量 ​

Quaternion — 四元数 ​

属性 ​

方法 ​

静态方法 ​

运算符 ​

Matrix — 变换矩阵 ​

静态方法 ​

方法 ​

运算符 ​

Color — 颜色 ​

属性 ​

静态方法（预设颜色） ​

其他静态方法 ​

运算符 ​

Ray — 射线 ​

Plane — 平面 ​

Bounds — 包围盒 ​

工具函数 ​

unison.math3d — 数学工具

使用方式

常量

快速构造函数

Vector2 — 二维向量

属性

方法

静态方法

运算符

Vector3 — 三维向量

属性

方法

静态方法

运算符

Vector4 — 四维向量

Quaternion — 四元数

属性

方法

静态方法

运算符

Matrix — 变换矩阵

静态方法

方法

运算符

Color — 颜色

属性

静态方法（预设颜色）

其他静态方法

运算符

Ray — 射线

Plane — 平面

Bounds — 包围盒

工具函数