snowykami/mbcp
1
0
Fork 0
mirror of https://github.com/snowykami/mbcp.git synced 2024-11-22 06:07:37 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

📝 litedoc新增类继承显示，新增变量自动获取注释，新增类方法和函数的区分，新增魔术方法的特殊展示模式

Browse Source
This commit is contained in:
远野千束 2024-08-28 22:07:43 +08:00
parent de42d34e38
commit c6ab7f34e9
82 changed files with 9965 additions and 683 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.github/workflows/deploy-docs.yml vendored
View File

@ -42,9 +42,9 @@ jobs:
- name: Setup API markdown
run: |-
python -m pip install pydantic
python -m liteyuki_autodoc mbcp -o docs/api -l zh-Hans
python -m liteyuki_autodoc mbcp -o docs/en/api -l en
python -m liteyuki_autodoc mbcp -o docs/ja/api -l ja
python -m litedoc mbcp -o docs/api -l zh-Hans
python -m litedoc mbcp -o docs/en/api -l en
python -m litedoc mbcp -o docs/ja/api -l ja
- name: 安装 pnpm
uses: pnpm/action-setup@v2

6
docs/.vitepress/config/en.ts
View File

@ -4,7 +4,11 @@ export const en = defineConfig({
lang: "en-US",
description: "A library made for Minecraft particle generation",
themeConfig: {
nav: [
{text: 'Get Start', link: '/guide'},
{text: 'API Document', link: '/api/'},
{text: 'Demo', link: '/demo/'},
],
},
})

6
docs/.vitepress/config/index.ts
View File

@ -3,6 +3,8 @@ import {defineConfig} from "vitepress";
import {common} from './common'
import {en} from './en'
import {zh} from './zh'
import {zht} from './zht'
import {ja} from './ja'
@ -10,6 +12,8 @@ export default defineConfig({
...common,
locales:{
root: { label: "简体中文", ...zh },
en: { label: "English", ...en }
en: { label: "English", ...en },
ja: { label: "日本語", ...ja },
zht: { label: "繁體中文", ...zht },
}
})

14
docs/.vitepress/config/ja.ts Normal file
View File

@ -0,0 +1,14 @@
import {defineConfig} from 'vitepress'
export const ja = defineConfig({
lang: "ja-JP",
description: "Minecraftのパーティクル生成用のライブラリ",
themeConfig: {
nav: [
{text: 'スタート', link: '/guide'},
{text: 'APIドキュメント', link: '/api/'},
{text: 'インスタンス', link: '/demo/'},
],
},
})

11
docs/.vitepress/config/zh.ts
View File

@ -1,21 +1,14 @@
import {defineConfig} from 'vitepress'
export const zh = defineConfig({
lang: "zh-Hans",
description: "一个用于Minecraft粒子计算和生成的库",
themeConfig: {
nav: [
{text: '快速开始', link: '/guide'},
{text: '快速开始', link: '/guide/'},
{text: 'API文档', link: '/api/'},
{text: '实例', link: '/demo/'},
],
// sidebar: {
// '/api/': {
// base: '/api/',
// items: [
// ]
// }
// }
},
})

14
docs/.vitepress/config/zht.ts Normal file
View File

@ -0,0 +1,14 @@
import {defineConfig} from 'vitepress'
export const zht = defineConfig({
lang: "zh-Hant",
description: "一個用於Minecraft粒子計算和生成的軟體庫",
themeConfig: {
nav: [
{text: '指引', link: '/guide/'},
{text: 'API文檔', link: '/api/'},
{text: '示範', link: '/demo/'},
],
},
})

130
docs/api/mp_math/angle.md
View File

@ -1,16 +1,14 @@
---
title: mbcp.mp_math.angle
---
### ***class*** `Angle`
### ***class*** `AnyAngle`
### *def* `__init__(self, value: float, is_radian: bool = False)`
### **class** `Angle`
### **class** `AnyAngle(Angle)`
### *method* `__init__(self, value: float, is_radian: bool = False)`
任意角度。
参数:
**参数**:
- value: 角度或弧度值
@ -19,7 +17,7 @@ title: mbcp.mp_math.angle
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __init__(self, value: float, is_radian: bool=False):
@ -37,19 +35,19 @@ def __init__(self, value: float, is_radian: bool=False):
</details>
### `@property`
### *def* `complementary(self) -> 'AnyAngle'`
### *method* `complementary(self) -> AnyAngle`
余角：两角的和为90°。
返回:
**返回**:
- 余角
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -64,19 +62,19 @@ def complementary(self) -> 'AnyAngle':
</details>
### `@property`
### *def* `supplementary(self) -> 'AnyAngle'`
### *method* `supplementary(self) -> AnyAngle`
补角：两角的和为180°。
返回:
**返回**:
- 补角
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -91,19 +89,19 @@ def supplementary(self) -> 'AnyAngle':
</details>
### `@property`
### *def* `degree(self) -> float`
### *method* `degree(self) -> float`
角度。
返回:
**返回**:
- 弧度
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -118,19 +116,19 @@ def degree(self) -> float:
</details>
### `@property`
### *def* `minimum_positive(self) -> 'AnyAngle'`
### *method* `minimum_positive(self) -> AnyAngle`
最小正角。
返回:
**返回**:
- 最小正角度
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -145,19 +143,19 @@ def minimum_positive(self) -> 'AnyAngle':
</details>
### `@property`
### *def* `maximum_negative(self) -> 'AnyAngle'`
### *method* `maximum_negative(self) -> AnyAngle`
最大负角。
返回:
**返回**:
- 最大负角度
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -172,19 +170,19 @@ def maximum_negative(self) -> 'AnyAngle':
</details>
### `@property`
### *def* `sin(self) -> float`
### *method* `sin(self) -> float`
正弦值。
返回:
**返回**:
- 正弦值
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -199,19 +197,19 @@ def sin(self) -> float:
</details>
### `@property`
### *def* `cos(self) -> float`
### *method* `cos(self) -> float`
余弦值。
返回:
**返回**:
- 余弦值
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -226,19 +224,19 @@ def cos(self) -> float:
</details>
### `@property`
### *def* `tan(self) -> float`
### *method* `tan(self) -> float`
正切值。
返回:
**返回**:
- 正切值
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -253,19 +251,19 @@ def tan(self) -> float:
</details>
### `@property`
### *def* `cot(self) -> float`
### *method* `cot(self) -> float`
余切值。
返回:
**返回**:
- 余切值
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -280,19 +278,19 @@ def cot(self) -> float:
</details>
### `@property`
### *def* `sec(self) -> float`
### *method* `sec(self) -> float`
正割值。
返回:
**返回**:
- 正割值
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -307,19 +305,19 @@ def sec(self) -> float:
</details>
### `@property`
### *def* `csc(self) -> float`
### *method* `csc(self) -> float`
余割值。
返回:
**返回**:
- 余割值
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -333,11 +331,11 @@ def csc(self) -> float:
```
</details>
### *def* `__add__(self, other: 'AnyAngle') -> 'AnyAngle'`
### *method* `self + other: AnyAngle => AnyAngle`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __add__(self, other: 'AnyAngle') -> 'AnyAngle':
@ -345,11 +343,11 @@ def __add__(self, other: 'AnyAngle') -> 'AnyAngle':
```
</details>
### *def* `__eq__(self, other)`
### *method* `__eq__(self, other)`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __eq__(self, other):
@ -357,11 +355,11 @@ def __eq__(self, other):
```
</details>
### *def* `__sub__(self, other: 'AnyAngle') -> 'AnyAngle'`
### *method* `self - other: AnyAngle => AnyAngle`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __sub__(self, other: 'AnyAngle') -> 'AnyAngle':
@ -369,11 +367,11 @@ def __sub__(self, other: 'AnyAngle') -> 'AnyAngle':
```
</details>
### *def* `__mul__(self, other: float) -> 'AnyAngle'`
### *method* `self * other: float => AnyAngle`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __mul__(self, other: float) -> 'AnyAngle':
@ -381,36 +379,12 @@ def __mul__(self, other: float) -> 'AnyAngle':
```
</details>
### *def* `__repr__(self)`
<details>
<summary>源码</summary>
```python
def __repr__(self):
return f'AnyAngle({self.radian}, is_radian=True)'
```
</details>
### *def* `__str__(self)`
<details>
<summary>源码</summary>
```python
def __str__(self):
return f'AnyAngle({self.degree}° or {self.radian} rad)'
```
</details>
### `@overload`
### *def* `__truediv__(self, other: float) -> 'AnyAngle'`
### *method* `self / other: float => AnyAngle`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -420,11 +394,11 @@ def __truediv__(self, other: float) -> 'AnyAngle':
</details>
### `@overload`
### *def* `__truediv__(self, other: 'AnyAngle') -> float`
### *method* `self / other: AnyAngle => float`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -433,11 +407,11 @@ def __truediv__(self, other: 'AnyAngle') -> float:
```
</details>
### *def* `__truediv__(self, other)`
### *method* `self / other`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __truediv__(self, other):

12
docs/api/mp_math/const.md
View File

@ -1,15 +1,3 @@
---
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`

51
docs/api/mp_math/equation.md
View File

@ -1,12 +1,12 @@
---
title: mbcp.mp_math.equation
---
### *def* `get_partial_derivative_func(func: MultiVarsFunc = EPSILON) -> MultiVarsFunc`
### *func* `get_partial_derivative_func(func: MultiVarsFunc = EPSILON) -> MultiVarsFunc`
求N元函数一阶偏导函数。这玩意不太稳定，慎用。
参数:
**参数**:
- func: 函数
@ -14,10 +14,18 @@ title: mbcp.mp_math.equation
- epsilon: 偏移量
**返回**:
- 偏导函数
**引发**:
- ValueError 无效变量类型
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def get_partial_derivative_func(func: MultiVarsFunc, var: int | tuple[int, ...], epsilon: Number=EPSILON) -> MultiVarsFunc:
@ -54,11 +62,11 @@ def get_partial_derivative_func(func: MultiVarsFunc, var: int | tuple[int, ...],
```
</details>
### *def* `partial_derivative_func() -> Var`
### *func* `partial_derivative_func() -> Var`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def partial_derivative_func(*args: Var) -> Var:
@ -70,11 +78,11 @@ def partial_derivative_func(*args: Var) -> Var:
```
</details>
### *def* `high_order_partial_derivative_func() -> Var`
### *func* `high_order_partial_derivative_func() -> Var`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def high_order_partial_derivative_func(*args: Var) -> Var:
@ -85,14 +93,13 @@ def high_order_partial_derivative_func(*args: Var) -> Var:
```
</details>
### ***class*** `CurveEquation`
### *def* `__init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc)`
### **class** `CurveEquation`
### *method* `__init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc)`
曲线方程。
参数:
**参数**:
- x_func: x函数
@ -103,7 +110,7 @@ def high_order_partial_derivative_func(*args: Var) -> Var:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc):
@ -120,12 +127,12 @@ def __init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc):
```
</details>
### *def* `__call__(self) -> Point3 | tuple[Point3, ...]`
### *method* `__call__(self) -> Point3 | tuple[Point3, ...]`
计算曲线上的点。
参数:
**参数**:
- *t:
@ -134,7 +141,7 @@ def __init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc):
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __call__(self, *t: Var) -> Point3 | tuple[Point3, ...]:
@ -153,17 +160,3 @@ def __call__(self, *t: Var) -> Point3 | tuple[Point3, ...]:
```
</details>
### *def* `__str__(self)`
<details>
<summary>源码</summary>
```python
def __str__(self):
return 'CurveEquation()'
```
</details>
### ***var*** `result_func = get_partial_derivative_func(result_func, v, epsilon)`

209
docs/api/mp_math/line.md
View File

@ -1,14 +1,13 @@
---
title: mbcp.mp_math.line
---
### ***class*** `Line3`
### *def* `__init__(self, point: 'Point3', direction: 'Vector3')`
### **class** `Line3`
### *method* `__init__(self, point: Point3, direction: Vector3)`
三维空间中的直线。由一个点和一个方向向量确定。
参数:
**参数**:
- point: 直线上的一点
@ -17,7 +16,7 @@ title: mbcp.mp_math.line
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __init__(self, point: 'Point3', direction: 'Vector3'):
@ -32,21 +31,25 @@ def __init__(self, point: 'Point3', direction: 'Vector3'):
```
</details>
### *def* `approx(self, other: 'Line3', epsilon: float = APPROX) -> bool`
### *method* `approx(self, other: Line3, epsilon: float = APPROX) -> bool`
判断两条直线是否近似相等。
参数:
**参数**:
- other: 另一条直线
- epsilon: 误差
**返回**:
- 是否近似相等
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def approx(self, other: 'Line3', epsilon: float=APPROX) -> bool:
@ -62,19 +65,27 @@ def approx(self, other: 'Line3', epsilon: float=APPROX) -> bool:
```
</details>
### *def* `cal_angle(self, other: 'Line3') -> 'AnyAngle'`
### *method* `cal_angle(self, other: Line3) -> AnyAngle`
计算直线和直线之间的夹角。
参数:
**参数**:
- other: 另一条直线
**返回**:
- 夹角弧度
**引发**:
- TypeError 不支持的类型
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_angle(self, other: 'Line3') -> 'AnyAngle':
@ -91,19 +102,27 @@ def cal_angle(self, other: 'Line3') -> 'AnyAngle':
```
</details>
### *def* `cal_distance(self, other: 'Line3 | Point3') -> float`
### *method* `cal_distance(self, other: Line3 | Point3) -> float`
计算直线和直线或点之间的距离。
参数:
**参数**:
- other: 平行直线或点
**返回**:
- 距离
**引发**:
- TypeError 不支持的类型
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_distance(self, other: 'Line3 | Point3') -> float:
@ -133,19 +152,29 @@ def cal_distance(self, other: 'Line3 | Point3') -> float:
```
</details>
### *def* `cal_intersection(self, other: 'Line3') -> 'Point3'`
### *method* `cal_intersection(self, other: Line3) -> Point3`
计算两条直线的交点。
参数:
**参数**:
- other: 另一条直线
**返回**:
- 交点
**引发**:
- ValueError 直线平行
- ValueError 直线不共面
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_intersection(self, other: 'Line3') -> 'Point3':
@ -167,19 +196,23 @@ def cal_intersection(self, other: 'Line3') -> 'Point3':
```
</details>
### *def* `cal_perpendicular(self, point: 'Point3') -> 'Line3'`
### *method* `cal_perpendicular(self, point: Point3) -> Line3`
计算直线经过指定点p的垂线。
参数:
**参数**:
- point: 指定点
**返回**:
- 垂线
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_perpendicular(self, point: 'Point3') -> 'Line3':
@ -194,19 +227,23 @@ def cal_perpendicular(self, point: 'Point3') -> 'Line3':
```
</details>
### *def* `get_point(self, t: RealNumber) -> 'Point3'`
### *method* `get_point(self, t: RealNumber) -> Point3`
获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
参数:
**参数**:
- t: 参数t
**返回**:
- 点
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def get_point(self, t: RealNumber) -> 'Point3':
@ -221,19 +258,19 @@ def get_point(self, t: RealNumber) -> 'Point3':
```
</details>
### *def* `get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc, OneSingleVarFunc]`
### *method* `get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc, OneSingleVarFunc]`
获取直线的参数方程。
返回:
**返回**:
- x(t), y(t), z(t)
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc, OneSingleVarFunc]:
@ -246,21 +283,25 @@ def get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc,
```
</details>
### *def* `is_approx_parallel(self, other: 'Line3', epsilon: float = 1e-06) -> bool`
### *method* `is_approx_parallel(self, other: Line3, epsilon: float = 1e-06) -> bool`
判断两条直线是否近似平行。
参数:
**参数**:
- other: 另一条直线
- epsilon: 误差
**返回**:
- 是否近似平行
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def is_approx_parallel(self, other: 'Line3', epsilon: float=1e-06) -> bool:
@ -276,19 +317,23 @@ def is_approx_parallel(self, other: 'Line3', epsilon: float=1e-06) -> bool:
```
</details>
### *def* `is_parallel(self, other: 'Line3') -> bool`
### *method* `is_parallel(self, other: Line3) -> bool`
判断两条直线是否平行。
参数:
**参数**:
- other: 另一条直线
**返回**:
- 是否平行
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def is_parallel(self, other: 'Line3') -> bool:
@ -303,19 +348,23 @@ def is_parallel(self, other: 'Line3') -> bool:
```
</details>
### *def* `is_collinear(self, other: 'Line3') -> bool`
### *method* `is_collinear(self, other: Line3) -> bool`
判断两条直线是否共线。
参数:
**参数**:
- other: 另一条直线
**返回**:
- 是否共线
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def is_collinear(self, other: 'Line3') -> bool:
@ -330,19 +379,23 @@ def is_collinear(self, other: 'Line3') -> bool:
```
</details>
### *def* `is_point_on(self, point: 'Point3') -> bool`
### *method* `is_point_on(self, point: Point3) -> bool`
判断点是否在直线上。
参数:
**参数**:
- point: 点
**返回**:
- 是否在直线上
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def is_point_on(self, point: 'Point3') -> bool:
@ -357,20 +410,24 @@ def is_point_on(self, point: 'Point3') -> bool:
```
</details>
### *def* `is_coplanar(self, other: 'Line3') -> bool`
### *method* `is_coplanar(self, other: Line3) -> bool`
判断两条直线是否共面。
充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
参数:
**参数**:
- other: 另一条直线
**返回**:
- 是否共面
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def is_coplanar(self, other: 'Line3') -> bool:
@ -386,7 +443,7 @@ def is_coplanar(self, other: 'Line3') -> bool:
```
</details>
### *def* `simplify(self)`
### *method* `simplify(self)`
简化直线方程，等价相等。
@ -397,7 +454,7 @@ def is_coplanar(self, other: 'Line3') -> bool:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def simplify(self):
@ -418,21 +475,25 @@ def simplify(self):
</details>
### `@classmethod`
### *def* `from_two_points(cls, p1: 'Point3', p2: 'Point3') -> 'Line3'`
### *method* `from_two_points(cls, p1: Point3, p2: Point3) -> Line3`
工厂函数 由两点构造直线。
参数:
**参数**:
- p1: 点1
- p2: 点2
**返回**:
- 直线
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@classmethod
@ -450,19 +511,23 @@ def from_two_points(cls, p1: 'Point3', p2: 'Point3') -> 'Line3':
```
</details>
### *def* `__and__(self, other: 'Line3') -> 'Line3 | Point3 | None'`
### *method* `__and__(self, other: Line3) -> Line3 | Point3 | None`
计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。
参数:
**参数**:
- other: 另一条直线
**返回**:
- 交点
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __and__(self, other: 'Line3') -> 'Line3 | Point3 | None':
@ -482,21 +547,21 @@ def __and__(self, other: 'Line3') -> 'Line3 | Point3 | None':
```
</details>
### *def* `__eq__(self, other) -> bool`
### *method* `__eq__(self, other) -> bool`
判断两条直线是否等价。
v1 // v2 ∧ (p1 - p2) // v1
参数:
**参数**:
- other:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __eq__(self, other) -> bool:
@ -514,43 +579,3 @@ def __eq__(self, other) -> bool:
```
</details>
### *def* `__str__(self)`
<details>
<summary>源码</summary>
```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
```
</details>
### *def* `__repr__(self)`
<details>
<summary>源码</summary>
```python
def __repr__(self):
return f'Line3({self.point}, {self.direction})'
```
</details>

60
docs/api/mp_math/mp_math_typing.md
View File

@ -1,37 +1,63 @@
---
title: mbcp.mp_math.mp_math_typing
---
### ***var*** `RealNumber: TypeAlias = int | float`
### ***var*** `RealNumber = int | float`
### ***var*** `Number: TypeAlias = RealNumber | complex`
- **类型**: `TypeAlias`
### ***var*** `SingleVar = TypeVar('SingleVar', bound=Number)`
### ***var*** `Number = RealNumber | complex`
### ***var*** `ArrayVar = TypeVar('ArrayVar', bound=Iterable[Number])`
- **类型**: `TypeAlias`
### ***var*** `Var: TypeAlias = SingleVar | ArrayVar`
### ***var*** `Var = SingleVar | ArrayVar`
### ***var*** `OneSingleVarFunc: TypeAlias = Callable[[SingleVar], SingleVar]`
- **类型**: `TypeAlias`
### ***var*** `OneArrayFunc: TypeAlias = Callable[[ArrayVar], ArrayVar]`
### ***var*** `OneSingleVarFunc = Callable[[SingleVar], SingleVar]`
### ***var*** `OneVarFunc: TypeAlias = OneSingleVarFunc | OneArrayFunc`
- **类型**: `TypeAlias`
### ***var*** `TwoSingleVarsFunc: TypeAlias = Callable[[SingleVar, SingleVar], SingleVar]`
### ***var*** `OneArrayFunc = Callable[[ArrayVar], ArrayVar]`
### ***var*** `TwoArraysFunc: TypeAlias = Callable[[ArrayVar, ArrayVar], ArrayVar]`
- **类型**: `TypeAlias`
### ***var*** `TwoVarsFunc: TypeAlias = TwoSingleVarsFunc | TwoArraysFunc`
### ***var*** `OneVarFunc = OneSingleVarFunc | OneArrayFunc`
### ***var*** `ThreeSingleVarsFunc: TypeAlias = Callable[[SingleVar, SingleVar, SingleVar], SingleVar]`
- **类型**: `TypeAlias`
### ***var*** `ThreeArraysFunc: TypeAlias = Callable[[ArrayVar, ArrayVar, ArrayVar], ArrayVar]`
### ***var*** `TwoSingleVarsFunc = Callable[[SingleVar, SingleVar], SingleVar]`
### ***var*** `ThreeVarsFunc: TypeAlias = ThreeSingleVarsFunc | ThreeArraysFunc`
- **类型**: `TypeAlias`
### ***var*** `MultiSingleVarsFunc: TypeAlias = Callable[..., SingleVar]`
### ***var*** `TwoArraysFunc = Callable[[ArrayVar, ArrayVar], ArrayVar]`
### ***var*** `MultiArraysFunc: TypeAlias = Callable[..., ArrayVar]`
- **类型**: `TypeAlias`
### ***var*** `MultiVarsFunc: TypeAlias = MultiSingleVarsFunc | MultiArraysFunc`
### ***var*** `TwoVarsFunc = TwoSingleVarsFunc | TwoArraysFunc`
- **类型**: `TypeAlias`
### ***var*** `ThreeSingleVarsFunc = Callable[[SingleVar, SingleVar, SingleVar], SingleVar]`
- **类型**: `TypeAlias`
### ***var*** `ThreeArraysFunc = Callable[[ArrayVar, ArrayVar, ArrayVar], ArrayVar]`
- **类型**: `TypeAlias`
### ***var*** `ThreeVarsFunc = ThreeSingleVarsFunc | ThreeArraysFunc`
- **类型**: `TypeAlias`
### ***var*** `MultiSingleVarsFunc = Callable[..., SingleVar]`
- **类型**: `TypeAlias`
### ***var*** `MultiArraysFunc = Callable[..., ArrayVar]`
- **类型**: `TypeAlias`
### ***var*** `MultiVarsFunc = MultiSingleVarsFunc | MultiArraysFunc`
- **类型**: `TypeAlias`

246
docs/api/mp_math/plane.md
View File

@ -1,37 +1,36 @@
---
title: mbcp.mp_math.plane
---
### ***class*** `Plane3`
### *def* `__init__(self, a: float, b: float, c: float, d: float)`
### **class** `Plane3`
### *method* `__init__(self, a: float, b: float, c: float, d: float)`
平面方程：ax + by + cz + d = 0
参数:
**参数**:
- a:
- a: x系数
- b:
- b: y系数
- c:
- c: z系数
- d:
- d: 常数项
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __init__(self, a: float, b: float, c: float, d: float):
"""
平面方程：ax + by + cz + d = 0
Args:
a:
b:
c:
d:
a: x系数
b: y系数
c: z系数
d: 常数项
"""
self.a = a
self.b = b
@ -40,31 +39,33 @@ def __init__(self, a: float, b: float, c: float, d: float):
```
</details>
### *def* `approx(self, other: 'Plane3') -> bool`
### *method* `approx(self, other: Plane3) -> bool`
判断两个平面是否近似相等。
参数:
**参数**:
- other:
- other: 另一个平面
**返回**:
- 是否近似相等
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def approx(self, other: 'Plane3') -> bool:
"""
判断两个平面是否近似相等。
Args:
other:
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)
@ -79,19 +80,27 @@ def approx(self, other: 'Plane3') -> bool:
```
</details>
### *def* `cal_angle(self, other: 'Line3 | Plane3') -> 'AnyAngle'`
### *method* `cal_angle(self, other: Line3 | Plane3) -> AnyAngle`
计算平面与平面之间的夹角。
参数:
**参数**:
- other: 另一个平面
**返回**:
- 夹角弧度
**引发**:
- TypeError 不支持的类型
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_angle(self, other: 'Line3 | Plane3') -> 'AnyAngle':
@ -113,19 +122,27 @@ def cal_angle(self, other: 'Line3 | Plane3') -> 'AnyAngle':
```
</details>
### *def* `cal_distance(self, other: 'Plane3 | Point3') -> float`
### *method* `cal_distance(self, other: Plane3 | Point3) -> float`
计算平面与平面或点之间的距离。
参数:
**参数**:
- other: 另一个平面或点
**返回**:
- 距离
**引发**:
- TypeError 不支持的类型
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_distance(self, other: 'Plane3 | Point3') -> float:
@ -147,28 +164,32 @@ def cal_distance(self, other: 'Plane3 | Point3') -> float:
```
</details>
### *def* `cal_intersection_line3(self, other: 'Plane3') -> 'Line3'`
### *method* `cal_intersection_line3(self, other: Plane3) -> Line3`
计算两平面的交线。该方法有问题，待修复。
计算两平面的交线。
参数:
**参数**:
- other: 另一个平面
**返回**:
- 两平面的交线
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_intersection_line3(self, other: 'Plane3') -> 'Line3':
"""
计算两平面的交线。该方法有问题，待修复。
计算两平面的交线。
Args:
other: 另一个平面
Returns:
交线
两平面的交线
Raises:
"""
if self.normal.is_parallel(other.normal):
@ -191,19 +212,27 @@ def cal_intersection_line3(self, other: 'Plane3') -> 'Line3':
```
</details>
### *def* `cal_intersection_point3(self, other: 'Line3') -> 'Point3'`
### *method* `cal_intersection_point3(self, other: Line3) -> Point3`
计算平面与直线的交点。
参数:
**参数**:
- other: 不与平面平行或在平面上的直线
**返回**:
- 交点
**引发**:
- ValueError 平面与直线平行或重合
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_intersection_point3(self, other: 'Line3') -> 'Point3':
@ -224,19 +253,23 @@ def cal_intersection_point3(self, other: 'Line3') -> 'Point3':
```
</details>
### *def* `cal_parallel_plane3(self, point: 'Point3') -> 'Plane3'`
### *method* `cal_parallel_plane3(self, point: Point3) -> Plane3`
计算平行于该平面且过指定点的平面。
参数:
**参数**:
- point: 指定点
**返回**:
- 所求平面
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_parallel_plane3(self, point: 'Point3') -> 'Plane3':
@ -245,25 +278,29 @@ def cal_parallel_plane3(self, point: 'Point3') -> 'Plane3':
Args:
point: 指定点
Returns:
平面
所求平面
"""
return Plane3.from_point_and_normal(point, self.normal)
```
</details>
### *def* `is_parallel(self, other: 'Plane3') -> bool`
### *method* `is_parallel(self, other: Plane3) -> bool`
判断两个平面是否平行。
参数:
**参数**:
- other: 另一个平面
**返回**:
- 是否平行
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def is_parallel(self, other: 'Plane3') -> bool:
@ -279,19 +316,19 @@ def is_parallel(self, other: 'Plane3') -> bool:
</details>
### `@property`
### *def* `normal(self) -> 'Vector3'`
### *method* `normal(self) -> Vector3`
平面的法向量。
返回:
**返回**:
- 法向量
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -306,21 +343,25 @@ def normal(self) -> 'Vector3':
</details>
### `@classmethod`
### *def* `from_point_and_normal(cls, point: 'Point3', normal: 'Vector3') -> 'Plane3'`
### *method* `from_point_and_normal(cls, point: Point3, normal: Vector3) -> Plane3`
工厂函数 由点和法向量构造平面(点法式构造)。
参数:
**参数**:
- point: 平面上的一点
- normal: 法向量
**返回**:
- 平面
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@classmethod
@ -340,12 +381,12 @@ def from_point_and_normal(cls, point: 'Point3', normal: 'Vector3') -> 'Plane3':
</details>
### `@classmethod`
### *def* `from_three_points(cls, p1: 'Point3', p2: 'Point3', p3: 'Point3') -> 'Plane3'`
### *method* `from_three_points(cls, p1: Point3, p2: Point3, p3: Point3) -> Plane3`
工厂函数 由三点构造平面。
参数:
**参数**:
- p1: 点1
@ -353,10 +394,14 @@ def from_point_and_normal(cls, point: 'Point3', normal: 'Vector3') -> 'Plane3':
- p3: 点3
**返回**:
- 平面
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@classmethod
@ -378,21 +423,25 @@ def from_three_points(cls, p1: 'Point3', p2: 'Point3', p3: 'Point3') -> 'Plane3'
</details>
### `@classmethod`
### *def* `from_two_lines(cls, l1: 'Line3', l2: 'Line3') -> 'Plane3'`
### *method* `from_two_lines(cls, l1: Line3, l2: Line3) -> Plane3`
工厂函数 由两直线构造平面。
参数:
**参数**:
- l1: 直线1
- l2: 直线2
**返回**:
- 平面
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@classmethod
@ -414,21 +463,25 @@ def from_two_lines(cls, l1: 'Line3', l2: 'Line3') -> 'Plane3':
</details>
### `@classmethod`
### *def* `from_point_and_line(cls, point: 'Point3', line: 'Line3') -> 'Plane3'`
### *method* `from_point_and_line(cls, point: Point3, line: Line3) -> Plane3`
工厂函数 由点和直线构造平面。
参数:
**参数**:
- point: 面上一点
- line: 面上直线，不包含点
**返回**:
- 平面
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@classmethod
@ -445,45 +498,12 @@ def from_point_and_line(cls, point: 'Point3', line: 'Line3') -> 'Plane3':
```
</details>
### *def* `__repr__(self)`
<details>
<summary>源码</summary>
```python
def __repr__(self):
return f'Plane3({self.a}, {self.b}, {self.c}, {self.d})'
```
</details>
### *def* `__str__(self)`
<details>
<summary>源码</summary>
```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'
```
</details>
### `@overload`
### *def* `__and__(self, other: 'Line3') -> 'Point3 | None'`
### *method* `__and__(self, other: Line3) -> Point3 | None`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -493,11 +513,11 @@ def __and__(self, other: 'Line3') -> 'Point3 | None':
</details>
### `@overload`
### *def* `__and__(self, other: 'Plane3') -> 'Line3 | None'`
### *method* `__and__(self, other: Plane3) -> Line3 | None`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -506,19 +526,23 @@ def __and__(self, other: 'Plane3') -> 'Line3 | None':
```
</details>
### *def* `__and__(self, other)`
### *method* `__and__(self, other)`
取两平面的交集（人话：交线）
参数:
**参数**:
- other:
**返回**:
- 不平行平面的交线，平面平行返回None
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __and__(self, other):
@ -542,11 +566,11 @@ def __and__(self, other):
```
</details>
### *def* `__eq__(self, other) -> bool`
### *method* `__eq__(self, other) -> bool`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __eq__(self, other) -> bool:
@ -554,11 +578,11 @@ def __eq__(self, other) -> bool:
```
</details>
### *def* `__rand__(self, other: 'Line3') -> 'Point3'`
### *method* `__rand__(self, other: Line3) -> Point3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __rand__(self, other: 'Line3') -> 'Point3':
@ -566,23 +590,3 @@ def __rand__(self, other: 'Line3') -> 'Point3':
```
</details>
### ***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])`

57
docs/api/mp_math/point.md
View File

@ -1,14 +1,13 @@
---
title: mbcp.mp_math.point
---
### ***class*** `Point3`
### *def* `__init__(self, x: float, y: float, z: float)`
### **class** `Point3`
### *method* `__init__(self, x: float, y: float, z: float)`
笛卡尔坐标系中的点。
参数:
**参数**:
- x: x 坐标
@ -19,7 +18,7 @@ title: mbcp.mp_math.point
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __init__(self, x: float, y: float, z: float):
@ -36,21 +35,25 @@ def __init__(self, x: float, y: float, z: float):
```
</details>
### *def* `approx(self, other: 'Point3', epsilon: float = APPROX) -> bool`
### *method* `approx(self, other: Point3, epsilon: float = APPROX) -> bool`
判断两个点是否近似相等。
参数:
**参数**:
- other:
- epsilon:
**返回**:
- 是否近似相等
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def approx(self, other: 'Point3', epsilon: float=APPROX) -> bool:
@ -67,24 +70,12 @@ def approx(self, other: 'Point3', epsilon: float=APPROX) -> bool:
```
</details>
### *def* `__str__(self)`
<details>
<summary>源码</summary>
```python
def __str__(self):
return f'Point3({self.x}, {self.y}, {self.z})'
```
</details>
### `@overload`
### *def* `__add__(self, other: 'Vector3') -> 'Point3'`
### *method* `self + other: Vector3 => Point3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -94,11 +85,11 @@ def __add__(self, other: 'Vector3') -> 'Point3':
</details>
### `@overload`
### *def* `__add__(self, other: 'Point3') -> 'Point3'`
### *method* `self + other: Point3 => Point3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -107,20 +98,20 @@ def __add__(self, other: 'Point3') -> 'Point3':
```
</details>
### *def* `__add__(self, other)`
### *method* `self + other`
P + V -> P
P + P -> P
参数:
**参数**:
- other:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __add__(self, other):
@ -135,19 +126,19 @@ def __add__(self, other):
```
</details>
### *def* `__eq__(self, other)`
### *method* `__eq__(self, other)`
判断两个点是否相等。
参数:
**参数**:
- other:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __eq__(self, other):
@ -161,21 +152,21 @@ def __eq__(self, other):
```
</details>
### *def* `__sub__(self, other: 'Point3') -> 'Vector3'`
### *method* `self - other: Point3 => Vector3`
P - P -> V
P - V -> P 已在 :class:`Vector3` 中实现
参数:
**参数**:
- other:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __sub__(self, other: 'Point3') -> 'Vector3':

31
docs/api/mp_math/segment.md
View File

@ -1,9 +1,8 @@
---
title: mbcp.mp_math.segment
---
### ***class*** `Segment3`
### *def* `__init__(self, p1: 'Point3', p2: 'Point3')`
### **class** `Segment3`
### *method* `__init__(self, p1: Point3, p2: Point3)`
三维空间中的线段。
@ -13,7 +12,7 @@ title: mbcp.mp_math.segment
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __init__(self, p1: 'Point3', p2: 'Point3'):
@ -33,27 +32,3 @@ def __init__(self, p1: 'Point3', p2: 'Point3'):
```
</details>
### *def* `__repr__(self)`
<details>
<summary>源码</summary>
```python
def __repr__(self):
return f'Segment3({self.p1}, {self.p2})'
```
</details>
### *def* `__str__(self)`
<details>
<summary>源码</summary>
```python
def __str__(self):
return f'Segment3({self.p1} -> {self.p2})'
```
</details>

88
docs/api/mp_math/utils.md
View File

@ -1,32 +1,36 @@
---
title: mbcp.mp_math.utils
---
### *def* `clamp() -> float`
### *func* `clamp() -> float`
区间截断函数。
区间限定函数
参数:
**参数**:
- x:
- x: 待限定的值
- min_:
- min_: 最小值
- max_:
- max_: 最大值
**返回**:
- 限制后的值
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def clamp(x: float, min_: float, max_: float) -> float:
"""
区间截断函数。
区间限定函数
Args:
x:
min_:
max_:
x: 待限定的值
min_: 最小值
max_: 最大值
Returns:
限制后的值
@ -35,33 +39,36 @@ def clamp(x: float, min_: float, max_: float) -> float:
```
</details>
### *def* `approx(x: float = 0.0, y: float = APPROX) -> bool`
### *func* `approx(x: float = 0.0, y: float = APPROX) -> bool`
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
参数:
**参数**:
- x:
- x: 数1
- y:
- y: 数2
- epsilon:
- epsilon: 误差
**返回**:
- 是否近似相等
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def approx(x: float, y: float=0.0, epsilon: float=APPROX) -> bool:
"""
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
Args:
x:
y:
epsilon:
x: 数1
y: 数2
epsilon: 误差
Returns:
是否近似相等
"""
@ -69,21 +76,25 @@ def approx(x: float, y: float=0.0, epsilon: float=APPROX) -> bool:
```
</details>
### *def* `sign(x: float = False) -> str`
### *func* `sign(x: float = False) -> str`
获取数的符号。
参数:
**参数**:
- x: 数
- only_neg: 是否只返回负数的符号
**返回**:
- 符号 + - ""
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def sign(x: float, only_neg: bool=False) -> str:
@ -103,7 +114,7 @@ def sign(x: float, only_neg: bool=False) -> str:
```
</details>
### *def* `sign_format(x: float = False) -> str`
### *func* `sign_format(x: float = False) -> str`
格式化符号数
@ -111,16 +122,20 @@ def sign(x: float, only_neg: bool=False) -> str:
1 -> +1
0 -> ""
参数:
**参数**:
- x: 数
- only_neg: 是否只返回负数的符号
**返回**:
- 符号 + - ""
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def sign_format(x: float, only_neg: bool=False) -> str:
@ -143,13 +158,12 @@ def sign_format(x: float, only_neg: bool=False) -> str:
```
</details>
### ***class*** `Approx`
### *def* `__init__(self, value: RealNumber)`
### **class** `Approx`
### *method* `__init__(self, value: RealNumber)`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __init__(self, value: RealNumber):
@ -157,11 +171,11 @@ def __init__(self, value: RealNumber):
```
</details>
### *def* `__eq__(self, other)`
### *method* `__eq__(self, other)`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __eq__(self, other):
@ -178,11 +192,11 @@ def __eq__(self, other):
```
</details>
### *def* `raise_type_error(self, other)`
### *method* `raise_type_error(self, other)`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def raise_type_error(self, other):
@ -190,11 +204,11 @@ def raise_type_error(self, other):
```
</details>
### *def* `__ne__(self, other)`
### *method* `__ne__(self, other)`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __ne__(self, other):

205
docs/api/mp_math/vector.md
View File

@ -1,14 +1,13 @@
---
title: mbcp.mp_math.vector
---
### ***class*** `Vector3`
### *def* `__init__(self, x: float, y: float, z: float)`
### **class** `Vector3`
### *method* `__init__(self, x: float, y: float, z: float)`
3维向量
参数:
**参数**:
- x: x轴分量
@ -19,7 +18,7 @@ title: mbcp.mp_math.vector
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __init__(self, x: float, y: float, z: float):
@ -36,21 +35,25 @@ def __init__(self, x: float, y: float, z: float):
```
</details>
### *def* `approx(self, other: 'Vector3', epsilon: float = APPROX) -> bool`
### *method* `approx(self, other: Vector3, epsilon: float = APPROX) -> bool`
判断两个向量是否近似相等。
参数:
**参数**:
- other:
- epsilon:
**返回**:
- 是否近似相等
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def approx(self, other: 'Vector3', epsilon: float=APPROX) -> bool:
@ -67,19 +70,23 @@ def approx(self, other: 'Vector3', epsilon: float=APPROX) -> bool:
```
</details>
### *def* `cal_angle(self, other: 'Vector3') -> 'AnyAngle'`
### *method* `cal_angle(self, other: Vector3) -> AnyAngle`
计算两个向量之间的夹角。
参数:
**参数**:
- other: 另一个向量
**返回**:
- 夹角
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cal_angle(self, other: 'Vector3') -> 'AnyAngle':
@ -94,7 +101,7 @@ def cal_angle(self, other: 'Vector3') -> 'AnyAngle':
```
</details>
### *def* `cross(self, other: 'Vector3') -> 'Vector3'`
### *method* `cross(self, other: Vector3) -> Vector3`
向量积 叉乘：v1 cross v2 -> v3
@ -103,10 +110,18 @@ def cal_angle(self, other: 'Vector3') -> 'AnyAngle':
其余结果的模为平行四边形的面积。
**参数**:
- other:
**返回**:
- 行列式的结果
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def cross(self, other: 'Vector3') -> 'Vector3':
@ -133,21 +148,25 @@ def cross(self, other: 'Vector3') -> 'Vector3':
```
</details>
### *def* `is_approx_parallel(self, other: 'Vector3', epsilon: float = APPROX) -> bool`
### *method* `is_approx_parallel(self, other: Vector3, epsilon: float = APPROX) -> bool`
判断两个向量是否近似平行。
参数:
**参数**:
- other: 另一个向量
- epsilon: 允许的误差
**返回**:
- 是否近似平行
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def is_approx_parallel(self, other: 'Vector3', epsilon: float=APPROX) -> bool:
@ -163,19 +182,23 @@ def is_approx_parallel(self, other: 'Vector3', epsilon: float=APPROX) -> bool:
```
</details>
### *def* `is_parallel(self, other: 'Vector3') -> bool`
### *method* `is_parallel(self, other: Vector3) -> bool`
判断两个向量是否平行。
参数:
**参数**:
- other: 另一个向量
**返回**:
- 是否平行
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def is_parallel(self, other: 'Vector3') -> bool:
@ -190,7 +213,7 @@ def is_parallel(self, other: 'Vector3') -> bool:
```
</details>
### *def* `normalize(self)`
### *method* `normalize(self)`
将向量归一化。
@ -200,7 +223,7 @@ def is_parallel(self, other: 'Vector3') -> bool:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def normalize(self):
@ -217,7 +240,7 @@ def normalize(self):
</details>
### `@property`
### *def* `np_array(self) -> 'np.ndarray'`
### *method* `np_array(self) -> np.ndarray`
@ -225,7 +248,7 @@ def normalize(self):
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -239,19 +262,19 @@ def np_array(self) -> 'np.ndarray':
</details>
### `@property`
### *def* `length(self) -> float`
### *method* `length(self) -> float`
向量的模。
返回:
**返回**:
- 模
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -266,19 +289,19 @@ def length(self) -> float:
</details>
### `@property`
### *def* `unit(self) -> 'Vector3'`
### *method* `unit(self) -> Vector3`
获取该向量的单位向量。
返回:
**返回**:
- 单位向量
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@property
@ -292,11 +315,11 @@ def unit(self) -> 'Vector3':
```
</details>
### *def* `__abs__(self)`
### *method* `__abs__(self)`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __abs__(self):
@ -305,11 +328,11 @@ def __abs__(self):
</details>
### `@overload`
### *def* `__add__(self, other: 'Vector3') -> 'Vector3'`
### *method* `self + other: Vector3 => Vector3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -319,11 +342,11 @@ def __add__(self, other: 'Vector3') -> 'Vector3':
</details>
### `@overload`
### *def* `__add__(self, other: 'Point3') -> 'Point3'`
### *method* `self + other: Point3 => Point3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -332,21 +355,21 @@ def __add__(self, other: 'Point3') -> 'Point3':
```
</details>
### *def* `__add__(self, other)`
### *method* `self + other`
V + P -> P
V + V -> V
参数:
**参数**:
- other:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __add__(self, other):
@ -368,19 +391,23 @@ def __add__(self, other):
```
</details>
### *def* `__eq__(self, other)`
### *method* `__eq__(self, other)`
判断两个向量是否相等。
参数:
**参数**:
- other:
**返回**:
- 是否相等
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __eq__(self, other):
@ -395,7 +422,7 @@ def __eq__(self, other):
```
</details>
### *def* `__radd__(self, other: 'Point3') -> 'Point3'`
### *method* `self + other: Point3 => Point3`
P + V -> P
@ -407,7 +434,7 @@ P + V -> P
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __radd__(self, other: 'Point3') -> 'Point3':
@ -423,11 +450,11 @@ def __radd__(self, other: 'Point3') -> 'Point3':
</details>
### `@overload`
### *def* `__sub__(self, other: 'Vector3') -> 'Vector3'`
### *method* `self - other: Vector3 => Vector3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -437,11 +464,11 @@ def __sub__(self, other: 'Vector3') -> 'Vector3':
</details>
### `@overload`
### *def* `__sub__(self, other: 'Point3') -> 'Point3'`
### *method* `self - other: Point3 => Point3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -450,21 +477,21 @@ def __sub__(self, other: 'Point3') -> 'Point3':
```
</details>
### *def* `__sub__(self, other)`
### *method* `self - other`
V - P -> P
V - V -> V
参数:
**参数**:
- other:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __sub__(self, other):
@ -485,19 +512,19 @@ def __sub__(self, other):
```
</details>
### *def* `__rsub__(self, other: 'Point3')`
### *method* `self - other: Point3`
P - V -> P
参数:
**参数**:
- other:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __rsub__(self, other: 'Point3'):
@ -516,11 +543,11 @@ def __rsub__(self, other: 'Point3'):
</details>
### `@overload`
### *def* `__mul__(self, other: 'Vector3') -> 'Vector3'`
### *method* `self * other: Vector3 => Vector3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -530,11 +557,11 @@ def __mul__(self, other: 'Vector3') -> 'Vector3':
</details>
### `@overload`
### *def* `__mul__(self, other: RealNumber) -> 'Vector3'`
### *method* `self * other: RealNumber => Vector3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@overload
@ -543,19 +570,19 @@ def __mul__(self, other: RealNumber) -> 'Vector3':
```
</details>
### *def* `__mul__(self, other: 'int | float | Vector3') -> 'Vector3'`
### *method* `self * other: int | float | Vector3 => Vector3`
数组运算 非点乘。点乘使用@，叉乘使用cross。
参数:
**参数**:
- other:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __mul__(self, other: 'int | float | Vector3') -> 'Vector3':
@ -575,11 +602,11 @@ def __mul__(self, other: 'int | float | Vector3') -> 'Vector3':
```
</details>
### *def* `__rmul__(self, other: 'RealNumber') -> 'Vector3'`
### *method* `self * other: RealNumber => Vector3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __rmul__(self, other: 'RealNumber') -> 'Vector3':
@ -587,19 +614,19 @@ def __rmul__(self, other: 'RealNumber') -> 'Vector3':
```
</details>
### *def* `__matmul__(self, other: 'Vector3') -> 'RealNumber'`
### *method* `self @ other: Vector3 => RealNumber`
点乘。
参数:
**参数**:
- other:
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __matmul__(self, other: 'Vector3') -> 'RealNumber':
@ -613,11 +640,11 @@ def __matmul__(self, other: 'Vector3') -> 'RealNumber':
```
</details>
### *def* `__truediv__(self, other: RealNumber) -> 'Vector3'`
### *method* `self / other: RealNumber => Vector3`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __truediv__(self, other: RealNumber) -> 'Vector3':
@ -625,11 +652,11 @@ def __truediv__(self, other: RealNumber) -> 'Vector3':
```
</details>
### *def* `__neg__(self)`
### *method* `- self`
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
def __neg__(self):
@ -637,35 +664,27 @@ def __neg__(self):
```
</details>
### *def* `__repr__(self)`
<details>
<summary>源码</summary>
```python
def __repr__(self):
return f'Vector3({self.x}, {self.y}, {self.z})'
```
</details>
### *def* `__str__(self)`
<details>
<summary>源码</summary>
```python
def __str__(self):
return f'Vector3({self.x}, {self.y}, {self.z})'
```
</details>
### ***var*** `zero_vector3 = Vector3(0, 0, 0)`
- **类型**: `Vector3`
- **说明**: 零向量
### ***var*** `x_axis = Vector3(1, 0, 0)`
- **类型**: `Vector3`
- **说明**: x轴单位向量
### ***var*** `y_axis = Vector3(0, 1, 0)`
- **类型**: `Vector3`
- **说明**: y轴单位向量
### ***var*** `z_axis = Vector3(0, 0, 1)`
- **类型**: `Vector3`
- **说明**: z轴单位向量

13
docs/api/presets/model/index.md
View File

@ -1,24 +1,27 @@
---
title: mbcp.presets.model
---
### ***class*** `GeometricModels`
### **class** `GeometricModels`
### `@staticmethod`
### *def* `sphere(radius: float, density: float)`
### *method* `sphere(radius: float, density: float)`
生成球体上的点集。
参数:
**参数**:
- radius:
- density:
**返回**:
- List[Point3]: 球体上的点集。
<details>
<summary>源码</summary>
<summary> <i>源代码</i> </summary>
```python
@staticmethod

3
docs/en/api/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp
---

423
docs/en/api/mp_math/angle.md Normal file
View File

@ -0,0 +1,423 @@
---
title: mbcp.mp_math.angle
---
### **class** `Angle`
### **class** `AnyAngle(Angle)`
### *method* `__init__(self, value: float, is_radian: bool = False)`
任意角度。
**Arguments**:
- value: 角度或弧度值
- is_radian: 是否为弧度，默认为否
<details>
<summary> <i>Source code</i> </summary>
```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
```
</details>
### `@property`
### *method* `complementary(self) -> AnyAngle`
余角：两角的和为90°。
**Return**:
- 余角
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def complementary(self) -> 'AnyAngle':
"""
余角：两角的和为90°。
Returns:
余角
"""
return AnyAngle(PI / 2 - self.minimum_positive.radian, is_radian=True)
```
</details>
### `@property`
### *method* `supplementary(self) -> AnyAngle`
补角：两角的和为180°。
**Return**:
- 补角
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def supplementary(self) -> 'AnyAngle':
"""
补角：两角的和为180°。
Returns:
补角
"""
return AnyAngle(PI - self.minimum_positive.radian, is_radian=True)
```
</details>
### `@property`
### *method* `degree(self) -> float`
角度。
**Return**:
- 弧度
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def degree(self) -> float:
"""
角度。
Returns:
弧度
"""
return self.radian * 180 / PI
```
</details>
### `@property`
### *method* `minimum_positive(self) -> AnyAngle`
最小正角。
**Return**:
- 最小正角度
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def minimum_positive(self) -> 'AnyAngle':
"""
最小正角。
Returns:
最小正角度
"""
return AnyAngle(self.radian % (2 * PI))
```
</details>
### `@property`
### *method* `maximum_negative(self) -> AnyAngle`
最大负角。
**Return**:
- 最大负角度
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def maximum_negative(self) -> 'AnyAngle':
"""
最大负角。
Returns:
最大负角度
"""
return AnyAngle(-self.radian % (2 * PI), is_radian=True)
```
</details>
### `@property`
### *method* `sin(self) -> float`
正弦值。
**Return**:
- 正弦值
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def sin(self) -> float:
"""
正弦值。
Returns:
正弦值
"""
return math.sin(self.radian)
```
</details>
### `@property`
### *method* `cos(self) -> float`
余弦值。
**Return**:
- 余弦值
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def cos(self) -> float:
"""
余弦值。
Returns:
余弦值
"""
return math.cos(self.radian)
```
</details>
### `@property`
### *method* `tan(self) -> float`
正切值。
**Return**:
- 正切值
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def tan(self) -> float:
"""
正切值。
Returns:
正切值
"""
return math.tan(self.radian)
```
</details>
### `@property`
### *method* `cot(self) -> float`
余切值。
**Return**:
- 余切值
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def cot(self) -> float:
"""
余切值。
Returns:
余切值
"""
return 1 / math.tan(self.radian)
```
</details>
### `@property`
### *method* `sec(self) -> float`
正割值。
**Return**:
- 正割值
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def sec(self) -> float:
"""
正割值。
Returns:
正割值
"""
return 1 / math.cos(self.radian)
```
</details>
### `@property`
### *method* `csc(self) -> float`
余割值。
**Return**:
- 余割值
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def csc(self) -> float:
"""
余割值。
Returns:
余割值
"""
return 1 / math.sin(self.radian)
```
</details>
### *method* `self + other: AnyAngle => AnyAngle`
<details>
<summary> <i>Source code</i> </summary>
```python
def __add__(self, other: 'AnyAngle') -> 'AnyAngle':
return AnyAngle(self.radian + other.radian, is_radian=True)
```
</details>
### *method* `__eq__(self, other)`
<details>
<summary> <i>Source code</i> </summary>
```python
def __eq__(self, other):
return approx(self.radian, other.radian)
```
</details>
### *method* `self - other: AnyAngle => AnyAngle`
<details>
<summary> <i>Source code</i> </summary>
```python
def __sub__(self, other: 'AnyAngle') -> 'AnyAngle':
return AnyAngle(self.radian - other.radian, is_radian=True)
```
</details>
### *method* `self * other: float => AnyAngle`
<details>
<summary> <i>Source code</i> </summary>
```python
def __mul__(self, other: float) -> 'AnyAngle':
return AnyAngle(self.radian * other, is_radian=True)
```
</details>
### `@overload`
### *method* `self / other: float => AnyAngle`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __truediv__(self, other: float) -> 'AnyAngle':
...
```
</details>
### `@overload`
### *method* `self / other: AnyAngle => float`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __truediv__(self, other: 'AnyAngle') -> float:
...
```
</details>
### *method* `self / other`
<details>
<summary> <i>Source code</i> </summary>
```python
def __truediv__(self, other):
if isinstance(other, AnyAngle):
return self.radian / other.radian
return AnyAngle(self.radian / other, is_radian=True)
```
</details>

3
docs/en/api/mp_math/const.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.mp_math.const
---

162
docs/en/api/mp_math/equation.md Normal file
View File

@ -0,0 +1,162 @@
---
title: mbcp.mp_math.equation
---
### *func* `get_partial_derivative_func(func: MultiVarsFunc = EPSILON) -> MultiVarsFunc`
求N元函数一阶偏导函数。这玩意不太稳定，慎用。
**Arguments**:
- func: 函数
- var: 变量位置，可为整数(一阶偏导)或整数元组(高阶偏导)
- epsilon: 偏移量
**Return**:
- 偏导函数
**Raises**:
- ValueError 无效变量类型
<details>
<summary> <i>Source code</i> </summary>
```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')
```
</details>
### *func* `partial_derivative_func() -> Var`
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *func* `high_order_partial_derivative_func() -> Var`
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### **class** `CurveEquation`
### *method* `__init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc)`
曲线方程。
**Arguments**:
- x_func: x函数
- y_func: y函数
- z_func: z函数
<details>
<summary> <i>Source code</i> </summary>
```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
```
</details>
### *method* `__call__(self) -> Point3 | tuple[Point3, ...]`
计算曲线上的点。
**Arguments**:
- *t:
- 参数:
<details>
<summary> <i>Source code</i> </summary>
```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))])
```
</details>

3
docs/en/api/mp_math/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.mp_math
---

581
docs/en/api/mp_math/line.md Normal file
View File

@ -0,0 +1,581 @@
---
title: mbcp.mp_math.line
---
### **class** `Line3`
### *method* `__init__(self, point: Point3, direction: Vector3)`
三维空间中的直线。由一个点和一个方向向量确定。
**Arguments**:
- point: 直线上的一点
- direction: 直线的方向向量
<details>
<summary> <i>Source code</i> </summary>
```python
def __init__(self, point: 'Point3', direction: 'Vector3'):
"""
三维空间中的直线。由一个点和一个方向向量确定。
Args:
point: 直线上的一点
direction: 直线的方向向量
"""
self.point = point
self.direction = direction
```
</details>
### *method* `approx(self, other: Line3, epsilon: float = APPROX) -> bool`
判断两条直线是否近似相等。
**Arguments**:
- other: 另一条直线
- epsilon: 误差
**Return**:
- 是否近似相等
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `cal_angle(self, other: Line3) -> AnyAngle`
计算直线和直线之间的夹角。
**Arguments**:
- other: 另一条直线
**Return**:
- 夹角弧度
**Raises**:
- TypeError 不支持的类型
<details>
<summary> <i>Source code</i> </summary>
```python
def cal_angle(self, other: 'Line3') -> 'AnyAngle':
"""
计算直线和直线之间的夹角。
Args:
other: 另一条直线
Returns:
夹角弧度
Raises:
TypeError: 不支持的类型
"""
return self.direction.cal_angle(other.direction)
```
</details>
### *method* `cal_distance(self, other: Line3 | Point3) -> float`
计算直线和直线或点之间的距离。
**Arguments**:
- other: 平行直线或点
**Return**:
- 距离
**Raises**:
- TypeError 不支持的类型
<details>
<summary> <i>Source code</i> </summary>
```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.')
```
</details>
### *method* `cal_intersection(self, other: Line3) -> Point3`
计算两条直线的交点。
**Arguments**:
- other: 另一条直线
**Return**:
- 交点
**Raises**:
- ValueError 直线平行
- ValueError 直线不共面
<details>
<summary> <i>Source code</i> </summary>
```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
```
</details>
### *method* `cal_perpendicular(self, point: Point3) -> Line3`
计算直线经过指定点p的垂线。
**Arguments**:
- point: 指定点
**Return**:
- 垂线
<details>
<summary> <i>Source code</i> </summary>
```python
def cal_perpendicular(self, point: 'Point3') -> 'Line3':
"""
计算直线经过指定点p的垂线。
Args:
point: 指定点
Returns:
垂线
"""
return Line3(point, self.direction.cross(point - self.point))
```
</details>
### *method* `get_point(self, t: RealNumber) -> Point3`
获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
**Arguments**:
- t: 参数t
**Return**:
- 点
<details>
<summary> <i>Source code</i> </summary>
```python
def get_point(self, t: RealNumber) -> 'Point3':
"""
获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
Args:
t: 参数t
Returns:
点
"""
return self.point + t * self.direction
```
</details>
### *method* `get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc, OneSingleVarFunc]`
获取直线的参数方程。
**Return**:
- x(t), y(t), z(t)
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `is_approx_parallel(self, other: Line3, epsilon: float = 1e-06) -> bool`
判断两条直线是否近似平行。
**Arguments**:
- other: 另一条直线
- epsilon: 误差
**Return**:
- 是否近似平行
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `is_parallel(self, other: Line3) -> bool`
判断两条直线是否平行。
**Arguments**:
- other: 另一条直线
**Return**:
- 是否平行
<details>
<summary> <i>Source code</i> </summary>
```python
def is_parallel(self, other: 'Line3') -> bool:
"""
判断两条直线是否平行。
Args:
other: 另一条直线
Returns:
是否平行
"""
return self.direction.is_parallel(other.direction)
```
</details>
### *method* `is_collinear(self, other: Line3) -> bool`
判断两条直线是否共线。
**Arguments**:
- other: 另一条直线
**Return**:
- 是否共线
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `is_point_on(self, point: Point3) -> bool`
判断点是否在直线上。
**Arguments**:
- point: 点
**Return**:
- 是否在直线上
<details>
<summary> <i>Source code</i> </summary>
```python
def is_point_on(self, point: 'Point3') -> bool:
"""
判断点是否在直线上。
Args:
point: 点
Returns:
是否在直线上
"""
return (point - self.point).is_parallel(self.direction)
```
</details>
### *method* `is_coplanar(self, other: Line3) -> bool`
判断两条直线是否共面。
充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
**Arguments**:
- other: 另一条直线
**Return**:
- 是否共面
<details>
<summary> <i>Source code</i> </summary>
```python
def is_coplanar(self, other: 'Line3') -> bool:
"""
判断两条直线是否共面。
充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
Args:
other: 另一条直线
Returns:
是否共面
"""
return self.direction.cross(other.direction) @ (self.point - other.point) == 0
```
</details>
### *method* `simplify(self)`
简化直线方程，等价相等。
自体简化，不返回值。
按照可行性一次对x y z 化 0 处理，并对向量单位化
<details>
<summary> <i>Source code</i> </summary>
```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
```
</details>
### `@classmethod`
### *method* `from_two_points(cls, p1: Point3, p2: Point3) -> Line3`
工厂函数 由两点构造直线。
**Arguments**:
- p1: 点1
- p2: 点2
**Return**:
- 直线
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `__and__(self, other: Line3) -> Line3 | Point3 | None`
计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。
**Arguments**:
- other: 另一条直线
**Return**:
- 交点
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `__eq__(self, other) -> bool`
判断两条直线是否等价。
v1 // v2 ∧ (p1 - p2) // v1
**Arguments**:
- other:
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>

63
docs/en/api/mp_math/mp_math_typing.md Normal file
View File

@ -0,0 +1,63 @@
---
title: mbcp.mp_math.mp_math_typing
---
### ***var*** `RealNumber = int | float`
- **Type**: `TypeAlias`
### ***var*** `Number = RealNumber | complex`
- **Type**: `TypeAlias`
### ***var*** `Var = SingleVar | ArrayVar`
- **Type**: `TypeAlias`
### ***var*** `OneSingleVarFunc = Callable[[SingleVar], SingleVar]`
- **Type**: `TypeAlias`
### ***var*** `OneArrayFunc = Callable[[ArrayVar], ArrayVar]`
- **Type**: `TypeAlias`
### ***var*** `OneVarFunc = OneSingleVarFunc | OneArrayFunc`
- **Type**: `TypeAlias`
### ***var*** `TwoSingleVarsFunc = Callable[[SingleVar, SingleVar], SingleVar]`
- **Type**: `TypeAlias`
### ***var*** `TwoArraysFunc = Callable[[ArrayVar, ArrayVar], ArrayVar]`
- **Type**: `TypeAlias`
### ***var*** `TwoVarsFunc = TwoSingleVarsFunc | TwoArraysFunc`
- **Type**: `TypeAlias`
### ***var*** `ThreeSingleVarsFunc = Callable[[SingleVar, SingleVar, SingleVar], SingleVar]`
- **Type**: `TypeAlias`
### ***var*** `ThreeArraysFunc = Callable[[ArrayVar, ArrayVar, ArrayVar], ArrayVar]`
- **Type**: `TypeAlias`
### ***var*** `ThreeVarsFunc = ThreeSingleVarsFunc | ThreeArraysFunc`
- **Type**: `TypeAlias`
### ***var*** `MultiSingleVarsFunc = Callable[..., SingleVar]`
- **Type**: `TypeAlias`
### ***var*** `MultiArraysFunc = Callable[..., ArrayVar]`
- **Type**: `TypeAlias`
### ***var*** `MultiVarsFunc = MultiSingleVarsFunc | MultiArraysFunc`
- **Type**: `TypeAlias`

592
docs/en/api/mp_math/plane.md Normal file
View File

@ -0,0 +1,592 @@
---
title: mbcp.mp_math.plane
---
### **class** `Plane3`
### *method* `__init__(self, a: float, b: float, c: float, d: float)`
平面方程：ax + by + cz + d = 0
**Arguments**:
- a: x系数
- b: y系数
- c: z系数
- d: 常数项
<details>
<summary> <i>Source code</i> </summary>
```python
def __init__(self, a: float, b: float, c: float, d: float):
"""
平面方程：ax + by + cz + d = 0
Args:
a: x系数
b: y系数
c: z系数
d: 常数项
"""
self.a = a
self.b = b
self.c = c
self.d = d
```
</details>
### *method* `approx(self, other: Plane3) -> bool`
判断两个平面是否近似相等。
**Arguments**:
- other: 另一个平面
**Return**:
- 是否近似相等
<details>
<summary> <i>Source code</i> </summary>
```python
def approx(self, other: 'Plane3') -> bool:
"""
判断两个平面是否近似相等。
Args:
other: 另一个平面
Returns:
是否近似相等
"""
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
```
</details>
### *method* `cal_angle(self, other: Line3 | Plane3) -> AnyAngle`
计算平面与平面之间的夹角。
**Arguments**:
- other: 另一个平面
**Return**:
- 夹角弧度
**Raises**:
- TypeError 不支持的类型
<details>
<summary> <i>Source code</i> </summary>
```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)}')
```
</details>
### *method* `cal_distance(self, other: Plane3 | Point3) -> float`
计算平面与平面或点之间的距离。
**Arguments**:
- other: 另一个平面或点
**Return**:
- 距离
**Raises**:
- TypeError 不支持的类型
<details>
<summary> <i>Source code</i> </summary>
```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)}')
```
</details>
### *method* `cal_intersection_line3(self, other: Plane3) -> Line3`
计算两平面的交线。
**Arguments**:
- other: 另一个平面
**Return**:
- 两平面的交线
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `cal_intersection_point3(self, other: Line3) -> Point3`
计算平面与直线的交点。
**Arguments**:
- other: 不与平面平行或在平面上的直线
**Return**:
- 交点
**Raises**:
- ValueError 平面与直线平行或重合
<details>
<summary> <i>Source code</i> </summary>
```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))
```
</details>
### *method* `cal_parallel_plane3(self, point: Point3) -> Plane3`
计算平行于该平面且过指定点的平面。
**Arguments**:
- point: 指定点
**Return**:
- 所求平面
<details>
<summary> <i>Source code</i> </summary>
```python
def cal_parallel_plane3(self, point: 'Point3') -> 'Plane3':
"""
计算平行于该平面且过指定点的平面。
Args:
point: 指定点
Returns:
所求平面
"""
return Plane3.from_point_and_normal(point, self.normal)
```
</details>
### *method* `is_parallel(self, other: Plane3) -> bool`
判断两个平面是否平行。
**Arguments**:
- other: 另一个平面
**Return**:
- 是否平行
<details>
<summary> <i>Source code</i> </summary>
```python
def is_parallel(self, other: 'Plane3') -> bool:
"""
判断两个平面是否平行。
Args:
other: 另一个平面
Returns:
是否平行
"""
return self.normal.is_parallel(other.normal)
```
</details>
### `@property`
### *method* `normal(self) -> Vector3`
平面的法向量。
**Return**:
- 法向量
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def normal(self) -> 'Vector3':
"""
平面的法向量。
Returns:
法向量
"""
return Vector3(self.a, self.b, self.c)
```
</details>
### `@classmethod`
### *method* `from_point_and_normal(cls, point: Point3, normal: Vector3) -> Plane3`
工厂函数 由点和法向量构造平面(点法式构造)。
**Arguments**:
- point: 平面上的一点
- normal: 法向量
**Return**:
- 平面
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### `@classmethod`
### *method* `from_three_points(cls, p1: Point3, p2: Point3, p3: Point3) -> Plane3`
工厂函数 由三点构造平面。
**Arguments**:
- p1: 点1
- p2: 点2
- p3: 点3
**Return**:
- 平面
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### `@classmethod`
### *method* `from_two_lines(cls, l1: Line3, l2: Line3) -> Plane3`
工厂函数 由两直线构造平面。
**Arguments**:
- l1: 直线1
- l2: 直线2
**Return**:
- 平面
<details>
<summary> <i>Source code</i> </summary>
```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))
```
</details>
### `@classmethod`
### *method* `from_point_and_line(cls, point: Point3, line: Line3) -> Plane3`
工厂函数 由点和直线构造平面。
**Arguments**:
- point: 面上一点
- line: 面上直线，不包含点
**Return**:
- 平面
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### `@overload`
### *method* `__and__(self, other: Line3) -> Point3 | None`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __and__(self, other: 'Line3') -> 'Point3 | None':
...
```
</details>
### `@overload`
### *method* `__and__(self, other: Plane3) -> Line3 | None`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __and__(self, other: 'Plane3') -> 'Line3 | None':
...
```
</details>
### *method* `__and__(self, other)`
取两平面的交集（人话：交线）
**Arguments**:
- other:
**Return**:
- 不平行平面的交线，平面平行返回None
<details>
<summary> <i>Source code</i> </summary>
```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)}'")
```
</details>
### *method* `__eq__(self, other) -> bool`
<details>
<summary> <i>Source code</i> </summary>
```python
def __eq__(self, other) -> bool:
return self.approx(other)
```
</details>
### *method* `__rand__(self, other: Line3) -> Point3`
<details>
<summary> <i>Source code</i> </summary>
```python
def __rand__(self, other: 'Line3') -> 'Point3':
return self.cal_intersection_point3(other)
```
</details>

186
docs/en/api/mp_math/point.md Normal file
View File

@ -0,0 +1,186 @@
---
title: mbcp.mp_math.point
---
### **class** `Point3`
### *method* `__init__(self, x: float, y: float, z: float)`
笛卡尔坐标系中的点。
**Arguments**:
- x: x 坐标
- y: y 坐标
- z: z 坐标
<details>
<summary> <i>Source code</i> </summary>
```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
```
</details>
### *method* `approx(self, other: Point3, epsilon: float = APPROX) -> bool`
判断两个点是否近似相等。
**Arguments**:
- other:
- epsilon:
**Return**:
- 是否近似相等
<details>
<summary> <i>Source code</i> </summary>
```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])
```
</details>
### `@overload`
### *method* `self + other: Vector3 => Point3`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __add__(self, other: 'Vector3') -> 'Point3':
...
```
</details>
### `@overload`
### *method* `self + other: Point3 => Point3`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __add__(self, other: 'Point3') -> 'Point3':
...
```
</details>
### *method* `self + other`
P + V -> P
P + P -> P
**Arguments**:
- other:
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `__eq__(self, other)`
判断两个点是否相等。
**Arguments**:
- other:
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `self - other: Point3 => Vector3`
P - P -> V
P - V -> P 已在 :class:`Vector3` 中实现
**Arguments**:
- other:
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>

34
docs/en/api/mp_math/segment.md Normal file
View File

@ -0,0 +1,34 @@
---
title: mbcp.mp_math.segment
---
### **class** `Segment3`
### *method* `__init__(self, p1: Point3, p2: Point3)`
三维空间中的线段。
:param p1:
:param p2:
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>

218
docs/en/api/mp_math/utils.md Normal file
View File

@ -0,0 +1,218 @@
---
title: mbcp.mp_math.utils
---
### *func* `clamp() -> float`
区间限定函数
**Arguments**:
- x: 待限定的值
- min_: 最小值
- max_: 最大值
**Return**:
- 限制后的值
<details>
<summary> <i>Source code</i> </summary>
```python
def clamp(x: float, min_: float, max_: float) -> float:
"""
区间限定函数
Args:
x: 待限定的值
min_: 最小值
max_: 最大值
Returns:
限制后的值
"""
return max(min(x, max_), min_)
```
</details>
### *func* `approx(x: float = 0.0, y: float = APPROX) -> bool`
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
**Arguments**:
- x: 数1
- y: 数2
- epsilon: 误差
**Return**:
- 是否近似相等
<details>
<summary> <i>Source code</i> </summary>
```python
def approx(x: float, y: float=0.0, epsilon: float=APPROX) -> bool:
"""
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
Args:
x: 数1
y: 数2
epsilon: 误差
Returns:
是否近似相等
"""
return abs(x - y) < epsilon
```
</details>
### *func* `sign(x: float = False) -> str`
获取数的符号。
**Arguments**:
- x: 数
- only_neg: 是否只返回负数的符号
**Return**:
- 符号 + - ""
<details>
<summary> <i>Source code</i> </summary>
```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 ''
```
</details>
### *func* `sign_format(x: float = False) -> str`
格式化符号数
-1 -> -1
1 -> +1
0 -> ""
**Arguments**:
- x: 数
- only_neg: 是否只返回负数的符号
**Return**:
- 符号 + - ""
<details>
<summary> <i>Source code</i> </summary>
```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 ''
```
</details>
### **class** `Approx`
### *method* `__init__(self, value: RealNumber)`
<details>
<summary> <i>Source code</i> </summary>
```python
def __init__(self, value: RealNumber):
self.value = value
```
</details>
### *method* `__eq__(self, other)`
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `raise_type_error(self, other)`
<details>
<summary> <i>Source code</i> </summary>
```python
def raise_type_error(self, other):
raise TypeError(f'Unsupported type: {type(self.value)} and {type(other)}')
```
</details>
### *method* `__ne__(self, other)`
<details>
<summary> <i>Source code</i> </summary>
```python
def __ne__(self, other):
return not self.__eq__(other)
```
</details>

690
docs/en/api/mp_math/vector.md Normal file
View File

@ -0,0 +1,690 @@
---
title: mbcp.mp_math.vector
---
### **class** `Vector3`
### *method* `__init__(self, x: float, y: float, z: float)`
3维向量
**Arguments**:
- x: x轴分量
- y: y轴分量
- z: z轴分量
<details>
<summary> <i>Source code</i> </summary>
```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
```
</details>
### *method* `approx(self, other: Vector3, epsilon: float = APPROX) -> bool`
判断两个向量是否近似相等。
**Arguments**:
- other:
- epsilon:
**Return**:
- 是否近似相等
<details>
<summary> <i>Source code</i> </summary>
```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])
```
</details>
### *method* `cal_angle(self, other: Vector3) -> AnyAngle`
计算两个向量之间的夹角。
**Arguments**:
- other: 另一个向量
**Return**:
- 夹角
<details>
<summary> <i>Source code</i> </summary>
```python
def cal_angle(self, other: 'Vector3') -> 'AnyAngle':
"""
计算两个向量之间的夹角。
Args:
other: 另一个向量
Returns:
夹角
"""
return AnyAngle(math.acos(self @ other / (self.length * other.length)), is_radian=True)
```
</details>
### *method* `cross(self, other: Vector3) -> Vector3`
向量积 叉乘：v1 cross v2 -> v3
叉乘为0，则两向量平行。
其余结果的模为平行四边形的面积。
**Arguments**:
- other:
**Return**:
- 行列式的结果
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `is_approx_parallel(self, other: Vector3, epsilon: float = APPROX) -> bool`
判断两个向量是否近似平行。
**Arguments**:
- other: 另一个向量
- epsilon: 允许的误差
**Return**:
- 是否近似平行
<details>
<summary> <i>Source code</i> </summary>
```python
def is_approx_parallel(self, other: 'Vector3', epsilon: float=APPROX) -> bool:
"""
判断两个向量是否近似平行。
Args:
other: 另一个向量
epsilon: 允许的误差
Returns:
是否近似平行
"""
return self.cross(other).length < epsilon
```
</details>
### *method* `is_parallel(self, other: Vector3) -> bool`
判断两个向量是否平行。
**Arguments**:
- other: 另一个向量
**Return**:
- 是否平行
<details>
<summary> <i>Source code</i> </summary>
```python
def is_parallel(self, other: 'Vector3') -> bool:
"""
判断两个向量是否平行。
Args:
other: 另一个向量
Returns:
是否平行
"""
return self.cross(other).approx(zero_vector3)
```
</details>
### *method* `normalize(self)`
将向量归一化。
自体归一化，不返回值。
<details>
<summary> <i>Source code</i> </summary>
```python
def normalize(self):
"""
将向量归一化。
自体归一化，不返回值。
"""
length = self.length
self.x /= length
self.y /= length
self.z /= length
```
</details>
### `@property`
### *method* `np_array(self) -> np.ndarray`
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def np_array(self) -> 'np.ndarray':
"""
返回numpy数组
Returns:
"""
return np.array([self.x, self.y, self.z])
```
</details>
### `@property`
### *method* `length(self) -> float`
向量的模。
**Return**:
- 模
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def length(self) -> float:
"""
向量的模。
Returns:
模
"""
return math.sqrt(self.x ** 2 + self.y ** 2 + self.z ** 2)
```
</details>
### `@property`
### *method* `unit(self) -> Vector3`
获取该向量的单位向量。
**Return**:
- 单位向量
<details>
<summary> <i>Source code</i> </summary>
```python
@property
def unit(self) -> 'Vector3':
"""
获取该向量的单位向量。
Returns:
单位向量
"""
return self / self.length
```
</details>
### *method* `__abs__(self)`
<details>
<summary> <i>Source code</i> </summary>
```python
def __abs__(self):
return self.length
```
</details>
### `@overload`
### *method* `self + other: Vector3 => Vector3`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __add__(self, other: 'Vector3') -> 'Vector3':
...
```
</details>
### `@overload`
### *method* `self + other: Point3 => Point3`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __add__(self, other: 'Point3') -> 'Point3':
...
```
</details>
### *method* `self + other`
V + P -> P
V + V -> V
**Arguments**:
- other:
<details>
<summary> <i>Source code</i> </summary>
```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)}'")
```
</details>
### *method* `__eq__(self, other)`
判断两个向量是否相等。
**Arguments**:
- other:
**Return**:
- 是否相等
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### *method* `self + other: Point3 => Point3`
P + V -> P
别去点那边实现了。
:param other:
:return:
<details>
<summary> <i>Source code</i> </summary>
```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)
```
</details>
### `@overload`
### *method* `self - other: Vector3 => Vector3`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __sub__(self, other: 'Vector3') -> 'Vector3':
...
```
</details>
### `@overload`
### *method* `self - other: Point3 => Point3`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __sub__(self, other: 'Point3') -> 'Point3':
...
```
</details>
### *method* `self - other`
V - P -> P
V - V -> V
**Arguments**:
- other:
<details>
<summary> <i>Source code</i> </summary>
```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)}"')
```
</details>
### *method* `self - other: Point3`
P - V -> P
**Arguments**:
- other:
<details>
<summary> <i>Source code</i> </summary>
```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'")
```
</details>
### `@overload`
### *method* `self * other: Vector3 => Vector3`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __mul__(self, other: 'Vector3') -> 'Vector3':
...
```
</details>
### `@overload`
### *method* `self * other: RealNumber => Vector3`
<details>
<summary> <i>Source code</i> </summary>
```python
@overload
def __mul__(self, other: RealNumber) -> 'Vector3':
...
```
</details>
### *method* `self * other: int | float | Vector3 => Vector3`
数组运算 非点乘。点乘使用@，叉乘使用cross。
**Arguments**:
- other:
<details>
<summary> <i>Source code</i> </summary>
```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)}'")
```
</details>
### *method* `self * other: RealNumber => Vector3`
<details>
<summary> <i>Source code</i> </summary>
```python
def __rmul__(self, other: 'RealNumber') -> 'Vector3':
return self.__mul__(other)
```
</details>
### *method* `self @ other: Vector3 => RealNumber`
点乘。
**Arguments**:
- other:
<details>
<summary> <i>Source code</i> </summary>
```python
def __matmul__(self, other: 'Vector3') -> 'RealNumber':
"""
点乘。
Args:
other:
Returns:
"""
return self.x * other.x + self.y * other.y + self.z * other.z
```
</details>
### *method* `self / other: RealNumber => Vector3`
<details>
<summary> <i>Source code</i> </summary>
```python
def __truediv__(self, other: RealNumber) -> 'Vector3':
return Vector3(self.x / other, self.y / other, self.z / other)
```
</details>
### *method* `- self`
<details>
<summary> <i>Source code</i> </summary>
```python
def __neg__(self):
return Vector3(-self.x, -self.y, -self.z)
```
</details>
### ***var*** `zero_vector3 = Vector3(0, 0, 0)`
- **Type**: `Vector3`
- **Description**: 零向量
### ***var*** `x_axis = Vector3(1, 0, 0)`
- **Type**: `Vector3`
- **Description**: x轴单位向量
### ***var*** `y_axis = Vector3(0, 1, 0)`
- **Type**: `Vector3`
- **Description**: y轴单位向量
### ***var*** `z_axis = Vector3(0, 0, 1)`
- **Type**: `Vector3`
- **Description**: z轴单位向量

3
docs/en/api/particle/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.particle
---

3
docs/en/api/presets/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.presets
---

47
docs/en/api/presets/model/index.md Normal file
View File

@ -0,0 +1,47 @@
---
title: mbcp.presets.model
---
### **class** `GeometricModels`
### `@staticmethod`
### *method* `sphere(radius: float, density: float)`
生成球体上的点集。
**Arguments**:
- radius:
- density:
**Return**:
- List[Point3]: 球体上的点集。
<details>
<summary> <i>Source code</i> </summary>
```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)]
```
</details>

1
docs/guide/index.md Normal file
View File

@ -0,0 +1 @@
# 开始不了一点

2
docs/index.md
View File

@ -9,7 +9,7 @@ hero:
actions:
- theme: brand
text: 快速开始
link: md-ex
link: guide/
- theme: alt
text: API文档
link: api/

3
docs/ja/api/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp
---

423
docs/ja/api/mp_math/angle.md Normal file
View File

@ -0,0 +1,423 @@
---
title: mbcp.mp_math.angle
---
### **class** `Angle`
### **class** `AnyAngle(Angle)`
### *method* `__init__(self, value: float, is_radian: bool = False)`
任意角度。
**引数**:
- value: 角度或弧度值
- is_radian: 是否为弧度，默认为否
<details>
<summary> <i>ソースコード</i> </summary>
```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
```
</details>
### `@property`
### *method* `complementary(self) -> AnyAngle`
余角：两角的和为90°。
**戻り値**:
- 余角
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def complementary(self) -> 'AnyAngle':
"""
余角：两角的和为90°。
Returns:
余角
"""
return AnyAngle(PI / 2 - self.minimum_positive.radian, is_radian=True)
```
</details>
### `@property`
### *method* `supplementary(self) -> AnyAngle`
补角：两角的和为180°。
**戻り値**:
- 补角
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def supplementary(self) -> 'AnyAngle':
"""
补角：两角的和为180°。
Returns:
补角
"""
return AnyAngle(PI - self.minimum_positive.radian, is_radian=True)
```
</details>
### `@property`
### *method* `degree(self) -> float`
角度。
**戻り値**:
- 弧度
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def degree(self) -> float:
"""
角度。
Returns:
弧度
"""
return self.radian * 180 / PI
```
</details>
### `@property`
### *method* `minimum_positive(self) -> AnyAngle`
最小正角。
**戻り値**:
- 最小正角度
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def minimum_positive(self) -> 'AnyAngle':
"""
最小正角。
Returns:
最小正角度
"""
return AnyAngle(self.radian % (2 * PI))
```
</details>
### `@property`
### *method* `maximum_negative(self) -> AnyAngle`
最大负角。
**戻り値**:
- 最大负角度
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def maximum_negative(self) -> 'AnyAngle':
"""
最大负角。
Returns:
最大负角度
"""
return AnyAngle(-self.radian % (2 * PI), is_radian=True)
```
</details>
### `@property`
### *method* `sin(self) -> float`
正弦值。
**戻り値**:
- 正弦值
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def sin(self) -> float:
"""
正弦值。
Returns:
正弦值
"""
return math.sin(self.radian)
```
</details>
### `@property`
### *method* `cos(self) -> float`
余弦值。
**戻り値**:
- 余弦值
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def cos(self) -> float:
"""
余弦值。
Returns:
余弦值
"""
return math.cos(self.radian)
```
</details>
### `@property`
### *method* `tan(self) -> float`
正切值。
**戻り値**:
- 正切值
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def tan(self) -> float:
"""
正切值。
Returns:
正切值
"""
return math.tan(self.radian)
```
</details>
### `@property`
### *method* `cot(self) -> float`
余切值。
**戻り値**:
- 余切值
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def cot(self) -> float:
"""
余切值。
Returns:
余切值
"""
return 1 / math.tan(self.radian)
```
</details>
### `@property`
### *method* `sec(self) -> float`
正割值。
**戻り値**:
- 正割值
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def sec(self) -> float:
"""
正割值。
Returns:
正割值
"""
return 1 / math.cos(self.radian)
```
</details>
### `@property`
### *method* `csc(self) -> float`
余割值。
**戻り値**:
- 余割值
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def csc(self) -> float:
"""
余割值。
Returns:
余割值
"""
return 1 / math.sin(self.radian)
```
</details>
### *method* `self + other: AnyAngle => AnyAngle`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __add__(self, other: 'AnyAngle') -> 'AnyAngle':
return AnyAngle(self.radian + other.radian, is_radian=True)
```
</details>
### *method* `__eq__(self, other)`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __eq__(self, other):
return approx(self.radian, other.radian)
```
</details>
### *method* `self - other: AnyAngle => AnyAngle`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __sub__(self, other: 'AnyAngle') -> 'AnyAngle':
return AnyAngle(self.radian - other.radian, is_radian=True)
```
</details>
### *method* `self * other: float => AnyAngle`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __mul__(self, other: float) -> 'AnyAngle':
return AnyAngle(self.radian * other, is_radian=True)
```
</details>
### `@overload`
### *method* `self / other: float => AnyAngle`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __truediv__(self, other: float) -> 'AnyAngle':
...
```
</details>
### `@overload`
### *method* `self / other: AnyAngle => float`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __truediv__(self, other: 'AnyAngle') -> float:
...
```
</details>
### *method* `self / other`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __truediv__(self, other):
if isinstance(other, AnyAngle):
return self.radian / other.radian
return AnyAngle(self.radian / other, is_radian=True)
```
</details>

3
docs/ja/api/mp_math/const.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.mp_math.const
---

162
docs/ja/api/mp_math/equation.md Normal file
View File

@ -0,0 +1,162 @@
---
title: mbcp.mp_math.equation
---
### *func* `get_partial_derivative_func(func: MultiVarsFunc = EPSILON) -> MultiVarsFunc`
求N元函数一阶偏导函数。这玩意不太稳定，慎用。
**引数**:
- func: 函数
- var: 变量位置，可为整数(一阶偏导)或整数元组(高阶偏导)
- epsilon: 偏移量
**戻り値**:
- 偏导函数
**例外**:
- ValueError 无效变量类型
<details>
<summary> <i>ソースコード</i> </summary>
```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')
```
</details>
### *func* `partial_derivative_func() -> Var`
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *func* `high_order_partial_derivative_func() -> Var`
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### **class** `CurveEquation`
### *method* `__init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc)`
曲线方程。
**引数**:
- x_func: x函数
- y_func: y函数
- z_func: z函数
<details>
<summary> <i>ソースコード</i> </summary>
```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
```
</details>
### *method* `__call__(self) -> Point3 | tuple[Point3, ...]`
计算曲线上的点。
**引数**:
- *t:
- 参数:
<details>
<summary> <i>ソースコード</i> </summary>
```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))])
```
</details>

3
docs/ja/api/mp_math/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.mp_math
---

581
docs/ja/api/mp_math/line.md Normal file
View File

@ -0,0 +1,581 @@
---
title: mbcp.mp_math.line
---
### **class** `Line3`
### *method* `__init__(self, point: Point3, direction: Vector3)`
三维空间中的直线。由一个点和一个方向向量确定。
**引数**:
- point: 直线上的一点
- direction: 直线的方向向量
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __init__(self, point: 'Point3', direction: 'Vector3'):
"""
三维空间中的直线。由一个点和一个方向向量确定。
Args:
point: 直线上的一点
direction: 直线的方向向量
"""
self.point = point
self.direction = direction
```
</details>
### *method* `approx(self, other: Line3, epsilon: float = APPROX) -> bool`
判断两条直线是否近似相等。
**引数**:
- other: 另一条直线
- epsilon: 误差
**戻り値**:
- 是否近似相等
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `cal_angle(self, other: Line3) -> AnyAngle`
计算直线和直线之间的夹角。
**引数**:
- other: 另一条直线
**戻り値**:
- 夹角弧度
**例外**:
- TypeError 不支持的类型
<details>
<summary> <i>ソースコード</i> </summary>
```python
def cal_angle(self, other: 'Line3') -> 'AnyAngle':
"""
计算直线和直线之间的夹角。
Args:
other: 另一条直线
Returns:
夹角弧度
Raises:
TypeError: 不支持的类型
"""
return self.direction.cal_angle(other.direction)
```
</details>
### *method* `cal_distance(self, other: Line3 | Point3) -> float`
计算直线和直线或点之间的距离。
**引数**:
- other: 平行直线或点
**戻り値**:
- 距离
**例外**:
- TypeError 不支持的类型
<details>
<summary> <i>ソースコード</i> </summary>
```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.')
```
</details>
### *method* `cal_intersection(self, other: Line3) -> Point3`
计算两条直线的交点。
**引数**:
- other: 另一条直线
**戻り値**:
- 交点
**例外**:
- ValueError 直线平行
- ValueError 直线不共面
<details>
<summary> <i>ソースコード</i> </summary>
```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
```
</details>
### *method* `cal_perpendicular(self, point: Point3) -> Line3`
计算直线经过指定点p的垂线。
**引数**:
- point: 指定点
**戻り値**:
- 垂线
<details>
<summary> <i>ソースコード</i> </summary>
```python
def cal_perpendicular(self, point: 'Point3') -> 'Line3':
"""
计算直线经过指定点p的垂线。
Args:
point: 指定点
Returns:
垂线
"""
return Line3(point, self.direction.cross(point - self.point))
```
</details>
### *method* `get_point(self, t: RealNumber) -> Point3`
获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
**引数**:
- t: 参数t
**戻り値**:
- 点
<details>
<summary> <i>ソースコード</i> </summary>
```python
def get_point(self, t: RealNumber) -> 'Point3':
"""
获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
Args:
t: 参数t
Returns:
点
"""
return self.point + t * self.direction
```
</details>
### *method* `get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc, OneSingleVarFunc]`
获取直线的参数方程。
**戻り値**:
- x(t), y(t), z(t)
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `is_approx_parallel(self, other: Line3, epsilon: float = 1e-06) -> bool`
判断两条直线是否近似平行。
**引数**:
- other: 另一条直线
- epsilon: 误差
**戻り値**:
- 是否近似平行
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `is_parallel(self, other: Line3) -> bool`
判断两条直线是否平行。
**引数**:
- other: 另一条直线
**戻り値**:
- 是否平行
<details>
<summary> <i>ソースコード</i> </summary>
```python
def is_parallel(self, other: 'Line3') -> bool:
"""
判断两条直线是否平行。
Args:
other: 另一条直线
Returns:
是否平行
"""
return self.direction.is_parallel(other.direction)
```
</details>
### *method* `is_collinear(self, other: Line3) -> bool`
判断两条直线是否共线。
**引数**:
- other: 另一条直线
**戻り値**:
- 是否共线
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `is_point_on(self, point: Point3) -> bool`
判断点是否在直线上。
**引数**:
- point: 点
**戻り値**:
- 是否在直线上
<details>
<summary> <i>ソースコード</i> </summary>
```python
def is_point_on(self, point: 'Point3') -> bool:
"""
判断点是否在直线上。
Args:
point: 点
Returns:
是否在直线上
"""
return (point - self.point).is_parallel(self.direction)
```
</details>
### *method* `is_coplanar(self, other: Line3) -> bool`
判断两条直线是否共面。
充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
**引数**:
- other: 另一条直线
**戻り値**:
- 是否共面
<details>
<summary> <i>ソースコード</i> </summary>
```python
def is_coplanar(self, other: 'Line3') -> bool:
"""
判断两条直线是否共面。
充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
Args:
other: 另一条直线
Returns:
是否共面
"""
return self.direction.cross(other.direction) @ (self.point - other.point) == 0
```
</details>
### *method* `simplify(self)`
简化直线方程，等价相等。
自体简化，不返回值。
按照可行性一次对x y z 化 0 处理，并对向量单位化
<details>
<summary> <i>ソースコード</i> </summary>
```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
```
</details>
### `@classmethod`
### *method* `from_two_points(cls, p1: Point3, p2: Point3) -> Line3`
工厂函数 由两点构造直线。
**引数**:
- p1: 点1
- p2: 点2
**戻り値**:
- 直线
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `__and__(self, other: Line3) -> Line3 | Point3 | None`
计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。
**引数**:
- other: 另一条直线
**戻り値**:
- 交点
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `__eq__(self, other) -> bool`
判断两条直线是否等价。
v1 // v2 ∧ (p1 - p2) // v1
**引数**:
- other:
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>

63
docs/ja/api/mp_math/mp_math_typing.md Normal file
View File

@ -0,0 +1,63 @@
---
title: mbcp.mp_math.mp_math_typing
---
### ***var*** `RealNumber = int | float`
- **タイプ**: `TypeAlias`
### ***var*** `Number = RealNumber | complex`
- **タイプ**: `TypeAlias`
### ***var*** `Var = SingleVar | ArrayVar`
- **タイプ**: `TypeAlias`
### ***var*** `OneSingleVarFunc = Callable[[SingleVar], SingleVar]`
- **タイプ**: `TypeAlias`
### ***var*** `OneArrayFunc = Callable[[ArrayVar], ArrayVar]`
- **タイプ**: `TypeAlias`
### ***var*** `OneVarFunc = OneSingleVarFunc | OneArrayFunc`
- **タイプ**: `TypeAlias`
### ***var*** `TwoSingleVarsFunc = Callable[[SingleVar, SingleVar], SingleVar]`
- **タイプ**: `TypeAlias`
### ***var*** `TwoArraysFunc = Callable[[ArrayVar, ArrayVar], ArrayVar]`
- **タイプ**: `TypeAlias`
### ***var*** `TwoVarsFunc = TwoSingleVarsFunc | TwoArraysFunc`
- **タイプ**: `TypeAlias`
### ***var*** `ThreeSingleVarsFunc = Callable[[SingleVar, SingleVar, SingleVar], SingleVar]`
- **タイプ**: `TypeAlias`
### ***var*** `ThreeArraysFunc = Callable[[ArrayVar, ArrayVar, ArrayVar], ArrayVar]`
- **タイプ**: `TypeAlias`
### ***var*** `ThreeVarsFunc = ThreeSingleVarsFunc | ThreeArraysFunc`
- **タイプ**: `TypeAlias`
### ***var*** `MultiSingleVarsFunc = Callable[..., SingleVar]`
- **タイプ**: `TypeAlias`
### ***var*** `MultiArraysFunc = Callable[..., ArrayVar]`
- **タイプ**: `TypeAlias`
### ***var*** `MultiVarsFunc = MultiSingleVarsFunc | MultiArraysFunc`
- **タイプ**: `TypeAlias`

592
docs/ja/api/mp_math/plane.md Normal file
View File

@ -0,0 +1,592 @@
---
title: mbcp.mp_math.plane
---
### **class** `Plane3`
### *method* `__init__(self, a: float, b: float, c: float, d: float)`
平面方程：ax + by + cz + d = 0
**引数**:
- a: x系数
- b: y系数
- c: z系数
- d: 常数项
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __init__(self, a: float, b: float, c: float, d: float):
"""
平面方程：ax + by + cz + d = 0
Args:
a: x系数
b: y系数
c: z系数
d: 常数项
"""
self.a = a
self.b = b
self.c = c
self.d = d
```
</details>
### *method* `approx(self, other: Plane3) -> bool`
判断两个平面是否近似相等。
**引数**:
- other: 另一个平面
**戻り値**:
- 是否近似相等
<details>
<summary> <i>ソースコード</i> </summary>
```python
def approx(self, other: 'Plane3') -> bool:
"""
判断两个平面是否近似相等。
Args:
other: 另一个平面
Returns:
是否近似相等
"""
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
```
</details>
### *method* `cal_angle(self, other: Line3 | Plane3) -> AnyAngle`
计算平面与平面之间的夹角。
**引数**:
- other: 另一个平面
**戻り値**:
- 夹角弧度
**例外**:
- TypeError 不支持的类型
<details>
<summary> <i>ソースコード</i> </summary>
```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)}')
```
</details>
### *method* `cal_distance(self, other: Plane3 | Point3) -> float`
计算平面与平面或点之间的距离。
**引数**:
- other: 另一个平面或点
**戻り値**:
- 距离
**例外**:
- TypeError 不支持的类型
<details>
<summary> <i>ソースコード</i> </summary>
```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)}')
```
</details>
### *method* `cal_intersection_line3(self, other: Plane3) -> Line3`
计算两平面的交线。
**引数**:
- other: 另一个平面
**戻り値**:
- 两平面的交线
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `cal_intersection_point3(self, other: Line3) -> Point3`
计算平面与直线的交点。
**引数**:
- other: 不与平面平行或在平面上的直线
**戻り値**:
- 交点
**例外**:
- ValueError 平面与直线平行或重合
<details>
<summary> <i>ソースコード</i> </summary>
```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))
```
</details>
### *method* `cal_parallel_plane3(self, point: Point3) -> Plane3`
计算平行于该平面且过指定点的平面。
**引数**:
- point: 指定点
**戻り値**:
- 所求平面
<details>
<summary> <i>ソースコード</i> </summary>
```python
def cal_parallel_plane3(self, point: 'Point3') -> 'Plane3':
"""
计算平行于该平面且过指定点的平面。
Args:
point: 指定点
Returns:
所求平面
"""
return Plane3.from_point_and_normal(point, self.normal)
```
</details>
### *method* `is_parallel(self, other: Plane3) -> bool`
判断两个平面是否平行。
**引数**:
- other: 另一个平面
**戻り値**:
- 是否平行
<details>
<summary> <i>ソースコード</i> </summary>
```python
def is_parallel(self, other: 'Plane3') -> bool:
"""
判断两个平面是否平行。
Args:
other: 另一个平面
Returns:
是否平行
"""
return self.normal.is_parallel(other.normal)
```
</details>
### `@property`
### *method* `normal(self) -> Vector3`
平面的法向量。
**戻り値**:
- 法向量
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def normal(self) -> 'Vector3':
"""
平面的法向量。
Returns:
法向量
"""
return Vector3(self.a, self.b, self.c)
```
</details>
### `@classmethod`
### *method* `from_point_and_normal(cls, point: Point3, normal: Vector3) -> Plane3`
工厂函数 由点和法向量构造平面(点法式构造)。
**引数**:
- point: 平面上的一点
- normal: 法向量
**戻り値**:
- 平面
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### `@classmethod`
### *method* `from_three_points(cls, p1: Point3, p2: Point3, p3: Point3) -> Plane3`
工厂函数 由三点构造平面。
**引数**:
- p1: 点1
- p2: 点2
- p3: 点3
**戻り値**:
- 平面
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### `@classmethod`
### *method* `from_two_lines(cls, l1: Line3, l2: Line3) -> Plane3`
工厂函数 由两直线构造平面。
**引数**:
- l1: 直线1
- l2: 直线2
**戻り値**:
- 平面
<details>
<summary> <i>ソースコード</i> </summary>
```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))
```
</details>
### `@classmethod`
### *method* `from_point_and_line(cls, point: Point3, line: Line3) -> Plane3`
工厂函数 由点和直线构造平面。
**引数**:
- point: 面上一点
- line: 面上直线，不包含点
**戻り値**:
- 平面
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### `@overload`
### *method* `__and__(self, other: Line3) -> Point3 | None`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __and__(self, other: 'Line3') -> 'Point3 | None':
...
```
</details>
### `@overload`
### *method* `__and__(self, other: Plane3) -> Line3 | None`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __and__(self, other: 'Plane3') -> 'Line3 | None':
...
```
</details>
### *method* `__and__(self, other)`
取两平面的交集（人话：交线）
**引数**:
- other:
**戻り値**:
- 不平行平面的交线，平面平行返回None
<details>
<summary> <i>ソースコード</i> </summary>
```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)}'")
```
</details>
### *method* `__eq__(self, other) -> bool`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __eq__(self, other) -> bool:
return self.approx(other)
```
</details>
### *method* `__rand__(self, other: Line3) -> Point3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __rand__(self, other: 'Line3') -> 'Point3':
return self.cal_intersection_point3(other)
```
</details>

186
docs/ja/api/mp_math/point.md Normal file
View File

@ -0,0 +1,186 @@
---
title: mbcp.mp_math.point
---
### **class** `Point3`
### *method* `__init__(self, x: float, y: float, z: float)`
笛卡尔坐标系中的点。
**引数**:
- x: x 坐标
- y: y 坐标
- z: z 坐标
<details>
<summary> <i>ソースコード</i> </summary>
```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
```
</details>
### *method* `approx(self, other: Point3, epsilon: float = APPROX) -> bool`
判断两个点是否近似相等。
**引数**:
- other:
- epsilon:
**戻り値**:
- 是否近似相等
<details>
<summary> <i>ソースコード</i> </summary>
```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])
```
</details>
### `@overload`
### *method* `self + other: Vector3 => Point3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __add__(self, other: 'Vector3') -> 'Point3':
...
```
</details>
### `@overload`
### *method* `self + other: Point3 => Point3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __add__(self, other: 'Point3') -> 'Point3':
...
```
</details>
### *method* `self + other`
P + V -> P
P + P -> P
**引数**:
- other:
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `__eq__(self, other)`
判断两个点是否相等。
**引数**:
- other:
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `self - other: Point3 => Vector3`
P - P -> V
P - V -> P 已在 :class:`Vector3` 中实现
**引数**:
- other:
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>

34
docs/ja/api/mp_math/segment.md Normal file
View File

@ -0,0 +1,34 @@
---
title: mbcp.mp_math.segment
---
### **class** `Segment3`
### *method* `__init__(self, p1: Point3, p2: Point3)`
三维空间中的线段。
:param p1:
:param p2:
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>

218
docs/ja/api/mp_math/utils.md Normal file
View File

@ -0,0 +1,218 @@
---
title: mbcp.mp_math.utils
---
### *func* `clamp() -> float`
区间限定函数
**引数**:
- x: 待限定的值
- min_: 最小值
- max_: 最大值
**戻り値**:
- 限制后的值
<details>
<summary> <i>ソースコード</i> </summary>
```python
def clamp(x: float, min_: float, max_: float) -> float:
"""
区间限定函数
Args:
x: 待限定的值
min_: 最小值
max_: 最大值
Returns:
限制后的值
"""
return max(min(x, max_), min_)
```
</details>
### *func* `approx(x: float = 0.0, y: float = APPROX) -> bool`
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
**引数**:
- x: 数1
- y: 数2
- epsilon: 误差
**戻り値**:
- 是否近似相等
<details>
<summary> <i>ソースコード</i> </summary>
```python
def approx(x: float, y: float=0.0, epsilon: float=APPROX) -> bool:
"""
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
Args:
x: 数1
y: 数2
epsilon: 误差
Returns:
是否近似相等
"""
return abs(x - y) < epsilon
```
</details>
### *func* `sign(x: float = False) -> str`
获取数的符号。
**引数**:
- x: 数
- only_neg: 是否只返回负数的符号
**戻り値**:
- 符号 + - ""
<details>
<summary> <i>ソースコード</i> </summary>
```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 ''
```
</details>
### *func* `sign_format(x: float = False) -> str`
格式化符号数
-1 -> -1
1 -> +1
0 -> ""
**引数**:
- x: 数
- only_neg: 是否只返回负数的符号
**戻り値**:
- 符号 + - ""
<details>
<summary> <i>ソースコード</i> </summary>
```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 ''
```
</details>
### **class** `Approx`
### *method* `__init__(self, value: RealNumber)`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __init__(self, value: RealNumber):
self.value = value
```
</details>
### *method* `__eq__(self, other)`
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `raise_type_error(self, other)`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def raise_type_error(self, other):
raise TypeError(f'Unsupported type: {type(self.value)} and {type(other)}')
```
</details>
### *method* `__ne__(self, other)`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __ne__(self, other):
return not self.__eq__(other)
```
</details>

690
docs/ja/api/mp_math/vector.md Normal file
View File

@ -0,0 +1,690 @@
---
title: mbcp.mp_math.vector
---
### **class** `Vector3`
### *method* `__init__(self, x: float, y: float, z: float)`
3维向量
**引数**:
- x: x轴分量
- y: y轴分量
- z: z轴分量
<details>
<summary> <i>ソースコード</i> </summary>
```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
```
</details>
### *method* `approx(self, other: Vector3, epsilon: float = APPROX) -> bool`
判断两个向量是否近似相等。
**引数**:
- other:
- epsilon:
**戻り値**:
- 是否近似相等
<details>
<summary> <i>ソースコード</i> </summary>
```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])
```
</details>
### *method* `cal_angle(self, other: Vector3) -> AnyAngle`
计算两个向量之间的夹角。
**引数**:
- other: 另一个向量
**戻り値**:
- 夹角
<details>
<summary> <i>ソースコード</i> </summary>
```python
def cal_angle(self, other: 'Vector3') -> 'AnyAngle':
"""
计算两个向量之间的夹角。
Args:
other: 另一个向量
Returns:
夹角
"""
return AnyAngle(math.acos(self @ other / (self.length * other.length)), is_radian=True)
```
</details>
### *method* `cross(self, other: Vector3) -> Vector3`
向量积 叉乘：v1 cross v2 -> v3
叉乘为0，则两向量平行。
其余结果的模为平行四边形的面积。
**引数**:
- other:
**戻り値**:
- 行列式的结果
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `is_approx_parallel(self, other: Vector3, epsilon: float = APPROX) -> bool`
判断两个向量是否近似平行。
**引数**:
- other: 另一个向量
- epsilon: 允许的误差
**戻り値**:
- 是否近似平行
<details>
<summary> <i>ソースコード</i> </summary>
```python
def is_approx_parallel(self, other: 'Vector3', epsilon: float=APPROX) -> bool:
"""
判断两个向量是否近似平行。
Args:
other: 另一个向量
epsilon: 允许的误差
Returns:
是否近似平行
"""
return self.cross(other).length < epsilon
```
</details>
### *method* `is_parallel(self, other: Vector3) -> bool`
判断两个向量是否平行。
**引数**:
- other: 另一个向量
**戻り値**:
- 是否平行
<details>
<summary> <i>ソースコード</i> </summary>
```python
def is_parallel(self, other: 'Vector3') -> bool:
"""
判断两个向量是否平行。
Args:
other: 另一个向量
Returns:
是否平行
"""
return self.cross(other).approx(zero_vector3)
```
</details>
### *method* `normalize(self)`
将向量归一化。
自体归一化，不返回值。
<details>
<summary> <i>ソースコード</i> </summary>
```python
def normalize(self):
"""
将向量归一化。
自体归一化，不返回值。
"""
length = self.length
self.x /= length
self.y /= length
self.z /= length
```
</details>
### `@property`
### *method* `np_array(self) -> np.ndarray`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def np_array(self) -> 'np.ndarray':
"""
返回numpy数组
Returns:
"""
return np.array([self.x, self.y, self.z])
```
</details>
### `@property`
### *method* `length(self) -> float`
向量的模。
**戻り値**:
- 模
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def length(self) -> float:
"""
向量的模。
Returns:
模
"""
return math.sqrt(self.x ** 2 + self.y ** 2 + self.z ** 2)
```
</details>
### `@property`
### *method* `unit(self) -> Vector3`
获取该向量的单位向量。
**戻り値**:
- 单位向量
<details>
<summary> <i>ソースコード</i> </summary>
```python
@property
def unit(self) -> 'Vector3':
"""
获取该向量的单位向量。
Returns:
单位向量
"""
return self / self.length
```
</details>
### *method* `__abs__(self)`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __abs__(self):
return self.length
```
</details>
### `@overload`
### *method* `self + other: Vector3 => Vector3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __add__(self, other: 'Vector3') -> 'Vector3':
...
```
</details>
### `@overload`
### *method* `self + other: Point3 => Point3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __add__(self, other: 'Point3') -> 'Point3':
...
```
</details>
### *method* `self + other`
V + P -> P
V + V -> V
**引数**:
- other:
<details>
<summary> <i>ソースコード</i> </summary>
```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)}'")
```
</details>
### *method* `__eq__(self, other)`
判断两个向量是否相等。
**引数**:
- other:
**戻り値**:
- 是否相等
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### *method* `self + other: Point3 => Point3`
P + V -> P
别去点那边实现了。
:param other:
:return:
<details>
<summary> <i>ソースコード</i> </summary>
```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)
```
</details>
### `@overload`
### *method* `self - other: Vector3 => Vector3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __sub__(self, other: 'Vector3') -> 'Vector3':
...
```
</details>
### `@overload`
### *method* `self - other: Point3 => Point3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __sub__(self, other: 'Point3') -> 'Point3':
...
```
</details>
### *method* `self - other`
V - P -> P
V - V -> V
**引数**:
- other:
<details>
<summary> <i>ソースコード</i> </summary>
```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)}"')
```
</details>
### *method* `self - other: Point3`
P - V -> P
**引数**:
- other:
<details>
<summary> <i>ソースコード</i> </summary>
```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'")
```
</details>
### `@overload`
### *method* `self * other: Vector3 => Vector3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __mul__(self, other: 'Vector3') -> 'Vector3':
...
```
</details>
### `@overload`
### *method* `self * other: RealNumber => Vector3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
@overload
def __mul__(self, other: RealNumber) -> 'Vector3':
...
```
</details>
### *method* `self * other: int | float | Vector3 => Vector3`
数组运算 非点乘。点乘使用@，叉乘使用cross。
**引数**:
- other:
<details>
<summary> <i>ソースコード</i> </summary>
```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)}'")
```
</details>
### *method* `self * other: RealNumber => Vector3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __rmul__(self, other: 'RealNumber') -> 'Vector3':
return self.__mul__(other)
```
</details>
### *method* `self @ other: Vector3 => RealNumber`
点乘。
**引数**:
- other:
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __matmul__(self, other: 'Vector3') -> 'RealNumber':
"""
点乘。
Args:
other:
Returns:
"""
return self.x * other.x + self.y * other.y + self.z * other.z
```
</details>
### *method* `self / other: RealNumber => Vector3`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __truediv__(self, other: RealNumber) -> 'Vector3':
return Vector3(self.x / other, self.y / other, self.z / other)
```
</details>
### *method* `- self`
<details>
<summary> <i>ソースコード</i> </summary>
```python
def __neg__(self):
return Vector3(-self.x, -self.y, -self.z)
```
</details>
### ***var*** `zero_vector3 = Vector3(0, 0, 0)`
- **タイプ**: `Vector3`
- **説明**: 零向量
### ***var*** `x_axis = Vector3(1, 0, 0)`
- **タイプ**: `Vector3`
- **説明**: x轴单位向量
### ***var*** `y_axis = Vector3(0, 1, 0)`
- **タイプ**: `Vector3`
- **説明**: y轴单位向量
### ***var*** `z_axis = Vector3(0, 0, 1)`
- **タイプ**: `Vector3`
- **説明**: z轴单位向量

3
docs/ja/api/particle/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.particle
---

3
docs/ja/api/presets/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.presets
---

47
docs/ja/api/presets/model/index.md Normal file
View File

@ -0,0 +1,47 @@
---
title: mbcp.presets.model
---
### **class** `GeometricModels`
### `@staticmethod`
### *method* `sphere(radius: float, density: float)`
生成球体上的点集。
**引数**:
- radius:
- density:
**戻り値**:
- List[Point3]: 球体上的点集。
<details>
<summary> <i>ソースコード</i> </summary>
```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)]
```
</details>

3
docs/zht/api/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp
---

423
docs/zht/api/mp_math/angle.md Normal file
View File

@ -0,0 +1,423 @@
---
title: mbcp.mp_math.angle
---
### **class** `Angle`
### **class** `AnyAngle(Angle)`
### *method* `__init__(self, value: float, is_radian: bool = False)`
任意角度。
**變數説明**:
- value: 角度或弧度值
- is_radian: 是否为弧度，默认为否
<details>
<summary> <i>源碼</i> </summary>
```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
```
</details>
### `@property`
### *method* `complementary(self) -> AnyAngle`
余角：两角的和为90°。
**返回**:
- 余角
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def complementary(self) -> 'AnyAngle':
"""
余角：两角的和为90°。
Returns:
余角
"""
return AnyAngle(PI / 2 - self.minimum_positive.radian, is_radian=True)
```
</details>
### `@property`
### *method* `supplementary(self) -> AnyAngle`
补角：两角的和为180°。
**返回**:
- 补角
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def supplementary(self) -> 'AnyAngle':
"""
补角：两角的和为180°。
Returns:
补角
"""
return AnyAngle(PI - self.minimum_positive.radian, is_radian=True)
```
</details>
### `@property`
### *method* `degree(self) -> float`
角度。
**返回**:
- 弧度
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def degree(self) -> float:
"""
角度。
Returns:
弧度
"""
return self.radian * 180 / PI
```
</details>
### `@property`
### *method* `minimum_positive(self) -> AnyAngle`
最小正角。
**返回**:
- 最小正角度
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def minimum_positive(self) -> 'AnyAngle':
"""
最小正角。
Returns:
最小正角度
"""
return AnyAngle(self.radian % (2 * PI))
```
</details>
### `@property`
### *method* `maximum_negative(self) -> AnyAngle`
最大负角。
**返回**:
- 最大负角度
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def maximum_negative(self) -> 'AnyAngle':
"""
最大负角。
Returns:
最大负角度
"""
return AnyAngle(-self.radian % (2 * PI), is_radian=True)
```
</details>
### `@property`
### *method* `sin(self) -> float`
正弦值。
**返回**:
- 正弦值
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def sin(self) -> float:
"""
正弦值。
Returns:
正弦值
"""
return math.sin(self.radian)
```
</details>
### `@property`
### *method* `cos(self) -> float`
余弦值。
**返回**:
- 余弦值
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def cos(self) -> float:
"""
余弦值。
Returns:
余弦值
"""
return math.cos(self.radian)
```
</details>
### `@property`
### *method* `tan(self) -> float`
正切值。
**返回**:
- 正切值
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def tan(self) -> float:
"""
正切值。
Returns:
正切值
"""
return math.tan(self.radian)
```
</details>
### `@property`
### *method* `cot(self) -> float`
余切值。
**返回**:
- 余切值
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def cot(self) -> float:
"""
余切值。
Returns:
余切值
"""
return 1 / math.tan(self.radian)
```
</details>
### `@property`
### *method* `sec(self) -> float`
正割值。
**返回**:
- 正割值
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def sec(self) -> float:
"""
正割值。
Returns:
正割值
"""
return 1 / math.cos(self.radian)
```
</details>
### `@property`
### *method* `csc(self) -> float`
余割值。
**返回**:
- 余割值
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def csc(self) -> float:
"""
余割值。
Returns:
余割值
"""
return 1 / math.sin(self.radian)
```
</details>
### *method* `self + other: AnyAngle => AnyAngle`
<details>
<summary> <i>源碼</i> </summary>
```python
def __add__(self, other: 'AnyAngle') -> 'AnyAngle':
return AnyAngle(self.radian + other.radian, is_radian=True)
```
</details>
### *method* `__eq__(self, other)`
<details>
<summary> <i>源碼</i> </summary>
```python
def __eq__(self, other):
return approx(self.radian, other.radian)
```
</details>
### *method* `self - other: AnyAngle => AnyAngle`
<details>
<summary> <i>源碼</i> </summary>
```python
def __sub__(self, other: 'AnyAngle') -> 'AnyAngle':
return AnyAngle(self.radian - other.radian, is_radian=True)
```
</details>
### *method* `self * other: float => AnyAngle`
<details>
<summary> <i>源碼</i> </summary>
```python
def __mul__(self, other: float) -> 'AnyAngle':
return AnyAngle(self.radian * other, is_radian=True)
```
</details>
### `@overload`
### *method* `self / other: float => AnyAngle`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __truediv__(self, other: float) -> 'AnyAngle':
...
```
</details>
### `@overload`
### *method* `self / other: AnyAngle => float`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __truediv__(self, other: 'AnyAngle') -> float:
...
```
</details>
### *method* `self / other`
<details>
<summary> <i>源碼</i> </summary>
```python
def __truediv__(self, other):
if isinstance(other, AnyAngle):
return self.radian / other.radian
return AnyAngle(self.radian / other, is_radian=True)
```
</details>

3
docs/zht/api/mp_math/const.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.mp_math.const
---

162
docs/zht/api/mp_math/equation.md Normal file
View File

@ -0,0 +1,162 @@
---
title: mbcp.mp_math.equation
---
### *func* `get_partial_derivative_func(func: MultiVarsFunc = EPSILON) -> MultiVarsFunc`
求N元函数一阶偏导函数。这玩意不太稳定，慎用。
**變數説明**:
- func: 函数
- var: 变量位置，可为整数(一阶偏导)或整数元组(高阶偏导)
- epsilon: 偏移量
**返回**:
- 偏导函数
**抛出**:
- ValueError 无效变量类型
<details>
<summary> <i>源碼</i> </summary>
```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')
```
</details>
### *func* `partial_derivative_func() -> Var`
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *func* `high_order_partial_derivative_func() -> Var`
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### **class** `CurveEquation`
### *method* `__init__(self, x_func: OneVarFunc, y_func: OneVarFunc, z_func: OneVarFunc)`
曲线方程。
**變數説明**:
- x_func: x函数
- y_func: y函数
- z_func: z函数
<details>
<summary> <i>源碼</i> </summary>
```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
```
</details>
### *method* `__call__(self) -> Point3 | tuple[Point3, ...]`
计算曲线上的点。
**變數説明**:
- *t:
- 参数:
<details>
<summary> <i>源碼</i> </summary>
```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))])
```
</details>

3
docs/zht/api/mp_math/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.mp_math
---

581
docs/zht/api/mp_math/line.md Normal file
View File

@ -0,0 +1,581 @@
---
title: mbcp.mp_math.line
---
### **class** `Line3`
### *method* `__init__(self, point: Point3, direction: Vector3)`
三维空间中的直线。由一个点和一个方向向量确定。
**變數説明**:
- point: 直线上的一点
- direction: 直线的方向向量
<details>
<summary> <i>源碼</i> </summary>
```python
def __init__(self, point: 'Point3', direction: 'Vector3'):
"""
三维空间中的直线。由一个点和一个方向向量确定。
Args:
point: 直线上的一点
direction: 直线的方向向量
"""
self.point = point
self.direction = direction
```
</details>
### *method* `approx(self, other: Line3, epsilon: float = APPROX) -> bool`
判断两条直线是否近似相等。
**變數説明**:
- other: 另一条直线
- epsilon: 误差
**返回**:
- 是否近似相等
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `cal_angle(self, other: Line3) -> AnyAngle`
计算直线和直线之间的夹角。
**變數説明**:
- other: 另一条直线
**返回**:
- 夹角弧度
**抛出**:
- TypeError 不支持的类型
<details>
<summary> <i>源碼</i> </summary>
```python
def cal_angle(self, other: 'Line3') -> 'AnyAngle':
"""
计算直线和直线之间的夹角。
Args:
other: 另一条直线
Returns:
夹角弧度
Raises:
TypeError: 不支持的类型
"""
return self.direction.cal_angle(other.direction)
```
</details>
### *method* `cal_distance(self, other: Line3 | Point3) -> float`
计算直线和直线或点之间的距离。
**變數説明**:
- other: 平行直线或点
**返回**:
- 距离
**抛出**:
- TypeError 不支持的类型
<details>
<summary> <i>源碼</i> </summary>
```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.')
```
</details>
### *method* `cal_intersection(self, other: Line3) -> Point3`
计算两条直线的交点。
**變數説明**:
- other: 另一条直线
**返回**:
- 交点
**抛出**:
- ValueError 直线平行
- ValueError 直线不共面
<details>
<summary> <i>源碼</i> </summary>
```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
```
</details>
### *method* `cal_perpendicular(self, point: Point3) -> Line3`
计算直线经过指定点p的垂线。
**變數説明**:
- point: 指定点
**返回**:
- 垂线
<details>
<summary> <i>源碼</i> </summary>
```python
def cal_perpendicular(self, point: 'Point3') -> 'Line3':
"""
计算直线经过指定点p的垂线。
Args:
point: 指定点
Returns:
垂线
"""
return Line3(point, self.direction.cross(point - self.point))
```
</details>
### *method* `get_point(self, t: RealNumber) -> Point3`
获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
**變數説明**:
- t: 参数t
**返回**:
- 点
<details>
<summary> <i>源碼</i> </summary>
```python
def get_point(self, t: RealNumber) -> 'Point3':
"""
获取直线上的点。同一条直线，但起始点和方向向量不同，则同一个t对应的点不同。
Args:
t: 参数t
Returns:
点
"""
return self.point + t * self.direction
```
</details>
### *method* `get_parametric_equations(self) -> tuple[OneSingleVarFunc, OneSingleVarFunc, OneSingleVarFunc]`
获取直线的参数方程。
**返回**:
- x(t), y(t), z(t)
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `is_approx_parallel(self, other: Line3, epsilon: float = 1e-06) -> bool`
判断两条直线是否近似平行。
**變數説明**:
- other: 另一条直线
- epsilon: 误差
**返回**:
- 是否近似平行
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `is_parallel(self, other: Line3) -> bool`
判断两条直线是否平行。
**變數説明**:
- other: 另一条直线
**返回**:
- 是否平行
<details>
<summary> <i>源碼</i> </summary>
```python
def is_parallel(self, other: 'Line3') -> bool:
"""
判断两条直线是否平行。
Args:
other: 另一条直线
Returns:
是否平行
"""
return self.direction.is_parallel(other.direction)
```
</details>
### *method* `is_collinear(self, other: Line3) -> bool`
判断两条直线是否共线。
**變數説明**:
- other: 另一条直线
**返回**:
- 是否共线
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `is_point_on(self, point: Point3) -> bool`
判断点是否在直线上。
**變數説明**:
- point: 点
**返回**:
- 是否在直线上
<details>
<summary> <i>源碼</i> </summary>
```python
def is_point_on(self, point: 'Point3') -> bool:
"""
判断点是否在直线上。
Args:
point: 点
Returns:
是否在直线上
"""
return (point - self.point).is_parallel(self.direction)
```
</details>
### *method* `is_coplanar(self, other: Line3) -> bool`
判断两条直线是否共面。
充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
**變數説明**:
- other: 另一条直线
**返回**:
- 是否共面
<details>
<summary> <i>源碼</i> </summary>
```python
def is_coplanar(self, other: 'Line3') -> bool:
"""
判断两条直线是否共面。
充要条件：两直线方向向量的叉乘与两直线上任意一点的向量的点积为0。
Args:
other: 另一条直线
Returns:
是否共面
"""
return self.direction.cross(other.direction) @ (self.point - other.point) == 0
```
</details>
### *method* `simplify(self)`
简化直线方程，等价相等。
自体简化，不返回值。
按照可行性一次对x y z 化 0 处理，并对向量单位化
<details>
<summary> <i>源碼</i> </summary>
```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
```
</details>
### `@classmethod`
### *method* `from_two_points(cls, p1: Point3, p2: Point3) -> Line3`
工厂函数 由两点构造直线。
**變數説明**:
- p1: 点1
- p2: 点2
**返回**:
- 直线
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `__and__(self, other: Line3) -> Line3 | Point3 | None`
计算两条直线点集合的交集。重合线返回自身，平行线返回None，交线返回交点。
**變數説明**:
- other: 另一条直线
**返回**:
- 交点
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `__eq__(self, other) -> bool`
判断两条直线是否等价。
v1 // v2 ∧ (p1 - p2) // v1
**變數説明**:
- other:
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>

63
docs/zht/api/mp_math/mp_math_typing.md Normal file
View File

@ -0,0 +1,63 @@
---
title: mbcp.mp_math.mp_math_typing
---
### ***var*** `RealNumber = int | float`
- **類型**: `TypeAlias`
### ***var*** `Number = RealNumber | complex`
- **類型**: `TypeAlias`
### ***var*** `Var = SingleVar | ArrayVar`
- **類型**: `TypeAlias`
### ***var*** `OneSingleVarFunc = Callable[[SingleVar], SingleVar]`
- **類型**: `TypeAlias`
### ***var*** `OneArrayFunc = Callable[[ArrayVar], ArrayVar]`
- **類型**: `TypeAlias`
### ***var*** `OneVarFunc = OneSingleVarFunc | OneArrayFunc`
- **類型**: `TypeAlias`
### ***var*** `TwoSingleVarsFunc = Callable[[SingleVar, SingleVar], SingleVar]`
- **類型**: `TypeAlias`
### ***var*** `TwoArraysFunc = Callable[[ArrayVar, ArrayVar], ArrayVar]`
- **類型**: `TypeAlias`
### ***var*** `TwoVarsFunc = TwoSingleVarsFunc | TwoArraysFunc`
- **類型**: `TypeAlias`
### ***var*** `ThreeSingleVarsFunc = Callable[[SingleVar, SingleVar, SingleVar], SingleVar]`
- **類型**: `TypeAlias`
### ***var*** `ThreeArraysFunc = Callable[[ArrayVar, ArrayVar, ArrayVar], ArrayVar]`
- **類型**: `TypeAlias`
### ***var*** `ThreeVarsFunc = ThreeSingleVarsFunc | ThreeArraysFunc`
- **類型**: `TypeAlias`
### ***var*** `MultiSingleVarsFunc = Callable[..., SingleVar]`
- **類型**: `TypeAlias`
### ***var*** `MultiArraysFunc = Callable[..., ArrayVar]`
- **類型**: `TypeAlias`
### ***var*** `MultiVarsFunc = MultiSingleVarsFunc | MultiArraysFunc`
- **類型**: `TypeAlias`

592
docs/zht/api/mp_math/plane.md Normal file
View File

@ -0,0 +1,592 @@
---
title: mbcp.mp_math.plane
---
### **class** `Plane3`
### *method* `__init__(self, a: float, b: float, c: float, d: float)`
平面方程：ax + by + cz + d = 0
**變數説明**:
- a: x系数
- b: y系数
- c: z系数
- d: 常数项
<details>
<summary> <i>源碼</i> </summary>
```python
def __init__(self, a: float, b: float, c: float, d: float):
"""
平面方程：ax + by + cz + d = 0
Args:
a: x系数
b: y系数
c: z系数
d: 常数项
"""
self.a = a
self.b = b
self.c = c
self.d = d
```
</details>
### *method* `approx(self, other: Plane3) -> bool`
判断两个平面是否近似相等。
**變數説明**:
- other: 另一个平面
**返回**:
- 是否近似相等
<details>
<summary> <i>源碼</i> </summary>
```python
def approx(self, other: 'Plane3') -> bool:
"""
判断两个平面是否近似相等。
Args:
other: 另一个平面
Returns:
是否近似相等
"""
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
```
</details>
### *method* `cal_angle(self, other: Line3 | Plane3) -> AnyAngle`
计算平面与平面之间的夹角。
**變數説明**:
- other: 另一个平面
**返回**:
- 夹角弧度
**抛出**:
- TypeError 不支持的类型
<details>
<summary> <i>源碼</i> </summary>
```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)}')
```
</details>
### *method* `cal_distance(self, other: Plane3 | Point3) -> float`
计算平面与平面或点之间的距离。
**變數説明**:
- other: 另一个平面或点
**返回**:
- 距离
**抛出**:
- TypeError 不支持的类型
<details>
<summary> <i>源碼</i> </summary>
```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)}')
```
</details>
### *method* `cal_intersection_line3(self, other: Plane3) -> Line3`
计算两平面的交线。
**變數説明**:
- other: 另一个平面
**返回**:
- 两平面的交线
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `cal_intersection_point3(self, other: Line3) -> Point3`
计算平面与直线的交点。
**變數説明**:
- other: 不与平面平行或在平面上的直线
**返回**:
- 交点
**抛出**:
- ValueError 平面与直线平行或重合
<details>
<summary> <i>源碼</i> </summary>
```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))
```
</details>
### *method* `cal_parallel_plane3(self, point: Point3) -> Plane3`
计算平行于该平面且过指定点的平面。
**變數説明**:
- point: 指定点
**返回**:
- 所求平面
<details>
<summary> <i>源碼</i> </summary>
```python
def cal_parallel_plane3(self, point: 'Point3') -> 'Plane3':
"""
计算平行于该平面且过指定点的平面。
Args:
point: 指定点
Returns:
所求平面
"""
return Plane3.from_point_and_normal(point, self.normal)
```
</details>
### *method* `is_parallel(self, other: Plane3) -> bool`
判断两个平面是否平行。
**變數説明**:
- other: 另一个平面
**返回**:
- 是否平行
<details>
<summary> <i>源碼</i> </summary>
```python
def is_parallel(self, other: 'Plane3') -> bool:
"""
判断两个平面是否平行。
Args:
other: 另一个平面
Returns:
是否平行
"""
return self.normal.is_parallel(other.normal)
```
</details>
### `@property`
### *method* `normal(self) -> Vector3`
平面的法向量。
**返回**:
- 法向量
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def normal(self) -> 'Vector3':
"""
平面的法向量。
Returns:
法向量
"""
return Vector3(self.a, self.b, self.c)
```
</details>
### `@classmethod`
### *method* `from_point_and_normal(cls, point: Point3, normal: Vector3) -> Plane3`
工厂函数 由点和法向量构造平面(点法式构造)。
**變數説明**:
- point: 平面上的一点
- normal: 法向量
**返回**:
- 平面
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### `@classmethod`
### *method* `from_three_points(cls, p1: Point3, p2: Point3, p3: Point3) -> Plane3`
工厂函数 由三点构造平面。
**變數説明**:
- p1: 点1
- p2: 点2
- p3: 点3
**返回**:
- 平面
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### `@classmethod`
### *method* `from_two_lines(cls, l1: Line3, l2: Line3) -> Plane3`
工厂函数 由两直线构造平面。
**變數説明**:
- l1: 直线1
- l2: 直线2
**返回**:
- 平面
<details>
<summary> <i>源碼</i> </summary>
```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))
```
</details>
### `@classmethod`
### *method* `from_point_and_line(cls, point: Point3, line: Line3) -> Plane3`
工厂函数 由点和直线构造平面。
**變數説明**:
- point: 面上一点
- line: 面上直线，不包含点
**返回**:
- 平面
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### `@overload`
### *method* `__and__(self, other: Line3) -> Point3 | None`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __and__(self, other: 'Line3') -> 'Point3 | None':
...
```
</details>
### `@overload`
### *method* `__and__(self, other: Plane3) -> Line3 | None`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __and__(self, other: 'Plane3') -> 'Line3 | None':
...
```
</details>
### *method* `__and__(self, other)`
取两平面的交集（人话：交线）
**變數説明**:
- other:
**返回**:
- 不平行平面的交线，平面平行返回None
<details>
<summary> <i>源碼</i> </summary>
```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)}'")
```
</details>
### *method* `__eq__(self, other) -> bool`
<details>
<summary> <i>源碼</i> </summary>
```python
def __eq__(self, other) -> bool:
return self.approx(other)
```
</details>
### *method* `__rand__(self, other: Line3) -> Point3`
<details>
<summary> <i>源碼</i> </summary>
```python
def __rand__(self, other: 'Line3') -> 'Point3':
return self.cal_intersection_point3(other)
```
</details>

186
docs/zht/api/mp_math/point.md Normal file
View File

@ -0,0 +1,186 @@
---
title: mbcp.mp_math.point
---
### **class** `Point3`
### *method* `__init__(self, x: float, y: float, z: float)`
笛卡尔坐标系中的点。
**變數説明**:
- x: x 坐标
- y: y 坐标
- z: z 坐标
<details>
<summary> <i>源碼</i> </summary>
```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
```
</details>
### *method* `approx(self, other: Point3, epsilon: float = APPROX) -> bool`
判断两个点是否近似相等。
**變數説明**:
- other:
- epsilon:
**返回**:
- 是否近似相等
<details>
<summary> <i>源碼</i> </summary>
```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])
```
</details>
### `@overload`
### *method* `self + other: Vector3 => Point3`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __add__(self, other: 'Vector3') -> 'Point3':
...
```
</details>
### `@overload`
### *method* `self + other: Point3 => Point3`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __add__(self, other: 'Point3') -> 'Point3':
...
```
</details>
### *method* `self + other`
P + V -> P
P + P -> P
**變數説明**:
- other:
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `__eq__(self, other)`
判断两个点是否相等。
**變數説明**:
- other:
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `self - other: Point3 => Vector3`
P - P -> V
P - V -> P 已在 :class:`Vector3` 中实现
**變數説明**:
- other:
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>

34
docs/zht/api/mp_math/segment.md Normal file
View File

@ -0,0 +1,34 @@
---
title: mbcp.mp_math.segment
---
### **class** `Segment3`
### *method* `__init__(self, p1: Point3, p2: Point3)`
三维空间中的线段。
:param p1:
:param p2:
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>

218
docs/zht/api/mp_math/utils.md Normal file
View File

@ -0,0 +1,218 @@
---
title: mbcp.mp_math.utils
---
### *func* `clamp() -> float`
区间限定函数
**變數説明**:
- x: 待限定的值
- min_: 最小值
- max_: 最大值
**返回**:
- 限制后的值
<details>
<summary> <i>源碼</i> </summary>
```python
def clamp(x: float, min_: float, max_: float) -> float:
"""
区间限定函数
Args:
x: 待限定的值
min_: 最小值
max_: 最大值
Returns:
限制后的值
"""
return max(min(x, max_), min_)
```
</details>
### *func* `approx(x: float = 0.0, y: float = APPROX) -> bool`
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
**變數説明**:
- x: 数1
- y: 数2
- epsilon: 误差
**返回**:
- 是否近似相等
<details>
<summary> <i>源碼</i> </summary>
```python
def approx(x: float, y: float=0.0, epsilon: float=APPROX) -> bool:
"""
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
Args:
x: 数1
y: 数2
epsilon: 误差
Returns:
是否近似相等
"""
return abs(x - y) < epsilon
```
</details>
### *func* `sign(x: float = False) -> str`
获取数的符号。
**變數説明**:
- x: 数
- only_neg: 是否只返回负数的符号
**返回**:
- 符号 + - ""
<details>
<summary> <i>源碼</i> </summary>
```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 ''
```
</details>
### *func* `sign_format(x: float = False) -> str`
格式化符号数
-1 -> -1
1 -> +1
0 -> ""
**變數説明**:
- x: 数
- only_neg: 是否只返回负数的符号
**返回**:
- 符号 + - ""
<details>
<summary> <i>源碼</i> </summary>
```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 ''
```
</details>
### **class** `Approx`
### *method* `__init__(self, value: RealNumber)`
<details>
<summary> <i>源碼</i> </summary>
```python
def __init__(self, value: RealNumber):
self.value = value
```
</details>
### *method* `__eq__(self, other)`
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `raise_type_error(self, other)`
<details>
<summary> <i>源碼</i> </summary>
```python
def raise_type_error(self, other):
raise TypeError(f'Unsupported type: {type(self.value)} and {type(other)}')
```
</details>
### *method* `__ne__(self, other)`
<details>
<summary> <i>源碼</i> </summary>
```python
def __ne__(self, other):
return not self.__eq__(other)
```
</details>

690
docs/zht/api/mp_math/vector.md Normal file
View File

@ -0,0 +1,690 @@
---
title: mbcp.mp_math.vector
---
### **class** `Vector3`
### *method* `__init__(self, x: float, y: float, z: float)`
3维向量
**變數説明**:
- x: x轴分量
- y: y轴分量
- z: z轴分量
<details>
<summary> <i>源碼</i> </summary>
```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
```
</details>
### *method* `approx(self, other: Vector3, epsilon: float = APPROX) -> bool`
判断两个向量是否近似相等。
**變數説明**:
- other:
- epsilon:
**返回**:
- 是否近似相等
<details>
<summary> <i>源碼</i> </summary>
```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])
```
</details>
### *method* `cal_angle(self, other: Vector3) -> AnyAngle`
计算两个向量之间的夹角。
**變數説明**:
- other: 另一个向量
**返回**:
- 夹角
<details>
<summary> <i>源碼</i> </summary>
```python
def cal_angle(self, other: 'Vector3') -> 'AnyAngle':
"""
计算两个向量之间的夹角。
Args:
other: 另一个向量
Returns:
夹角
"""
return AnyAngle(math.acos(self @ other / (self.length * other.length)), is_radian=True)
```
</details>
### *method* `cross(self, other: Vector3) -> Vector3`
向量积 叉乘：v1 cross v2 -> v3
叉乘为0，则两向量平行。
其余结果的模为平行四边形的面积。
**變數説明**:
- other:
**返回**:
- 行列式的结果
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `is_approx_parallel(self, other: Vector3, epsilon: float = APPROX) -> bool`
判断两个向量是否近似平行。
**變數説明**:
- other: 另一个向量
- epsilon: 允许的误差
**返回**:
- 是否近似平行
<details>
<summary> <i>源碼</i> </summary>
```python
def is_approx_parallel(self, other: 'Vector3', epsilon: float=APPROX) -> bool:
"""
判断两个向量是否近似平行。
Args:
other: 另一个向量
epsilon: 允许的误差
Returns:
是否近似平行
"""
return self.cross(other).length < epsilon
```
</details>
### *method* `is_parallel(self, other: Vector3) -> bool`
判断两个向量是否平行。
**變數説明**:
- other: 另一个向量
**返回**:
- 是否平行
<details>
<summary> <i>源碼</i> </summary>
```python
def is_parallel(self, other: 'Vector3') -> bool:
"""
判断两个向量是否平行。
Args:
other: 另一个向量
Returns:
是否平行
"""
return self.cross(other).approx(zero_vector3)
```
</details>
### *method* `normalize(self)`
将向量归一化。
自体归一化，不返回值。
<details>
<summary> <i>源碼</i> </summary>
```python
def normalize(self):
"""
将向量归一化。
自体归一化，不返回值。
"""
length = self.length
self.x /= length
self.y /= length
self.z /= length
```
</details>
### `@property`
### *method* `np_array(self) -> np.ndarray`
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def np_array(self) -> 'np.ndarray':
"""
返回numpy数组
Returns:
"""
return np.array([self.x, self.y, self.z])
```
</details>
### `@property`
### *method* `length(self) -> float`
向量的模。
**返回**:
- 模
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def length(self) -> float:
"""
向量的模。
Returns:
模
"""
return math.sqrt(self.x ** 2 + self.y ** 2 + self.z ** 2)
```
</details>
### `@property`
### *method* `unit(self) -> Vector3`
获取该向量的单位向量。
**返回**:
- 单位向量
<details>
<summary> <i>源碼</i> </summary>
```python
@property
def unit(self) -> 'Vector3':
"""
获取该向量的单位向量。
Returns:
单位向量
"""
return self / self.length
```
</details>
### *method* `__abs__(self)`
<details>
<summary> <i>源碼</i> </summary>
```python
def __abs__(self):
return self.length
```
</details>
### `@overload`
### *method* `self + other: Vector3 => Vector3`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __add__(self, other: 'Vector3') -> 'Vector3':
...
```
</details>
### `@overload`
### *method* `self + other: Point3 => Point3`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __add__(self, other: 'Point3') -> 'Point3':
...
```
</details>
### *method* `self + other`
V + P -> P
V + V -> V
**變數説明**:
- other:
<details>
<summary> <i>源碼</i> </summary>
```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)}'")
```
</details>
### *method* `__eq__(self, other)`
判断两个向量是否相等。
**變數説明**:
- other:
**返回**:
- 是否相等
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### *method* `self + other: Point3 => Point3`
P + V -> P
别去点那边实现了。
:param other:
:return:
<details>
<summary> <i>源碼</i> </summary>
```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)
```
</details>
### `@overload`
### *method* `self - other: Vector3 => Vector3`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __sub__(self, other: 'Vector3') -> 'Vector3':
...
```
</details>
### `@overload`
### *method* `self - other: Point3 => Point3`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __sub__(self, other: 'Point3') -> 'Point3':
...
```
</details>
### *method* `self - other`
V - P -> P
V - V -> V
**變數説明**:
- other:
<details>
<summary> <i>源碼</i> </summary>
```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)}"')
```
</details>
### *method* `self - other: Point3`
P - V -> P
**變數説明**:
- other:
<details>
<summary> <i>源碼</i> </summary>
```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'")
```
</details>
### `@overload`
### *method* `self * other: Vector3 => Vector3`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __mul__(self, other: 'Vector3') -> 'Vector3':
...
```
</details>
### `@overload`
### *method* `self * other: RealNumber => Vector3`
<details>
<summary> <i>源碼</i> </summary>
```python
@overload
def __mul__(self, other: RealNumber) -> 'Vector3':
...
```
</details>
### *method* `self * other: int | float | Vector3 => Vector3`
数组运算 非点乘。点乘使用@，叉乘使用cross。
**變數説明**:
- other:
<details>
<summary> <i>源碼</i> </summary>
```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)}'")
```
</details>
### *method* `self * other: RealNumber => Vector3`
<details>
<summary> <i>源碼</i> </summary>
```python
def __rmul__(self, other: 'RealNumber') -> 'Vector3':
return self.__mul__(other)
```
</details>
### *method* `self @ other: Vector3 => RealNumber`
点乘。
**變數説明**:
- other:
<details>
<summary> <i>源碼</i> </summary>
```python
def __matmul__(self, other: 'Vector3') -> 'RealNumber':
"""
点乘。
Args:
other:
Returns:
"""
return self.x * other.x + self.y * other.y + self.z * other.z
```
</details>
### *method* `self / other: RealNumber => Vector3`
<details>
<summary> <i>源碼</i> </summary>
```python
def __truediv__(self, other: RealNumber) -> 'Vector3':
return Vector3(self.x / other, self.y / other, self.z / other)
```
</details>
### *method* `- self`
<details>
<summary> <i>源碼</i> </summary>
```python
def __neg__(self):
return Vector3(-self.x, -self.y, -self.z)
```
</details>
### ***var*** `zero_vector3 = Vector3(0, 0, 0)`
- **類型**: `Vector3`
- **説明**: 零向量
### ***var*** `x_axis = Vector3(1, 0, 0)`
- **類型**: `Vector3`
- **説明**: x轴单位向量
### ***var*** `y_axis = Vector3(0, 1, 0)`
- **類型**: `Vector3`
- **説明**: y轴单位向量
### ***var*** `z_axis = Vector3(0, 0, 1)`
- **類型**: `Vector3`
- **説明**: z轴单位向量

3
docs/zht/api/particle/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.particle
---

3
docs/zht/api/presets/index.md Normal file
View File

@ -0,0 +1,3 @@
---
title: mbcp.presets
---

47
docs/zht/api/presets/model/index.md Normal file
View File

@ -0,0 +1,47 @@
---
title: mbcp.presets.model
---
### **class** `GeometricModels`
### `@staticmethod`
### *method* `sphere(radius: float, density: float)`
生成球体上的点集。
**變數説明**:
- radius:
- density:
**返回**:
- List[Point3]: 球体上的点集。
<details>
<summary> <i>源碼</i> </summary>
```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)]
```
</details>

0
liteyuki_autodoc/__init__.py → litedoc/__init__.py
View File

2
liteyuki_autodoc/__main__.py → litedoc/__main__.py
View File

@ -18,7 +18,7 @@ import argparse
import os
import sys
from liteyuki_autodoc.output import generate_from_module
from litedoc.output import generate_from_module
def main():

0
liteyuki_autodoc/docstring/__init__.py → litedoc/docstring/__init__.py
View File

14
liteyuki_autodoc/docstring/docstring.py → litedoc/docstring/docstring.py
View File

@ -12,7 +12,7 @@ from typing import Optional
from pydantic import BaseModel, Field
from liteyuki_autodoc.i18n import get_text
from litedoc.i18n import get_text
class Attr(BaseModel):
@ -126,24 +126,24 @@ class Docstring(BaseModel):
# print(self.reduction())
# print(self.desc, self.return_)
if self.args:
ret += PREFIX + f"{get_text(lang, 'docstring.args')}:\n\n"
ret += PREFIX + f"**{get_text(lang, 'docstring.args')}**:\n\n"
for arg in self.args:
ret += PREFIX + f"- {arg.name}: {arg.type} {arg.desc}\n\n"
if self.attrs:
ret += PREFIX + f"{get_text(lang, 'docstring.attrs')}:\n\n"
ret += PREFIX + f"**{get_text(lang, 'docstring.attrs')}**:\n\n"
for attr in self.attrs:
ret += PREFIX + f"- {attr.name}: {attr.type} {attr.desc}\n\n"
if self.return_ is not None:
ret += PREFIX + f"{get_text(lang, 'docstring.return')}:\n\n"
ret += PREFIX + f"**{get_text(lang, 'docstring.return')}**:\n\n"
ret += PREFIX + f"- {self.return_.desc}\n\n"
if self.raise_:
ret += PREFIX + f"{get_text(lang, 'docstring.raises')}:\n\n"
ret += PREFIX + f"**{get_text(lang, 'docstring.raises')}**:\n\n"
for exception in self.raise_:
ret += PREFIX + f"- {exception.name} {exception.desc}\n\n"
if self.example:
ret += PREFIX + f"{get_text(lang, 'docstring.example')}:\n\n"
ret += PREFIX + f"**{get_text(lang, 'docstring.example')}**:\n\n"
for example in self.example:
ret += PREFIX + f"- {example.desc}\n Input: {example.input}\n Output: {example.output}\n\n"
ret += PREFIX + f"- {example.desc}\n **{get_text(lang, 'docs.input')}**: {example.input}\n **{get_text(lang, 'docs.output')}**: {example.output}\n\n"
return ret
def __str__(self):

43
liteyuki_autodoc/docstring/parser.py → litedoc/docstring/parser.py
View File

@ -3,7 +3,7 @@ Google docstring parser for Python.
"""
from typing import Optional
from liteyuki_autodoc.docstring.docstring import Docstring
from litedoc.docstring.docstring import Docstring
class Parser:
@ -52,10 +52,30 @@ class GoogleDocstringParser(Parser):
self.docstring = Docstring()
def read_line(self, move: bool = True) -> str:
"""
每次读取一行
Args:
move: 是否移动指针
Returns:
"""
if self.lineno >= len(self.lines):
return ""
line = self.lines[self.lineno]
if move:
self.lineno += 1
return line
def match_token(self) -> Optional[str]:
"""
解析下一行的token
Returns:
"""
for token in self._tokens:
if self.lines[self.lineno][self.char:].startswith(token):
self.char += len(token)
line = self.read_line(move=False)
if line.strip().startswith(token):
self.lineno += 1
return self._tokens[token]
return None
@ -115,17 +135,12 @@ class GoogleDocstringParser(Parser):
在一个子解析器中，解析下一行，直到缩进小于等于当前行的缩进
Returns:
"""
while (self.lineno + 1) < len(self.lines):
line = self.lines[self.lineno + 1]
if line.startswith(" " * self.indent):
line = line[self.indent:]
self.lineno += 1
return line
else:
self.lineno += 1
return None
self.lineno += 1
return None
line = self.read_line(move=False)
if line.startswith(" " * self.indent):
self.lineno += 1
return line[self.indent:]
else:
return None
def parse(self) -> Docstring:
"""

18
liteyuki_autodoc/i18n.py → litedoc/i18n.py
View File

@ -9,7 +9,7 @@ NestedDict: TypeAlias = dict[str, 'str | NestedDict']
i18n_dict: dict[str, NestedDict] = {
"en" : {
"docstring": {
"args" : "Args",
"args" : "Arguments",
"return" : "Return",
"attribute": "Attribute",
"raises" : "Raises",
@ -17,6 +17,8 @@ i18n_dict: dict[str, NestedDict] = {
"yields" : "Yields",
},
"src": "Source code",
"desc": "Description",
"type": "Type",
},
"zh-Hans": {
"docstring": {
@ -27,18 +29,22 @@ i18n_dict: dict[str, NestedDict] = {
"example" : "示例",
"yields" : "产出",
},
"src": "源码",
"src": "源代码",
"desc": "说明",
"type": "类型",
},
"zh-Hant": {
"docstring": {
"args" : "參數",
"args" : "變數説明",
"return" : "返回",
"attribute": "屬性",
"raises" : "引發",
"example" : "示例",
"raises" : "抛出",
"example" : "範例",
"yields" : "產出",
},
"src": "源碼",
"desc": "説明",
"type": "類型",
},
"ja" : {
"docstring": {
@ -50,6 +56,8 @@ i18n_dict: dict[str, NestedDict] = {
"yields" : "生成",
},
"src": "ソースコード",
"desc": "説明",
"type": "タイプ",
},
}

4
liteyuki_autodoc/output.py → litedoc/output.py
View File

@ -10,8 +10,8 @@ Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
"""
import os.path
from liteyuki_autodoc.style.markdown import generate
from liteyuki_autodoc.syntax.astparser import AstParser
from litedoc.style.markdown import generate
from litedoc.syntax.astparser import AstParser
def write_to_file(content: str, output: str) -> None:

0
liteyuki_autodoc/style/__init__.py → litedoc/style/__init__.py
View File

32
liteyuki_autodoc/style/markdown.py → litedoc/style/markdown.py
View File

@ -10,9 +10,9 @@ Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
"""
from typing import Optional
from liteyuki_autodoc.syntax.astparser import AstParser
from liteyuki_autodoc.syntax.node import *
from liteyuki_autodoc.i18n import get_text
from litedoc.syntax.astparser import AstParser
from litedoc.syntax.node import *
from litedoc.i18n import get_text
def generate(parser: AstParser, lang: str, frontmatter: Optional[dict] = None) -> str:
@ -36,24 +36,24 @@ def generate(parser: AstParser, lang: str, frontmatter: Optional[dict] = None) -
# var > func > class
"""遍历函数"""
for func in parser.functions:
if func.name.startswith("_"):
continue
md += func.markdown(lang)
"""遍历类"""
for cls in parser.classes:
md += f"### ***class*** `{cls.name}`\n\n"
for mtd in cls.methods:
md += mtd.markdown(lang, 2, True)
for attr in cls.attrs:
if attr.type == TypeHint.NO_TYPEHINT:
md += f"#### ***attr*** `{attr.name} = {attr.value}`\n\n"
else:
md += f"#### ***attr*** `{attr.name}: {attr.type} = {attr.value}`\n\n"
md += cls.markdown(lang)
"""遍历变量"""
for var in parser.variables:
if var.type == TypeHint.NO_TYPEHINT:
md += f"### ***var*** `{var.name} = {var.value}`\n\n"
else:
md += f"### ***var*** `{var.name}: {var.type} = {var.value}`\n\n"
md += f"### ***var*** `{var.name} = {var.value}`\n\n"
if var.type != TypeHint.NO_TYPEHINT:
md += f"- **{get_text(lang, 'type')}**: `{var.type}`\n\n"
if var.docs is not None:
md += f"- **{get_text(lang, 'desc')}**: {var.docs}\n\n"
return md

135
liteyuki_autodoc/syntax/astparser.py → litedoc/syntax/astparser.py
View File

@ -9,11 +9,11 @@ Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Software: PyCharm
"""
import ast
import inspect
from .node import *
from ..docstring.parser import parse
class AstParser:
def __init__(self, code: str):
self.code = code
@ -25,6 +25,51 @@ class AstParser:
self.parse()
@staticmethod
def clear_quotes(s: str) -> str:
"""
去除类型注解中的引号
Args:
s:
Returns:
"""
return s.replace("'", "").replace('"', "")
def get_line_content(self, lineno: int, ignore_index_out: bool = True) -> str:
"""获取代码行内容
Args:
lineno: 行号
ignore_index_out: 是否忽略索引越界
Returns:
代码行内容
"""
if ignore_index_out:
if lineno < 1 or lineno > len(self.code.split("\n")):
return ""
return self.code.split("\n")[lineno - 1]
@staticmethod
def match_line_docs(linecontent: str) -> str:
"""匹配行内注释
Args:
linecontent: 行内容
Returns:
文档字符串
"""
in_string = False
string_char = ''
for i, char in enumerate(linecontent):
if char in ('"', "'"):
if in_string:
if char == string_char:
in_string = False
else:
in_string = True
string_char = char
elif char == '#' and not in_string:
return linecontent[i + 1:].strip()
return ""
def parse(self):
for node in ast.walk(self.tree):
if isinstance(node, ast.ClassDef):
@ -47,21 +92,21 @@ class AstParser:
posonlyargs=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in sub_node.args.posonlyargs
],
args=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in sub_node.args.args
],
kwonlyargs=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in sub_node.args.kwonlyargs
],
@ -77,26 +122,27 @@ class AstParser:
)
for default in sub_node.args.defaults
],
return_=ast.unparse(sub_node.returns).strip() if sub_node.returns else TypeHint.NO_RETURN,
return_=self.clear_quotes(ast.unparse(sub_node.returns).strip()) if sub_node.returns else TypeHint.NO_RETURN,
decorators=[ast.unparse(decorator).strip() for decorator in sub_node.decorator_list],
is_async=isinstance(sub_node, ast.AsyncFunctionDef),
src=ast.unparse(sub_node).strip()
src=ast.unparse(sub_node).strip(),
is_classmethod=True
))
elif isinstance(sub_node, (ast.Assign, ast.AnnAssign)):
if isinstance(sub_node, ast.Assign):
class_node.attrs.append(AttrNode(
name=sub_node.targets[0].id, # type: ignore
type=TypeHint.NO_TYPEHINT,
value=ast.unparse(sub_node.value).strip()
))
elif isinstance(sub_node, ast.AnnAssign):
class_node.attrs.append(AttrNode(
name=sub_node.target.id,
type=ast.unparse(sub_node.annotation).strip(),
value=ast.unparse(sub_node.value).strip() if sub_node.value else TypeHint.NO_DEFAULT
))
else:
raise ValueError(f"Unsupported node type: {type(sub_node)}")
# elif isinstance(sub_node, (ast.Assign, ast.AnnAssign)):
# if isinstance(sub_node, ast.Assign):
# class_node.attrs.append(AttrNode(
# name=sub_node.targets[0].id, # type: ignore
# type=TypeHint.NO_TYPEHINT,
# value=ast.unparse(sub_node.value).strip()
# ))
# elif isinstance(sub_node, ast.AnnAssign):
# class_node.attrs.append(AttrNode(
# name=sub_node.target.id,
# type=ast.unparse(sub_node.annotation).strip(),
# value=ast.unparse(sub_node.value).strip() if sub_node.value else TypeHint.NO_DEFAULT
# ))
# else:
# raise ValueError(f"Unsupported node type: {type(sub_node)}")
elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
# 仅打印模块级别的函数
@ -109,21 +155,21 @@ class AstParser:
posonlyargs=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in node.args.posonlyargs
],
args=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg, default in zip(node.args.args, node.args.defaults)
],
kwonlyargs=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in node.args.kwonlyargs
],
@ -139,7 +185,7 @@ class AstParser:
)
for default in node.args.defaults
],
return_=ast.unparse(node.returns).strip() if node.returns else TypeHint.NO_RETURN,
return_=self.clear_quotes(ast.unparse(node.returns).strip()) if node.returns else TypeHint.NO_RETURN,
decorators=[ast.unparse(decorator).strip() for decorator in node.decorator_list],
is_async=isinstance(node, ast.AsyncFunctionDef),
src=ast.unparse(node).strip()
@ -147,23 +193,40 @@ class AstParser:
elif isinstance(node, (ast.Assign, ast.AnnAssign)):
if not self._is_module_level_variable2(node):
# print("变量不在模块级别", ast.unparse(node))
continue
else:
pass
if isinstance(node, ast.Assign):
for target in node.targets:
if isinstance(target, ast.Name):
self.variables.append(AssignNode(
name=target.id,
value=ast.unparse(node.value).strip(),
type=ast.unparse(node.annotation).strip() if isinstance(node, ast.AnnAssign) else TypeHint.NO_TYPEHINT
))
elif isinstance(node, ast.AnnAssign):
lineno = node.lineno
prev_line = self.get_line_content(lineno - 1).strip()
curr_line = self.get_line_content(lineno).strip()
next_line = self.get_line_content(lineno + 1).strip()
# 获取文档字符串，优先检测下行"""
if next_line.startswith('"""'):
docs = next_line[3:-3]
elif prev_line.startswith('"""'):
docs = prev_line[3:-3]
else:
curr_docs = self.match_line_docs(curr_line)
if curr_docs:
docs = curr_docs
else:
docs = None
# if isinstance(node, ast.Assign):
# for target in node.targets:
# if isinstance(target, ast.Name):
# self.variables.append(AssignNode(
# name=target.id,
# value=ast.unparse(node.value).strip(),
# type=ast.unparse(node.annotation).strip() if isinstance(node, ast.AnnAssign) else TypeHint.NO_TYPEHINT
# ))
if isinstance(node, ast.AnnAssign):
self.variables.append(AssignNode(
name=node.target.id,
value=ast.unparse(node.value).strip() if node.value else TypeHint.NO_DEFAULT,
type=ast.unparse(node.annotation).strip()
type=ast.unparse(node.annotation).strip(),
docs=docs
))
def _is_module_level_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef):

89
liteyuki_autodoc/syntax/node.py → litedoc/syntax/node.py
View File

@ -13,8 +13,8 @@ from enum import Enum
from pydantic import BaseModel, Field
from liteyuki_autodoc.docstring.docstring import Docstring
from liteyuki_autodoc.i18n import get_text
from litedoc.docstring.docstring import Docstring
from litedoc.i18n import get_text
class TypeHint:
@ -37,6 +37,7 @@ class AssignNode(BaseModel):
name: str
type: str = ""
value: str
docs: Optional[str] = ""
class ArgNode(BaseModel):
@ -123,6 +124,22 @@ class FunctionNode(BaseModel):
decorators: list[str] = []
src: str
is_async: bool = False
is_classmethod: bool = False
magic_methods: dict[str, str] = {
"__add__" : "+",
"__radd__" : "+",
"__sub__" : "-",
"__rsub__" : "-",
"__mul__" : "*",
"__rmul__" : "*",
"__matmul__" : "@",
"__rmatmul__": "@",
"__mod__" : "%",
"__truediv__": "/",
"__rtruediv__": "/",
"__neg__" : "-",
} # 魔术方法, 例如运算符
def is_private(self):
"""
@ -140,12 +157,11 @@ class FunctionNode(BaseModel):
"""
return self.name.startswith("__") and self.name.endswith("__")
def markdown(self, lang: str, indent: int = 0, is_classmethod: bool = False) -> str:
def markdown(self, lang: str, indent: int = 0) -> str:
"""
Args:
indent: int
The number of spaces to indent the markdown.
is_classmethod: bool
lang: str
The language of the
Returns:
@ -155,21 +171,20 @@ class FunctionNode(BaseModel):
PREFIX = "" * indent
# if is_classmethod:
# PREFIX = "- #"
func_type = "func" if not self.is_classmethod else "method"
md = ""
# 装饰器部分
if len(self.decorators) > 0:
for decorator in self.decorators:
md += PREFIX + f"### `@{decorator}`\n"
if self.is_async:
md += PREFIX + "### *async def* "
md += PREFIX + f"### *async {func_type}* "
else:
md += PREFIX + "### *def* "
md += f"`{self.name}(" # code start
md += PREFIX + f"### *{func_type}* "
# code start
# 配对位置参数和位置参数默认值，无默认值用TypeHint.NO_DEFAULT
args: list[str] = [] # 可直接", ".join(args)得到位置参数部分
arg_i = 0
@ -204,25 +219,33 @@ class FunctionNode(BaseModel):
arg_text = f"{arg.name}"
if arg.type != TypeHint.NO_TYPEHINT:
arg_text += f": {arg.type}"
if kw_default.value != TypeHint.NO_DEFAULT:
arg_text += f" = {kw_default.value}"
args.append(arg_text)
md += ", ".join(args) + ")"
if self.return_ != TypeHint.NO_RETURN:
md += f" -> {self.return_}"
"""魔法方法"""
if self.name in self.magic_methods:
if len(args) == 2:
md += f"`{args[0]} {self.magic_methods[self.name]} {args[1]}"
elif len(args) == 1:
md += f"`{self.magic_methods[self.name]} {args[0]}"
if self.return_ != TypeHint.NO_RETURN:
md += f" => {self.return_}"
else:
md += f"`{self.name}(" # code start
md += ", ".join(args) + ")"
if self.return_ != TypeHint.NO_RETURN:
md += f" -> {self.return_}"
md += "`\n\n" # code end
"""此处预留docstring"""
if self.docs is not None:
md += f"\n{self.docs.markdown(lang, indent, is_classmethod)}\n"
md += f"\n{self.docs.markdown(lang, indent)}\n"
else:
pass
# 源码展示
md += PREFIX + f"\n<details>\n<summary>{get_text(lang, 'src')}</summary>\n\n```python\n{self.src}\n```\n</details>\n\n"
md += PREFIX + f"\n<details>\n<summary> <i>{get_text(lang, 'src')}</i> </summary>\n\n```python\n{self.src}\n```\n</details>\n\n"
return md
@ -251,11 +274,41 @@ class ClassNode(BaseModel):
The attributes of the class.
methods: list[MethodNode] = []
The methods of the class.
inherit: list["ClassNode"] = []
inherits: list["ClassNode"] = []
The classes that the class inherits from
"""
name: str
docs: Optional[Docstring] = None
attrs: list[AttrNode] = []
methods: list[FunctionNode] = []
inherit: list["ClassNode"] = []
inherits: list[str] = []
def markdown(self, lang: str) -> str:
"""
返回类的markdown文档
Args:
lang: str
The language of the
Returns:
markdown style document
"""
hidden_methods = [
"__str__",
"__repr__",
]
md = ""
md += f"### **class** `{self.name}"
if len(self.inherits) > 0:
md += f"({', '.join([cls for cls in self.inherits])})"
md += "`\n"
for method in self.methods:
if method.name in hidden_methods:
continue
md += method.markdown(lang, 2)
for attr in self.attrs:
if attr.type == TypeHint.NO_TYPEHINT:
md += f"#### ***attr*** `{attr.name} = {attr.value}`\n\n"
else:
md += f"#### ***attr*** `{attr.name}: {attr.type} = {attr.value}`\n\n"
return md

47
litedoc/translator.py Normal file
View File

@ -0,0 +1,47 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/29 下午12:02
@Author : snowykami
@Email : snowykami@outlook.com
@File : translator.py
@Software: PyCharm
"""
from typing import Optional
from translate import Translator # type: ignore
# 特殊映射语言
i18n_lang2googletrans_lang = {
"zh-Hans": "zh-cn",
"zh-Hant": "zh-tw",
"en" : "en",
}
def get_google_lang(lang: str) -> str:
"""
Get google translate language
Args:
lang: language
Returns:
google translate language
"""
return i18n_lang2googletrans_lang.get(lang, lang)
def translate(text: str, lang: str, source_lang: str) -> str:
"""
Translate text to target language
Args:
source_lang:
text: text
lang: target language
Returns:
translated text
"""
if lang == source_lang:
return text
google_lang = get_google_lang(lang)
return Translator(to_lang=google_lang, from_lang=source_lang).translate(text)

20
mbcp/mp_math/plane.py
View File

@ -22,10 +22,10 @@ class Plane3:
"""
平面方程：ax + by + cz + d = 0
Args:
a:
b:
c:
d:
a: x系数
b: y系数
c: z系数
d: 常数项
"""
self.a = a
self.b = b
@ -36,13 +36,10 @@ class Plane3:
"""
判断两个平面是否近似相等。
Args:
other:
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)
@ -91,11 +88,11 @@ class Plane3:
def cal_intersection_line3(self, other: 'Plane3') -> 'Line3':
"""
计算两平面的交线。该方法有问题，待修复。
计算两平面的交线。
Args:
other: 另一个平面
Returns:
交线
两平面的交线
Raises:
"""
if self.normal.is_parallel(other.normal):
@ -105,6 +102,7 @@ class Plane3:
x, y, z = 0, 0, 0
# 依次判断条件假设x=0, y=0, 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])
@ -146,7 +144,7 @@ class Plane3:
Args:
point: 指定点
Returns:
平面
所求平面
"""
return Plane3.from_point_and_normal(point, self.normal)

16
mbcp/mp_math/utils.py
View File

@ -22,11 +22,11 @@ if TYPE_CHECKING:
def clamp(x: float, min_: float, max_: float) -> float:
"""
区间截断函数。
区间限定函数
Args:
x:
min_:
max_:
x: 待限定的值
min_: 最小值
max_: 最大值
Returns:
限制后的值
@ -40,7 +40,6 @@ class Approx:
已实现对象 实数 Vector3 Point3 Plane3 Line3
"""
def __init__(self, value: RealNumber):
self.value = value
@ -67,10 +66,9 @@ def approx(x: float, y: float = 0.0, epsilon: float = APPROX) -> bool:
"""
判断两个数是否近似相等。或包装一个实数，用于判断是否近似于0。
Args:
x:
y:
epsilon:
x: 数1
y: 数2
epsilon: 误差
Returns:
是否近似相等
"""

8
mbcp/mp_math/vector.py
View File

@ -263,11 +263,11 @@ class Vector3:
return f"Vector3({self.x}, {self.y}, {self.z})"
zero_vector3 = Vector3(0, 0, 0)
zero_vector3: Vector3 = Vector3(0, 0, 0)
"""零向量"""
x_axis = Vector3(1, 0, 0)
x_axis: Vector3 = Vector3(1, 0, 0)
"""x轴单位向量"""
y_axis = Vector3(0, 1, 0)
y_axis: Vector3 = Vector3(0, 1, 0)
"""y轴单位向量"""
z_axis = Vector3(0, 0, 1)
z_axis: Vector3 = Vector3(0, 0, 1)
"""z轴单位向量"""

4
mkdoc.bat Normal file
View File

@ -0,0 +1,4 @@
python -m litedoc mbcp -o docs/api -l zh-Hans
python -m litedoc mbcp -o docs/en/api -l en
python -m litedoc mbcp -o docs/ja/api -l ja
python -m litedoc mbcp -o docs/zht/api -l zh-Hant

5
pyproject.toml
View File

@ -21,3 +21,8 @@ build-backend = "pdm.backend"
[tool.pdm]
distribution = true
[tool.pdm.dev-dependencies]
dev = [
"translate>=3.6.1",
]

16
tests/test_doc_translator.py Normal file
View File

@ -0,0 +1,16 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/29 下午12:06
@Author : snowykami
@Email : snowykami@outlook.com
@File : test_doc_translator.py
@Software: PyCharm
"""
from litedoc.translator import translate
def test():
print(translate("Hello, world!", "Chinese", "English"))