Differences between gbXML and HBJSON

[s183504]

I am currently investigating the different schemes provided for translating data between different applications. (IFC, gbXML, etc.)

I saw the demonstration of Pollination for exporting a sample model from Revit to HBJSON and then translating it to gbXML, and was wondering what the technical differences are between direct export from Revit to gbXML and going through HBJSON first, since the latter seems to produce a much more reliable product.

[mostapha]

Hi Casper(@s183504),

@chriswmackey can give you a more comprehensive answer to this question. I want to add a few links and some clarification here.

@s183504

I saw the demonstration of Pollination for exporting a sample model from Revit to HBJSON and then translating it to gbXML

Pollination Revit exports to many other formats besides gbXML. But you are right that it initially exports all the models as an HBJSON and then translates them to other file formats including gbXML.

@s183504

what the technical differences are between direct export from Revit to gbXML and going through HBJSON first, since the latter seems to produce a much more reliable product.

A good place to start to read about HBJSON and its structure is here. It documents the schema and some of the core decisions that shaped how HBJSON is designed.

Home

In my opinion, the reasons that make HBJSON a better interoperability schema than gbXML are:

1. It has a built-in validation. If your model is valid then it should be translated to other formats correctly.
2. It doesn’t stop at being only a schema. We also developed several translators to export to other file formats and read from other file formats. By taking the responsibility of doing so we can guarantee end-to-end quality in the process. As of today, you can export an HBJSON file to GEM for IES-VE, INP for eQuest, IDF for EnergyPlus, OSM for OpenStudio, RAD for Radiance, and IDM for IDA-ICE. It also exports to gbXML.
3. It has only 5 rules for geometry. The rest of the platform-specific nuances are taken care of in each translator. This approach minimizes the possible points of failure. 2.1 Face3D Schema · ladybug-tools/honeybee-schema Wiki · GitHub
4. It has been built to be extendable from day one: 1.2 Extending the Model Schema · ladybug-tools/honeybee-schema Wiki · GitHub - That has kept the core part of the schema smaller and easier to maintain. It has also made it possible for other developers to extend the schema without us making any changes to the core schema. Honeybee Passive House is one of the examples.

The reason that it works well for the Revit plugin in particular are:

1. The Pollination Revit plugin approach is to allow the user to help the extractor by providing information about the model. For example, we don’t try to guess what elements should be exported as apertures. We let the user decide.
2. Pollination routines for extracting the analytical model are better than the one that is used natively by Revit. We took a serious stance on the importance of the quality of the geometry.
3. Pollination has several automated fixes and checks for preparing the analytical model during the export process.

Hopefully, this gives you enough information to get started. Let us know if you have any other questions.

[chriswmackey]

Hi @s183504 ,

Thanks for your question.

I don’t know if I can comment much on what happens in the native Revit gbXML export because we’re not the authors of it. But I can confirm that I have not found a case where someone preferred to use Revit-native gbXML export over re-tracing geometry in the destination energy modeling software. It just seems that the cleanup work required to make the open Room volumes from the Revit-native gbXML usable is greater than the work of re-tracing over plans and elevations in the destination BEM software.

Conversely, I know of many people who have used the HBJSON-assisted pathway in the Pollination plugins to reach their destination energy modeling software without re-racing over the geometry from plans/elevations and this saved them a lot of time. Most people these days will use the built-in translators from HBJSON to IES-VE .GEM format, or eQuest .inp format, or IDA-ICE .idm format, or OpenStudio .osm format instead of the gbXML pathway. We’re usually able to match things better to the destination BEM software by using their native formats and gbXML has some fundamental limitations that I’ll list below. But gbXML is still the preferred way to export from Pollination to DesignBuilder and most BEM software still supports some type of gbXML import, though it often does not work as well as the import of native file formats like GEM, inp or idm.

As @mostapha said, a lot of this can be chalked up to the fact that we designed HBJSON with a clear set of geometry rules and we released the first versions of HBJSON with a Command line interface that can validate your HBJSON files and give you a detailed list of everything that is invalid about a given HBJSON file. This command line interface is used throughout the pollination plugins and it draws a line between what needs to be fixed within the CAD/BEM software vs. what’s the responsibility of us to fix as the authors of translation pathways from HBJSON to different simulation engines. Essentially, if your model passes this validation and is somehow not simulate-able in an engine, then it is our responsibility as the authors of HBJSON to fix it in the translator.

The development of gbXML did not happen with as clear of an agreement about what makes a valid vs invalid gbXML, which created a situation where each BEM software and CAD/BIM interface did their own interpretation of what a valid gbXML meant for them. For example, the authors of the Revit-native gbXML translators clearly think that open Room volumes are acceptable in gbXML and EnergyPlus kinda allows this but IES-VE relies on room volumes being closed for it to work correctly. It wasn’t until a few years ago that an online validation tool for gbXML was published, which has helped a lot in addressing this situation. But it was released well over a decade after gbXML was first published and most gbXML importers/exporters have not been updated to follow the recommendations of the validator.

Aside from this, there were several “geometry best practices” that we learned from using Rhino so much over the last few years, which we embedded into HBJSON but weren’t necessarily common knowledge when gbXML was first developed. To give a short list of these things:

1. Holes in planar geometry - The planar geometry specification used in HBJSON has a separate property for the vertices of “holes” from those that make the “boundary” of the geometry. This may not seem remarkable but gbXML has no such distinction, which was probably ok for most BEM platforms at the time gbXML was first developed, which did not support holes in planar geometry. However, practically all CAD and BIM platforms support holes in planar geometry and it can be real challenge to map things from CAD/BIM to BEM without this.
2. Adjustable Model tolerance and units - The HBJSON format includes a property for “tolerance”, which allows you to specify when two vertices that are close to one another are considered equivalent. Like holes, this may not seem like a remarkable property but it’s practically impossible for HBJSON to work as well as it does without this. Without tolerance, we could not reliably tell you whether a given room geometry is closed and without geometries being closed, we could not ensure that all Room Faces point outwards from the Room volume, auto-assign specifications for Floor/Ceiling by normal direction, automatically solve adjacency between matching geometries. Tolerance is critical for almost all operations we perform on the geometry. And the important thing to recognize is that every BEM engine and CAD/BIM platform uses different default tolerances. EnergyPlus/OpenStudio has a fixed native tolerance of 1 cm that cannot be changed. Revit has a native tolerance of 0.001 feet, which cannot be changed (yes, Revit uses feet as its native geometry units). McNeel was smart and designed Rhino with a tolerance that can be changed for different use cases and geometry sources. We borrowed this idea from them and similarly designed HBJSON with adjustable tolerance and units. It has paid off tremendously in our ability to absorb geometry from any platform, successfully perform geometry operations on it, and translate it to other places that may use a different tolerance or units system.
3. Support for orphaned objects (and loading “incomplete” models) - Most BEM applications have a strict nested hierarchy from Room/Zone> Face/Surface/Wall/Roof > Aperture/FenestrationSurface/Window. And you can never have a Window without a parent Wall, for example. The rigid hierarchy is often helpful for ensuring valid input but it makes the format a poor medium to build, edit and fix incomplete models. It’s partly for this reason why HBJSON allows you to make “orphaned” objects, which are outside the hierarchy but, perhaps with some editing, can become a part of a valid Room. It’s also helpful for engines like Radiance, which really do not care about the Room hierarchy. But our general philosophy of letting you load incomplete models into plugins like Pollination Rhino without dismissing the geometry as invalid and not letting you open it is important for being able to fix things.

Hope that helps.