# zlbmath

**Repository Path**: wujilingfeng/zlbmath

## Basic Information

- **Project Name**: zlbmath
- **Description**: 基础数学库，基本的几何，组合数学算法
- **Primary Language**: 其他
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-08
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zlbmath

zlbmath 是用 Zig 实现的轻量数学基础库，提供线性代数、矩阵（稠密/稀疏）、计算几何 (2D/3D)、奇异值分解（SVD）、多项式求根、凸优化与碰撞检测（GJK）等常用算法。设计目标是模块化、尽量无分配（或可选分配）、并便于在游戏引擎与工程项目中复用。

核心定位（简短）
- 面向工程与实时场景的数值工具集，关注可重用性与数值稳定性。
- 将底层数值原语（向量/矩阵/四元数/数值辅助）与较高层算法（SVD、GJK、剖分、优化）分离，方便组合与测试。

主要能力（概览）
- 稠密矩阵：创建、转置、乘法、逆与常用矩阵运算。
- 稀疏矩阵：稀疏表示、矩阵-向量乘法与 LU 支持。
- 矩阵分解：基于 Golub–Reinsch 风格的 SVD，用于最小二乘与降维。
- 多项式：一次到四次方程求根（含复数根表示）。
- 计算几何：点/线/面运算、点在多边形测试、线段交、最近点、三角剖分（耳朵裁剪）等。
- 碰撞检测：通用 N 维的 GJK 距离/碰撞实现。
- 凸优化：基本梯度法与线性/二次规划（含单纯形法）。
- 数值稳定性：统一容差、退化检测与明确错误码（例如 `Math_Compute_Abandon`、`NoConvergence`、`SingularMatrix` 等）。

核心模块（摘要）
- `src/root.zig` — 库导出入口
- `src/main.zig` — 示例/测试可执行（可选）
- `src/algorithm/`  
  - `geometry_tool.zig` — 计算几何实用工具  
  - `gjk.zig` — GJK 距离/碰撞算法  
  - `subdivision_of_polygon.zig` — 多边形三角剖分（耳朵裁剪）  
  - `svd.zig` — SVD 实现  
  - `convex_opt.zig` / `convex_optn.zig` — 凸优化实现  
- `src/algorithm/matrix/`  
  - `lbmatrix.zig` — 稠密矩阵操作  
  - `sparse_matrix.zig` — 稀疏矩阵结构与求解辅助  
  - `math/lbmath.zig` — 低级数学原语与数值工具（见下）

关于 `lbmath.zig`
目的
- 为库内其它模块提供高性能、可复用的低级数学原语与数值辅助函数。

主要内容（按类别）
- 向量与标量运算：向量加/减、缩放、线性组合、范数与稳定的距离计算。
- 向量/矩阵工具：点积、叉积、正交化、基底变换与常用 helper。
- 四元数与旋转：四元数构造、乘法、归一化、与旋转矩阵的互转工具。
- 数值辅助：稳定求平方和/pythag、默认容差（例如 `defaultTolerance`）、近似比较与误差处理工具。
- 比较与退化处理：统一的比较策略、退化检测与错误码（例如 `Math_Compute_Abandon`）。
- 轻量工具：复数表示（用于多项式根）、组合/排列辅助等小工具。

设计要点
- 尽量避免内部隐式分配；允许调用方传入缓冲以降低分配开销。
- 对潜在不收敛或退化的操作返回明确错误，调用方需检查并处理。

快速开始
- 运行测试：
```/dev/null/quickstart.sh#L1-3
zig test
```

- 构建与运行（若存在 `build.zig`）：
```/dev/null/quickstart.sh#L1-4
zig build
zig build run
```

示例导入方式
```/dev/null/example.zig#L1-16
// 方式一：通过 build.zig 或包名暴露为库
const zlb = @import("zlbmath_lib");

// 方式二：直接导入源码模块（开发或脚本方式）
const lbmath = @import("src/algorithm/matrix/math/lbmath.zig");
const geom = @import("src/algorithm/geometry_tool.zig");
```

测试与数值注意事项
- 项目中很多文件包含 `test` 块（例如 `geometry_tool.zig`、`lbmath.zig` 等），建议通过 `zig test` 验证实现与边界行为。
- 数值函数可能在退化情形下返回错误（例如 SVD 不收敛、稀疏矩阵奇异等），请在调用处捕获并处理。

示例用例
- 游戏物理：用 `gjk.gjk_distance_generic` 进行凸体距离计算与碰撞检测。
- 网格处理：利用 `geometry_tool` 的坐标变换与 `subdivision_of_polygon` 进行剖分与网格预处理。
- 数据分析：用 `svd.dsvd` 做 PCA 或最小二乘拟合。
- 优化求解：使用 `convex_opt` / `convex_optn` 提供的基本求解器处理带约束问题。

贡献与许可证
- 欢迎提交 issue 与 PR。请遵循 Zig 的代码风格与错误处理惯例，并为新增功能添加对应 `test` 覆盖。