117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
# MeshKernelPy 中文文档
|
||
|
||
[](https://sonarcloud.io/dashboard?id=Deltares_MeshKernelPy)
|
||
[](https://badge.fury.io/py/meshkernel)
|
||
|
||
`MeshKernelPy` 是用于创建和编辑网格的 Python 库，支持一维和二维非结构网格。其底层 C++ 库为 [MeshKernel](https://github.com/Deltares/MeshKernel)。
|
||
|
||
## 文档导航
|
||
|
||
- [示例教程：全部 15 个中文网页](examples/index.md)
|
||
- [完整 API 参考：类、方法、参数与枚举](api/modules.md)
|
||
|
||
本中文文档的示例译自本地 `MeshKernelPy-main/docs`，API 说明依据对应 `meshkernel` 源码完整整理，源码版本为 **8.3.0**。示例代码和命令按源文件保留；页面图片使用本地资源，绘图来自原笔记本已保存的输出。
|
||
|
||
## 安装
|
||
|
||
执行以下命令，从 [PyPI](https://pypi.org/project/meshkernel/) 安装：
|
||
|
||
```bash
|
||
pip install meshkernel
|
||
```
|
||
|
||
在 Windows 上，如果通过 pip 安装 wheel 后导入库时出现问题，可能需要安装 [Visual Studio 2019 的 Visual C++ 可再发行组件](https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170)。
|
||
|
||
## 功能示例
|
||
|
||
### 在多边形内部创建三角网格
|
||
|
||
本示例按期望的边长离散多边形边界，从而创建网格。
|
||
|
||
|
||
|
||
### 网格正交化
|
||
|
||
采用交错布置的有限体积流动求解器要求网格尽可能正交。MeshKernel 提供网格调整算法，使网格正交性与平滑性达到良好的平衡。
|
||
|
||
|
||
|
||
### 网格加密
|
||
|
||
可以根据采样数据或选定的多边形区域，对网格进行局部加密。
|
||
|
||
|
||
|
||
## 参与开发
|
||
|
||
要在本地安装 `MeshKernelPy`，请在虚拟环境中执行：
|
||
|
||
```bash
|
||
pip install -e ".[tests, lint, docs]"
|
||
```
|
||
|
||
然后将编译好的 `MeshKernelApi.dll` 放入 `src` 文件夹。
|
||
|
||
请将编辑器配置为使用 [black](https://black.readthedocs.io/en/stable/) 和 [isort](https://pycqa.github.io/isort/) 格式化代码。修改 Jupyter 笔记本时，可以使用 [jupyterlab-code-formatter](https://jupyterlab-code-formatter.readthedocs.io/en/latest/installation.html)。
|
||
|
||
## 构建并安装 wheel
|
||
|
||
### 按平台构建 {#platform-build}
|
||
|
||
项目提供了用于构建 wheel 的安装脚本，已知可在 Windows、Linux 和 macOS 上使用。
|
||
|
||
安装依赖：
|
||
|
||
```powershell
|
||
python -m pip install --upgrade pip
|
||
python -m pip install wheel numpy matplotlib pytest
|
||
```
|
||
|
||
构建 wheel 前，必须设置环境变量 `BACK_END_BRANCH`，以指定生成 wheel 时要构建的 [MeshKernel](https://github.com/Deltares/MeshKernel) 分支。按照源文档约定，若 MeshKernelPy 位于 `main` 分支，应将其设为 `master`；若位于发布分支，应设为 `release`。MeshKernel 发布分支的版本号硬编码在 `meshkernel/version.py` 中。
|
||
|
||
在项目根目录执行以下命令，构建 wheel：
|
||
|
||
```powershell
|
||
python setup.py build_ext
|
||
python setup.py sdist bdist_wheel
|
||
```
|
||
|
||
安装生成的 wheel：
|
||
|
||
```powershell
|
||
python -m pip install <meshkernel_wheel_name>
|
||
```
|
||
|
||
其中，`<meshkernel_wheel_name>` 为生成的 wheel 文件名。运行 `pytest` 即可进行测试。
|
||
|
||
### Manylinux Docker 镜像
|
||
|
||
为了向 PyPI 发布 Linux wheel，项目提供了基于 `manylinux_2_28_x86_64` 的 Docker 镜像。该镜像包含编译 C++ 原生 MeshKernel 库所需的 CMake 和 Boost。
|
||
|
||
使用以下命令构建 Docker 镜像：
|
||
|
||
```powershell
|
||
chmod +x scripts/compile_deps.sh
|
||
chmod +x scripts/build_deps.sh
|
||
docker build --progress=plain ./scripts -t build_linux_library
|
||
```
|
||
|
||
镜像构建完成后，使用以下命令构建 Linux wheel：
|
||
|
||
```powershell
|
||
docker run -e BACK_END_BRANCH=<meshkernel_back_end_branch_name> -v $(pwd):/root --rm build_linux_library
|
||
```
|
||
|
||
其中，`<meshkernel_back_end_branch_name>` 为 `master` 或 `release`，具体参见[按平台构建](#platform-build)。
|
||
|
||
可发布的 Linux wheel 位于 `dist/wheelhouse` 目录。
|
||
|
||
## 许可证
|
||
|
||
`MeshKernelPy` 使用 MIT 许可证，但 PyPI 上发布的 wheel 捆绑了采用 LGPL 许可证的 [MeshKernel](https://github.com/Deltares/MeshKernel)。使用前请确认这些许可证满足你的需求。
|
||
|
||
## 文档入口
|
||
|
||
- [中文示例教程](examples/index.md)
|
||
- [中文 API 参考](api/modules.md)
|