lizi-engine 0.1.10

LiziEngine

LiziEngine API 文档

项目概述

LiziEngine 是一个现代化的向量场可视化引擎，采用模块化架构设计，提供高性能的向量场计算和渲染功能。通过模拟物理中的力场（如电磁力），LiziEngine 能够高效处理实体间的受力计算，避免传统碰撞检测的性能瓶颈。

核心特性

• 高性能计算: 支持 CPU 和 GPU 加速计算，适合大规模向量场模拟
• 模块化架构: 采用依赖注入、事件驱动和状态管理的设计模式
• 灵活的插件系统: 支持自定义计算模式、渲染效果和用户交互
• 实时可视化: 基于 OpenGL 的高效渲染，支持交互式操作
• 易于扩展: 清晰的 API 接口，便于开发者添加新功能

快速开始

安装

pip install -r requirements.txt

基本使用

from lizi_engine.compute.vector_field import vector_calculator

# 创建向量网格
grid = vector_calculator.create_vector_grid(width=640, height=480)

# 创建径向向量场模式
vector_calculator.create_radial_pattern(grid, center=(320, 240), radius=100, magnitude=1.0)

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

架构概览

LiziEngine 采用分层架构设计，主要包含以下模块：

核心层 (core/)

负责应用的生命周期管理和模块间协调：

• AppCore: 应用核心，整合所有管理器
• Container: 依赖注入容器
• EventBus: 事件系统
• StateManager: 状态管理
• ConfigManager: 配置管理

计算层 (compute/)

提供向量场计算功能：

• VectorFieldCalculator: 主计算接口，支持 CPU/GPU 切换
• CPUVectorFieldCalculator: CPU 实现
• GPUVectorFieldCalculator: GPU 实现（基于 OpenCL）

渲染层 (graphics/)

处理可视化渲染：

• VectorFieldRenderer: 向量场渲染器
• ShaderProgram: 着色器程序管理

窗口层 (window/)

管理窗口和输入：

• Window: GLFW 窗口管理
• InputHandler: 输入事件处理

插件层 (plugins/)

扩展功能：

• UIManager: UI 插件基类
• Controller: 控制器插件
• MarkerSystem: 标记系统

API 参考

VectorFieldCalculator

向量场计算器的主要接口。

方法

create_vector_grid(width: int, height: int, default: Tuple[float, float] = (0, 0)) -> np.ndarray

创建指定大小的向量网格。

参数:

• width (int): 网格宽度
• height (int): 网格高度
• default (Tuple[float, float]): 默认向量值

返回值: 形状为 (height, width, 2) 的 numpy 数组

示例:

grid = vector_calculator.create_vector_grid(640, 480, (0.0, 0.0))

update_grid_with_adjacent_sum(grid: np.ndarray) -> np.ndarray

根据相邻向量更新整个网格。

参数:

• grid (np.ndarray): 输入网格

返回值: 更新后的网格

示例:

updated_grid = vector_calculator.update_grid_with_adjacent_sum(grid)

create_radial_pattern(grid: np.ndarray, center: Tuple[float, float] = None, radius: float = None, magnitude: float = 1.0) -> np.ndarray

创建径向向量场模式（从中心向外辐射）。

参数:

• grid (np.ndarray): 目标网格
• center (Tuple[float, float]): 中心坐标，默认为网格中心
• radius (float): 影响半径，默认为网格最小边长的一半
• magnitude (float): 向量强度

返回值: 修改后的网格

create_tangential_pattern(grid: np.ndarray, center: Tuple[float, float] = None, radius: float = None, magnitude: float = 1.0) -> np.ndarray

创建切线向量场模式（围绕中心旋转）。

参数:

• grid (np.ndarray): 目标网格
• center (Tuple[float, float]): 中心坐标，默认为网格中心
• radius (float): 影响半径，默认为网格最小边长的一半
• magnitude (float): 向量强度

返回值: 修改后的网格

add_vector_at_position(grid: np.ndarray, x: float, y: float, vx: float, vy: float) -> None

在指定浮点坐标处添加向量，使用双线性插值分布到相邻整数坐标。

参数:

• grid (np.ndarray): 目标网格
• x (float): X 坐标
• y (float): Y 坐标
• vx (float): X 分量
• vy (float): Y 分量

fit_vector_at_position(grid: np.ndarray, x: float, y: float) -> Tuple[float, float]

在指定浮点坐标处使用双线性插值拟合向量值。

参数:

• grid (np.ndarray): 输入网格
• x (float): X 坐标
• y (float): Y 坐标

返回值: 插值后的向量 (vx, vy)

set_device(device: str) -> bool

设置计算设备。

参数:

• device (str): "cpu" 或 "gpu"

返回值: 设置是否成功

ConfigManager

配置管理器。

方法

get(key: str, default: Any = None) -> Any

获取配置值。

参数:

• key (str): 配置键，支持点分隔的嵌套访问
• default (Any): 默认值

示例:

width = config_manager.get("grid.width", 640)

set(key: str, value: Any) -> None

设置配置值。

参数:

• key (str): 配置键
• value (Any): 配置值

StateManager

状态管理器。

方法

get(key: str, default: Any = None) -> Any

获取状态值。

set(key: str, value: Any) -> None

设置状态值并触发变更通知。

EventBus

事件系统。

方法

subscribe(event_type: EventType, handler: EventHandler) -> None

订阅事件。

publish(event: Event) -> None

发布事件。

插件开发

创建计算插件

from lizi_engine.compute.vector_field import VectorFieldCalculator

class MyComputePlugin:
    def __init__(self, vector_calculator: VectorFieldCalculator):
        self.calculator = vector_calculator

    def create_custom_pattern(self, grid: np.ndarray) -> np.ndarray:
        # 实现自定义向量场模式
        h, w = grid.shape[:2]
        for y in range(h):
            for x in range(w):
                vx = np.sin(x * 0.01) * np.cos(y * 0.01)
                vy = np.cos(x * 0.01) * np.sin(y * 0.01)
                grid[y, x] = (vx, vy)
        return grid

创建 UI 插件

from plugins.ui import UIManager
from lizi_engine.input import input_handler, KeyMap

class MyUIPlugin(UIManager):
    def register_callbacks(self, grid: np.ndarray, **kwargs):
        super().register_callbacks(grid, **kwargs)

        def on_custom_key():
            print("Custom action triggered!")

        input_handler.register_key_callback(KeyMap.X, on_custom_key)

配置说明

LiziEngine 使用 JSON 配置文件，支持运行时热更新。

示例配置

{
  "grid": {
    "width": 640,
    "height": 480
  },
  "vector": {
    "scale": 1.0,
    "self": {"weight": 0.2},
    "neighbor": {"weight": 0.2}
  },
  "compute": {
    "device": "gpu",
    "iterations": 1
  },
  "render": {
    "vector": {"lines": false}
  }
}

性能优化

• GPU 加速: 对于大规模计算，推荐使用 GPU 模式
• 权重调优: 调整自身权重和邻居权重以优化计算效果
• 迭代次数: 根据需要调整向量场更新迭代次数
• 内存管理: 及时清理不再使用的网格对象

故障排除

常见问题

1. GPU 计算不可用: 确保系统安装了 OpenCL 运行时
2. OpenGL 错误: 检查显卡驱动是否支持 OpenGL
3. 内存不足: 减小网格尺寸或使用 CPU 模式
4. 性能问题: 调整配置参数或切换计算设备

调试技巧

• 使用 vector_calculator.current_device 检查当前计算设备
• 查看控制台输出了解初始化状态
• 使用配置文件调整调试选项

许可证

MIT License