# MeshKernelPy 文档 - 中文翻译

[![质量门禁状态](https://sonarcloud.io/api/project_badges/measure?project=Deltares_MeshKernelPy&metric=alert_status)](https://sonarcloud.io/dashboard?id=Deltares_MeshKernelPy)
[![PyPI 版本](https://badge.fury.io/py/meshkernel.svg)](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)。

## 功能示例

### 在多边形内部创建三角网格

本示例按期望的边长离散多边形边界，从而创建网格。

![在多边形内部生成的三角网格](images/TriangularMeshInPolygon.jpg)

### 网格正交化

采用交错布置的有限体积流动求解器要求网格尽可能正交。MeshKernel 提供网格调整算法，使网格正交性与平滑性达到良好的平衡。

![网格正交化效果](images/MeshOrthogonalization.jpg)

### 网格加密

可以根据采样数据或选定的多边形区域，对网格进行局部加密。

![网格局部加密效果](images/GridRefinement.jpg)

## 参与开发

要在本地安装 `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

### 按平台构建

项目提供了用于构建 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)