lizi-engine 0.1.11

LiziEngine

LiziEngine

目录

• 项目概述
• 视频演示
• 安装和运行
  • 系统要求
  • 下载方式
  • 安装依赖
  • 运行示例
  • 键盘控制
• 向量场计算原理
  • 基本概念
  • 计算方法
  • 支持的向量场模式
  • CPU vs GPU 计算
• 架构设计
  • 底层引擎 (lizi_engine/)
  • 插件系统 (plugins/)
• 配置说明
• 更新日志
• 常见问题
• 许可证
• 联系方式
• 贡献

项目概述

LiziEngine 是一个由向量场驱动的物理引擎，它通过模拟现实中的力场（如电磁力）来驱动实体运动，从而在根本上解决传统方法在处理碰撞检测的性能瓶颈。相比与每个实体互相遍历计算，本项目仅需让它们独立计算坐标下的向量值即可处理受力问题。

视频演示

重力模拟与电荷模拟 【物理引擎开发日志#01】-哔哩哔哩

A Physics Engine Without Collision Detection -Youtube

安装和运行

系统要求

• Python 3.7+
• OpenGL 支持
• GPU 计算需要 OpenCL 运行时（可选）

下载方式

直接下载源码并解压，发行版里是打包的底层库。

安装依赖

pip install -r requirements.txt
# 或者使用 pip install lizi-engine 直接安装底层库

主要依赖包：

• numpy>=1.21.0 (数值计算)
• glfw>=2.5.0 (窗口管理)
• PyOpenGL>=3.1.6 (OpenGL 渲染)
• pyopencl>=2021.1.0 (GPU 计算，可选)
• pybind11>=2.6.0 (C++ 绑定)

运行示例

# 基本使用示例 - 展示核心功能
python examples/basic_usage.py

# 重力箱示例 - 物理模拟
python examples/gravity_box.py

# 输入演示 - 交互功能展示
python examples/input_demo.py

键盘控制

• 空格键: 重新生成切线模式
• G键: 切换网格显示
• C键: 清空网格
• U键: 切换实时更新
• 鼠标拖拽: 平移视图
• 滚轮: 缩放视图

向量场计算原理

基本概念

向量场是一个二维网格数据结构，每个网格点包含一个二维向量 (vx, vy)，表示该点的方向和强度。向量场的计算涉及相邻点的相互影响，形成复杂的动态模式。

计算方法

1. 相邻向量求和

对于每个网格点，计算其自身和上下左右四个邻居向量的加权和：

新向量值 = 自身值 × 自身权重 + 邻居总和 × 邻居权重

• 自身权重 (vector_self_weight): 控制自身向量对结果的影响
• 邻居权重 (vector_neighbor_weight): 控制邻居向量对结果的影响

2. 向量场更新

迭代向量场的每个向量值：

# 向量场更新
vector_calculator.update_grid_with_adjacent_sum(grid)

3. 双线性插值

在浮点坐标处添加或读取向量时，使用双线性插值进行平滑处理：

# 在指定位置拟合一个向量
fit_vector_at_position(grid, x, y)

# 在指定位置添加一个向量
add_vector_at_position(grid, x, y, vx, vy)

支持的向量场模式

微小向量添加

在指定位置创建局部影响，只影响当前位置及其上下左右邻居：

create_tiny_vector(self, grid, x, y, mag)

径向模式 (Radial Pattern)

向量从中心向外辐射，形成扩散效果（仅用于测试，只支持整数坐标）：

create_radial_pattern(self, grid, center, radius, magnitude)

切线模式 (Tangential Pattern)

向量围绕中心旋转，形成漩涡效果（仅用于测试，只支持整数坐标）：

create_tangential_pattern(self, grid, center, radius, magnitude)

CPU vs GPU 计算

• CPU 计算: 使用 NumPy 向量化操作，适合中小规模计算，易于调试
• GPU 计算: 使用 OpenCL 加速，大规模并行计算，性能显著提升，适合实时应用

架构设计

底层引擎 (lizi_engine/)

• core: 核心模块
• compute: 计算模块，由主接口统一cpu与gpu计算方式
• graphics: 渲染器模块
• window: 窗口管理器模块
• input: 输入管理器模块

插件系统 (plugins/)

• controller.py: 控制器插件，处理用户输入和向量场操作
• marker_system.py: 标记系统，支持在向量场上添加标记点
• ui.py: UI 管理器，处理界面交互和事件分发

配置说明

config.json 中的主要配置项：

{
    "grid": {
        "width": 640,
        "height": 480,
        "color": [
            0.3,
            0.3,
            0.3
        ]
    },
    "cell": {
        "size": 2.0 //格子大小
    },
    "vector": {
        "color": [
            0.2,
            0.6,
            1.0
        ],
        "scale": 1.0, //向量长度缩放
        "self": {
            "weight": 0.2 //自身权重
        },
        "neighbor": {
            "weight": 0.2 //邻居权重
        }
    },
    "cam": {
        "x": 0.0,
        "y": 0.0,
        "zoom": 1.0
    },
    "show": {
        "grid": true //是否显示网格线
    },
    "background": {
        "color": [
            0.1,
            0.1,
            0.1
        ]
    },
    "antialiasing": true, //是否开启抗锯齿
    "line": {
        "width": 1.0 //线宽
    },
    "compute": {
        "device": "gpu", //计算设备，cpu或gpu
        "iterations": 1 //迭代次数
    },
    "render": {
        "vector": {
            "lines": false //是否显示向量线
        }
    }
}

更新日志

v0.1.0 Alpha (2026-01-01)

• 初始发布版本
• 支持向量场驱动的物理模拟
• 实现 CPU 和 GPU 计算模式
• 提供基本插件系统
• 包含多个示例程序

常见问题

Q: 如何切换 CPU 和 GPU 计算模式？

A: 在 config.json 中设置 "compute": {"device": "cpu"} 或 "gpu"。

Q: 运行示例时出现 OpenGL 错误怎么办？

A: 确保您的系统支持 OpenGL，并安装了合适的图形驱动。

Q: 如何添加自定义向量场模式？

A: 参考 lizi_engine/compute/vector_field.py 中的现有模式，实现新的计算函数。

Q: 项目支持哪些操作系统？

A: 目前主要在 Windows 上测试，其他操作系统可能需要调整依赖。

许可证

MIT License

联系方式

[e-mail]

贡献

本项目处于demo阶段，可能存在一些未发现的问题。 我们需要你的支持与协助！ 如果你感兴趣，请务必点一个star让我们被更多人看到！

如何贡献

1. 报告问题: 如果您发现bug或有功能建议，请在GitHub Issues中提交。
2. 提交代码: Fork本仓库，创建功能分支，提交PR。
3. 文档改进: 帮助完善文档或添加示例。
4. 测试: 在不同平台上测试并报告兼容性问题。

开发环境设置

git clone https://github.com/hechengyancheng/LiziEngine.git
cd LiziEngine
pip install -r requirements.txt

代码规范

• 使用PEP 8风格
• 添加必要的注释和文档字符串
• 提交前进行测试

API 文档

详细的API文档请参考 doc/ 目录下的文档：

• READEME.md