feat: add CFD/radiance/urban/community schema files, pres, docs

2026-05-28 15:06:30 +08:00
parent 9f730223ce
commit 68bb9e2181
40 changed files with 11373 additions and 686 deletions
@@ -0,0 +1,349 @@
+# 基于 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 定义