-
Notifications
You must be signed in to change notification settings - Fork 9
1.1 Model Schema
The Honeybee Model schema is a detailed means of describing building geometry in 3D space. It is designed to be extensible such that properties for various simulation engines can be assigned to this geometry. Schemas have been developed to extend the core Honeybee Model for EnergyPlus/OpenStudio as well as Radiance. This section will focus on only describing the core Model schema in the absence of any extensions.
Honeybee Models are composed of 5 geometry objects all of which represent planar geometry. In order of most coarse/abstract to most fine/detailed, these objects are:
- Room
- Face
- Aperture
- Door
- Shade
Some of these objects can be assigned to others in parent/child object relationships as follows:
The coarsest object in the Honeybee Model schema is the Room
, which represents a single closed volume and maps to a zone within energy simulation workflows. Rooms
are composed of planar Faces
, representing walls, roofs, and floors. Faces
can be assigned Apertures
, which typically represent windows but can also represent light tubes, daylight domes or any opening that admits light into a building. Faces
can also be assigned Doors
, which can be opaque or transparent. Lastly, Shades
can be assigned to any of the other 4 objects: Rooms
, Faces
, Apertures
, Doors
. When they are assigned to Apertures
, Shades
can represent window sills, mullions, light shelves, louvers, etc. When they are assigned to Doors
, they can represent entryway canopies or they can be used to account for the thickness of walls in doorways, When they are assigned to Faces
, they can represent balconies and overhangs. When assigned to Rooms
, they can represent furniture, interior partitions, etc.
The relationship between Honeybee objects in 3D space can be visualized as follows:
All 5 of these objects can be added to a Honeybee Model
object each under a respective key as follows:
The use of the term "orphaned" denotes objects that lack a parent object. For example, an Face
under the orphaned_faces
key lacks a parent Room
. All 5 of these keys are optional but note that you cannot have a simulate-able energy model without rooms
(Radiance models are not governed by this restriction). Also note that the only keys that are relevant for energy modeling are rooms
and orphaned_shades
.
While some models that do not require the parent/child hierarchy can be set up fairly flat, there are a number of advantages to making use of the hierarchy like so:
And assigning Shades
to the objects they are shading like so:
Some advantages of the hierarchical nested schema are that:
- Adding/removing
Rooms
orFaces
from the schema is much easier in that you can simply delete or add aRoom
and all objects nested underneath it are also deleted/added. - For large models, it's often advantageous to visualize only a portion of the model and this is faster/easier when objects are nested. For example, if you only want to load a single story of a building, you just get the list of
Room
names in that story and load all of the geometry objects that are nested under each of theRooms
(no need to lookupFaces
,Apertures
or other objects in a different part of the schema or interact with the geometry you don’t care about). - Many of the Honeybee extensions that add properties for simulation engines make use of the fact that some objects are assigned to a parent in order to add capabilities to those objects. For example,
Shades
assigned toApertures
in Radiance 3-phase simulations can be used to develop shade controls on an aperture-by-aperture basis. Similarly, such simulations make use of the fact thatRooms
are closed volumes to run ray tracing calculations of the interior of each Room independently of others.
While hierarchy has advantages, there are limitations and adhering strictly to the object hierarchy can often be an unnecessary formality for many simple studies (like shadow studies) and so the flatter structure with the "orphaned" keys can be used. It is also because of the limitations of hierarchy that Rooms
are not the child object of any other object in the Honeybee schema (like Stories
or Buildings
). Having Rooms
as the coarsest object allows for the grouping / editing of Rooms
as users see fit, whether this is by story, by orientation of windows, by program, etc. In other words, the flexibility of being able to group Rooms
into custom arrays for filtering/editing can often outweigh the benefit of a dedicated object that is meant to take Rooms
as children. However, if stories or buildings are needed, these objects are supported in the Dragonfly schema.