350 lines
15 KiB
Markdown
350 lines
15 KiB
Markdown
# 基于 HBJSON 扩展多尺度数据模型：方案设计
|
||
|
||
> 日期：2026-05-28
|
||
> 来源：HBJSON Schema 分析与多尺度扩展讨论
|
||
|
||
---
|
||
|
||
## 一、背景
|
||
|
||
HBJSON（Honeybee Schema）是 Ladybug Tools 生态中建筑单体性能模拟的标准数据交换格式。它以 Room → Face → Aperture/Door 的层级结构表达建筑三维几何，并通过 `properties` 扩展点挂载 EnergyPlus/Radiance/DOE-2 的模拟参数。
|
||
|
||
本课题"多尺度绿色性能云端模拟"需要在建筑单体之上，覆盖社区和城市尺度的模拟需求。本文先解读 HBJSON 结构，再分析 Ladybug Tools 现有方案（Dragonfly）的能力与局限，最后提出多尺度扩展方案。
|
||
|
||
---
|
||
|
||
## 二、HBJSON Schema 结构解读
|
||
|
||
### 2.1 整体文件结构
|
||
|
||
HBJSON 是一个自包含的 JSON 文件，由一个顶层 `Model` 对象统领所有数据。文件不依赖外部引用，所有几何、构造、材料、负荷、时间表均内嵌或通过 identifier 引用。
|
||
|
||
### 2.2 顶层 Model 对象
|
||
|
||
`Model` 是文件的根节点，核心字段如下：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `type` | string | 固定为 `"Model"` |
|
||
| `version` | string | Schema 版本号，格式 `x.y.z` |
|
||
| `rooms[]` | Room[] | 建筑房间列表，每个 Room 是一个封闭三维空间 |
|
||
| `orphaned_faces[]` | Face[] | 无父 Room 的面（不可用于能耗模拟导出） |
|
||
| `orphaned_apertures[]` | Aperture[] | 无父 Face 的窗 |
|
||
| `orphaned_doors[]` | Door[] | 无父 Face 的门 |
|
||
| `orphaned_shades[]` | Shade[] | 无父对象的独立遮阳 |
|
||
| `shade_meshes[]` | ShadeMesh[] | 网格遮阳（周边建筑、地形） |
|
||
| `units` | enum | 几何单位：`Meters` / `Millimeters` / `Feet` / `Inches` / `Centimeters` |
|
||
| `tolerance` | float | 顶点容差（米制默认 0.01），用于几何容差检查 |
|
||
| `angle_tolerance` | float | 角度容差（默认 1.0 度），用于共线/共面检查 |
|
||
| `properties` | ModelProperties | 模型级扩展属性（Energy / Radiance / DOE-2） |
|
||
|
||
### 2.3 几何层级与嵌套关系
|
||
|
||
几何对象按严格的层级嵌套：
|
||
|
||
```
|
||
Model
|
||
├── rooms[]
|
||
│ ├── faces[] ← 包围 Room 的面（≥4 个形成封闭体积）
|
||
│ │ ├── apertures[] ← 窗（开洞，透光）
|
||
│ │ │ ├── indoor_shades[] ← 室内遮阳（窗帘、窗台）
|
||
│ │ │ └── outdoor_shades[] ← 室外遮阳（百叶、格栅）
|
||
│ │ ├── doors[] ← 门
|
||
│ │ ├── indoor_shades[]
|
||
│ │ └── outdoor_shades[] ← 室外遮阳（阳台、挑檐）
|
||
│ ├── indoor_shades[] ← 室内家具/隔断
|
||
│ └── outdoor_shades[] ← 室外树木/景观
|
||
└── shade_meshes[] ← 独立网格遮阳
|
||
```
|
||
|
||
各对象核心字段：
|
||
- `Room`：`faces[]`（面列表）、`multiplier`（标准层复用系数）、`zone`（热区标识）、`story`（楼层标识）、`exclude_floor_area`（是否排除楼板面积）
|
||
- `Face`：`face_type`（`Wall` / `Floor` / `RoofCeiling` / `AirBoundary`）、`boundary_condition`（边界条件）
|
||
- `Aperture` / `Door`：`is_operable`（可开启）、`is_glass`（玻璃门）
|
||
- `Shade`：`is_detached`（是否脱离主体）
|
||
|
||
### 2.4 几何原语
|
||
|
||
所有 3D 几何基于以下原语构建：
|
||
|
||
**Point3D**：三维坐标点
|
||
```json
|
||
{ "type": "Point3D", "x": 0.0, "y": 0.0, "z": 0.0 }
|
||
```
|
||
|
||
**Face3D**：平面多边形（Face/Aperture/Door 的几何基础）
|
||
```json
|
||
{
|
||
"type": "Face3D",
|
||
"boundary": [[x,y,z], [x,y,z], ...], // 外轮廓顶点，≥3 个
|
||
"holes": [[...], ...], // 孔洞轮廓（可选）
|
||
"plane": { "n": [0,0,1], "o": [0,0,0] } // 法线 + 原点（可选，自动推导）
|
||
}
|
||
```
|
||
|
||
**Mesh3D**：三角/四边形网格（ShadeMesh 的几何基础）
|
||
```json
|
||
{
|
||
"type": "Mesh3D",
|
||
"vertices": [[x,y,z], ...], // 顶点池
|
||
"faces": [[0,1,2], [1,3,2]], // 面索引（3 或 4 个索引）
|
||
"colors": [{ "r":255, "g":0, "b":0, "a":255 }] // 顶点/面着色（可选）
|
||
}
|
||
```
|
||
|
||
### 2.5 边界条件（Boundary Conditions）
|
||
|
||
Face 的 `boundary_condition` 字段定义面与外部环境的关系，共 5 种类型：
|
||
|
||
| 类型 | 适用场景 | 核心参数 |
|
||
|---|---|---|
|
||
| `Outdoors` | 外表面暴露于室外 | `sun_exposure`、`wind_exposure`、`view_factor`（对地视角系数） |
|
||
| `Surface` | 与另一表面对接 | `boundary_condition_objects`（相邻对象 identifier 列表，Face 为 2 个，SubFace 为 3 个） |
|
||
| `Ground` | 接地面 | 无附加参数 |
|
||
| `Adiabatic` | 绝热面（相邻空间温湿度相同） | 无附加参数 |
|
||
| `OtherSideTemperature` | 给定外侧温度边界 | `heat_transfer_coefficient`（W/m²K）、`temperature`（℃） |
|
||
|
||
约束：`AirBoundary` 类型的 Face **必须**有 `Surface` 边界条件，校验器会强制检查。
|
||
|
||
### 2.6 Abridged（简写）模式
|
||
|
||
HBJSON 的核心设计特征。每个 properties 对象均有两种形态：
|
||
|
||
| 模式 | 结构 | 用途 |
|
||
|---|---|---|
|
||
| `XXXProperties` | 内嵌完整对象（含所有 Material、Construction 定义） | 运行时内存对象 |
|
||
| `XXXPropertiesAbridged` | 仅存 identifier 字符串引用 | 序列化到 JSON 文件 |
|
||
|
||
工作机制：
|
||
```
|
||
Room.properties.energy.construction_set: "Generic2005Construction"
|
||
│
|
||
▼
|
||
Model.properties.energy.construction_sets: [
|
||
{ "identifier": "Generic2005Construction",
|
||
"wall_construction": "WallCons_Generic", ... }
|
||
]
|
||
Model.properties.energy.constructions: [
|
||
{ "identifier": "WallCons_Generic", "layers": ["mat_1", "mat_2"] }
|
||
]
|
||
Model.properties.energy.materials: [
|
||
{ "identifier": "mat_1", "type": "EnergyMaterial", ... }
|
||
]
|
||
```
|
||
|
||
这种"外键引用"模式避免了几何层级的循环嵌套，大幅减小文件体积，是处理大型建筑模型的关键优化。
|
||
|
||
### 2.7 扩展属性系统（Properties Extension）
|
||
|
||
每个几何层级都通过 `properties` 字段挂载多引擎数据，采用插件式架构：
|
||
|
||
```
|
||
properties:
|
||
├── energy — EnergyPlus（构造、负荷、HVAC、时间表）
|
||
├── radiance — Radiance（材质、动态遮阳状态、传感器网格）
|
||
└── doe2 — DOE-2（历史兼容）
|
||
```
|
||
|
||
各层级的 Energy 属性举例：
|
||
- `Model` 级：`constructions[]`、`materials[]`、`programs[]`（使用模式）、`schedules[]`、`hvacs[]`
|
||
- `Room` 级：`construction_set`（引用）、`program_type`（引用）、`hvac`（引用）、`shw`（引用），以及逐条覆盖的 `people`、`lighting`、`equipment`、`infiltration`、`ventilation`、`setpoint`
|
||
- `Face` 级：`construction`（引用）、`vent_crack`（AirflowNetwork 裂缝）
|
||
- `Aperture` 级：`construction`（引用）、`vent_opening`
|
||
- `Shade` 级：`construction`（引用）、`transmittance_schedule`（透射率时间表）、`pv_properties`（光伏）
|
||
|
||
### 2.8 标识符与元数据
|
||
|
||
所有对象继承 `IDdBaseModel`，统一标识规范：
|
||
|
||
| 字段 | 约束 | 说明 |
|
||
|---|---|---|
|
||
| `identifier` | `^[.A-Za-z0-9_-]+$`，1-100 字符 | 唯一标识，序列化/引用/跨引擎传递均使用此字段 |
|
||
| `display_name` | 无限制 | 仅用于 UI 展示，可含中文、空格、特殊字符 |
|
||
| `user_data` | 可选字典 | 用户自定义附加数据，键值需为基本类型 |
|
||
|
||
### 2.9 容差机制
|
||
|
||
HBJSON 通过两个参数处理 CAD 几何导入时的浮点误差：
|
||
|
||
- `tolerance`（距离容差）：顶点坐标差值小于此值视为重合，用于封闭体积检查、法线校正
|
||
- `angle_tolerance`（角度容差）：边方向夹角小于此值视为共线，用于冗余顶点清理
|
||
|
||
EnergyPlus 要求几何单位为米且封闭体积，因此 `units: "Meters"` + 合理的 `tolerance` 是导出成功的必要条件。
|
||
|
||
---
|
||
|
||
## 三、Ladybug Tools 现有方案：Dragonfly
|
||
|
||
Dragonfly 是 Ladybug Tools 生态中面向社区/城市尺度的独立项目，schema 定义在 `dragonfly-schema`。
|
||
|
||
### 3.1 Dragonfly 层级结构
|
||
|
||
```
|
||
Dragonfly Model
|
||
├── buildings[]
|
||
│ ├── unique_stories[]
|
||
│ │ ├── room_2ds[] ← 2D 楼层板 + 参数化立面
|
||
│ │ └── multiplier ← 标准层复用
|
||
│ ├── room_3ds[] ← 可选的完整 Honeybee Room（3D）
|
||
│ └── roof ← 屋顶几何
|
||
├── context_shades[] ← 周边建筑/地形（Face3D / Mesh3D）
|
||
├── units / tolerance / angle_tolerance
|
||
└── properties ← Energy / Radiance / DOE-2 / Comparison
|
||
```
|
||
|
||
### 3.2 Dragonfly 与 Honeybee 的关系
|
||
|
||
```
|
||
Dragonfly (社区/城市尺度)
|
||
│ 几何: 2D 楼层板 + 参数化窗户/遮阳/屋顶
|
||
│ ↓ translate_to_honeybee()
|
||
▼
|
||
Honeybee (建筑单体尺度)
|
||
│ 几何: 完整 3D Face3D
|
||
│ ↓ to_idf() / to_rad()
|
||
▼
|
||
EnergyPlus / Radiance
|
||
```
|
||
|
||
关键事实：Dragonfly 不是 HBJSON 的"上层扩展"，而是一个**独立的 schema**，通过 `translate_to_honeybee()` 降维生成 HBJSON。
|
||
|
||
### 3.3 Dragonfly 的能力与局限
|
||
|
||
| 尺度 | 能力 | 局限 |
|
||
|---|---|---|
|
||
| 建筑单体 | Room2D（2D 楼板+参数化立面）→ 可转 Honeybee | 非 3D 精确几何 |
|
||
| 建筑群 | Building 列表 + ContextShade | 仅遮阳关系，无交互 |
|
||
| 社区 | 多 Building + reference_vector 定位 | 无管网/微气候/能源系统 |
|
||
|
||
### 3.4 缺失层（社区 → 城市之间）
|
||
|
||
- **区域能源系统**（District Energy）——冷热源站、管网拓扑、换热站
|
||
- **场地要素**——道路、绿地、水体、地形
|
||
- **微气候**——UHI（城市热岛）、风环境耦合
|
||
- **城市尺度**——土地利用分区、交通、人口密度
|
||
- **跨建筑交互**——阴影投射、反射辐射、废热排放
|
||
|
||
---
|
||
|
||
## 四、扩展方案对比
|
||
|
||
### 4.1 方案对比
|
||
|
||
| 方案 | 核心思路 | 优势 | 劣势 |
|
||
|---|---|---|---|
|
||
| 一：HBJSON 之上增加 Site 层 | 包裹 MultiScaleModel，内嵌 HBJSON | 完全向后兼容，单文件云端模拟 | 文件体积较大 |
|
||
| 二：扩展 Dragonfly properties | 在 Dragonfly Model 增加城市扩展 | 与 Ladybug Tools 原生兼容 | Room2D 几何精度不足，HBJSON 反向映射不完美 |
|
||
| 三：独立格式 + HBJSON 引用 | CityModel 引用外部 hbjson 文件 | 解耦，可版本控制 | 多文件依赖，不适合云端一键模拟 |
|
||
|
||
### 4.2 推荐方案：方案一的增强版
|
||
|
||
在 HBJSON 之上增加 `MultiScaleModel` 容器，保持 HBJSON 结构不变，新增 Site 和 Urban 层级。
|
||
|
||
设计原则：
|
||
1. 完全向后兼容——`sites[].buildings[]` 是标准 HBJSON Model，现有工具无需修改
|
||
2. 增量扩展——只增加 Site 和 Urban 两个新层级
|
||
3. 可分级模拟——可只取一个 Site 做社区模拟，也可取全部做城市模拟
|
||
|
||
---
|
||
|
||
## 五、MultiScaleModel Schema 设计
|
||
|
||
### 5.1 顶层结构
|
||
|
||
```json
|
||
{
|
||
"type": "MultiScaleModel",
|
||
"version": "0.1.0",
|
||
"units": "Meters",
|
||
"tolerance": 0.01,
|
||
"sites": [...],
|
||
"properties": { "urban": {...} }
|
||
}
|
||
```
|
||
|
||
### 5.2 Site 结构（社区/街区尺度）
|
||
|
||
```
|
||
Site
|
||
├── identifier ← 场地标识
|
||
├── boundary ← 2D 边界 [[x,y], ...]
|
||
├── buildings[] ← HBJSON Model（内嵌）
|
||
├── context_shades[] ← 周边建筑/地形
|
||
│
|
||
├── terrain ← 地形
|
||
│ ├── type: "Grid" | "TIN"
|
||
│ └── data ← 高程网格或三角网
|
||
│
|
||
├── infrastructure ← 基础设施
|
||
│ ├── roads[] ← 道路中心线 + 断面
|
||
│ ├── green_spaces[] ← 绿地（Face3D + 植被类型）
|
||
│ └── water_bodies[] ← 水体
|
||
│
|
||
├── district_energy ← 区域能源系统
|
||
│ ├── plants[] ← 源站（CHP、地源热泵、锅炉房）
|
||
│ │ ├── type, capacity, cop, fuel_type
|
||
│ │ └── location [x, y, z]
|
||
│ ├── networks[] ← 管网
|
||
│ │ ├── type: "CHW" | "HW" | "Steam"
|
||
│ │ ├── pipes[] ← 管段（起点、终点、管径、保温）
|
||
│ │ └── supply_temp, return_temp
|
||
│ └── connections[] ← 建筑-管网接入
|
||
│ ├── building_ref, network_ref, flow_rate
|
||
│
|
||
└── properties
|
||
├── energy
|
||
└── microclimate ← 微气候
|
||
├── uhi_model ← 热岛强度参数
|
||
└── wind_model ← 风场参数
|
||
```
|
||
|
||
### 5.3 Urban 结构（城市尺度）
|
||
|
||
```
|
||
properties.urban
|
||
├── climate_zones[] ← 气候分区
|
||
├── land_use[] ← 用地性质
|
||
└── schedule ← 城市级时间表（交通、人口）
|
||
```
|
||
|
||
---
|
||
|
||
## 六、关键技术决策
|
||
|
||
| 决策点 | 推荐 | 理由 |
|
||
|---|---|---|
|
||
| 建筑几何引用 | 内嵌 HBJSON | 保持与 HBJSON 自包含格式的一致性，减少解析复杂度；多文件方案需额外处理文件依赖和版本一致性 |
|
||
| 几何精度 | 社区用 Dragonfly Room2D，城市用简模 | 城市尺度不需要 Face 级精度，简化计算 |
|
||
| 微气候耦合 | 参数化而非 CFD | CFD 耦合计算量过大，用 UHI 修正系数 |
|
||
| 区域能源 | 拓扑网络 + 简化水力模型 | 不需要详细水力计算，关注热平衡 |
|
||
| 向后兼容 | 完全保留 HBJSON 结构 | 现有 honeybee 工具链零修改 |
|
||
|
||
---
|
||
|
||
## 七、下一步：新增 community/urban 尺度实体
|
||
|
||
当前 `schema-building.json` 已完全对齐 HBJSON（建筑单体几何尺度）。社区和城市尺度的实体定义需要新建独立的 `schema-community.json` / `schema-urban.json`，不应直接混入 schema-building.json，以保持与 HBJSON 的严格兼容。
|
||
|
||
除几何外，各模拟领域均已独立建库，且按尺度拆分：
|
||
|
||
- 建筑尺度：`schema-building.json`（几何）/ `schema-energy.json` / `schema-radiance.json` / `schema-cfd.json`
|
||
- 社区尺度：`schema-community.json`（几何）/ `schema-community-energy.json` / `schema-community-cfd.json` / `schema-community-microclimate.json`
|
||
- 城市尺度：`schema-urban.json`（几何）/ `schema-urban-energy.json` / `schema-urban-cfd.json`
|
||
|
||
新增实体规划：
|
||
|
||
| 层级 | 文件 | 实体 |
|
||
|---|---|---|
|
||
| Site 几何 | `schema-community.json` | Site / TerrainGrid / TerrainTIN / Road / GreenSpace / WaterBody |
|
||
| 区域能源 | `schema-community-energy.json` | DistrictEnergy / Plant / Network / Pipe / BuildingConnection |
|
||
| 社区 CFD | `schema-community-cfd.json` | CommunityCFDSettings / WindProfile / CFDDomain / Mesh / Turbulence |
|
||
| 微气候 | `schema-community-microclimate.json` | MicroClimate |
|
||
| 城市几何 | `schema-urban.json` | ClimateZone / LandUse |
|
||
| 城市能源 | `schema-urban-energy.json` | UrbanEnergyDemand / RenewablePotential / UrbanEnergyBalance |
|
||
| 城市 CFD | `schema-urban-cfd.json` | UrbanCFDSettings / WindComfortAssessment |
|
||
|
||
MultiScaleModel 作为顶层容器，通过引用方式关联三个尺度：
|
||
- `sites[].buildings[]` → 引用 bps/building 的 HBJSON Model
|
||
- `sites[].terrain/infrastructure` → 由 bps/community 定义
|
||
- `properties.urban` → 由 bps/urban 定义
|