sindre 2026.4.24

自用脚本库

Sindre - 多功能Python工具库

一个集成了LMDB数据库、3D处理、报告生成、部署工具等多种功能的Python工具库

📖 完整API文档

2026年4月后版本只维护python3.12+

📦 下载Releases · 🐛 报告Bug · 💡 提出新特性

📋 目录

• 功能特性
• 快速开始
• 安装指南
• 核心模块
• 使用示例
• API文档
• 开发指南
• 贡献指南
• 许可证

✨ 功能特性

• 🔍 LMDB数据库管理: 高性能的键值存储，支持多进程操作和大规模数据管理
• 🎯 3D数据处理: 网格处理、点云操作、3D可视化、牙科专用算法
• 📊 报告生成: 自动生成HTML测试报告和数据分析报告
• 🚀 部署工具: ONNX、TensorRT、共享内存等部署方案
• 🛠️ Windows工具: 系统级工具函数和安装包制作
• 📝 日志管理: 多进程日志记录和异常捕获
• 🧪 测试框架: 完整的pytest测试套件
• 🤖 AI/深度学习: 3D深度学习网络、损失函数、注意力机制
• 🖼️ 2D图像处理: 图像处理、增强、算法
• 🎵 音视频处理: 媒体文件处理、音频转文字
• 🌐 Web/UI: FastAPI服务、PyQt5界面
• 💬 LLM集成: 大语言模型API集成

🚀 快速开始

基本安装

# 从PyPI安装
pip install sindre

# 或者从源码安装
git clone https://github.com/SindreYang/sindre.git
cd sindre
pip install -e .

快速示例

# LMDB数据库操作
import sindre.lmdb as lmdb
import numpy as np

# 写入数据
data = {'input': np.random.rand(10, 10), 'target': [0, 2, 10]}
with lmdb.Writer('./test_lmdb') as db:
    db.put_samples(data)

# 读取数据
with lmdb.Reader('./test_lmdb') as reader:
    sample = reader[0]
    print(sample.keys())
```python
# 3D网格处理
from sindre.utils3d.sindremesh import SindreMesh
import numpy as np

vertices = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]])
faces = np.array([[0, 1, 2]])
mesh = SindreMesh(vertices=vertices, faces=faces)
mesh.show()  # 3D可视化

📦 安装指南

系统要求

• Python: >= 3.8
• 操作系统: Windows, Linux, macOS
• 内存: 建议 >= 8GB（3D/AI处理需要更多）
• 磁盘空间: 至少 1GB 可用空间
• GPU: 可选，AI/3D渲染可加速

安装方法

从PyPI安装

# 基础安装（最小依赖）
pip install sindre

# 完整安装（所有功能）
pip install sindre[full]

# 选择性安装
pip install sindre[2d]    # 仅2D图像处理
pip install sindre[3d]    # 仅3D处理
pip install sindre[ai]    # 仅AI/深度学习
pip install sindre[llm]   # 仅语言模型
pip install sindre[dev]   # 开发工具
pip install sindre[deploy] # 部署工具

从源码安装

# 克隆项目
git clone https://github.com/SindreYang/sindre.git
cd sindre

# 安装基础依赖
pip install -r requirements.txt

# 开发模式（推荐用于开发）
pip install -e .[full]

# 生产模式
pip install .[full]

# 构建wheel包
python setup.py bdist_wheel

依赖说明

主要依赖包括：

• numpy: 数值计算
• torch: 深度学习框架
• vedo: 3D可视化
• lmdb: 数据库存储
• onnxruntime: 模型推理
• pytest: 测试框架
• opencv-python: 图像处理
• pyqt5: GUI界面
• fastapi: Web服务
• transformers: LLM集成
• moviepy: 音视频处理

🧩 核心模块

📊 LMDB模块 (sindre.lmdb)

高性能键值存储数据库，支持多进程操作和大规模数据管理。

主要功能:

• 高效的数据读写
• 多进程安全
• 内存映射优化
• 元数据管理
• 数据库合并、分割、修复
• SSD优化读取

🎯 3D处理模块 (sindre.utils3d)

完整的3D数据处理解决方案。

子模块:

• sindremesh: 网格处理与格式互转
• dental_tools: 牙科专用算法
• sample: 采样算法
• render: 3D渲染

📋 报告模块 (sindre.deploy.report)

自动生成测试报告和数据分析报告。

主要功能:

• HTML报告生成
• 测试结果统计
• 自定义模板
• 多格式导出

🚀 部署模块 (sindre.deploy)

模型部署和优化工具。

子模块:

• ai_deploy: AI模型部署 (ONNX, TensorRT)
• ai_ops: AI操作
• report: 报告生成
• share_memory: 共享内存

🛠️ Windows工具 (sindre.platform.win)

Windows系统专用工具。

主要功能:

• 窗口透明度设置
• Python文件编译为PYD
• NSIS安装包制作
• 系统工具集成
• 任务栏管理
• 端口管理
• 服务管理

📝 通用工具 (sindre.general)

通用工具函数和日志管理。

主要功能:

• 多进程日志（基于loguru）
• 异常捕获
• 文件操作（加载/保存）
• 压缩文件处理
• 网络下载
• 系统命令执行

🖼️ 2D图像模块 (sindre.utils2d)

图像处理和计算机视觉工具。

子模块:

• sindreimage: 图像处理

🎵 音视频模块 (sindre.utilsav)

音频和视频处理工具。

子模块:

• sindremedia: 媒体处理

📱 应用模块 (sindre.apps)

基于库核心功能构建的应用程序。

子模块:

• Annotator3D: 3D标注工具
• Viewer: 3D模型查看器
• WebViewer: Web-based 3D查看器

🤖 AI/深度学习模块 (sindre.ai)

AI模型训练、推理和部署工具。

子模块:

• attention_utils: 注意力机制
• llm: 大语言模型
• peft_utils: PEFT模型微调工具
• nlp_utils: 自然语言处理工具
• vision2d: 2D视觉处理
  • dinov2_utils: DINOv2模型工具
  • unet_utils: UNet网络
  • yolov8_utils: YOLOv8工具
• vision3d: 3D视觉处理
  • implicit_utils: 隐式表示（包含混元3D模型）
  • pointcloud_utils: 点云处理（包含PointNet++、DGCNN等网络）
• av: 音视频处理
  • image: 图像处理
  • video: 视频处理
  • voice: 语音处理

💡 使用示例

1. LMDB数据库操作

import sindre.lmdb as lmdb
import numpy as np

# 创建数据库并写入数据
with lmdb.Writer('./dataset.lmdb', map_size_limit=1024) as db:
    # 设置元数据
    db.set_meta_str("description", "测试数据集")
    db.set_meta_str("version", "1.0")
    
    # 批量写入数据
    samples = {}
    for i in range(1000):
        samples[i] = {
            'points': np.random.rand(100, 3),
            'labels': np.random.randint(0, 10, 100),
            'metadata': {'id': i, 'source': 'synthetic'}
        }
    db.put_samples(samples)

# 读取数据
with lmdb.Reader('./dataset.lmdb') as reader:
    print(f"数据库大小: {len(reader)}")
    print(f"元数据: {reader.get_meta_key_info()}")
    
    # 随机访问
    sample = reader[42]
    print(f"样本42的点数: {sample['points'].shape}")
    
    # 批量读取
    batch = reader.get_samples(0, 10)
    print(f"批量读取: {len(batch)} 个样本")

2. 3D网格处理

from sindre.utils3d.sindremesh import SindreMesh
import numpy as np

# 创建简单网格
vertices = np.array([
    [0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0],
    [0, 0, 1], [1, 0, 1], [0, 1, 1], [1, 1, 1]
])
faces = np.array([
    [0, 1, 2], [1, 3, 2],  # 底面
    [4, 6, 5], [5, 6, 7],  # 顶面
    [0, 4, 1], [1, 4, 5],  # 侧面
    [2, 3, 6], [3, 7, 6],  # 侧面
    [0, 2, 4], [2, 6, 4],  # 侧面
    [1, 5, 3], [3, 5, 7]   # 侧面
])

# 创建网格对象
mesh = SindreMesh(vertices=vertices, faces=faces)

# 显示网格信息
print(mesh)
print(f"顶点数: {len(mesh.vertices)}")
print(f"面数: {len(mesh.faces)}")

# 3D可视化
mesh.show()

# 采样点云
points = mesh.sample(density=0.1)
print(f"采样点数: {len(points)}")

# 格式转换
trimesh_mesh = mesh.to_trimesh()
open3d_mesh = mesh.to_open3d()

3. 报告生成

from sindre.deploy.report import Report
from PIL import Image
import numpy as np

# 创建报告对象
report = Report()

# 添加测试结果
test_results = [
    {
        "className": "TestModel",
        "methodName": "test_accuracy",
        "description": "测试模型准确率",
        "spendTime": 2.5,
        "status": "成功",
        "log": ["准确率: 95.2%", "损失: 0.048"]
    },
    {
        "className": "TestModel", 
        "methodName": "test_inference",
        "description": "测试推理速度",
        "spendTime": 1.8,
        "status": "成功",
        "log": ["平均推理时间: 15ms"]
    }
]

for result in test_results:
    report.append_row(result)

# 添加图片（可选）
# 创建示例图像
img = Image.new('RGB', (100, 100), color='red')
b64_image = Report.PIL_To_B64(img)
test_results[0]["log"].append(b64_image)

# 生成报告
report.write(output_path="./test_report.html")

4. 部署工具

import torch
from sindre.deploy import onnxruntime_deploy, tensorrt_deploy

# 准备输入数据
input_data = torch.randn(1, 3, 224, 224).numpy()

# ONNX模型部署
onnx_infer = onnxruntime_deploy.OnnxInfer("model.onnx", device='cuda')
result = onnx_infer(input_data)
print(f"ONNX推理结果形状: {result.shape}")

# TensorRT部署
trt_infer = tensorrt_deploy.TRTInfer()
trt_infer.load_model("model.engine")
result = trt_infer(input_data)
print(f"TensorRT推理结果形状: {result.shape}")

5. Windows工具

from sindre.platform.win import tools, taskbar

# 编译Python文件为pyd
tools.py2pyd(
    source_dir=r"C:\project\src",
    clear_py=False,  # 保留原py文件
    exclude_patterns=["test_*.py"]  # 排除测试文件
)

# 设置窗口透明度
taskbar.set_windows_alpha(128, "Shell_TrayWnd")

# 制作安装包
tools.exe2nsis(
    work_dir=r"C:\project",
    files_to_compress=[r"C:\project\app.exe", r"C:\project\config.ini"],
    exe_name="MyApp.exe"
)

6. 高级日志记录

from sindre.general.logs import CustomLogger
import time

# 创建日志记录器
logger = CustomLogger(
    logger_name="MyApp",
    level="DEBUG",
    console_output=True,
    file_output=True,
    log_file="app.log",
    rotation="10 MB",  # 10MB轮转
    retention="30 days"  # 保留30天
).get_logger()

# 记录不同级别日志
logger.debug("调试信息")
logger.info("应用程序启动")
logger.warning("内存使用率较高")
logger.error("文件读取失败")

# 带上下文的日志
logger.info("处理完成", extra={"file": "data.csv", "rows": 1000, "time": time.time()})

# 异常记录
try:
    result = 1 / 0
except Exception as e:
    logger.exception("除零错误")

# 重定向print到日志
logger.redirect_print()
print("这条消息会被记录到日志文件")

7. 3D深度学习

import torch
from sindre.ai.vision3d.pointcloud_utils.pointnet2 import PointNet2

# 创建模型
model = PointNet2(num_classes=40)

# 准备输入
points = torch.rand(8, 1024, 3)

# 前向传播
logits = model(points)
print(f"模型输出形状: {logits.shape}")

# 计算损失
from sindre.ai.losses import get_loss
labels = torch.randint(0, 40, (8,))
loss = get_loss(logits, labels)
print(f"损失值: {loss.item()}")

📚 API文档

完整的API文档请访问：https://sindreyang.github.io/sindre/

本地构建

# 安装文档依赖
pip install mkdocs mkdocs-material mkdocstrings-python

# 本地预览
mkdocs serve

# 构建静态网站
mkdocs build

模块文档

• LMDB模块 - 数据库操作
• 3D模块 - 3D处理工具
• 部署模块 - 模型部署
• 通用模块 - 基础工具
• 报告模块 - 报告生成
• Windows工具 - Windows特定功能

🛠️ 开发指南

项目结构

sindre/
├── .github/              # GitHub Actions工作流
├── docs/                 # 文档目录
│   ├── index.md         # 主页
│   ├── lmdb.md          # LMDB模块文档
│   ├── report.md        # 报告模块文档
│   ├── 3d.md            # 3D处理模块文档
│   ├── deploy.md        # 部署模块文档
│   ├── win_tools.md     # Windows工具文档
│   └── general.md       # 通用工具文档
├── sindre/              # 核心代码
│   ├── lmdb/            # LMDB数据库模块
│   ├── utils3d/         # 3D处理模块
│   ├── utils2d/         # 2D图像处理模块
│   ├── utilsav/         # 音视频处理模块
│   ├── ai/              # AI/深度学习模块
│   ├── deploy/          # 部署工具模块
│   ├── general/         # 通用工具模块
│   ├── platform/        # 平台特定工具
│   │   └── win/         # Windows工具
│   ├── apps/            # 应用程序
│   └── __init__.py      # 库初始化
├── test/                # 测试代码
├── requirements.txt     # 依赖列表
├── setup.py            # 安装配置
└── README.md           # 项目说明

运行测试

# 运行所有测试
pytest

# 运行特定模块测试
pytest test/test_lmdb.py
pytest test/test_utils3d.py

# 生成测试报告
pytest --html=report.html --self-contained-html

代码规范

• 使用Google风格的docstring
• 遵循PEP 8代码规范
• 所有函数和类都需要类型注解
• 测试覆盖率要求 > 80%

🤝 贡献指南

我们欢迎所有形式的贡献！

贡献方式

1. 报告Bug: 在GitHub Issues中报告问题
2. 提出新特性: 在Issues中提出建议
3. 提交代码: Fork项目并提交Pull Request
4. 改进文档: 帮助完善文档和示例

开发流程

1. Fork项目到你的GitHub账户
2. 克隆你的fork到本地
3. 创建功能分支: git checkout -b feature/amazing-feature
4. 提交更改: git commit -m 'Add amazing feature'
5. 推送分支: git push origin feature/amazing-feature
6. 创建Pull Request

代码审查

所有提交的代码都会经过审查，确保：

• 代码质量符合标准
• 测试覆盖充分
• 文档更新完整
• 向后兼容性

📄 许可证

本项目采用LGPL许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

感谢所有为这个项目做出贡献的开发者和用户！

📞 联系我们

• GitHub Issues: https://github.com/SindreYang/sindre/issues
• 文档: https://sindreyang.github.io/sindre/
• 邮箱: 通过GitHub Issues联系

---

如果这个项目对你有帮助，请给它一个 ⭐️