# 基于 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 定义