pycgal-tools-builder是一个用于将 C++ 实现的 3D 几何工具库封装为 Python 可调用安装包的项目

## PyCGAL-Tools-Package-Python-Project 🛠️ ### 简介 该项目的主要目的是将 **pycgal-tools-builder-msvc-project** 编译生成的动态链接库（**.DLL / .SO文件**）封装为一个 Python 可用的安装包。 <img src="https://mr-lai.oss-cn-zhangjiakou.aliyuncs.com/huaweimetabook/napkin-selection%20(5).png" alt="napkin-selection (5)" style="zoom: 33%;" /> ### 构建步骤 1. **准备依赖项**：确保 C++ 项目已成功编译，并且 DLL 文件位于 `pycgal/` 目录中。确认你已经安装了 `setuptools` 和 `wheel`。 2. **创建 Python 安装包**：在 `pycgal-tools-package-python-project/pycgal` 目录中运行以下命令： ``` python setup.py sdist bdist_wheel ``` 这将会在 `dist/` 目录下生成 `.tar.gz` 和 `.whl` 文件，这两个文件是最终发布的安装包格式。 3. **安装和测试**：你可以通过 `pip` 安装本地生成的 wheel 包，进行测试： ```cmd # 创建安装环境, 目前 MSVC 编译的DLL只能适配 Python==3.11.8 版本。 conda create -n pybind11env python=3.11.8 # 激活环境 conda activate pybind11env # 安装 pip install dist/pycgal-1.x.x-cp311-cp311-win_amd64.whl # 测试，能够成功输出版本即可 python >>> import pycgal >>> pycgal.get_version() >>> ```  ### 代码结构说明 ```python pycgal-tools-package-python-project │ ├── pycgal # 编译好的动态链接库 │ ├──__init__.py # Python层面 针对 C++接口进行封装 │ ├──pycgal.pyd │ ├──xxx.dll │ └── ... │ ├── setup.py # 构建Python包逻辑代码 ├── MANIFEST.in ├── LICENSE └── README.md ``` ### 接口说明 #### 1. 创建模块 (`_create`) 此模块提供了创建 2D 和 3D 几何体的接口，包括点、多边形、折线、三角形、面等。 - `get_version() -> str`: 获取当前库的版本信息。 - `create_point_2(x: float, y: float) -> Point_2`: 创建一个二维点。 - `create_point_3(x: float, y: float, z: float) -> Point_3`: 创建一个三维点。 - `create_polygon_2(points: List[Point_2]) -> Polygon_2`: 创建一个二维多边形。 - `create_polyline_3(points: List[Point_3]) -> Polyline_3`: 创建一条三维折线。 - `create_triangle_3(p1: Point_3, p2: Point_3, p3: Point_3) -> Triangle_3`: 创建一个三角形。 - `create_face(points: List[Point_3]) -> Face`: 创建一个面片。 - `face2triangles(face: Face) -> List[Triangle_3]`: 将一个面片拆分为多个三角形。 - `create_surface_mesh(vertices: List[Point_3], vertex_indexes: List[int], internal_point: Point_3 = None) -> Surface_mesh`: 创建表面网格。 - `create_polyhedron_by_faces(faces: List[Face], internal_point: Point_3 = None) -> Nef_polyhedron`: 通过面创建多面体。 - `create_polyhedron_by_triangles(triangles: List[Triangle_3], internal_point: Point_3 = None) -> Nef_polyhedron`: 通过三角形创建多面体。 - `create_nef_by_triangles(triangles: List[Triangle_3], internal_point: Point_3 = None) -> Nef_polyhedron`: 通过三角形创建 Nef 多面体。 - `polyhedron2nef(polyhedrons: Nef_polyhedron) -> Nef_polyhedron`: 将一个普通多面体转换为 Nef_polyhedron多面体。 - `nef2polyhedron(nef: Nef_polyhedron) -> Polyhedron`: 将 Nef_polyhedron多面体转换为普通多面体。 - `create_regular_cylinder(polygon: Polygon_2, z_min: float, height: float) -> Polyhedron`: 创建一个正柱体。 - `create_prism(bottom_poly: Polygon_2, top_poly: Polygon_2, z_min: float, height: float) -> Polyhedron`: 创建一个棱柱。 #### 2. 坐标转换模块 (`_converter`) 用于在地理坐标系和笛卡尔坐标系之间转换几何对象。 - `initialize_projection(ori_epsg: int = 4490, target_epsg: int = 4978) -> None`: 初始化投影转换系统。 - `transform_point_2(point: Point_2) -> Point_2`: 转换二维点的坐标。 - `transform_point_3(point: Point_3) -> Point_3`: 转换三维点的坐标。 - `transform_polygon_2(poly: Polygon_2) -> Polygon_2`: 转换二维多边形的坐标。 - `transform_segment_3(segment: Segment_3) -> Segment_3`: 转换三维线段的坐标。 - `transform_polyline_3(line: Polyline_3) -> Polyline_3`: 转换三维折线的坐标。 - `transform_triangle_3(triangle: Triangle_3) -> Triangle_3`: 转换三维三角形的坐标。 - `transform_face(face: Face) -> Face`: 转换面的坐标。 - `transform_surface_mesh(mesh: Surface_mesh) -> Surface_mesh`: 转换表面网格的坐标。 - `transform_polyhedron(polyhedron: Polyhedron) -> Polyhedron`: 转换多面体的坐标。 - `transform_nef(nef: Nef_polyhedron) -> Nef_polyhedron`: 转换 Nef_polyhedron 多面体的坐标。 - `cleanup_projection() -> None`: 清理投影转换系统。 #### 3. 可视化模块 (`_view`) 提供一个简单的可视化接口，支持加载几何体进行显示。 - `create_previewer() -> Previewer`: 创建一个预览器，用于几何体可视化。 - `load_polyhedron(viewer: Previewer, polyhedron: Polyhedron, rgba: Tuple[float, float, float, float]) -> None`: 加载并显示多面体。 - `load_surface_mesh(viewer: Previewer, mesh: Surface_mesh, rgba: Tuple[float, float, float, float]) -> None`: 加载并显示表面网格。 - `load_nef(viewer: Previewer, nef: Nef_polyhedron, rgba: Tuple[float, float, float, float]) -> None`: 加载并显示 Nef 多面体。 - `load_segments(viewer: Previewer, segments: List[Segment_3], rgba: Tuple[float, float, float, float]) -> None`: 加载并显示三维线段。 #### 4. 工具模块 (`_tools`) 包括几何体的操作和一些打印功能。 - `adjust_faces_for_polyhedron(faces: List[Face], internal_point: Point_3) -> List[Face]`: 调整多面体的面方向。 - `adjust_triangles_for_polyhedron(triangles: List[Triangle_3], internal_point: Point_3) -> List[Triangle_3]`: 调整多面体的三角形方向。 - `print_point_3(point: Point_3) -> List[float]`: 打印并返回点的坐标。 - `print_polyline_3(polyline: Polyline_3) -> List[List[float]]`: 打印并返回折线的坐标。 - `print_polyhedron(polyhedron: Polyhedron) -> Tuple[List[List[float]], List[List[int]]]`: 打印并返回多面体的顶点和面索引。 - `print_nef(nef_polyhedron: Nef_polyhedron) -> Tuple[List[List[float]], List[List[int]]]`: 打印并返回 Nef_polyhedron 多面体的顶点和面索引。 - `print_surface_mesh(mesh: Surface_mesh) -> Tuple[List[List[float]], List[List[int]]]`: 打印并返回表面网格的顶点和面索引。 - `calculate_bounding_box(geometry: Union[Polyline_3, Polyhedron, Nef_polyhedron, Surface_mesh]) -> List[Point_3]`: 计算几何体的边界框。 #### 5. 相交检测模块 (`_intersect`) 用于测试几何体之间的相交情况。 - `do_intersect(obj1: Union[Polyline_3, Polyhedron, Nef_polyhedron, Surface_mesh], obj2: Union[Polyline_3, Polyhedron, Nef_polyhedron, Surface_mesh]) -> bool`: 检测两个几何对象是否相交。 - `do_intersect_one_to_many(target: Union[Surface_mesh, Polyline_3, Nef_polyhedron, Polyhedron], objects: Union[List[Polyhedron], List[Nef_polyhedron]]) -> List[int]`: 检测一个复杂几何对象与多个简单几何体的相交情况。返回 1 表示相交，0 表示不相交。 ### 使用示例 1. **创建一个棱形体** ```python import pycgal # 创建 一个 上宽下窄的 棱形体, 这里要注意点的顺序，不能自相交，且底部和顶部的点的位置和数量要一致 b_p1 = pycgal.create_point_2(113.23, 23) b_p2 = pycgal.create_point_2(113.23, 23.28) b_p3 = pycgal.create_point_2(113.748, 23.28) b_p4 = pycgal.create_point_2(113.748, 23) t_p1 = pycgal.create_point_2(113.227, 22.4) t_p2 = pycgal.create_point_2(113.227, 23.48) t_p3 = pycgal.create_point_2(113.778, 23.48) t_p4 = pycgal.create_point_2(113.778, 22.4)