2.1 Face3D Schema

All geometry objects within a Model are planar objects in 3D space and make use of the same object to represent this geometry called Face3D. Four of the objects make use of it directly under a "geometry" key (Face, Aperture, Door, Shade) and the Room object makes use of it indirectly through the other four objects. Its schema is as follows:

The "boundary" key

The only key that is required to make a Face3Dis the "boundary" key. This key houses at least 3 vertices that make up the boundary of the planar shape. Each vertex is defined by by an array of 3 numbers representing (x, y, z) coordinates. Vertices must lie within the same plane in order to be valid. However, no formal check is preformed as part of the validation of a given JSON file since planarity can vary within a tolerance for different types of studies and still be valid. It is therefore up to the user to ensure that vertices represent a shape that is planar to the accuracy of the simulation they are running.

The "holes" key

There are often cases where it is useful to specify holes within a given planar shape to note the existence of courtyard in a floor plate among other situations. For these cases an optional "holes" key can be used to specify the vertices of the holes in the shape. Each hole should be a list of at least 3 points and each point a list of 3 (x, y, z) values. Hole vertices must lie within the same plane as each other and the Face3D's "boundary" vertices.

Those familiar with EnergyPlus and Radiance know that such holes are not supported within these engines but, for these cases, Honeybee converts the Face3D with holes into a single list of vertices that trace out the boundary of the whole shape, winding inward to cut out the holes.

The "plane" key

The "plane" key is completely optional and, in most cases, it is not necessary since the Face3D plane can be easily derived from the "boundary" vertices. However, there are certain cases where it is useful to be specific about this plane since operations like the generation of radiance point grids from floor Face3Ds will use the X and Y axes of the Face3D plane to determine the orientation of the generated grid.

Another common case is when it is important that a given Face3D's direction be enforced, such as a Face with a Radiance mirror material. Such mirror materials can only reflect light off of one side of the Face they are applied to and, in the absence of a "plane" key, Honeybee uses the right-hand rule (assuming counter-clockwise vertices) to determine the direction that the Face3D is facing. When users cannot guarantee that their vertices will always be counter-clockwise, a input "plane" key will override the default right-hand rule enforcement, ensuring the Face3D is always written into simulation engine, with a direction that respects the "plane" normal.

The 5 Golden Rules of Honeybee Schema Geometry

For the geometry within a honeybee schema file to be valid, there are 5 geometry rules that must be respected. These are:

1. All Face3Ds must be planar
2. All Face3Ds must NOT be self-intersecting (like a bowtie shape)
3. All children sub-faces (Apertures and Doors) must be co-planar with their parent Face and lie completely within its boundary
4. All adjacent object pairs (faces and sub-faces with a Surface boundary condition) must have matching areas
5. All Room volumes must be closed solids

Schema users who are familiar with simulation engines like EnergyPlus know that there are many more rules beyond these 5 that often must be followed in order to have valid input for the engine. As an example, EnergyPlus requires all vertices of walls, roofs, and floors to point outward from a zone and to start from the upper-left vertex of the face moving counter-clockwise. Another EnergyPlus rule is that all windows and doors must point in the same direction as their parent wall. Yet another is that EnergyPus does not support windows or doors with more than 4 vertices, meaning that such objects must be triangulated in order to be represented in the energy simulation.

Thankfully, users of the honeybee schema need not worry about such engine-specific rules in order to create valid schema definitions that will align with the intentions of geometry authors once exported to simulation engines. This is because Honeybee possesses geometry libraries that will automatically convert to valid formats for a given engine before simulation. The only requirements that must be satisfied in order for this automated conversion to work is that these "big 5" rules must be respected. Otherwise, it will not be possible to determine things like which side of aRoom volume is outward vs. inward.