Files

T

ringo 7eab40f8fc docs: 更新 README — 社区 Schema defs 数量与 CEA 映射文档链接

- schema-community.json: 7→11 defs（新增 BuildingRef, WeatherContext, SimulationContext）
- schema-community-energy.json: 8→11 defs（新增 CommunityEnergyDemand 等）
- 移除 AI 标注（已人工审核）
- 新增 bps-schema 社区级字段说明
- 新增 CEA 字段映射文档链接

2026-05-29 14:47:52 +08:00

9.8 KiB

Raw Permalink Blame History

bps-schema

建筑性能模拟数据模型。所有类型定义以 draft-2020-12 标准 JSON Schema 为准。

文件架构

采用"尺度 × 模拟域"二维分文件架构。每个尺度按几何和模拟域拆分为独立文件。

建筑单体尺度

文件	$id	defs	说明
`schema-building.json`	bps/building	30	建筑几何实体，对齐 HBJSON 几何层级
`schema-energy.json`	bps/energy	49	EnergyPlus 能耗模拟参数
`schema-radiance.json`	bps/radiance	25	Radiance 采光模拟参数
`schema-cfd.json`	bps/cfd	14	CFD 建筑风环境模拟参数（AI 生成的示例文件，需人工审核后使用）

社区尺度

文件	$id	defs	说明
`schema-community.json`	bps/community	11	社区几何：Site / Terrain / Road / GreenSpace / WaterBody / BuildingRef / WeatherContext / SimulationContext
`schema-community-energy.json`	bps/community-energy	11	区域能源：Plant / Network / Pipe / BuildingConnection / CommunityEnergyDemand
`schema-community-cfd.json`	bps/community-cfd	13	社区风环境：计算域 / 网格 / 湍流 / 边界条件 / 求解器（AI 生成的示例文件，需人工审核后使用）
`schema-community-microclimate.json`	bps/community-microclimate	2	微气候：UHI 强度 / 风速修正 / 地表反照率（AI 生成的示例文件，需人工审核后使用）

城市尺度

文件	$id	defs	说明
`schema-urban.json`	bps/urban	3	城市几何：ClimateZone / LandUse（AI 生成的示例文件，需人工审核后使用）
`schema-urban-energy.json`	bps/urban-energy	5	城市能源：需求聚合 / 可再生能源潜力 / 碳平衡（AI 生成的示例文件，需人工审核后使用）
`schema-urban-cfd.json`	bps/urban-cfd	15	城市风环境：行人高度评估 / 街道峡谷 / 风舒适标准（AI 生成的示例文件，需人工审核后使用）

聚合入口

文件	$id	defs	说明
`schema-all.json`	bps/all	11	引用以上所有文件，提供完整验证入口

合计：11 个领域文件 + 1 个聚合文件，178 个类型定义。

与 CEA 的字段映射

详见 docs/cea-mapping.md。该文档记录了 bps-schema 各字段与 CEA（City Energy Analyst）输入/输出文件的对应关系，涵盖社区级的建筑属性、气象配置、模拟配置、用能需求汇总。高层持续更新。

Schema 规范

所有文件均遵循 JSON Schema draft-2020-12：

$defs — 所有类型、枚举、实体的定义区
$ref — 类型引用，使用 JSON Schema 标准 $ref 机制
oneOf — 判别联合体（如边界条件的 5 种类型）
allOf — 实体组合（_IdentifiedObject + 具体属性）
const / enum — 类型判别字段和枚举值
required — 必填字段
default — 缺省值
minimum / maximum / exclusiveMinimum — 数值约束
pattern / minLength / maxLength — 字符串约束
additionalProperties: false — 严格模式，禁止额外字段

schema-building.json：建筑几何

对齐 honeybee-schema 几何层级，覆盖 Model → Room → Face → Aperture/Door → Shade 层级。

几何原语

Point3D — 三维坐标 (x, y, z)
Face3D — 平面多边形（boundary + holes + plane）
Mesh3D — 三角/四边形网格（vertices + faces + colors）
Plane — 平面（法线 n + 原点 o + x 轴）
Color — RGBA 颜色

边界条件

Outdoors / Surface / Ground / Adiabatic / OtherSideTemperature
Aperture/Door 仅支持 Outdoors 和 Surface 两种

标识符规范

identifier：^[.A-Za-z0-9_-]+$，1-100 字符
display_name：无限制（仅用于 UI 展示）
user_data：可选字典

schema-energy.json：能耗模拟参数

覆盖 HBJSON energy properties 核心实体：材料、构造、时间表、负荷、HVAC、构造集、程序类型。

材料

EnergyMaterial — 有质量材料
EnergyMaterialNoMass — 无质量材料
EnergyMaterialVegetation — 植被材料
EnergyWindowMaterialGlazing / Gas / GasCustom / GasMixture / SimpleGlazSys — 窗材料
EnergyWindowMaterialBlind / Shade — 百叶/遮阳
EnergyWindowFrame — 窗框

构造

OpaqueConstruction / WindowConstruction / AirBoundaryConstruction / ShadeConstruction
各自 Abridged 版本（identifier 引用）
WindowConstructionShade / WindowConstructionDynamic — 含动态遮阳的窗构造

时间表

ScheduleTypeLimit / ScheduleDay / ScheduleFixedInterval / ScheduleRulesetAbridged / ScheduleRule

负荷与设定值

PeopleAbridged / LightingAbridged / ElectricEquipmentAbridged / GasEquipmentAbridged
ServiceHotWaterAbridged / InfiltrationAbridged / VentilationAbridged
SetpointAbridged / InternalMassAbridged / ProcessAbridged

程序类型 / 构造集 / HVAC

ProgramTypeAbridged / ConstructionSetAbridged
DefaultProgramTypesAbridged / DefaultConstructionSetAbridged
IdealAirSystemAbridged

schema-radiance.json：采光模拟参数

兼容 HBJSON radiance properties，覆盖 Radiance 材质、构造集、传感器网格、视角。

材质（Modifiers）

Plastic — 塑料材质（RGB 反射率 + 镜面度 + 粗糙度）
Metal — 金属材质（继承 Plastic，镜面度默认 0.9）
Trans — 半透明材质（透射漫反射比 + 透射镜面比）
Glass — 玻璃材质（RGB 透射率 + 折射率）
Mirror — 镜面材质（RGB 反射率）
Light / Glow — 发光材质（RGB 发射率）
BSDF — 双向散射分布函数材质（BSDF XML 数据 + 朝向）
Void — 空材质

材质集（Modifier Sets）

WallModifierSetAbridged / FloorModifierSetAbridged / RoofCeilingModifierSetAbridged
ApertureModifierSetAbridged / DoorModifierSetAbridged / ShadeModifierSetAbridged
ModifierSet — 材质集聚合

传感器与视角

Sensor / SensorGrid — 传感器网格
View — Radiance 视角（6 种视角类型）

schema-cfd.json：CFD 风环境模拟

独立领域（非 HBJSON），覆盖 CFD 建筑风环境分析的完整参数体系。

核心参数

WindProfile — 风剖面（4 种剖面 + 地形类别 + 风向）
CFDDomain — 计算域定义
MeshParameters — 网格设置（基础网格 + 局部加密 + 壁面层）
TurbulenceParameters — 湍流设置（6 种模型 + 壁面函数）
BoundaryConditions — 进出口/顶部/侧面/地面/建筑墙面边界类型
SolverSettings — 求解器设置（稳态/瞬态 + SIMPLE/PISO + 收敛准则）

schema-community*.json：社区尺度

几何（schema-community.json）

Site — 场地顶级实体，含 2D 边界、地形、道路、绿地、水体
TerrainGrid / TerrainTIN — 高程网格或三角网
Road / GreenSpace / WaterBody — 基础设施
BuildingRef — 社区建筑引用，通过 ref 指向 building schema 标识符
CommunityBuildingAttributes — 社区尺度的建筑属性：使用类型、构造标准、层数、高度、底面积、热区/占位/电气比例
WeatherContext — 气象数据引用（EPW 路径、气候区、经纬度）
SimulationContext — 模拟配置（数据库区域、场景名称）

区域能源（schema-community-energy.json）

DistrictEnergy — 区域能源系统顶级实体
Plant — 源站（CHP / Boiler / HeatPump / Chiller / PV 等）
Network — 管网（CHW / HW / Steam / Electricity）
Pipe / BuildingConnection — 管段与建筑接入
CommunityEnergyDemand — 新增社区级用能需求汇总
- BuildingEnergyDemand — 每栋建筑年度用能（heating/cooling/electricity/dhw MWh + 峰值）
- AggregatedEnergyDemand — 社区聚合指标（总用能、EUI）
DistrictEnergy 新增 demand 字段，连接负荷输入与区域能源系统

风环境（schema-community-cfd.json）

CFDDomain — 社区尺度计算域
MeshParameters — 含局部加密区域
SolverSettings / TurbulenceParameters / BoundaryConditions

schema-urban*.json：城市尺度

几何（schema-urban.json）

ClimateZone — 气候分区（边界 + 气候区代码 + 度日数）
LandUse — 用地性质（边界 + 用地类型 + 容积率 + 建筑密度）

能源（schema-urban-energy.json）

UrbanEnergyDemand — 各用地类型年度能耗
RenewablePotential — 屋顶/立面/地面可再生能源潜力
UrbanEnergyBalance — 城市能源平衡（自给率 / 碳排放 / EUI）

风环境（schema-urban-cfd.json）

UrbanCFDSettings — 城市级 CFD 设置
WindComfortAssessment — 行人风舒适评估（Laws / NEN_8100 / COST_732 标准）
MeshParameters — 含行人高度加密层

使用方式

数据验证

pip install jsonschema
python3 -c "
import json, jsonschema
with open('schema-building.json') as f:
    schema = json.load(f)
with open('model.hbjson') as f:
    data = json.load(f)
jsonschema.validate(data, schema)
"

TypeScript 类型生成

npx quicktype schema-building.json -o dist/building.d.ts --lang typescript
npx quicktype schema-energy.json -o dist/energy.d.ts --lang typescript
npx quicktype schema-radiance.json -o dist/radiance.d.ts --lang typescript
npx quicktype schema-cfd.json -o dist/cfd.d.ts --lang typescript

Python Pydantic 生成

pip install datamodel-code-generator
datamodel-codegen --input schema-building.json --output dist/building.py --output-model-type pydantic_v2.BaseModel
datamodel-codegen --input schema-energy.json --output dist/energy.py --output-model-type pydantic_v2.BaseModel

9.8 KiB Raw Permalink Blame History Unescape Escape