Multi-Scale-Gen/bps-schema
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a84bf9e5857218f2914d65354e62312245225361
bps-schema/docs/multiscale-hbjson-extension.md
T

15 KiB
Raw Blame History

基于 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：三维坐标点

{ "type": "Point3D", "x": 0.0, "y": 0.0, "z": 0.0 }

Face3D：平面多边形（Face/Aperture/Door 的几何基础）

{
  "type": "Face3D",
  "boundary": [[x,y,z], [x,y,z], ...],   // 外轮廓顶点，≥3 个
  "holes": [[...], ...],                 // 孔洞轮廓（可选）
  "plane": { "n": [0,0,1], "o": [0,0,0] } // 法线 + 原点（可选，自动推导）
}

Mesh3D：三角/四边形网格（ShadeMesh 的几何基础）

{
  "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 顶层结构

{
  "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 定义
Reference in New Issue View Git Blame Copy Permalink