snowykami/mbcp
1
0
Fork 0
mirror of https://github.com/snowykami/mbcp.git synced 2024-11-25 15:55:03 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

✨ 支持Liteyuki Docstring

Browse Source
This commit is contained in:
远野千束 2024-08-31 09:25:28 +08:00
parent 04cb01910f
commit cb0e32b321
11 changed files with 210 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
mbcp/__init__.py
View File

@ -1,5 +1,5 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
本模块塞了一些预设的粒子生成器 本模块是主模块，用于导入所有模块
""" """
from .mp_math import * from .mp_math import *

14
mbcp/mp_math/__init__.py
View File

@ -2,13 +2,13 @@
""" """
本包定义了一些常用的导入，可直接从`mbcp.mp_math`导入使用 本包定义了一些常用的导入，可直接从`mbcp.mp_math`导入使用
导入的类有： 导入的类有：
- `AnyAngle`：任意角 - [`AnyAngle`](./angle#class-anyangle)：任意角度
- `CurveEquation`：曲线方程 - [`CurveEquation`](./equation#class-curveequation)：曲线方程
- `Line3`：三维直线 - [`Line3`](./line#class-line3)：三维直线
- `Plane3`：三维平面 - [`Plane3`](./plane#class-plane3)：三维平面
- `Point3`：三维点 - [`Point3`](./point#class-point3)：三维点
- `Segment3`：三维线段 - [`Segment3`](./segment#class-segment3)：三维线段
- `Vector3`：三维向量 - [`Vector3`](./vector#class-vector3)：三维向量
""" """
from .angle import AnyAngle from .angle import AnyAngle
from .const import * from .const import *

8
mbcp/mp_math/equation.py
View File

@ -13,9 +13,9 @@ class CurveEquation:
""" """
曲线方程。 曲线方程。
Args: Args:
x_func: x函数 x_func ([`OneVarFunc`](./mp_math_typing#var-onevarfunc)): x函数
y_func: y函数 y_func ([`OneVarFunc`](./mp_math_typing#var-onevarfunc)): y函数
z_func: z函数 z_func ([`OneVarFunc`](./mp_math_typing#var-onevarfunc)): z函数
""" """
self.x_func = x_func self.x_func = x_func
self.y_func = y_func self.y_func = y_func
@ -46,7 +46,7 @@ def get_partial_derivative_func(func: MultiVarsFunc, var: int | tuple[int, ...],
> 目前数学界对于一个函数的导函数并没有通解的说法，因此该函数的稳定性有待提升 > 目前数学界对于一个函数的导函数并没有通解的说法，因此该函数的稳定性有待提升
Args: Args:
func: 函数 func ([`MultiVarsFunc`](./mp_math_typing#var-multivarsfunc)): N元函数
var: 变量位置，可为整数(一阶偏导)或整数元组(高阶偏导) var: 变量位置，可为整数(一阶偏导)或整数元组(高阶偏导)
epsilon: 偏移量 epsilon: 偏移量
Returns: Returns:

8
mbcp/mp_math/function.py
View File

@ -15,8 +15,8 @@ def cal_gradient_3vf(func: ThreeSingleVarsFunc, p: Point3, epsilon: float = EPSI
> 已知一个函数$f(x, y, z)$，则其在点$(x_0, y_0, z_0)$处的梯度向量为: > 已知一个函数$f(x, y, z)$，则其在点$(x_0, y_0, z_0)$处的梯度向量为:
$\nabla f(x_0, y_0, z_0) = \left(\frac{\partial f}{\partial x}, \frac{\partial f}{\partial y}, \frac{\partial f}{\partial z}\right)$ $\nabla f(x_0, y_0, z_0) = \left(\frac{\partial f}{\partial x}, \frac{\partial f}{\partial y}, \frac{\partial f}{\partial z}\right)$
Args: Args:
func: 三元函数 func ([`ThreeSingleVarsFunc`](./mp_math_typing#var-threesinglevarsfunc)): 三元函数
p: 点 p ([`Point3`](./point#class-point3)): 点
epsilon: 偏移量 epsilon: 偏移量
Returns: Returns:
梯度 梯度
@ -33,8 +33,8 @@ def curry(func: MultiVarsFunc, *args: Var) -> OneVarFunc:
> [!tip] > [!tip]
> 有关函数柯里化，可参考[函数式编程--柯理化（Currying）](https://zhuanlan.zhihu.com/p/355859667) > 有关函数柯里化，可参考[函数式编程--柯理化（Currying）](https://zhuanlan.zhihu.com/p/355859667)
Args: Args:
func: 函数 func ([`MultiVarsFunc`](./mp_math_typing#var-multivarsfunc)): 函数
*args: 参数 *args ([`Var`](./mp_math_typing#var-var)): 参数
Returns: Returns:
柯里化后的函数 柯里化后的函数
Examples: Examples:

85
mbcp/mp_math/line.py
View File

@ -20,8 +20,8 @@ class Line3:
""" """
三维空间中的直线。由一个点和一个方向向量确定。 三维空间中的直线。由一个点和一个方向向量确定。
Args: Args:
point: 直线上的一点 point ([`Point3`](./point#class-point3)): 直线上的一点
direction: 直线的方向向量 direction ([`Vector3`](./vector#class-vector3)): 方向向量
""" """
self.point = point self.point = point
self.direction = direction self.direction = direction
@ -30,10 +30,10 @@ class Line3:
""" """
判断两条直线是否近似相等。 判断两条直线是否近似相等。
Args: Args:
other: 另一条直线 other ([`Line3`](./line#class-line3)): 另一条直线
epsilon: 误差 epsilon ([`float`](https://docs.python.org/3/library/functions.html#float)): 误差
Returns: Returns:
是否近似相等 [`bool`](https://docs.python.org/3/library/functions.html#bool): 是否近似相等
""" """
return self.is_approx_parallel(other, epsilon) and (self.point - other.point).is_approx_parallel(self.direction, epsilon) return self.is_approx_parallel(other, epsilon) and (self.point - other.point).is_approx_parallel(self.direction, epsilon)
@ -41,11 +41,9 @@ class Line3:
""" """
计算直线和直线之间的夹角。 计算直线和直线之间的夹角。
Args: Args:
other: 另一条直线 other ([`Line3`](./line#class-line3)): 另一条直线
Returns: Returns:
夹角弧度 [`AnyAngle`](./angle#class-anyangle): 夹角
Raises:
TypeError: 不支持的类型
""" """
return self.direction.cal_angle(other.direction) return self.direction.cal_angle(other.direction)
@ -53,12 +51,11 @@ class Line3:
""" """
计算直线和直线或点之间的距离。 计算直线和直线或点之间的距离。
Args: Args:
other: 平行直线或点 other ([`Line3`](./line#class-line3) | [`Point3`](./point#class-point3)): 另一条直线或点
Returns: Returns:
距离 [`float`](https%3A//docs.python.org/3/library/functions.html#float): 距离
Raises: Raises:
TypeError: 不支持的类型 [`TypeError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 不支持的类型
""" """
if isinstance(other, Line3): if isinstance(other, Line3):
# 相交/重合 = 0；平行和异面需要计算距离 # 相交/重合 = 0；平行和异面需要计算距离
@ -84,12 +81,12 @@ class Line3:
""" """
计算两条直线的交点。 计算两条直线的交点。
Args: Args:
other: 另一条直线 other ([`Line3`](./line#class-line3)): 另一条直线
Returns: Returns:
交点 [`Point3`](./point#class-point3): 交点
Raises: Raises:
ValueError: 直线平行 [`ValueError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 直线平行
ValueError: 直线不共面 `ValueError`: 直线不共面
""" """
if self.is_parallel(other): if self.is_parallel(other):
raise ValueError("Lines are parallel and do not intersect.") raise ValueError("Lines are parallel and do not intersect.")
@ -102,9 +99,9 @@ class Line3:
""" """
计算直线经过指定点p的垂线。 计算直线经过指定点p的垂线。
Args: Args:
point: 指定点 point ([`Point3`](./point#class-point3)): 指定点
Returns: Returns:
垂线 [`Line3`](./line#class-line3): 垂线
""" """
return Line3(point, self.direction.cross(point - self.point)) return Line3(point, self.direction.cross(point - self.point))
@ -112,9 +109,9 @@ class Line3:
""" """
获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。 获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
Args: Args:
t: 参数t t ([`RealNumber`](./mp_math_typing#var-realnumber)): 参数t
Returns: Returns:
点 [`Point3`](./point#class-point3): 点
""" """
return self.point + t * self.direction return self.point + t * self.direction
@ -122,7 +119,7 @@ class Line3:
""" """
获取直线的参数方程。 获取直线的参数方程。
Returns: Returns:
x(t), y(t), z(t) [`tuple`](https%3A//docs.python.org/3/library/stdtypes.html#tuple)[[`OneSingleVarFunc`](./mp_math_typing#var-onesinglevarfunc), `OneSingleVarFunc`, `OneSingleVarFunc`]: 参数方程
""" """
return (lambda t: self.point.x + self.direction.x * t, return (lambda t: self.point.x + self.direction.x * t,
lambda t: self.point.y + self.direction.y * t, lambda t: self.point.y + self.direction.y * t,
@ -132,10 +129,10 @@ class Line3:
""" """
判断两条直线是否近似平行。 判断两条直线是否近似平行。
Args: Args:
other: 另一条直线 other ([`Line3`](./line#class-line3)): 另一条直线
epsilon: 误差 epsilon ([`float`](https%3A//docs.python.org/3/library/functions.html#float)): 误差
Returns: Returns:
是否近似平行 [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否近似平行
""" """
return self.direction.is_approx_parallel(other.direction, epsilon) return self.direction.is_approx_parallel(other.direction, epsilon)
@ -143,9 +140,9 @@ class Line3:
""" """
判断两条直线是否平行。 判断两条直线是否平行。
Args: Args:
other: 另一条直线 other ([`Line3`](./line#class-line3)): 另一
Returns: Returns:
是否平行 [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否平行
""" """
return self.direction.is_parallel(other.direction) return self.direction.is_parallel(other.direction)
@ -153,9 +150,9 @@ class Line3:
""" """
判断两条直线是否共线。 判断两条直线是否共线。
Args: Args:
other: 另一条直线 other ([`Line3`](./line#class-line3)): 另一
Returns: Returns:
是否共线 [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否共线
""" """
return self.is_parallel(other) and (self.point - other.point).is_parallel(self.direction) return self.is_parallel(other) and (self.point - other.point).is_parallel(self.direction)
@ -163,9 +160,9 @@ class Line3:
""" """
判断点是否在直线上。 判断点是否在直线上。
Args: Args:
point: 点 point ([`Point3`](./point#class-point3)): 点
Returns: Returns:
是否在直线上 [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否在直线上
""" """
return (point - self.point).is_parallel(self.direction) return (point - self.point).is_parallel(self.direction)
@ -174,9 +171,9 @@ class Line3:
判断两条直线是否共面。 判断两条直线是否共面。
充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。 充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
Args: Args:
other: 另一条直线 other ([`Line3`](./line#class-line3)): 另一
Returns: Returns:
是否共面 [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否共面
""" """
return self.direction.cross(other.direction) @ (self.point - other.point) == 0 return self.direction.cross(other.direction) @ (self.point - other.point) == 0
@ -203,10 +200,10 @@ class Line3:
""" """
工厂函数 由两点构造直线。 工厂函数 由两点构造直线。
Args: Args:
p1: 点1 p1 ([`Point3`](./point#class-point3)): 点1
p2: 点2 p2 ([`Point3`](./point#class-point3)): 点2
Returns: Returns:
直线 [`Line3`](./line#class-line3): 直线
""" """
direction = p2 - p1 direction = p2 - p1
return cls(p1, direction) return cls(p1, direction)
@ -215,9 +212,9 @@ class Line3:
""" """
计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。 计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。
Args: Args:
other: 另一条直线 other ([`Line3`](./line#class-line3)): 另一条直线
Returns: Returns:
交点 [`Line3`](./line#class-line3) | [`Point3`](./point#class-point3) | [`None`](https://docs.python.org/3/library/constants.html#None): 交集
""" """
if self.is_collinear(other): if self.is_collinear(other):
return self return self
@ -232,10 +229,9 @@ class Line3:
v1 // v2 ∧ (p1 - p2) // v1 v1 // v2 ∧ (p1 - p2) // v1
Args: Args:
other: other ([`Line3`](./line#class-line3)): 另一条直线
Returns: Returns:
[`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否等价
""" """
return self.direction.is_parallel(other.direction) and (self.point - other.point).is_parallel(self.direction) return self.direction.is_parallel(other.direction) and (self.point - other.point).is_parallel(self.direction)
@ -243,7 +239,7 @@ class Line3:
""" """
返回点向式（x-x0） 返回点向式（x-x0）
Returns: Returns:
[`str`](https%3A//docs.python.org/3/library/functions.html#str): 点向式
""" """
s = "Line3: " s = "Line3: "
if self.direction.x != 0: if self.direction.x != 0:
@ -255,4 +251,9 @@ class Line3:
return s return s
def __repr__(self): def __repr__(self):
"""
返回直线的字符串表示。
Returns:
[`str`](https%3A//docs.python.org/3/library/functions.html#str) 字符串表示
"""
return f"Line3({self.point}, {self.direction})" return f"Line3({self.point}, {self.direction})"

88
mbcp/mp_math/plane.py
View File

@ -21,10 +21,10 @@ class Plane3:
""" """
平面方程：ax + by + cz + d = 0 平面方程：ax + by + cz + d = 0
Args: Args:
a: x系数 a ([`float`](https%3A//docs.python.org/3/library/functions.html#float)): x系数
b: y系数 b (`float`): y系数
c: z系数 c (`float`): z系数
d: 常数项 d (`float`): 常数项
""" """
self.a = a self.a = a
self.b = b self.b = b
@ -35,9 +35,9 @@ class Plane3:
""" """
判断两个平面是否近似相等。 判断两个平面是否近似相等。
Args: Args:
other: 另一个平面 other ([`Plane3`](./plane#class-plane3)): 另一个平面
Returns: Returns:
是否近似相等 [`bool`](https://docs.python.org/3/library/functions.html#bool): 是否近似相等
""" """
if self.a != 0: if self.a != 0:
k = other.a / self.a k = other.a / self.a
@ -55,11 +55,11 @@ class Plane3:
""" """
计算平面与平面之间的夹角。 计算平面与平面之间的夹角。
Args: Args:
other: 另一个平面 other ([`Line3`](./line#class-line3) | [`Plane3`](./plane#class-plane3)): 另一个平面或直线
Returns: Returns:
夹角弧度 [`AnyAngle`](./angle#class-anyangle): 夹角
Raises: Raises:
TypeError: 不支持的类型 [`TypeError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 不支持的类型
""" """
if isinstance(other, Line3): if isinstance(other, Line3):
return self.normal.cal_angle(other.direction).complementary return self.normal.cal_angle(other.direction).complementary
@ -72,11 +72,11 @@ class Plane3:
""" """
计算平面与平面或点之间的距离。 计算平面与平面或点之间的距离。
Args: Args:
other: 另一个平面或点 other ([`Plane3`](./plane#class-plane3) | [`Point3`](./point#class-point3)): 另一个平面或点
Returns: Returns:
距离 [`float`](https%3A//docs.python.org/3/library/functions.html#float): 距离
Raises: Raises:
TypeError: 不支持的类型 [`TypeError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 不支持的类型
""" """
if isinstance(other, Plane3): if isinstance(other, Plane3):
return 0 return 0
@ -89,10 +89,11 @@ class Plane3:
""" """
计算两平面的交线。 计算两平面的交线。
Args: Args:
other: 另一个平面 other ([`Plane3`](./plane#class-plane3)): 另一个平面
Returns: Returns:
两平面的交线 [`Line3`](./line#class-line3): 交线
Raises: Raises:
[`ValueError`](https%3A//docs.python.org/3/library/exceptions.html#ValueError): 平面平行且无交线
""" """
if self.normal.is_parallel(other.normal): if self.normal.is_parallel(other.normal):
raise ValueError("Planes are parallel and have no intersection.") raise ValueError("Planes are parallel and have no intersection.")
@ -121,11 +122,11 @@ class Plane3:
""" """
计算平面与直线的交点。 计算平面与直线的交点。
Args: Args:
other: 不与平面平行或在平面上的直线 other ([`Line3`](./line#class-line3)): 直线
Returns: Returns:
交点 [`Point3`](./point#class-point3): 交点
Raises: Raises:
ValueError: 平面与直线平行或重合 [`ValueError`](https%3A//docs.python.org/3/library/exceptions.html#ValueError): 平面与直线平行或重合
""" """
# 若平面的法向量与直线方向向量垂直，则直线与平面平行或重合 # 若平面的法向量与直线方向向量垂直，则直线与平面平行或重合
if self.normal @ other.direction == 0: if self.normal @ other.direction == 0:
@ -141,9 +142,9 @@ class Plane3:
""" """
计算平行于该平面且过指定点的平面。 计算平行于该平面且过指定点的平面。
Args: Args:
point: 指定点 point ([`Point3`](./point#class-point3)): 指定点
Returns: Returns:
所求平面 [`Plane3`](./plane#class-plane3): 平面
""" """
return Plane3.from_point_and_normal(point, self.normal) return Plane3.from_point_and_normal(point, self.normal)
@ -151,9 +152,9 @@ class Plane3:
""" """
判断两个平面是否平行。 判断两个平面是否平行。
Args: Args:
other: 另一个平面 other ([`Plane3`](./plane#class-plane3)): 另一个平面
Returns: Returns:
是否平行 [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否平行
""" """
return self.normal.is_parallel(other.normal) return self.normal.is_parallel(other.normal)
@ -162,7 +163,7 @@ class Plane3:
""" """
平面的法向量。 平面的法向量。
Returns: Returns:
法向量 [`Vector3`](./vector#class-vector3): 法向量
""" """
return Vector3(self.a, self.b, self.c) return Vector3(self.a, self.b, self.c)
@ -171,10 +172,10 @@ class Plane3:
""" """
工厂函数 由点和法向量构造平面(点法式构造)。 工厂函数 由点和法向量构造平面(点法式构造)。
Args: Args:
point: 平面上的一点 point ([`Point3`](./point#class-point3)): 平面上一点
normal: 法向量 normal ([`Vector3`](./vector#class-vector3)): 法向量
Returns: Returns:
平面 [`Plane3`](./plane#class-plane3): 平面
""" """
a, b, c = normal.x, normal.y, normal.z a, b, c = normal.x, normal.y, normal.z
d = -a * point.x - b * point.y - c * point.z # d = -ax - by - cz d = -a * point.x - b * point.y - c * point.z # d = -ax - by - cz
@ -185,9 +186,9 @@ class Plane3:
""" """
工厂函数 由三点构造平面。 工厂函数 由三点构造平面。
Args: Args:
p1: 点1 p1 ([`Point3`](./point#class-point3)): 点1
p2: 点2 p2 (`Point3`): 点2
p3: 点3 p3 (`Point3`): 点3
Returns: Returns:
平面 平面
""" """
@ -203,8 +204,8 @@ class Plane3:
""" """
工厂函数 由两直线构造平面。 工厂函数 由两直线构造平面。
Args: Args:
l1: 直线1 l1 ([`Line3`](./line#class-line3)): 直线
l2: 直线2 l2 (`Line3`): 直线
Returns: Returns:
平面 平面
""" """
@ -219,17 +220,27 @@ class Plane3:
""" """
工厂函数 由点和直线构造平面。 工厂函数 由点和直线构造平面。
Args: Args:
point: 面上一点 point ([`Point3`](./point#class-point3)): 平面上一点
line: 面上直线，不包含点 line ([`Line3`](./line#class-line3)): 直线
Returns: Returns:
平面 平面
""" """
return cls.from_point_and_normal(point, line.direction) return cls.from_point_and_normal(point, line.direction)
def __repr__(self): def __repr__(self):
"""
返回平面的字符串表示。
Returns:
[`str`](https%3A//docs.python.org/3/library/functions.html#str): 字符串表示
"""
return f"Plane3({self.a}, {self.b}, {self.c}, {self.d})" return f"Plane3({self.a}, {self.b}, {self.c}, {self.d})"
def __str__(self): def __str__(self):
"""
返回平面的字符串表示。
Returns:
[`str`](https%3A//docs.python.org/3/library/functions.html#str): 字符串表示
"""
s = "Plane3: " s = "Plane3: "
if self.a != 0: if self.a != 0:
s += f"{sign(self.a, only_neg=True)}{abs(self.a)}x" s += f"{sign(self.a, only_neg=True)}{abs(self.a)}x"
@ -253,9 +264,11 @@ class Plane3:
""" """
取两平面的交集（人话：交线） 取两平面的交集（人话：交线）
Args: Args:
other: other ([`Line3`](./line#class-line3) | [`Plane3`](./plane#class-plane3)): 另一个平面或直线
Returns: Returns:
不平行平面的交线，平面平行返回None [`Line3`](./line#class-line3) | [`Point3`](./point#class-point3) | [`None`](https%3A//docs.python.org/3/library/constants.html#None): 交集
Raises:
[`TypeError`](https%3A//docs.python.org/3/library/exceptions.html#TypeError): 不支持的类型
""" """
if isinstance(other, Plane3): if isinstance(other, Plane3):
if self.normal.is_parallel(other.normal): if self.normal.is_parallel(other.normal):
@ -269,6 +282,13 @@ class Plane3:
raise TypeError(f"unsupported operand type(s) for &: 'Plane3' and '{type(other)}'") raise TypeError(f"unsupported operand type(s) for &: 'Plane3' and '{type(other)}'")
def __eq__(self, other) -> bool: def __eq__(self, other) -> bool:
"""
判断两个平面是否等价。
Args:
other ([`Plane3`](./plane#class-plane3)): 另一个平面
Returns:
[`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否等价
"""
return self.approx(other) return self.approx(other)
def __rand__(self, other: 'Line3') -> 'Point3': def __rand__(self, other: 'Line3') -> 'Point3':

30
mbcp/mp_math/point.py
View File

@ -16,9 +16,9 @@ class Point3:
""" """
笛卡尔坐标系中的点。 笛卡尔坐标系中的点。
Args: Args:
x: x 坐标 x ([`float`](https://docs.python.org/3/library/functions.html#float)): x 坐标
y: y 坐标 y (`float`): y 坐标
z: z 坐标 z (`float`): z 坐标
""" """
self.x = x self.x = x
self.y = y self.y = y
@ -28,15 +28,19 @@ class Point3:
""" """
判断两个点是否近似相等。 判断两个点是否近似相等。
Args: Args:
other: other ([`Point3`](./point#class-point3)): 另一个点
epsilon: epsilon ([`float`](https://docs.python.org/3/library/functions.html#float)): 误差
Returns: Returns:
是否近似相等 [`bool`](https://docs.python.org/3/library/functions.html#bool): 是否近似相等
""" """
return all([abs(self.x - other.x) < epsilon, abs(self.y - other.y) < epsilon, abs(self.z - other.z) < epsilon]) return all([abs(self.x - other.x) < epsilon, abs(self.y - other.y) < epsilon, abs(self.z - other.z) < epsilon])
def __str__(self): def __str__(self):
"""
点的字符串表示。
Returns:
[`str`](https://docs.python.org/3/library/functions.html#str): 字符串
"""
return f"Point3({self.x}, {self.y}, {self.z})" return f"Point3({self.x}, {self.y}, {self.z})"
@overload @overload
@ -52,8 +56,9 @@ class Point3:
P + V -> P P + V -> P
P + P -> P P + P -> P
Args: Args:
other: other ([`Vector3`](./vector#class-vector3) | [`Point3`](./point#class-point3)): 另一个点或向量
Returns: Returns:
[`Point3`](./point#class-point3): 新的点
""" """
return Point3(self.x + other.x, self.y + other.y, self.z + other.z) return Point3(self.x + other.x, self.y + other.y, self.z + other.z)
@ -61,8 +66,9 @@ class Point3:
""" """
判断两个点是否相等。 判断两个点是否相等。
Args: Args:
other: other ([`Point3`](./point#class-point3)): 另一个点
Returns: Returns:
[`bool`](https://docs.python.org/3/library/functions.html#bool): 是否相等
""" """
return approx(self.x, other.x) and approx(self.y, other.y) and approx(self.z, other.z) return approx(self.x, other.x) and approx(self.y, other.y) and approx(self.z, other.z)
@ -70,11 +76,11 @@ class Point3:
""" """
P - P -> V P - P -> V
P - V -> P 已在 :class:`Vector3` 中实现 P - V -> P 已在 [`Vector3`](./vector#class-vector3) 中实现
Args: Args:
other: other ([`Point3`](./point#class-point3)): 另一个点
Returns: Returns:
[`Vector3`](./vector#class-vector3): 新的向量
""" """
from .vector import Vector3 from .vector import Vector3
return Vector3(self.x - other.x, self.y - other.y, self.z - other.z) return Vector3(self.x - other.x, self.y - other.y, self.z - other.z)

15
mbcp/mp_math/segment.py
View File

@ -14,8 +14,9 @@ class Segment3:
def __init__(self, p1: "Point3", p2: "Point3"): def __init__(self, p1: "Point3", p2: "Point3"):
""" """
三维空间中的线段。 三维空间中的线段。
:param p1: Args:
:param p2: p1 ([`Point3`](./point#class-point3)): 线段的一个端点
p2 ([`Point3`](./point#class-point3)): 线段的另一个端点
""" """
self.p1 = p1 self.p1 = p1
self.p2 = p2 self.p2 = p2
@ -28,7 +29,17 @@ class Segment3:
self.midpoint = Point3((self.p1.x + self.p2.x) / 2, (self.p1.y + self.p2.y) / 2, (self.p1.z + self.p2.z) / 2) self.midpoint = Point3((self.p1.x + self.p2.x) / 2, (self.p1.y + self.p2.y) / 2, (self.p1.z + self.p2.z) / 2)
def __repr__(self): def __repr__(self):
"""
线段的字符串表示(可执行)。
Returns:
[`str`](https://docs.python.org/3/library/functions.html#str): 字符串
"""
return f"Segment3({self.p1}, {self.p2})" return f"Segment3({self.p1}, {self.p2})"
def __str__(self): def __str__(self):
"""
线段的字符串表示。
Returns:
[`str`](https://docs.python.org/3/library/functions.html#str): 字符串
"""
return f"Segment3({self.p1} -> {self.p2})" return f"Segment3({self.p1} -> {self.p2})"

34
mbcp/mp_math/utils.py
View File

@ -18,12 +18,12 @@ def clamp(x: float, min_: float, max_: float) -> float:
""" """
区间限定函数 区间限定函数
Args: Args:
x: 待限定的值 x ([`float`](https://docs.python.org/3/library/functions.html#float)): 值
min_: 最小值 min_ (`float`): 最小值
max_: 最大值 max_ (`float`): 最大值
Returns: Returns:
限制后的值 `float`: 限定在区间内的值
""" """
return max(min(x, max_), min_) return max(min(x, max_), min_)
@ -31,10 +31,14 @@ def clamp(x: float, min_: float, max_: float) -> float:
class Approx: class Approx:
""" """
用于近似比较对象 用于近似比较对象
已实现对象 实数 Vector3 Point3 Plane3 Line3 已实现对象 实数 Vector3 Point3 Plane3 Line3
""" """
def __init__(self, value: RealNumber): def __init__(self, value: RealNumber):
"""
用于近似比较对象
Args:
value ([`RealNumber`](./mp_math_typing#realnumber)): 实数
"""
self.value = value self.value = value
def __eq__(self, other): def __eq__(self, other):
@ -60,11 +64,11 @@ def approx(x: float, y: float = 0.0, epsilon: float = APPROX) -> bool:
""" """
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。 判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
Args: Args:
x: 数1 x ([`float`](https://docs.python.org/3/library/functions.html#float)): 数1
y: 数2 y (`float`): 数2
epsilon: 误差 epsilon (`float`): 误差
Returns: Returns:
是否近似相等 [`bool`](https://docs.python.org/3/library/functions.html#bool): 是否近似相等
""" """
return abs(x - y) < epsilon return abs(x - y) < epsilon
@ -72,10 +76,10 @@ def approx(x: float, y: float = 0.0, epsilon: float = APPROX) -> bool:
def sign(x: float, only_neg: bool = False) -> str: def sign(x: float, only_neg: bool = False) -> str:
"""获取数的符号。 """获取数的符号。
Args: Args:
x: 数 x ([`float`](https://docs.python.org/3/library/functions.html#float)): 数
only_neg: 是否只返回负数的符号 only_neg ([`bool`](https://docs.python.org/3/library/functions.html#bool)): 是否只返回负数的符号
Returns: Returns:
符号 + - "" [`str`](https://docs.python.org/3/library/functions.html#str): 符号 + - ""
""" """
if x > 0: if x > 0:
return "+" if not only_neg else "" return "+" if not only_neg else ""
@ -91,10 +95,10 @@ def sign_format(x: float, only_neg: bool = False) -> str:
1 -> +1 1 -> +1
0 -> "" 0 -> ""
Args: Args:
x: 数 x ([`float`](https://docs.python.org/3/library/functions.html#float)): 数
only_neg: 是否只返回负数的符号 only_neg ([`bool`](https://docs.python.org/3/library/functions.html#bool)): 是否只返回负数的符号
Returns: Returns:
符号 + - "" [`str`](https://docs.python.org/3/library/functions.html#str): 符号 + - ""
""" """
if x > 0: if x > 0:
return f"+{x}" if not only_neg else f"{x}" return f"+{x}" if not only_neg else f"{x}"

72
mbcp/mp_math/vector.py
View File

@ -43,9 +43,9 @@ class Vector3:
""" """
计算两个向量之间的夹角。 计算两个向量之间的夹角。
Args: Args:
other: 另一个向量 other ([`Vector3`](#class-vector3)): 另一个向量
Returns: Returns:
夹角 [`AnyAngle`](./angle#class-anyangle): 夹角
""" """
return AnyAngle(math.acos(self @ other / (self.length * other.length)), is_radian=True) return AnyAngle(math.acos(self @ other / (self.length * other.length)), is_radian=True)
@ -65,9 +65,9 @@ class Vector3:
``x2 y2 z2`` ``x2 y2 z2``
Args: Args:
other: other ([`Vector3`](#class-vector3)): 另一个向量
Returns: Returns:
行列式的结果 [`Vector3`](#class-vector3): 叉乘结果
""" """
return Vector3(self.y * other.z - self.z * other.y, return Vector3(self.y * other.z - self.z * other.y,
self.z * other.x - self.x * other.z, self.z * other.x - self.x * other.z,
@ -77,10 +77,10 @@ class Vector3:
""" """
判断两个向量是否近似平行。 判断两个向量是否近似平行。
Args: Args:
other: 另一个向量 other ([`Vector3`](#class-vector3)): 另一个向量
epsilon: 允许的误差 epsilon ([`float`](https%3A//docs.python.org/3/library/functions.html#float)): 误差
Returns: Returns:
是否近似平行 [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否近似平行
""" """
return self.cross(other).length < epsilon return self.cross(other).length < epsilon
@ -88,9 +88,9 @@ class Vector3:
""" """
判断两个向量是否平行。 判断两个向量是否平行。
Args: Args:
other: 另一个向量 other ([`Vector3`](#class-vector3)): 另一个向量
Returns: Returns:
是否平行 [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否平行
""" """
return self.cross(other).approx(zero_vector3) return self.cross(other).approx(zero_vector3)
@ -110,6 +110,7 @@ class Vector3:
""" """
返回numpy数组 返回numpy数组
Returns: Returns:
[`np.ndarray`](https%3A//numpy.org/doc/stable/reference/generated/numpy.ndarray.html): numpy数组
""" """
return np.array([self.x, self.y, self.z]) return np.array([self.x, self.y, self.z])
@ -119,7 +120,7 @@ class Vector3:
""" """
向量的模。 向量的模。
Returns: Returns:
模 [`float`](https%3A//docs.python.org/3/library/functions.html#float): 模
""" """
return math.sqrt(self.x ** 2 + self.y ** 2 + self.z ** 2) return math.sqrt(self.x ** 2 + self.y ** 2 + self.z ** 2)
@ -128,7 +129,7 @@ class Vector3:
""" """
获取该向量的单位向量。 获取该向量的单位向量。
Returns: Returns:
单位向量 [`Vector3`](#class-vector3): 单位向量
""" """
return self / self.length return self / self.length
@ -148,9 +149,9 @@ class Vector3:
V + P -> P\n V + P -> P\n
V + V -> V V + V -> V
Args: Args:
other: other ([`Vector3`](#class-vector3) | [`Point3`](./point#class-point3)): 另一个向量或点
Returns: Returns:
[`Vector3`](#class-vector3) | [`Point3`](./point#class-point3): 新的向量或点
""" """
if isinstance(other, Vector3): if isinstance(other, Vector3):
return Vector3(self.x + other.x, self.y + other.y, self.z + other.z) return Vector3(self.x + other.x, self.y + other.y, self.z + other.z)
@ -163,9 +164,9 @@ class Vector3:
""" """
判断两个向量是否相等。 判断两个向量是否相等。
Args: Args:
other: other ([`Vector3`](#class-vector3)): 另一个向量
Returns: Returns:
是否相等 [`bool`](https%3A//docs.python.org/3/library/functions.html#bool): 是否相等
""" """
return approx(self.x, other.x) and approx(self.y, other.y) and approx(self.z, other.z) return approx(self.x, other.x) and approx(self.y, other.y) and approx(self.z, other.z)
@ -173,8 +174,10 @@ class Vector3:
""" """
P + V -> P\n P + V -> P\n
别去点那边实现了。 别去点那边实现了。
:param other: Args:
:return: other ([`Point3`](./point#class-point3)): 另一个点
Returns:
[`Point3`](./point#class-point3): 新的点
""" """
return Point3(self.x + other.x, self.y + other.y, self.z + other.z) return Point3(self.x + other.x, self.y + other.y, self.z + other.z)
@ -191,8 +194,9 @@ class Vector3:
V - P -> P\n V - P -> P\n
V - V -> V V - V -> V
Args: Args:
other: other ([`Vector3`](#class-vector3) | [`Point3`](./point#class-point3)): 另一个向量或点
Returns: Returns:
[`Vector3`](#class-vector3) | [`Point3`](./point#class-point3): 新的向量
""" """
if isinstance(other, Vector3): if isinstance(other, Vector3):
return Vector3(self.x - other.x, self.y - other.y, self.z - other.z) return Vector3(self.x - other.x, self.y - other.y, self.z - other.z)
@ -205,9 +209,9 @@ class Vector3:
""" """
P - V -> P P - V -> P
Args: Args:
other: other ([`Point3`](./point#class-point3)): 另一个点
Returns: Returns:
[`Point3`](./point#class-point3): 新的点
""" """
if isinstance(other, Point3): if isinstance(other, Point3):
@ -227,9 +231,9 @@ class Vector3:
""" """
数组运算 非点乘。点乘使用@，叉乘使用cross。 数组运算 非点乘。点乘使用@，叉乘使用cross。
Args: Args:
other: other ([`Vector3`](#class-vector3) | [`float`](https%3A//docs.python.org/3/library/functions.html#float)): 另一个向量或数
Returns: Returns:
[`Vector3`](#class-vector): 数组运算结果
""" """
if isinstance(other, Vector3): if isinstance(other, Vector3):
@ -246,21 +250,37 @@ class Vector3:
""" """
点乘。 点乘。
Args: Args:
other: other ([`Vector3`](#class-vector3)): 另一个向量
Returns: Returns:
[`float`](https%3A//docs.python.org/3/library/functions.html#float): 点乘结果
""" """
return self.x * other.x + self.y * other.y + self.z * other.z return self.x * other.x + self.y * other.y + self.z * other.z
def __truediv__(self, other: RealNumber) -> 'Vector3': def __truediv__(self, other: RealNumber) -> 'Vector3':
return Vector3(self.x / other, self.y / other, self.z / other) return Vector3(self.x / other, self.y / other, self.z / other)
def __neg__(self): def __neg__(self) -> 'Vector3':
"""
取负。
Returns:
[`Vector3`](#class-vector3): 负向量
"""
return Vector3(-self.x, -self.y, -self.z) return Vector3(-self.x, -self.y, -self.z)
def __repr__(self): def __repr__(self) -> str:
"""
向量的字符串表示(可执行)。
Returns:
[`str`](https%3A//docs.python.org/3/library/functions.html#str): 字符串
"""
return f"Vector3({self.x}, {self.y}, {self.z})" return f"Vector3({self.x}, {self.y}, {self.z})"
def __str__(self): def __str__(self) -> str:
"""
向量的字符串表示。
Returns:
[`str`](https%3A//docs.python.org/3/library/functions.html#str): 字符串
"""
return f"Vector3({self.x}, {self.y}, {self.z})" return f"Vector3({self.x}, {self.y}, {self.z})"

8
mbcp/presets/__init__.py
View File

@ -1,10 +1,4 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 本模块塞了一些预设
@Time : 2024/8/12 下午9:12
@Author : snowykami
@Email : snowykami@outlook.com
@File : __init__.py
@Software: PyCharm
""" """