sindre-bind 1.0.0

Python与C++混合编程库 - 整合高性能C++模块的Python绑定

sindre_bind

Python与C++混合编程库 - 整合高性能C++模块的Python绑定

📋 概述

sindre_bind 是一个为Python开发者提供高性能C++库访问的Python包。通过pybind11和C扩展，我们将多个强大的C++库集成到Python生态中，同时提供了完善的异常处理机制，防止C++内部异常导致Python程序崩溃。

支持的系统和Python版本

• 操作系统:

  • Windows 10+ (x64)
  • Linux (x64)

• Python版本: 3.12+ （强制要求）

本库不支持其他操作系统或Python版本。

📦 包含的模块

1. PyMeshFix - 3D网格修复工具

用于修复不规范的3D网格模型，包括：

• 填补孔洞
• 清除自相交面
• 去除退化三角形
• 连接分离的网格成分

支持格式: STL, OBJ, PLY, OFF

from sindre_bind import MeshFix

status = MeshFix.mesh_fix("broken_model.stl", "fixed_model.stl", "stl")
print(status)  # 输出修复结果

2. PyAICrypto - AI密码学库

提供基于AI的密码学加密/解密功能：

from sindre_bind import AICrypto

# 加密
encrypted = AICrypto.convert(b"sensitive_data", "secret_key")

# 解密（使用相同密钥）
decrypted = AICrypto.convert(encrypted, "secret_key")

3. PyGCO - Graph Cut Optimization

用于图像分割等全局能量最小化问题（可选模块）

🚀 安装指南

从源代码编译

前置需求

• CMake >= 3.15
• Python 3.12 开发头文件 (python3.12-dev 或 Python 3.12 SDK)
• pybind11 (自动通过 pip 安装)
• NumPy 1.8.2+ (自动依赖)
• Visual Studio 2019+ (Windows) 或 GCC/Clang (Linux)

编译步骤

1. 克隆或下载项目

git clone <repository-url>
cd sindre_bind

2. 创建构建目录

mkdir build
cd build

3. 配置和编译

Windows (PowerShell/CMD):

cmake -G "Visual Studio 16 2019" -A x64 ..
cmake --build . --config Release

Linux:

cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

4. 编译输出

编译完成后，Python模块将输出到 outputs/sindre_bind/ 目录：

• PyMeshFix.pyd (Windows) 或 PyMeshFix.so (Linux)
• PyAICrypto.pyd (Windows) 或 PyAICrypto.so (Linux)
• PyGCO.pyd (Windows) 或 PyGCO.so (Linux)

添加可选的C++源代码

某些模块需要额外的C++源代码：

MeshFix 源代码

cmake -DMESHFIX_SOURCE_DIR=/path/to/meshfix/source ..
cmake --build .

AI_Crypto 源代码

cmake -DAI_CRYPTO_SOURCE_DIR=/path/to/ai_crypto/source ..
cmake --build .

💻 使用示例

基本使用

import sindre_bind
from sindre_bind import show_info, get_available_modules

# 显示包信息
show_info()

# 检查可用模块
modules = get_available_modules()
for name, available in modules.items():
    print(f"{name}: {'✓' if available else '✗'}")

MeshFix 示例

from sindre_bind import MeshFix

try:
    result = MeshFix.mesh_fix("input.stl", "output.stl", "stl")
    print(f"网格修复完成: {result}")
except Exception as e:
    print(f"错误: {e}")

AICrypto 示例

from sindre_bind import AICrypto

try:
    key = "my_secret_key_12345"
    data = b"important message"
    
    # 加密
    encrypted = AICrypto.convert(data, key)
    print(f"加密后长度: {len(encrypted)} 字节")
    
    # 解密
    decrypted = AICrypto.convert(encrypted, key)
    print(f"解密成功: {decrypted == data}")
    
except ValueError as e:
    print(f"参数错误: {e}")
except RuntimeError as e:
    print(f"处理错误: {e}")

🔒 异常处理

所有C++调用都经过异常包装，确保：

1. 参数验证 - 无效的输入参数会抛出 ValueError
2. 运行时异常 - C++异常会转换为 RuntimeError
3. 未知异常 - 未预期的异常会被安全捕获

from sindre_bind import MeshFix

try:
    MeshFix.mesh_fix("", "output.stl", "stl")  # 空文件名
except ValueError as e:
    print(f"输入无效: {e}")
except RuntimeError as e:
    print(f"执行失败: {e}")

📂 项目结构

sindre_bind/
├── CMakeLists.txt              # 主CMake配置
├── README.md                   # 本文件
├── include/
│   └── exception_wrapper.h     # 异常处理头文件
├── src/
│   ├── gco/                    # Graph Cut Optimization
│   ├── MeshFix/                # 网格修复模块
│   └── pybind_ai_crypto/       # AI密码学模块
├── outputs/
│   └── sindre_bind/
│       ├── __init__.py         # Python包初始化
│       ├── PyMeshFix.pyd/.so
│       ├── PyAICrypto.pyd/.so
│       └── PyGCO.pyd/.so       # 编译输出的Python模块
└── scripts/
    ├── build.sh/build.bat      # 一键编译脚本
    └── upload_pypi.sh/upload_pypi.bat  # PyPI上传脚本

🛠️ 开发和编译

一键编译（推荐）

Linux/macOS:

bash scripts/build.sh

Windows (PowerShell):

.\scripts\build.bat

手动编译

# 创建构建目录
mkdir -p build && cd build

# 配置
cmake -DCMAKE_BUILD_TYPE=Release ..

# 编译
cmake --build . --config Release

# 编译输出到 outputs/sindre_bind/

📤 上传到PyPI

准备

1. 创建 setup.py 和 pyproject.toml
2. 准备发行说明

上传

开发版本（测试PyPI）:

python scripts/upload_pypi.py test

正式版本（PyPI）:

python scripts/upload_pypi.py

或使用脚本：

Linux/macOS:

bash scripts/upload_pypi.sh

Windows (PowerShell):

.\scripts\upload_pypi.bat

📝 故障排除

编译错误

问题	解决方案
python3.12 未找到	安装 Python 3.12 或设置 PYTHON_EXECUTABLE
pybind11 未找到	运行 pip install pybind11
NumPy 版本不匹配	运行 pip install 'numpy>=1.8.2'
源代码路径错误	使用 -DMESHFIX_SOURCE_DIR=... 指定路径

导入错误

>>> import sindre_bind
警告: 无法导入模块 'PyMeshFix'

解决:

1. 确认编译已完成: ls outputs/sindre_bind/
2. 确认Python版本: python --version（应为 3.12+）
3. 重新编译: cd build && cmake --build .

📄 许可证

MIT License

👨‍💼 作者

• Sindre - [e-mail]

🤝 贡献

欢迎提交问题和改进建议！

⚠️ 免责声明

本库提供的C++模块可能包含第三方代码，请查看各模块的许可证。使用本库生成的输出数据时，请遵守所有适用的法律和许可协议。

---

最后更新: 2026年4月21日 版本: 1.0.0