diff --git a/docs/ja/api/mp_math/angle.md b/docs/ja/api/mp_math/angle.md index 545fe31..afc0439 100644 --- a/docs/ja/api/mp_math/angle.md +++ b/docs/ja/api/mp_math/angle.md @@ -1,14 +1,10 @@ --- title: mbcp.mp_math.angle --- -### **class** `Angle` -### **class** `AnyAngle(Angle)` -### *method* `__init__(self, value: float, is_radian: bool = False)` 任意角度。 -**引数**: - value: 角度或弧度值 @@ -17,7 +13,6 @@ title: mbcp.mp_math.angle
- ソースコード ```python def __init__(self, value: float, is_radian: bool=False): @@ -35,19 +30,16 @@ def __init__(self, value: float, is_radian: bool=False):
### `@property` -### *method* `complementary(self) -> AnyAngle` 余角：两角的和为90°。 -**戻り値**: - 余角
- ソースコード ```python @property @@ -62,19 +54,16 @@ def complementary(self) -> 'AnyAngle':
### `@property` -### *method* `supplementary(self) -> AnyAngle` 补角：两角的和为180°。 -**戻り値**: - 补角
- ソースコード ```python @property @@ -89,19 +78,16 @@ def supplementary(self) -> 'AnyAngle':
### `@property` -### *method* `degree(self) -> float` 角度。 -**戻り値**: - 弧度
- ソースコード ```python @property @@ -116,19 +102,16 @@ def degree(self) -> float:
### `@property` -### *method* `minimum_positive(self) -> AnyAngle` 最小正角。 -**戻り値**: - 最小正角度
- ソースコード ```python @property @@ -143,19 +126,16 @@ def minimum_positive(self) -> 'AnyAngle':
### `@property` -### *method* `maximum_negative(self) -> AnyAngle` 最大负角。 -**戻り値**: - 最大负角度
- ソースコード ```python @property @@ -170,19 +150,16 @@ def maximum_negative(self) -> 'AnyAngle':
### `@property` -### *method* `sin(self) -> float` 正弦值。 -**戻り値**: - 正弦值
- ソースコード ```python @property @@ -197,19 +174,16 @@ def sin(self) -> float:
### `@property` -### *method* `cos(self) -> float` 余弦值。 -**戻り値**: - 余弦值
- ソースコード ```python @property @@ -224,19 +198,16 @@ def cos(self) -> float:
### `@property` -### *method* `tan(self) -> float` 正切值。 -**戻り値**: - 正切值
- ソースコード ```python @property @@ -251,19 +222,16 @@ def tan(self) -> float:
### `@property` -### *method* `cot(self) -> float` 余切值。 -**戻り値**: - 余切值
- ソースコード ```python @property @@ -278,19 +246,16 @@ def cot(self) -> float:
### `@property` -### *method* `sec(self) -> float` 正割值。 -**戻り値**: - 正割值
- ソースコード ```python @property @@ -305,19 +270,16 @@ def sec(self) -> float:
### `@property` -### *method* `csc(self) -> float` 余割值。 -**戻り値**: - 余割值
- ソースコード ```python @property @@ -331,11 +293,9 @@ def csc(self) -> float: ```
-### *method* `self + other: AnyAngle => AnyAngle`
- ソースコード ```python def __add__(self, other: 'AnyAngle') -> 'AnyAngle': @@ -343,11 +303,9 @@ def __add__(self, other: 'AnyAngle') -> 'AnyAngle': ```
-### *method* `__eq__(self, other)`
- ソースコード ```python def __eq__(self, other): @@ -355,11 +313,9 @@ def __eq__(self, other): ```
-### *method* `self - other: AnyAngle => AnyAngle`
- ソースコード ```python def __sub__(self, other: 'AnyAngle') -> 'AnyAngle': @@ -367,11 +323,9 @@ def __sub__(self, other: 'AnyAngle') -> 'AnyAngle': ```
-### *method* `self * other: float => AnyAngle`
- ソースコード ```python def __mul__(self, other: float) -> 'AnyAngle': @@ -380,11 +334,9 @@ def __mul__(self, other: float) -> 'AnyAngle':
### `@overload` -### *method* `self / other: float => AnyAngle`
- ソースコード ```python @overload @@ -394,11 +346,9 @@ def __truediv__(self, other: float) -> 'AnyAngle':
### `@overload` -### *method* `self / other: AnyAngle => float`
- ソースコード ```python @overload @@ -407,11 +357,9 @@ def __truediv__(self, other: 'AnyAngle') -> float: ```
-### *method* `self / other`
- ソースコード ```python def __truediv__(self, other): diff --git a/docs/zh-Hant/api/index.md b/docs/zh-Hant/api/index.md new file mode 100644 index 0000000..6d251e8 --- /dev/null +++ b/docs/zh-Hant/api/index.md @@ -0,0 +1,3 @@ +--- +title: mbcp +--- diff --git a/docs/zh-Hant/api/mp_math/angle.md b/docs/zh-Hant/api/mp_math/angle.md new file mode 100644 index 0000000..9539679 --- /dev/null +++ b/docs/zh-Hant/api/mp_math/angle.md @@ -0,0 +1,449 @@ +--- +title: mbcp.mp_math.angle +--- +### ***class*** `Angle` + +### ***class*** `AnyAngle` + +### *def* `__init__(self, value: float, is_radian: bool = False)` + + +任意角度。 + +參數: + +- value: 角度或弧度值 + +- is_radian: 是否为弧度，默认为否 + + + +
+源碼 + +```python +def __init__(self, value: float, is_radian: bool=False): + """ + 任意角度。 + Args: + value: 角度或弧度值 + is_radian: 是否为弧度，默认为否 + """ + if is_radian: + self.radian = value + else: + self.radian = value * PI / 180 +``` +
+ +### `@property` +### *def* `complementary(self) -> 'AnyAngle'` + + +余角：两角的和为90°。 + +返回: + +- 余角 + + + +
+源碼 + +```python +@property +def complementary(self) -> 'AnyAngle': + """ + 余角：两角的和为90°。 + Returns: + 余角 + """ + return AnyAngle(PI / 2 - self.minimum_positive.radian, is_radian=True) +``` +
+ +### `@property` +### *def* `supplementary(self) -> 'AnyAngle'` + + +补角：两角的和为180°。 + +返回: + +- 补角 + + + +
+源碼 + +```python +@property +def supplementary(self) -> 'AnyAngle': + """ + 补角：两角的和为180°。 + Returns: + 补角 + """ + return AnyAngle(PI - self.minimum_positive.radian, is_radian=True) +``` +
+ +### `@property` +### *def* `degree(self) -> float` + + +角度。 + +返回: + +- 弧度 + + + +
+源碼 + +```python +@property +def degree(self) -> float: + """ + 角度。 + Returns: + 弧度 + """ + return self.radian * 180 / PI +``` +
+ +### `@property` +### *def* `minimum_positive(self) -> 'AnyAngle'` + + +最小正角。 + +返回: + +- 最小正角度 + + + +
+源碼 + +```python +@property +def minimum_positive(self) -> 'AnyAngle': + """ + 最小正角。 + Returns: + 最小正角度 + """ + return AnyAngle(self.radian % (2 * PI)) +``` +
+ +### `@property` +### *def* `maximum_negative(self) -> 'AnyAngle'` + + +最大负角。 + +返回: + +- 最大负角度 + + + +
+源碼 + +```python +@property +def maximum_negative(self) -> 'AnyAngle': + """ + 最大负角。 + Returns: + 最大负角度 + """ + return AnyAngle(-self.radian % (2 * PI), is_radian=True) +``` +
+ +### `@property` +### *def* `sin(self) -> float` + + +正弦值。 + +返回: + +- 正弦值 + + + +
+源碼 + +```python +@property +def sin(self) -> float: + """ + 正弦值。 + Returns: + 正弦值 + """ + return math.sin(self.radian) +``` +
+ +### `@property` +### *def* `cos(self) -> float` + + +余弦值。 + +返回: + +- 余弦值 + + + +
+源碼 + +```python +@property +def cos(self) -> float: + """ + 余弦值。 + Returns: + 余弦值 + """ + return math.cos(self.radian) +``` +
+ +### `@property` +### *def* `tan(self) -> float` + + +正切值。 + +返回: + +- 正切值 + + + +
+源碼 + +```python +@property +def tan(self) -> float: + """ + 正切值。 + Returns: + 正切值 + """ + return math.tan(self.radian) +``` +
+ +### `@property` +### *def* `cot(self) -> float` + + +余切值。 + +返回: + +- 余切值 + + + +
+源碼 + +```python +@property +def cot(self) -> float: + """ + 余切值。 + Returns: + 余切值 + """ + return 1 / math.tan(self.radian) +``` +
+ +### `@property` +### *def* `sec(self) -> float` + + +正割值。 + +返回: + +- 正割值 + + + +
+源碼 + +```python +@property +def sec(self) -> float: + """ + 正割值。 + Returns: + 正割值 + """ + return 1 / math.cos(self.radian) +``` +
+ +### `@property` +### *def* `csc(self) -> float` + + +余割值。 + +返回: + +- 余割值 + + + +
+源碼 + +```python +@property +def csc(self) -> float: + """ + 余割值。 + Returns: + 余割值 + """ + return 1 / math.sin(self.radian) +``` +
+ +### *def* `__add__(self, other: 'AnyAngle') -> 'AnyAngle'` + + +
+源碼 + +```python +def __add__(self, other: 'AnyAngle') -> 'AnyAngle': + return AnyAngle(self.radian + other.radian, is_radian=True) +``` +
+ +### *def* `__eq__(self, other)` + + +
+源碼 + +```python +def __eq__(self, other): + return approx(self.radian, other.radian) +``` +
+ +### *def* `__sub__(self, other: 'AnyAngle') -> 'AnyAngle'` + + +
+源碼 + +```python +def __sub__(self, other: 'AnyAngle') -> 'AnyAngle': + return AnyAngle(self.radian - other.radian, is_radian=True) +``` +
+ +### *def* `__mul__(self, other: float) -> 'AnyAngle'` + + +
+源碼 + +```python +def __mul__(self, other: float) -> 'AnyAngle': + return AnyAngle(self.radian * other, is_radian=True) +``` +
+ +### *def* `__repr__(self)` + + +
+源碼 + +```python +def __repr__(self): + return f'AnyAngle({self.radian}, is_radian=True)' +``` +
+ +### *def* `__str__(self)` + + +
+源碼 + +```python +def __str__(self): + return f'AnyAngle({self.degree}° or {self.radian} rad)' +``` +
+ +### `@overload` +### *def* `__truediv__(self, other: float) -> 'AnyAngle'` + + +
+源碼 + +```python +@overload +def __truediv__(self, other: float) -> 'AnyAngle': + ... +``` +
+ +### `@overload` +### *def* `__truediv__(self, other: 'AnyAngle') -> float` + + +
+源碼 + +```python +@overload +def __truediv__(self, other: 'AnyAngle') -> float: + ... +``` +
+ +### *def* `__truediv__(self, other)` + + +
+源碼 + +```python +def __truediv__(self, other): + if isinstance(other, AnyAngle): + return self.radian / other.radian + return AnyAngle(self.radian / other, is_radian=True) +``` +
+ diff --git a/docs/zh-Hant/api/mp_math/const.md b/docs/zh-Hant/api/mp_math/const.md new file mode 100644 index 0000000..888edf3 --- /dev/null +++ b/docs/zh-Hant/api/mp_math/const.md @@ -0,0 +1,15 @@ +--- +title: mbcp.mp_math.const +--- +### ***var*** `PI = math.pi` + +### ***var*** `E = math.e` + +### ***var*** `GOLDEN_RATIO = (1 + math.sqrt(5)) / 2` + +### ***var*** `GAMMA = 0.5772156649015329` + +### ***var*** `EPSILON = 0.0001` + +### ***var*** `APPROX = 0.001` + diff --git a/docs/zh-Hant/api/mp_math/equation.md b/docs/zh-Hant/api/mp_math/equation.md new file mode 100644 index 0000000..8a2a0a4 --- /dev/null +++ b/docs/zh-Hant/api/mp_math/equation.md @@ -0,0 +1,177 @@ +--- +title: mbcp.mp_math.equation +--- +### *def* `get_partial_derivative_func(func: MultiVarsFunc = EPSILON) -> MultiVarsFunc` + + +求N元函数一阶偏导函数。这玩意不太稳定，慎用。 + +參數: + +- func: 函数 + +- var: 变量位置，可为整数(一阶偏导)或整数元组(高阶偏导) + +- epsilon: 偏移量 + +返回: + +- 偏导函数 + +引發: + +- ValueError 无效变量类型 + + + +
+源碼 + +```python +def get_partial_derivative_func(func: MultiVarsFunc, var: int | tuple[int, ...], epsilon: Number=EPSILON) -> MultiVarsFunc: + """ + 求N元函数一阶偏导函数。这玩意不太稳定，慎用。 + Args: + func: 函数 + var: 变量位置，可为整数(一阶偏导)或整数元组(高阶偏导) + epsilon: 偏移量 + Returns: + 偏导函数 + Raises: + ValueError: 无效变量类型 + """ + if isinstance(var, int): + + def partial_derivative_func(*args: Var) -> Var: + args_list_plus = list(args) + args_list_plus[var] += epsilon + args_list_minus = list(args) + args_list_minus[var] -= epsilon + return (func(*args_list_plus) - func(*args_list_minus)) / (2 * epsilon) + return partial_derivative_func + elif isinstance(var, tuple): + + def high_order_partial_derivative_func(*args: Var) -> Var: + result_func = func + for v in var: + result_func = get_partial_derivative_func(result_func, v, epsilon) + return result_func(*args) + return high_order_partial_derivative_func + else: + raise ValueError('Invalid var type') +``` +
+ +### *def* `partial_derivative_func() -> Var` + + +
+源碼 + +```python +def partial_derivative_func(*args: Var) -> Var: + args_list_plus = list(args) + args_list_plus[var] += epsilon + args_list_minus = list(args) + args_list_minus[var] -= epsilon + return (func(*args_list_plus) - func(*args_list_minus)) / (2 * epsilon) +``` +
+ +### *def* `high_order_partial_derivative_func() -> Var` + + +
+源碼 + +```python +def high_order_partial_derivative_func(*args: Var) -> Var: + result_func = func + for v in var: + result_func = get_partial_derivative_func(result_func, v, epsilon) + return result_func(*args) +``` +
+ +### ***class*** `CurveEquation` + +### *def* `__init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc)` + + +曲线方程。 + +參數: + +- x_func: x函数 + +- y_func: y函数 + +- z_func: z函数 + + + +
+源碼 + +```python +def __init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc): + """ + 曲线方程。 + Args: + x_func: x函数 + y_func: y函数 + z_func: z函数 + """ + self.x_func = x_func + self.y_func = y_func + self.z_func = z_func +``` +
+ +### *def* `__call__(self) -> Point3 | tuple[Point3, ...]` + + +计算曲线上的点。 + +參數: + +- *t: + +- 参数: + + + +
+源碼 + +```python +def __call__(self, *t: Var) -> Point3 | tuple[Point3, ...]: + """ + 计算曲线上的点。 + Args: + *t: + 参数 + Returns: + + """ + if len(t) == 1: + return Point3(self.x_func(t[0]), self.y_func(t[0]), self.z_func(t[0])) + else: + return tuple([Point3(x, y, z) for x, y, z in zip(self.x_func(t), self.y_func(t), self.z_func(t))]) +``` +
+ +### *def* `__str__(self)` + + +
+源碼 + +```python +def __str__(self): + return 'CurveEquation()' +``` +
+ +### ***var*** `result_func = get_partial_derivative_func(result_func, v, epsilon)` + diff --git a/docs/zh-Hant/api/mp_math/index.md b/docs/zh-Hant/api/mp_math/index.md new file mode 100644 index 0000000..6e3261c --- /dev/null +++ b/docs/zh-Hant/api/mp_math/index.md @@ -0,0 +1,3 @@ +--- +title: mbcp.mp_math +--- diff --git a/docs/zh-Hant/api/mp_math/line.md b/docs/zh-Hant/api/mp_math/line.md new file mode 100644 index 0000000..305e4d5 --- /dev/null +++ b/docs/zh-Hant/api/mp_math/line.md @@ -0,0 +1,622 @@ +--- +title: mbcp.mp_math.line +--- +### ***class*** `Line3` + +### *def* `__init__(self, point: 'Point3', direction: 'Vector3')` + + +三维空间中的直线。由一个点和一个方向向量确定。 + +參數: + +- point: 直线上的一点 + +- direction: 直线的方向向量 + + + +
+源碼 + +```python +def __init__(self, point: 'Point3', direction: 'Vector3'): + """ + 三维空间中的直线。由一个点和一个方向向量确定。 + Args: + point: 直线上的一点 + direction: 直线的方向向量 + """ + self.point = point + self.direction = direction +``` +
+ +### *def* `approx(self, other: 'Line3', epsilon: float = APPROX) -> bool` + + +判断两条直线是否近似相等。 + +參數: + +- other: 另一条直线 + +- epsilon: 误差 + +返回: + +- 是否近似相等 + + + +
+源碼 + +```python +def approx(self, other: 'Line3', epsilon: float=APPROX) -> bool: + """ + 判断两条直线是否近似相等。 + Args: + other: 另一条直线 + epsilon: 误差 + Returns: + 是否近似相等 + """ + return self.is_approx_parallel(other, epsilon) and (self.point - other.point).is_approx_parallel(self.direction, epsilon) +``` +
+ +### *def* `cal_angle(self, other: 'Line3') -> 'AnyAngle'` + + +计算直线和直线之间的夹角。 + +參數: + +- other: 另一条直线 + +返回: + +- 夹角弧度 + +引發: + +- TypeError 不支持的类型 + + + +
+源碼 + +```python +def cal_angle(self, other: 'Line3') -> 'AnyAngle': + """ + 计算直线和直线之间的夹角。 + Args: + other: 另一条直线 + Returns: + 夹角弧度 + Raises: + TypeError: 不支持的类型 + """ + return self.direction.cal_angle(other.direction) +``` +
+ +### *def* `cal_distance(self, other: 'Line3 | Point3') -> float` + + +计算直线和直线或点之间的距离。 + +參數: + +- other: 平行直线或点 + +返回: + +- 距离 + +引發: + +- TypeError 不支持的类型 + + + +
+源碼 + +```python +def cal_distance(self, other: 'Line3 | Point3') -> float: + """ + 计算直线和直线或点之间的距离。 + Args: + other: 平行直线或点 + + Returns: + 距离 + Raises: + TypeError: 不支持的类型 + """ + if isinstance(other, Line3): + if self == other: + return 0 + elif self.is_parallel(other): + return (other.point - self.point).cross(self.direction).length / self.direction.length + elif not self.is_coplanar(other): + return abs(self.direction.cross(other.direction) @ (self.point - other.point) / self.direction.cross(other.direction).length) + else: + return 0 + elif isinstance(other, Point3): + return (other - self.point).cross(self.direction).length / self.direction.length + else: + raise TypeError('Unsupported type.') +``` +
+ +### *def* `cal_intersection(self, other: 'Line3') -> 'Point3'` + + +计算两条直线的交点。 + +參數: + +- other: 另一条直线 + +返回: + +- 交点 + +引發: + +- ValueError 直线平行 + +- ValueError 直线不共面 + + + +
+源碼 + +```python +def cal_intersection(self, other: 'Line3') -> 'Point3': + """ + 计算两条直线的交点。 + Args: + other: 另一条直线 + Returns: + 交点 + Raises: + ValueError: 直线平行 + ValueError: 直线不共面 + """ + if self.is_parallel(other): + raise ValueError('Lines are parallel and do not intersect.') + if not self.is_coplanar(other): + raise ValueError('Lines are not coplanar and do not intersect.') + return self.point + self.direction.cross(other.direction) @ other.direction.cross(self.point - other.point) / self.direction.cross(other.direction).length ** 2 * self.direction +``` +
+ +### *def* `cal_perpendicular(self, point: 'Point3') -> 'Line3'` + + +计算直线经过指定点p的垂线。 + +參數: + +- point: 指定点 + +返回: + +- 垂线 + + + +
+源碼 + +```python +def cal_perpendicular(self, point: 'Point3') -> 'Line3': + """ + 计算直线经过指定点p的垂线。 + Args: + point: 指定点 + Returns: + 垂线 + """ + return Line3(point, self.direction.cross(point - self.point)) +``` +
+ +### *def* `get_point(self, t: RealNumber) -> 'Point3'` + + +获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。 + +參數: + +- t: 参数t + +返回: + +- 点 + + + +
+源碼 + +```python +def get_point(self, t: RealNumber) -> 'Point3': + """ + 获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。 + Args: + t: 参数t + Returns: + 点 + """ + return self.point + t * self.direction +``` +
+ +### *def* `get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc, OneSingleVarFunc]` + + +获取直线的参数方程。 + +返回: + +- x(t), y(t), z(t) + + + +
+源碼 + +```python +def get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc, OneSingleVarFunc]: + """ + 获取直线的参数方程。 + Returns: + x(t), y(t), z(t) + """ + return (lambda t: self.point.x + self.direction.x * t, lambda t: self.point.y + self.direction.y * t, lambda t: self.point.z + self.direction.z * t) +``` +
+ +### *def* `is_approx_parallel(self, other: 'Line3', epsilon: float = 1e-06) -> bool` + + +判断两条直线是否近似平行。 + +參數: + +- other: 另一条直线 + +- epsilon: 误差 + +返回: + +- 是否近似平行 + + + +
+源碼 + +```python +def is_approx_parallel(self, other: 'Line3', epsilon: float=1e-06) -> bool: + """ + 判断两条直线是否近似平行。 + Args: + other: 另一条直线 + epsilon: 误差 + Returns: + 是否近似平行 + """ + return self.direction.is_approx_parallel(other.direction, epsilon) +``` +
+ +### *def* `is_parallel(self, other: 'Line3') -> bool` + + +判断两条直线是否平行。 + +參數: + +- other: 另一条直线 + +返回: + +- 是否平行 + + + +
+源碼 + +```python +def is_parallel(self, other: 'Line3') -> bool: + """ + 判断两条直线是否平行。 + Args: + other: 另一条直线 + Returns: + 是否平行 + """ + return self.direction.is_parallel(other.direction) +``` +
+ +### *def* `is_collinear(self, other: 'Line3') -> bool` + + +判断两条直线是否共线。 + +參數: + +- other: 另一条直线 + +返回: + +- 是否共线 + + + +
+源碼 + +```python +def is_collinear(self, other: 'Line3') -> bool: + """ + 判断两条直线是否共线。 + Args: + other: 另一条直线 + Returns: + 是否共线 + """ + return self.is_parallel(other) and (self.point - other.point).is_parallel(self.direction) +``` +
+ +### *def* `is_point_on(self, point: 'Point3') -> bool` + + +判断点是否在直线上。 + +參數: + +- point: 点 + +返回: + +- 是否在直线上 + + + +
+源碼 + +```python +def is_point_on(self, point: 'Point3') -> bool: + """ + 判断点是否在直线上。 + Args: + point: 点 + Returns: + 是否在直线上 + """ + return (point - self.point).is_parallel(self.direction) +``` +
+ +### *def* `is_coplanar(self, other: 'Line3') -> bool` + + +判断两条直线是否共面。 +充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。 + +參數: + +- other: 另一条直线 + +返回: + +- 是否共面 + + + +
+源碼 + +```python +def is_coplanar(self, other: 'Line3') -> bool: + """ + 判断两条直线是否共面。 + 充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。 + Args: + other: 另一条直线 + Returns: + 是否共面 + """ + return self.direction.cross(other.direction) @ (self.point - other.point) == 0 +``` +
+ +### *def* `simplify(self)` + + +简化直线方程，等价相等。 +自体简化，不返回值。 + +按照可行性一次对x y z 化 0 处理，并对向量单位化 + + + +
+源碼 + +```python +def simplify(self): + """ + 简化直线方程，等价相等。 + 自体简化，不返回值。 + + 按照可行性一次对x y z 化 0 处理，并对向量单位化 + """ + self.direction.normalize() + if self.direction.x == 0: + self.point.x = 0 + if self.direction.y == 0: + self.point.y = 0 + if self.direction.z == 0: + self.point.z = 0 +``` +
+ +### `@classmethod` +### *def* `from_two_points(cls, p1: 'Point3', p2: 'Point3') -> 'Line3'` + + +工厂函数 由两点构造直线。 + +參數: + +- p1: 点1 + +- p2: 点2 + +返回: + +- 直线 + + + +
+源碼 + +```python +@classmethod +def from_two_points(cls, p1: 'Point3', p2: 'Point3') -> 'Line3': + """ + 工厂函数 由两点构造直线。 + Args: + p1: 点1 + p2: 点2 + Returns: + 直线 + """ + direction = p2 - p1 + return cls(p1, direction) +``` +
+ +### *def* `__and__(self, other: 'Line3') -> 'Line3 | Point3 | None'` + + +计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。 + +參數: + +- other: 另一条直线 + +返回: + +- 交点 + + + +
+源碼 + +```python +def __and__(self, other: 'Line3') -> 'Line3 | Point3 | None': + """ + 计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。 + Args: + other: 另一条直线 + Returns: + 交点 + """ + if self.is_collinear(other): + return self + elif self.is_parallel(other) or not self.is_coplanar(other): + return None + else: + return self.cal_intersection(other) +``` +
+ +### *def* `__eq__(self, other) -> bool` + + +判断两条直线是否等价。 + +v1 // v2 ∧ (p1 - p2) // v1 + +參數: + +- other: + + + +
+源碼 + +```python +def __eq__(self, other) -> bool: + """ + 判断两条直线是否等价。 + + v1 // v2 ∧ (p1 - p2) // v1 + Args: + other: + + Returns: + + """ + return self.direction.is_parallel(other.direction) and (self.point - other.point).is_parallel(self.direction) +``` +
+ +### *def* `__str__(self)` + + + + + + +
+源碼 + +```python +def __str__(self): + """ + 返回点向式（x-x0） + Returns: + + """ + s = 'Line3: ' + if self.direction.x != 0: + s += f'(x{sign_format(-self.point.x)})/{self.direction.x}' + if self.direction.y != 0: + s += f' = (y{sign_format(-self.point.y)})/{self.direction.y}' + if self.direction.z != 0: + s += f' = (z{sign_format(-self.point.z)})/{self.direction.z}' + return s +``` +
+ +### *def* `__repr__(self)` + + +
+源碼 + +```python +def __repr__(self): + return f'Line3({self.point}, {self.direction})' +``` +
+ diff --git a/docs/zh-Hant/api/mp_math/mp_math_typing.md b/docs/zh-Hant/api/mp_math/mp_math_typing.md new file mode 100644 index 0000000..b166130 --- /dev/null +++ b/docs/zh-Hant/api/mp_math/mp_math_typing.md @@ -0,0 +1,37 @@ +--- +title: mbcp.mp_math.mp_math_typing +--- +### ***var*** `RealNumber: TypeAlias = int | float` + +### ***var*** `Number: TypeAlias = RealNumber | complex` + +### ***var*** `SingleVar = TypeVar('SingleVar', bound=Number)` + +### ***var*** `ArrayVar = TypeVar('ArrayVar', bound=Iterable[Number])` + +### ***var*** `Var: TypeAlias = SingleVar | ArrayVar` + +### ***var*** `OneSingleVarFunc: TypeAlias = Callable[[SingleVar], SingleVar]` + +### ***var*** `OneArrayFunc: TypeAlias = Callable[[ArrayVar], ArrayVar]` + +### ***var*** `OneVarFunc: TypeAlias = OneSingleVarFunc | OneArrayFunc` + +### ***var*** `TwoSingleVarsFunc: TypeAlias = Callable[[SingleVar, SingleVar], SingleVar]` + +### ***var*** `TwoArraysFunc: TypeAlias = Callable[[ArrayVar, ArrayVar], ArrayVar]` + +### ***var*** `TwoVarsFunc: TypeAlias = TwoSingleVarsFunc | TwoArraysFunc` + +### ***var*** `ThreeSingleVarsFunc: TypeAlias = Callable[[SingleVar, SingleVar, SingleVar], SingleVar]` + +### ***var*** `ThreeArraysFunc: TypeAlias = Callable[[ArrayVar, ArrayVar, ArrayVar], ArrayVar]` + +### ***var*** `ThreeVarsFunc: TypeAlias = ThreeSingleVarsFunc | ThreeArraysFunc` + +### ***var*** `MultiSingleVarsFunc: TypeAlias = Callable[..., SingleVar]` + +### ***var*** `MultiArraysFunc: TypeAlias = Callable[..., ArrayVar]` + +### ***var*** `MultiVarsFunc: TypeAlias = MultiSingleVarsFunc | MultiArraysFunc` + diff --git a/docs/zh-Hant/api/mp_math/plane.md b/docs/zh-Hant/api/mp_math/plane.md new file mode 100644 index 0000000..f19cc6d --- /dev/null +++ b/docs/zh-Hant/api/mp_math/plane.md @@ -0,0 +1,648 @@ +--- +title: mbcp.mp_math.plane +--- +### ***class*** `Plane3` + +### *def* `__init__(self, a: float, b: float, c: float, d: float)` + + +平面方程：ax + by + cz + d = 0 + +參數: + +- a: + +- b: + +- c: + +- d: + + + +
+源碼 + +```python +def __init__(self, a: float, b: float, c: float, d: float): + """ + 平面方程：ax + by + cz + d = 0 + Args: + a: + b: + c: + d: + """ + self.a = a + self.b = b + self.c = c + self.d = d +``` +
+ +### *def* `approx(self, other: 'Plane3') -> bool` + + +判断两个平面是否近似相等。 + +參數: + +- other: + +返回: + +- 是否近似相等 + + + +
+源碼 + +```python +def approx(self, other: 'Plane3') -> bool: + """ + 判断两个平面是否近似相等。 + Args: + other: + + Returns: + 是否近似相等 + """ + a = 3 + if self.a != 0: + k = other.a / self.a + return approx(other.b, self.b * k) and approx(other.c, self.c * k) and approx(other.d, self.d * k) + elif self.b != 0: + k = other.b / self.b + return approx(other.a, self.a * k) and approx(other.c, self.c * k) and approx(other.d, self.d * k) + elif self.c != 0: + k = other.c / self.c + return approx(other.a, self.a * k) and approx(other.b, self.b * k) and approx(other.d, self.d * k) + else: + return False +``` +
+ +### *def* `cal_angle(self, other: 'Line3 | Plane3') -> 'AnyAngle'` + + +计算平面与平面之间的夹角。 + +參數: + +- other: 另一个平面 + +返回: + +- 夹角弧度 + +引發: + +- TypeError 不支持的类型 + + + +
+源碼 + +```python +def cal_angle(self, other: 'Line3 | Plane3') -> 'AnyAngle': + """ + 计算平面与平面之间的夹角。 + Args: + other: 另一个平面 + Returns: + 夹角弧度 + Raises: + TypeError: 不支持的类型 + """ + if isinstance(other, Line3): + return self.normal.cal_angle(other.direction).complementary + elif isinstance(other, Plane3): + return AnyAngle(math.acos(self.normal @ other.normal / (self.normal.length * other.normal.length)), is_radian=True) + else: + raise TypeError(f'Unsupported type: {type(other)}') +``` +
+ +### *def* `cal_distance(self, other: 'Plane3 | Point3') -> float` + + +计算平面与平面或点之间的距离。 + +參數: + +- other: 另一个平面或点 + +返回: + +- 距离 + +引發: + +- TypeError 不支持的类型 + + + +
+源碼 + +```python +def cal_distance(self, other: 'Plane3 | Point3') -> float: + """ + 计算平面与平面或点之间的距离。 + Args: + other: 另一个平面或点 + Returns: + 距离 + Raises: + TypeError: 不支持的类型 + """ + if isinstance(other, Plane3): + return 0 + elif isinstance(other, Point3): + return abs(self.a * other.x + self.b * other.y + self.c * other.z + self.d) / (self.a ** 2 + self.b ** 2 + self.c ** 2) ** 0.5 + else: + raise TypeError(f'Unsupported type: {type(other)}') +``` +
+ +### *def* `cal_intersection_line3(self, other: 'Plane3') -> 'Line3'` + + +计算两平面的交线。该方法有问题，待修复。 + +參數: + +- other: 另一个平面 + +返回: + +- 交线 + + + +
+源碼 + +```python +def cal_intersection_line3(self, other: 'Plane3') -> 'Line3': + """ + 计算两平面的交线。该方法有问题，待修复。 + Args: + other: 另一个平面 + Returns: + 交线 + Raises: + """ + if self.normal.is_parallel(other.normal): + raise ValueError('Planes are parallel and have no intersection.') + direction = self.normal.cross(other.normal) + x, y, z = (0, 0, 0) + if self.a != 0 and other.a != 0: + A = np.array([[self.b, self.c], [other.b, other.c]]) + B = np.array([-self.d, -other.d]) + y, z = np.linalg.solve(A, B) + elif self.b != 0 and other.b != 0: + A = np.array([[self.a, self.c], [other.a, other.c]]) + B = np.array([-self.d, -other.d]) + x, z = np.linalg.solve(A, B) + elif self.c != 0 and other.c != 0: + A = np.array([[self.a, self.b], [other.a, other.b]]) + B = np.array([-self.d, -other.d]) + x, y = np.linalg.solve(A, B) + return Line3(Point3(x, y, z), direction) +``` +
+ +### *def* `cal_intersection_point3(self, other: 'Line3') -> 'Point3'` + + +计算平面与直线的交点。 + +參數: + +- other: 不与平面平行或在平面上的直线 + +返回: + +- 交点 + +引發: + +- ValueError 平面与直线平行或重合 + + + +
+源碼 + +```python +def cal_intersection_point3(self, other: 'Line3') -> 'Point3': + """ + 计算平面与直线的交点。 + Args: + other: 不与平面平行或在平面上的直线 + Returns: + 交点 + Raises: + ValueError: 平面与直线平行或重合 + """ + if self.normal @ other.direction == 0: + raise ValueError('The plane and the line are parallel or coincident.') + x, y, z = other.get_parametric_equations() + t = -(self.a * other.point.x + self.b * other.point.y + self.c * other.point.z + self.d) / (self.a * other.direction.x + self.b * other.direction.y + self.c * other.direction.z) + return Point3(x(t), y(t), z(t)) +``` +
+ +### *def* `cal_parallel_plane3(self, point: 'Point3') -> 'Plane3'` + + +计算平行于该平面且过指定点的平面。 + +參數: + +- point: 指定点 + +返回: + +- 平面 + + + +
+源碼 + +```python +def cal_parallel_plane3(self, point: 'Point3') -> 'Plane3': + """ + 计算平行于该平面且过指定点的平面。 + Args: + point: 指定点 + Returns: + 平面 + """ + return Plane3.from_point_and_normal(point, self.normal) +``` +
+ +### *def* `is_parallel(self, other: 'Plane3') -> bool` + + +判断两个平面是否平行。 + +參數: + +- other: 另一个平面 + +返回: + +- 是否平行 + + + +
+源碼 + +```python +def is_parallel(self, other: 'Plane3') -> bool: + """ + 判断两个平面是否平行。 + Args: + other: 另一个平面 + Returns: + 是否平行 + """ + return self.normal.is_parallel(other.normal) +``` +
+ +### `@property` +### *def* `normal(self) -> 'Vector3'` + + +平面的法向量。 + +返回: + +- 法向量 + + + +
+源碼 + +```python +@property +def normal(self) -> 'Vector3': + """ + 平面的法向量。 + Returns: + 法向量 + """ + return Vector3(self.a, self.b, self.c) +``` +
+ +### `@classmethod` +### *def* `from_point_and_normal(cls, point: 'Point3', normal: 'Vector3') -> 'Plane3'` + + +工厂函数 由点和法向量构造平面(点法式构造)。 + +參數: + +- point: 平面上的一点 + +- normal: 法向量 + +返回: + +- 平面 + + + +
+源碼 + +```python +@classmethod +def from_point_and_normal(cls, point: 'Point3', normal: 'Vector3') -> 'Plane3': + """ + 工厂函数 由点和法向量构造平面(点法式构造)。 + Args: + point: 平面上的一点 + normal: 法向量 + Returns: + 平面 + """ + a, b, c = (normal.x, normal.y, normal.z) + d = -a * point.x - b * point.y - c * point.z + return cls(a, b, c, d) +``` +
+ +### `@classmethod` +### *def* `from_three_points(cls, p1: 'Point3', p2: 'Point3', p3: 'Point3') -> 'Plane3'` + + +工厂函数 由三点构造平面。 + +參數: + +- p1: 点1 + +- p2: 点2 + +- p3: 点3 + +返回: + +- 平面 + + + +
+源碼 + +```python +@classmethod +def from_three_points(cls, p1: 'Point3', p2: 'Point3', p3: 'Point3') -> 'Plane3': + """ + 工厂函数 由三点构造平面。 + Args: + p1: 点1 + p2: 点2 + p3: 点3 + Returns: + 平面 + """ + v1 = p2 - p1 + v2 = p3 - p1 + normal = v1.cross(v2) + return cls.from_point_and_normal(p1, normal) +``` +
+ +### `@classmethod` +### *def* `from_two_lines(cls, l1: 'Line3', l2: 'Line3') -> 'Plane3'` + + +工厂函数 由两直线构造平面。 + +參數: + +- l1: 直线1 + +- l2: 直线2 + +返回: + +- 平面 + + + +
+源碼 + +```python +@classmethod +def from_two_lines(cls, l1: 'Line3', l2: 'Line3') -> 'Plane3': + """ + 工厂函数 由两直线构造平面。 + Args: + l1: 直线1 + l2: 直线2 + Returns: + 平面 + """ + v1 = l1.direction + v2 = l2.point - l1.point + if v2 == zero_vector3: + v2 = l2.get_point(1) - l1.point + return cls.from_point_and_normal(l1.point, v1.cross(v2)) +``` +
+ +### `@classmethod` +### *def* `from_point_and_line(cls, point: 'Point3', line: 'Line3') -> 'Plane3'` + + +工厂函数 由点和直线构造平面。 + +參數: + +- point: 面上一点 + +- line: 面上直线，不包含点 + +返回: + +- 平面 + + + +
+源碼 + +```python +@classmethod +def from_point_and_line(cls, point: 'Point3', line: 'Line3') -> 'Plane3': + """ + 工厂函数 由点和直线构造平面。 + Args: + point: 面上一点 + line: 面上直线，不包含点 + Returns: + 平面 + """ + return cls.from_point_and_normal(point, line.direction) +``` +
+ +### *def* `__repr__(self)` + + +
+源碼 + +```python +def __repr__(self): + return f'Plane3({self.a}, {self.b}, {self.c}, {self.d})' +``` +
+ +### *def* `__str__(self)` + + +
+源碼 + +```python +def __str__(self): + s = 'Plane3: ' + if self.a != 0: + s += f'{sign(self.a, only_neg=True)}{abs(self.a)}x' + if self.b != 0: + s += f' {sign(self.b)} {abs(self.b)}y' + if self.c != 0: + s += f' {sign(self.c)} {abs(self.c)}z' + if self.d != 0: + s += f' {sign(self.d)} {abs(self.d)}' + return s + ' = 0' +``` +
+ +### `@overload` +### *def* `__and__(self, other: 'Line3') -> 'Point3 | None'` + + +
+源碼 + +```python +@overload +def __and__(self, other: 'Line3') -> 'Point3 | None': + ... +``` +
+ +### `@overload` +### *def* `__and__(self, other: 'Plane3') -> 'Line3 | None'` + + +
+源碼 + +```python +@overload +def __and__(self, other: 'Plane3') -> 'Line3 | None': + ... +``` +
+ +### *def* `__and__(self, other)` + + +取两平面的交集（人话：交线） + +參數: + +- other: + +返回: + +- 不平行平面的交线，平面平行返回None + + + +
+源碼 + +```python +def __and__(self, other): + """ + 取两平面的交集（人话：交线） + Args: + other: + Returns: + 不平行平面的交线，平面平行返回None + """ + if isinstance(other, Plane3): + if self.normal.is_parallel(other.normal): + return None + return self.cal_intersection_line3(other) + elif isinstance(other, Line3): + if self.normal @ other.direction == 0: + return None + return self.cal_intersection_point3(other) + else: + raise TypeError(f"unsupported operand type(s) for &: 'Plane3' and '{type(other)}'") +``` +
+ +### *def* `__eq__(self, other) -> bool` + + +
+源碼 + +```python +def __eq__(self, other) -> bool: + return self.approx(other) +``` +
+ +### *def* `__rand__(self, other: 'Line3') -> 'Point3'` + + +
+源碼 + +```python +def __rand__(self, other: 'Line3') -> 'Point3': + return self.cal_intersection_point3(other) +``` +
+ +### ***var*** `k = other.a / self.a` + +### ***var*** `A = np.array([[self.b, self.c], [other.b, other.c]])` + +### ***var*** `B = np.array([-self.d, -other.d])` + +### ***var*** `v2 = l2.get_point(1) - l1.point` + +### ***var*** `k = other.b / self.b` + +### ***var*** `A = np.array([[self.a, self.c], [other.a, other.c]])` + +### ***var*** `B = np.array([-self.d, -other.d])` + +### ***var*** `k = other.c / self.c` + +### ***var*** `A = np.array([[self.a, self.b], [other.a, other.b]])` + +### ***var*** `B = np.array([-self.d, -other.d])` + diff --git a/docs/zh-Hant/api/mp_math/point.md b/docs/zh-Hant/api/mp_math/point.md new file mode 100644 index 0000000..f8b52e8 --- /dev/null +++ b/docs/zh-Hant/api/mp_math/point.md @@ -0,0 +1,199 @@ +--- +title: mbcp.mp_math.point +--- +### ***class*** `Point3` + +### *def* `__init__(self, x: float, y: float, z: float)` + + +笛卡尔坐标系中的点。 + +參數: + +- x: x 坐标 + +- y: y 坐标 + +- z: z 坐标 + + + +
+源碼 + +```python +def __init__(self, x: float, y: float, z: float): + """ + 笛卡尔坐标系中的点。 + Args: + x: x 坐标 + y: y 坐标 + z: z 坐标 + """ + self.x = x + self.y = y + self.z = z +``` +
+ +### *def* `approx(self, other: 'Point3', epsilon: float = APPROX) -> bool` + + +判断两个点是否近似相等。 + +參數: + +- other: + +- epsilon: + +返回: + +- 是否近似相等 + + + +
+源碼 + +```python +def approx(self, other: 'Point3', epsilon: float=APPROX) -> bool: + """ + 判断两个点是否近似相等。 + Args: + other: + epsilon: + + Returns: + 是否近似相等 + """ + return all([abs(self.x - other.x) < epsilon, abs(self.y - other.y) < epsilon, abs(self.z - other.z) < epsilon]) +``` +
+ +### *def* `__str__(self)` + + +
+源碼 + +```python +def __str__(self): + return f'Point3({self.x}, {self.y}, {self.z})' +``` +
+ +### `@overload` +### *def* `__add__(self, other: 'Vector3') -> 'Point3'` + + +
+源碼 + +```python +@overload +def __add__(self, other: 'Vector3') -> 'Point3': + ... +``` +
+ +### `@overload` +### *def* `__add__(self, other: 'Point3') -> 'Point3'` + + +
+源碼 + +```python +@overload +def __add__(self, other: 'Point3') -> 'Point3': + ... +``` +
+ +### *def* `__add__(self, other)` + + +P + V -> P +P + P -> P + +參數: + +- other: + + + +
+源碼 + +```python +def __add__(self, other): + """ + P + V -> P + P + P -> P + Args: + other: + Returns: + """ + return Point3(self.x + other.x, self.y + other.y, self.z + other.z) +``` +
+ +### *def* `__eq__(self, other)` + + +判断两个点是否相等。 + +參數: + +- other: + + + +
+源碼 + +```python +def __eq__(self, other): + """ + 判断两个点是否相等。 + Args: + other: + Returns: + """ + return approx(self.x, other.x) and approx(self.y, other.y) and approx(self.z, other.z) +``` +
+ +### *def* `__sub__(self, other: 'Point3') -> 'Vector3'` + + +P - P -> V + +P - V -> P 已在 :class:`Vector3` 中实现 + +參數: + +- other: + + + +
+源碼 + +```python +def __sub__(self, other: 'Point3') -> 'Vector3': + """ + P - P -> V + + P - V -> P 已在 :class:`Vector3` 中实现 + Args: + other: + Returns: + + """ + from .vector import Vector3 + return Vector3(self.x - other.x, self.y - other.y, self.z - other.z) +``` +
+ diff --git a/docs/zh-Hant/api/mp_math/segment.md b/docs/zh-Hant/api/mp_math/segment.md new file mode 100644 index 0000000..54a2eae --- /dev/null +++ b/docs/zh-Hant/api/mp_math/segment.md @@ -0,0 +1,59 @@ +--- +title: mbcp.mp_math.segment +--- +### ***class*** `Segment3` + +### *def* `__init__(self, p1: 'Point3', p2: 'Point3')` + + +三维空间中的线段。 +:param p1: +:param p2: + + + +
+源碼 + +```python +def __init__(self, p1: 'Point3', p2: 'Point3'): + """ + 三维空间中的线段。 + :param p1: + :param p2: + """ + self.p1 = p1 + self.p2 = p2 + '方向向量' + self.direction = self.p2 - self.p1 + '长度' + self.length = self.direction.length + '中心点' + 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)` + + +
+源碼 + +```python +def __repr__(self): + return f'Segment3({self.p1}, {self.p2})' +``` +
+ +### *def* `__str__(self)` + + +
+源碼 + +```python +def __str__(self): + return f'Segment3({self.p1} -> {self.p2})' +``` +
+ diff --git a/docs/zh-Hant/api/mp_math/utils.md b/docs/zh-Hant/api/mp_math/utils.md new file mode 100644 index 0000000..57bb639 --- /dev/null +++ b/docs/zh-Hant/api/mp_math/utils.md @@ -0,0 +1,220 @@ +--- +title: mbcp.mp_math.utils +--- +### *def* `clamp() -> float` + + +区间截断函数。 + +參數: + +- x: + +- min_: + +- max_: + +返回: + +- 限制后的值 + + + +
+源碼 + +```python +def clamp(x: float, min_: float, max_: float) -> float: + """ + 区间截断函数。 + Args: + x: + min_: + max_: + + Returns: + 限制后的值 + """ + return max(min(x, max_), min_) +``` +
+ +### *def* `approx(x: float = 0.0, y: float = APPROX) -> bool` + + +判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。 + +參數: + +- x: + +- y: + +- epsilon: + +返回: + +- 是否近似相等 + + + +
+源碼 + +```python +def approx(x: float, y: float=0.0, epsilon: float=APPROX) -> bool: + """ + 判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。 + Args: + x: + y: + epsilon: + + Returns: + 是否近似相等 + """ + return abs(x - y) < epsilon +``` +
+ +### *def* `sign(x: float = False) -> str` + + +获取数的符号。 + +參數: + +- x: 数 + +- only_neg: 是否只返回负数的符号 + +返回: + +- 符号 + - "" + + + +
+源碼 + +```python +def sign(x: float, only_neg: bool=False) -> str: + """获取数的符号。 + Args: + x: 数 + only_neg: 是否只返回负数的符号 + Returns: + 符号 + - "" + """ + if x > 0: + return '+' if not only_neg else '' + elif x < 0: + return '-' + else: + return '' +``` +
+ +### *def* `sign_format(x: float = False) -> str` + + +格式化符号数 +-1 -> -1 +1 -> +1 +0 -> "" + +參數: + +- x: 数 + +- only_neg: 是否只返回负数的符号 + +返回: + +- 符号 + - "" + + + +
+源碼 + +```python +def sign_format(x: float, only_neg: bool=False) -> str: + """格式化符号数 + -1 -> -1 + 1 -> +1 + 0 -> "" + Args: + x: 数 + only_neg: 是否只返回负数的符号 + Returns: + 符号 + - "" + """ + if x > 0: + return f'+{x}' if not only_neg else f'{x}' + elif x < 0: + return f'-{abs(x)}' + else: + return '' +``` +
+ +### ***class*** `Approx` + +### *def* `__init__(self, value: RealNumber)` + + +
+源碼 + +```python +def __init__(self, value: RealNumber): + self.value = value +``` +
+ +### *def* `__eq__(self, other)` + + +
+源碼 + +```python +def __eq__(self, other): + if isinstance(self.value, (float, int)): + if isinstance(other, (float, int)): + return abs(self.value - other) < APPROX + else: + self.raise_type_error(other) + elif isinstance(self.value, Vector3): + if isinstance(other, (Vector3, Point3, Plane3, Line3)): + return all([approx(self.value.x, other.x), approx(self.value.y, other.y), approx(self.value.z, other.z)]) + else: + self.raise_type_error(other) +``` +
+ +### *def* `raise_type_error(self, other)` + + +
+源碼 + +```python +def raise_type_error(self, other): + raise TypeError(f'Unsupported type: {type(self.value)} and {type(other)}') +``` +
+ +### *def* `__ne__(self, other)` + + +
+源碼 + +```python +def __ne__(self, other): + return not self.__eq__(other) +``` +
+ diff --git a/docs/zh-Hant/api/mp_math/vector.md b/docs/zh-Hant/api/mp_math/vector.md new file mode 100644 index 0000000..c496b5c --- /dev/null +++ b/docs/zh-Hant/api/mp_math/vector.md @@ -0,0 +1,699 @@ +--- +title: mbcp.mp_math.vector +--- +### ***class*** `Vector3` + +### *def* `__init__(self, x: float, y: float, z: float)` + + +3维向量 + +參數: + +- x: x轴分量 + +- y: y轴分量 + +- z: z轴分量 + + + +
+源碼 + +```python +def __init__(self, x: float, y: float, z: float): + """ + 3维向量 + Args: + x: x轴分量 + y: y轴分量 + z: z轴分量 + """ + self.x = x + self.y = y + self.z = z +``` +
+ +### *def* `approx(self, other: 'Vector3', epsilon: float = APPROX) -> bool` + + +判断两个向量是否近似相等。 + +參數: + +- other: + +- epsilon: + +返回: + +- 是否近似相等 + + + +
+源碼 + +```python +def approx(self, other: 'Vector3', epsilon: float=APPROX) -> bool: + """ + 判断两个向量是否近似相等。 + Args: + other: + epsilon: + + Returns: + 是否近似相等 + """ + return all([abs(self.x - other.x) < epsilon, abs(self.y - other.y) < epsilon, abs(self.z - other.z) < epsilon]) +``` +
+ +### *def* `cal_angle(self, other: 'Vector3') -> 'AnyAngle'` + + +计算两个向量之间的夹角。 + +參數: + +- other: 另一个向量 + +返回: + +- 夹角 + + + +
+源碼 + +```python +def cal_angle(self, other: 'Vector3') -> 'AnyAngle': + """ + 计算两个向量之间的夹角。 + Args: + other: 另一个向量 + Returns: + 夹角 + """ + return AnyAngle(math.acos(self @ other / (self.length * other.length)), is_radian=True) +``` +
+ +### *def* `cross(self, other: 'Vector3') -> 'Vector3'` + + +向量积 叉乘：v1 cross v2 -> v3 + +叉乘为0，则两向量平行。 +其余结果的模为平行四边形的面积。 + + +參數: + +- other: + +返回: + +- 行列式的结果 + + + +
+源碼 + +```python +def cross(self, other: 'Vector3') -> 'Vector3': + """ + 向量积 叉乘：v1 cross v2 -> v3 + + 叉乘为0，则两向量平行。 + 其余结果的模为平行四边形的面积。 + + 返回如下行列式的结果： + + ``i j k`` + + ``x1 y1 z1`` + + ``x2 y2 z2`` + + Args: + other: + Returns: + 行列式的结果 + """ + return Vector3(self.y * other.z - self.z * other.y, self.z * other.x - self.x * other.z, self.x * other.y - self.y * other.x) +``` +
+ +### *def* `is_approx_parallel(self, other: 'Vector3', epsilon: float = APPROX) -> bool` + + +判断两个向量是否近似平行。 + +參數: + +- other: 另一个向量 + +- epsilon: 允许的误差 + +返回: + +- 是否近似平行 + + + +
+源碼 + +```python +def is_approx_parallel(self, other: 'Vector3', epsilon: float=APPROX) -> bool: + """ + 判断两个向量是否近似平行。 + Args: + other: 另一个向量 + epsilon: 允许的误差 + Returns: + 是否近似平行 + """ + return self.cross(other).length < epsilon +``` +
+ +### *def* `is_parallel(self, other: 'Vector3') -> bool` + + +判断两个向量是否平行。 + +參數: + +- other: 另一个向量 + +返回: + +- 是否平行 + + + +
+源碼 + +```python +def is_parallel(self, other: 'Vector3') -> bool: + """ + 判断两个向量是否平行。 + Args: + other: 另一个向量 + Returns: + 是否平行 + """ + return self.cross(other).approx(zero_vector3) +``` +
+ +### *def* `normalize(self)` + + +将向量归一化。 + +自体归一化，不返回值。 + + + +
+源碼 + +```python +def normalize(self): + """ + 将向量归一化。 + + 自体归一化，不返回值。 + """ + length = self.length + self.x /= length + self.y /= length + self.z /= length +``` +
+ +### `@property` +### *def* `np_array(self) -> 'np.ndarray'` + + + + + + +
+源碼 + +```python +@property +def np_array(self) -> 'np.ndarray': + """ + 返回numpy数组 + Returns: + """ + return np.array([self.x, self.y, self.z]) +``` +
+ +### `@property` +### *def* `length(self) -> float` + + +向量的模。 + +返回: + +- 模 + + + +
+源碼 + +```python +@property +def length(self) -> float: + """ + 向量的模。 + Returns: + 模 + """ + return math.sqrt(self.x ** 2 + self.y ** 2 + self.z ** 2) +``` +
+ +### `@property` +### *def* `unit(self) -> 'Vector3'` + + +获取该向量的单位向量。 + +返回: + +- 单位向量 + + + +
+源碼 + +```python +@property +def unit(self) -> 'Vector3': + """ + 获取该向量的单位向量。 + Returns: + 单位向量 + """ + return self / self.length +``` +
+ +### *def* `__abs__(self)` + + +
+源碼 + +```python +def __abs__(self): + return self.length +``` +
+ +### `@overload` +### *def* `__add__(self, other: 'Vector3') -> 'Vector3'` + + +
+源碼 + +```python +@overload +def __add__(self, other: 'Vector3') -> 'Vector3': + ... +``` +
+ +### `@overload` +### *def* `__add__(self, other: 'Point3') -> 'Point3'` + + +
+源碼 + +```python +@overload +def __add__(self, other: 'Point3') -> 'Point3': + ... +``` +
+ +### *def* `__add__(self, other)` + + +V + P -> P + +V + V -> V + +參數: + +- other: + + + +
+源碼 + +```python +def __add__(self, other): + """ + V + P -> P + + V + V -> V + Args: + other: + Returns: + + """ + if isinstance(other, Vector3): + return Vector3(self.x + other.x, self.y + other.y, self.z + other.z) + elif isinstance(other, Point3): + return Point3(self.x + other.x, self.y + other.y, self.z + other.z) + else: + raise TypeError(f"unsupported operand type(s) for +: 'Vector3' and '{type(other)}'") +``` +
+ +### *def* `__eq__(self, other)` + + +判断两个向量是否相等。 + +參數: + +- other: + +返回: + +- 是否相等 + + + +
+源碼 + +```python +def __eq__(self, other): + """ + 判断两个向量是否相等。 + Args: + other: + Returns: + 是否相等 + """ + return approx(self.x, other.x) and approx(self.y, other.y) and approx(self.z, other.z) +``` +
+ +### *def* `__radd__(self, other: 'Point3') -> 'Point3'` + + +P + V -> P + +别去点那边实现了。 +:param other: +:return: + + + +
+源碼 + +```python +def __radd__(self, other: 'Point3') -> 'Point3': + """ + P + V -> P + + 别去点那边实现了。 + :param other: + :return: + """ + return Point3(self.x + other.x, self.y + other.y, self.z + other.z) +``` +
+ +### `@overload` +### *def* `__sub__(self, other: 'Vector3') -> 'Vector3'` + + +
+源碼 + +```python +@overload +def __sub__(self, other: 'Vector3') -> 'Vector3': + ... +``` +
+ +### `@overload` +### *def* `__sub__(self, other: 'Point3') -> 'Point3'` + + +
+源碼 + +```python +@overload +def __sub__(self, other: 'Point3') -> 'Point3': + ... +``` +
+ +### *def* `__sub__(self, other)` + + +V - P -> P + +V - V -> V + +參數: + +- other: + + + +
+源碼 + +```python +def __sub__(self, other): + """ + V - P -> P + + V - V -> V + Args: + other: + Returns: + """ + if isinstance(other, Vector3): + return Vector3(self.x - other.x, self.y - other.y, self.z - other.z) + elif isinstance(other, Point3): + return Point3(self.x - other.x, self.y - other.y, self.z - other.z) + else: + raise TypeError(f'unsupported operand type(s) for -: "Vector3" and "{type(other)}"') +``` +
+ +### *def* `__rsub__(self, other: 'Point3')` + + +P - V -> P + +參數: + +- other: + + + +
+源碼 + +```python +def __rsub__(self, other: 'Point3'): + """ + P - V -> P + Args: + other: + Returns: + + """ + if isinstance(other, Point3): + return Point3(other.x - self.x, other.y - self.y, other.z - self.z) + else: + raise TypeError(f"unsupported operand type(s) for -: '{type(other)}' and 'Vector3'") +``` +
+ +### `@overload` +### *def* `__mul__(self, other: 'Vector3') -> 'Vector3'` + + +
+源碼 + +```python +@overload +def __mul__(self, other: 'Vector3') -> 'Vector3': + ... +``` +
+ +### `@overload` +### *def* `__mul__(self, other: RealNumber) -> 'Vector3'` + + +
+源碼 + +```python +@overload +def __mul__(self, other: RealNumber) -> 'Vector3': + ... +``` +
+ +### *def* `__mul__(self, other: 'int | float | Vector3') -> 'Vector3'` + + +数组运算 非点乘。点乘使用@，叉乘使用cross。 + +參數: + +- other: + + + +
+源碼 + +```python +def __mul__(self, other: 'int | float | Vector3') -> 'Vector3': + """ + 数组运算 非点乘。点乘使用@，叉乘使用cross。 + Args: + other: + + Returns: + """ + if isinstance(other, Vector3): + return Vector3(self.x * other.x, self.y * other.y, self.z * other.z) + elif isinstance(other, (float, int)): + return Vector3(self.x * other, self.y * other, self.z * other) + else: + raise TypeError(f"unsupported operand type(s) for *: 'Vector3' and '{type(other)}'") +``` +
+ +### *def* `__rmul__(self, other: 'RealNumber') -> 'Vector3'` + + +
+源碼 + +```python +def __rmul__(self, other: 'RealNumber') -> 'Vector3': + return self.__mul__(other) +``` +
+ +### *def* `__matmul__(self, other: 'Vector3') -> 'RealNumber'` + + +点乘。 + +參數: + +- other: + + + +
+源碼 + +```python +def __matmul__(self, other: 'Vector3') -> 'RealNumber': + """ + 点乘。 + Args: + other: + Returns: + """ + return self.x * other.x + self.y * other.y + self.z * other.z +``` +
+ +### *def* `__truediv__(self, other: RealNumber) -> 'Vector3'` + + +
+源碼 + +```python +def __truediv__(self, other: RealNumber) -> 'Vector3': + return Vector3(self.x / other, self.y / other, self.z / other) +``` +
+ +### *def* `__neg__(self)` + + +
+源碼 + +```python +def __neg__(self): + return Vector3(-self.x, -self.y, -self.z) +``` +
+ +### *def* `__repr__(self)` + + +
+源碼 + +```python +def __repr__(self): + return f'Vector3({self.x}, {self.y}, {self.z})' +``` +
+ +### *def* `__str__(self)` + + +
+源碼 + +```python +def __str__(self): + return f'Vector3({self.x}, {self.y}, {self.z})' +``` +
+ +### ***var*** `zero_vector3 = Vector3(0, 0, 0)` + +### ***var*** `x_axis = Vector3(1, 0, 0)` + +### ***var*** `y_axis = Vector3(0, 1, 0)` + +### ***var*** `z_axis = Vector3(0, 0, 1)` + diff --git a/docs/zh-Hant/api/particle/index.md b/docs/zh-Hant/api/particle/index.md new file mode 100644 index 0000000..4b514d5 --- /dev/null +++ b/docs/zh-Hant/api/particle/index.md @@ -0,0 +1,3 @@ +--- +title: mbcp.particle +--- diff --git a/docs/zh-Hant/api/presets/index.md b/docs/zh-Hant/api/presets/index.md new file mode 100644 index 0000000..472366f --- /dev/null +++ b/docs/zh-Hant/api/presets/index.md @@ -0,0 +1,3 @@ +--- +title: mbcp.presets +--- diff --git a/docs/zh-Hant/api/presets/model/index.md b/docs/zh-Hant/api/presets/model/index.md new file mode 100644 index 0000000..123e021 --- /dev/null +++ b/docs/zh-Hant/api/presets/model/index.md @@ -0,0 +1,48 @@ +--- +title: mbcp.presets.model +--- +### ***class*** `GeometricModels` + +### `@staticmethod` +### *def* `sphere(radius: float, density: float)` + + +生成球体上的点集。 + +參數: + +- radius: + +- density: + +返回: + +- List[Point3]: 球体上的点集。 + + + +
+源碼 + +```python +@staticmethod +def sphere(radius: float, density: float): + """ + 生成球体上的点集。 + Args: + radius: + density: + Returns: + List[Point3]: 球体上的点集。 + """ + area = 4 * np.pi * radius ** 2 + num = int(area * density) + phi_list = np.arccos([clamp(-1 + (2.0 * _ - 1.0) / num, -1, 1) for _ in range(num)]) + theta_list = np.sqrt(num * np.pi) * phi_list + x_array = radius * np.sin(phi_list) * np.cos(theta_list) + y_array = radius * np.sin(phi_list) * np.sin(theta_list) + z_array = radius * np.cos(phi_list) + return [Point3(x_array[i], y_array[i], z_array[i]) for i in range(num)] +``` +
+