Metadata-Version: 2.4
Name: sindre_bind
Version: 1.0.0
Summary: Python与C++混合编程库 - 整合高性能C++模块的Python绑定
Home-page: https://github.com/sindre/sindre_bind
Author: Sindre
Author-email: Sindre <yx@mviai.com>
License: MIT
Project-URL: Homepage, https://github.com/sindre/sindre_bind
Project-URL: Documentation, https://github.com/sindre/sindre_bind#readme
Project-URL: Repository, https://github.com/sindre/sindre_bind.git
Project-URL: Bug Tracker, https://github.com/sindre/sindre_bind/issues
Keywords: C++,Python,binding,pybind11,MeshFix,GCO,Graph Cut
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.8.2
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=3.9; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Provides-Extra: build
Requires-Dist: cmake>=3.15; extra == "build"
Requires-Dist: pybind11>=2.6.0; extra == "build"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# sindre_bind

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

![Python Version](https://img.shields.io/badge/Python-3.12%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Status](https://img.shields.io/badge/Status-Active-brightgreen)

## 📋 概述

**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

```python
from sindre_bind import MeshFix

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

### 2. **PyAICrypto** - AI密码学库

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

```python
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. **克隆或下载项目**

```bash
git clone <repository-url>
cd sindre_bind
```

2. **创建构建目录**

```bash
mkdir build
cd build
```

3. **配置和编译**

**Windows (PowerShell/CMD):**
```bash
cmake -G "Visual Studio 16 2019" -A x64 ..
cmake --build . --config Release
```

**Linux:**
```bash
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 源代码

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

#### AI_Crypto 源代码

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

## 💻 使用示例

### 基本使用

```python
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 示例

```python
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 示例

```python
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. **未知异常** - 未预期的异常会被安全捕获

```python
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
bash scripts/build.sh
```

**Windows (PowerShell):**
```powershell
.\scripts\build.bat
```

### 手动编译

```bash
# 创建构建目录
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）:**
```bash
python scripts/upload_pypi.py test
```

**正式版本（PyPI）:**
```bash
python scripts/upload_pypi.py
```

或使用脚本：

**Linux/macOS:**
```bash
bash scripts/upload_pypi.sh
```

**Windows (PowerShell):**
```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=...` 指定路径 |

### 导入错误

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

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

## 📄 许可证

MIT License

## 👨‍💼 作者

- **Sindre** - yx@mviai.com

## 🤝 贡献

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

## ⚠️ 免责声明

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

---

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