lbt-blender

Languages: English | 中文

This is a vibe-coding project and in early stage, it may help, but take your own risk.

A Blender extension that loads EPW (EnergyPlus Weather) climate data and generates 3D meshes for visualization via native bpy/bmesh APIs.

Built on ladybug-tools/ladybug core, inspired by ladybug-blender

Compliant with the Blender 4.2+ Extensions platform, zero Sverchok dependency, pure-Python wheels bundled for offline use.

Features

Feature	Description	Since
EPW Import	Parse `.epw`, cache 8760 hours × 26 fields	v0.1.0
Data Browser Panel	N-panel showing location/timezone/annual stats/field list	v0.1.0
3D Sun Path	Ground azimuth ring + sun trajectory curve + sun position points (3 separate Objects, above-horizon only)	v0.1.0
3D Wind Rose	16-direction × 6-speed-bin aggregated wedge prisms, with polar grid + color legend + direction labels	v0.1.0
Mesh Heatmap	Map any field to a target mesh's vertex colors (viridis / turbo / hot)	v0.1.0
3D Psychrometric Chart	Temperature-humidity grid with saturation/enthalpy/wet-bulb lines, based on ladybug `PsychrometricChart`	v0.3.0
3D Monthly Chart	1–3 field bar/band chart with monthly/daily/hourly data, based on ladybug `MonthlyChart`	v0.3.0
Direct Sun Hours	Cumulative sun hours on selected surfaces via `ladybug_radiance` `DirectSunStudy`, with face-color output	v0.3.0

Each visualization also generates a title + Location info text object (city, lat/lon, timezone, elevation).

Directory Structure

lbt-blender/
├── blender_manifest.toml      # Extension manifest (wheels / permissions / build excludes)
├── __init__.py                # register()/unregister()
├── wheels/                    # 4 pure-Python wheels (ladybug_core / ladybug_geometry / ladybug_radiance / click)
├── core/                      # EPW loading, data adapters, scene cache, field metadata
├── operators/                 # 7 OT_ Operators (load_epw / generate_sunpath / generate_windrose / generate_psychchart / generate_monthlychart / generate_directsun / apply_heatmap)
├── builders/                  # bmesh mesh builders (mesh_sunpath / mesh_windrose / mesh_psychchart / mesh_monthlychart / mesh_directsun / color_heatmap / colormaps / _lb_geo)
├── ui/                        # N-panel (main / data / visualize — 7 sub-panels)
├── props/                     # LADYBUG_PG_scene PropertyGroup
├── tests/                     # Unit tests + integration tests + sample EPW
└── docs/spec.md               # Design spec

Build

Requires Blender 4.2+ (developed and tested on 5.1.x).

blender --command extension build
# Output: lbt_blender-0.3.0.zip

The [build] paths_exclude_pattern in blender_manifest.toml excludes _wheels_extracted/, tests/, docs/, *.pkl, __pycache__/ and other dev-only files. The final zip contains only the manifest + source + wheels.

Install

Option 1: Command line (recommended for CI/automation)

# List repositories to confirm user_default exists
blender --command extension repo-list

# Install and enable
blender --command extension install-file -r user_default --enable lbt_blender-0.3.0.zip

# Uninstall
blender --command extension remove lbt_blender

Option 2: Blender GUI

Edit → Preferences → Extensions → Install from Disk, select lbt_blender-0.3.0.zip.

After installation the extension lives at:

%APPDATA%\Blender Foundation\Blender\<version>\extensions\user_default\lbt_blender\

Wheels are extracted into the extension's private site-packages and do not pollute Blender's main Python.

Usage

Launch Blender, open the 3D Viewport
Press N to open the sidebar → switch to the Ladybug tab
EPW Data panel → click "Load EPW File" and pick an .epw
Select a field (e.g. dry_bulb_temperature) to view min/max/mean
Sun Path / Wind Rose / Psychrometric Chart / Monthly Chart / Direct Sun Hours / Heatmap panels generate the visualizations

Generated Objects are plain Mesh/Curve/Text, usable by any Blender tool (materials, modifiers, geometry nodes, rendering).

Testing

Unit tests (core layer, no bpy dependency)

Requires system Python 3.11+. The script auto-extracts wheels/ to a temp dir:

python tests/test_core.py

Integration tests (Blender headless)

Requires a local Blender executable:

blender --background --python tests/test_blender.py

Covers: extension register → EPW load → Sun Path (DAILY_NOON + HOURLY) → Wind Rose → Psychrometric Chart → Monthly Chart → Direct Sun Hours → Heatmap → unregister.

End-to-end verification of the installed extension

Install the zip first (see above), then run:

blender --background --python tests/verify_installed.py

This script verifies the installed version (not the dev source tree) via the bl_ext.user_default.lbt_blender namespace, covering wheel auto-extraction, PropertyGroup registration, and the full workflow of all 7 operators.

Regenerate the sample EPW

python tests/generate_sample_epw.py
# Output: tests/sample.epw

Debugging

Interactive debugging inside Blender

Launch Blender (without --background)
Window → Toggle System Console for real-time logs
Operate the extension in the N-panel; all self.report({'INFO'/'ERROR'}) and traceback.print_exc() output appears in the console
Inspect scene state with bpy.context.scene.ladybug in the Python Console

VS Code remote debugging (optional)

Start debugpy listener inside Blender:

import debugpy
debugpy.listen(("localhost", 5678))
print("Waiting for debugger...")
debugpy.wait_for_client()

VS Code launch.json:

{
  "name": "Attach to Blender",
  "type": "python",
  "request": "attach",
  "connect": {"host": "localhost", "port": 5678},
  "pathMappings": [
    {"localRoot": "${workspaceFolder}", "remoteRoot": "<extension install path>"}
  ]
}

Dev source mode (testing without packaging)

Symlinking or copying the project root into Blender's scripts directory makes the dev source load, but wheels will not auto-extract. Recommended: use Install from Disk so wheels are extracted into the extension's private site-packages, matching the production environment.

License

AGPL-3.0-or-later

Because the bundled ladybug-core is AGPL-3.0, the whole extension must use the same license. Distributions must include the LICENSE + copyright notice; closed-source distribution is not permitted.

Design Document

See docs/spec.md for the full spec.

Lbt-Blender中文文档

语言： English | 中文

注意：这是vibe coding项目，且在开发早期，它也许有帮助，但也需知风险。

加载 EPW（EnergyPlus Weather）气候数据并通过原生 bpy/bmesh 生成 3D 网格进行可视化的 Blender 扩展。

基于 ladybug-tools/ladybug 核心，受到ladybug-blender的启发。

遵循 Blender 4.2+ Extensions 平台规范，零 Sverchok 依赖，纯 Python wheel 内嵌打包，离线可用。

功能

功能	说明	版本
EPW 导入	解析 `.epw`，缓存 8760 小时 × 26 字段	v0.1.0
数据浏览面板	N 面板展示位置/时区/年度统计/字段列表	v0.1.0
3D 太阳路径	地面方位环 + 太阳轨迹曲线 + 太阳位置点（三个独立 Object，仅地平线以上）	v0.1.0
3D 风玫瑰	16 方向 × 6 风速桶聚合为楔形棱柱，含极坐标网格 + 颜色图例 + 方向标注	v0.1.0
分析网格热力图	把任意字段映射到目标 mesh 的顶点颜色（viridis / turbo / hot）	v0.1.0
3D 心理图	温湿度网格 + 饱和线/等焓线/湿球线，基于 ladybug `PsychrometricChart`	v0.3.0
3D 月度图	1–3 字段柱状图/带状图，支持月度/日/小时数据，基于 ladybug `MonthlyChart`	v0.3.0
累计日照时间	基于 `ladybug_radiance` `DirectSunStudy` 计算选定表面累计日照小时数，面颜色输出	v0.3.0

每个可视化还会生成图名 + Location 信息文字对象（城市、经纬度、时区、海拔）。

目录结构

lbt-blender/
├── blender_manifest.toml      # 扩展清单（wheels / permissions / build 排除）
├── __init__.py                # register()/unregister()
├── wheels/                    # 4 个纯 Python wheel（ladybug_core / ladybug_geometry / ladybug_radiance / click）
├── core/                      # EPW 加载、数据适配、场景缓存、字段元数据
├── operators/                 # 7 个 OT_ Operator（load_epw / generate_sunpath / generate_windrose / generate_psychchart / generate_monthlychart / generate_directsun / apply_heatmap）
├── builders/                  # bmesh 网格构建（mesh_sunpath / mesh_windrose / mesh_psychchart / mesh_monthlychart / mesh_directsun / color_heatmap / colormaps / _lb_geo）
├── ui/                        # N 面板（main / data / visualize — 7 个子面板）
├── props/                     # LADYBUG_PG_scene PropertyGroup
├── tests/                     # 单测 + 集成测试 + 样本 EPW
└── docs/spec.md               # 设计规格

构建

需要 Blender 4.2+（在 5.1.x 上开发测试）。

blender --command extension build
# 产出: lbt_blender-0.3.0.zip

[build] paths_exclude_pattern 在 blender_manifest.toml 中已排除 _wheels_extracted/、tests/、docs/、*.pkl、__pycache__/ 等开发期文件。最终 zip 仅含 manifest + 源码 + wheels。

安装

方式一：命令行（推荐用于 CI/自动化）

# 列出可用仓库，确认 user_default 存在
blender --command extension repo-list

# 安装并启用
blender --command extension install-file -r user_default --enable lbt_blender-0.3.0.zip

# 卸载
blender --command extension remove lbt_blender

方式二：Blender GUI

Edit → Preferences → Extensions → Install from Disk，选择 lbt_blender-0.3.0.zip。

安装后扩展位于：

%APPDATA%\Blender Foundation\Blender\<version>\extensions\user_default\lbt_blender\

wheel 解压到扩展私有 site-packages，不污染 Blender 主 Python。

使用

启动 Blender，打开 3D 视图
按 N 打开侧边栏 → 切换到 Ladybug 标签
EPW 数据 面板 → 点击 "Load EPW File" 选择 .epw
选择字段（如 dry_bulb_temperature），查看 min/max/mean
太阳路径 / 风玫瑰 / 心理图 / 月度图 / 累计日照 / 热力图 面板按需生成

生成的 Object 是普通 Mesh / Curve / Text，可被任何 Blender 工具（材质、修改器、几何节点、渲染）继续使用。

测试

单元测试（core 层，不依赖 bpy）

需要系统 Python 3.11+。脚本会自动解压 wheels/ 到临时目录：

python tests/test_core.py

集成测试（Blender headless）

需要本地 Blender 可执行文件路径：

blender --background --python tests/test_blender.py

测试项：扩展 register → EPW 加载 → Sun Path（DAILY_NOON + HOURLY）→ Wind Rose → Psychrometric Chart → Monthly Chart → Direct Sun Hours → Heatmap → unregister。

已安装扩展的端到端验证

先安装 zip（见上文），然后跑：

blender --background --python tests/verify_installed.py

该脚本通过 bl_ext.user_default.lbt_blender 命名空间验证已安装版本（而非 dev 源码目录），覆盖 wheel 自动解压、PropertyGroup 挂载、所有 7 个 operator 的完整流程。

重新生成样本 EPW

python tests/generate_sample_epw.py
# 产出: tests/sample.epw

调试

Blender 内交互调试

启动 Blender（不要 --background）
Window → Toggle System Console 查看实时日志
在 N 面板操作扩展，所有 self.report({'INFO'/'ERROR'}) 和 traceback.print_exc() 输出都会显示在控制台
用 bpy.context.scene.ladybug 在 Python Console 中读取场景状态

VS Code 远程调试（可选）

在 Blender 内启动 debugpy 监听：

import debugpy
debugpy.listen(("localhost", 5678))
print("Waiting for debugger...")
debugpy.wait_for_client()

VS Code 配置 launch.json：

{
  "name": "Attach to Blender",
  "type": "python",
  "request": "attach",
  "connect": {"host": "localhost", "port": 5678},
  "pathMappings": [
    {"localRoot": "${workspaceFolder}", "remoteRoot": "<扩展安装路径>"}
  ]
}

Dev 源码模式（不打包测试）

把项目根软链或复制到 Blender 的 scripts 目录可让 dev 源码生效，但 wheel 不会自动解压。推荐用 Install from Disk 走正式流程，wheel 自动解压到扩展私有 site-packages，最接近生产环境。

许可证

AGPL-3.0-or-later

设计文档

详细规格见 docs/spec.md。

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
builders		builders
core		core
docs		docs
operators		operators
props		props
tests		tests
ui		ui
wheels		wheels
.gitignore		.gitignore
README.md		README.md
__init__.py		__init__.py
blender_manifest.toml		blender_manifest.toml

Folders and files

Latest commit

History

Repository files navigation