geo_viewer_api

Geometry Viewer API tutorial

The geometry viewer is accessible through the API. The current configurations include displaying data and color rendering. Below is the full script that accesses the geometry viewer API.

import BuildSimHub as bshapi
project_api_key = "f98aadb3-254f-428d-a321-82a6e4b9424c"  
model_api_key = "b86d9ddb-645b-4dad-b96e-1856b5a0ed48"  
  
bsh = bshapi.BuildSimHubAPIClient()  
model = bsh.model_results(project_api_key, model_api_key)
display_json = dict()  
display_json['type'] = 'zone' # required: surface or zone  
display_json['unit'] = 'Watt'  
display_json['color_scale'] = 'yes' # optional, if color is presented, color scale will be set to no  
  
data = dict()  
data['SPACE1-1'] = 26627.78  
data['SPACE2-1'] = 11233.23  
data['SPACE3-1'] = 25892.06  
data['SPACE4-1'] = 11233.23  
data['SPACE5-1'] = 21035.68  
display_json['data'] = data  # required  
  
# you can pick your own color if the color_scale is set to no  
color = dict()  
color['SPACE1-1'] = '0x1A535C' # color format is 0x + RGB hex code  
color['SPACE2-1'] = '0x4ECDC4'  
color['SPACE3-1'] = '0xF7FFF7'  
color['SPACE4-1'] = '0xFF6B6B'  
color['SPACE5-1'] = '0xFFE66D'  
# display_json['color'] = color  
  
# additional display information  
info = dict()  
info['SPACE1-1'] = [{'key': 'sensorId', 'value': 'x2232'}]  # color format is 0x + RGB hex code  
info['SPACE2-1'] = [{'key': 'sensorId', 'value': 'x2642'}, {'key': 'thermostat', 'value': 32}]  
info['SPACE3-1'] = [{'key': 'sensorId', 'value': 'x8392'}]  
info['SPACE4-1'] = [{'key': 'sensorId', 'value': 'x3323'}]  
info['SPACE5-1'] = [{'key': 'sensorId', 'value': 'x3222'}]  
display_json['info'] = info
model.bldg_geo(display_json)

Now let's break the code down and explore how to utilize the 3D geometry viewer API fully!

API structure

The 3D geometry viewer API request consists of two major components

1. Script to access API
2. A JSON data structure that specifies the data and color rendering rules.

The script to access API can be easily written with the python library.

import BuildSimHub as bshapi
project_api_key = "f98aadb3-254f-428d-a321-82a6e4b9424c"  
model_api_key = "b86d9ddb-645b-4dad-b96e-1856b5a0ed48"  
  
bsh = bshapi.BuildSimHubAPIClient()  
model = bsh.model_results(project_api_key, model_api_key)

model.bldg_geo()

That's it! With this code, you can successfully open the 3D geometry viewer. However, the 3D geometry viewer does not display any data in colors. To enable color rendering, we have to supply the data in JSON format.

JSON data structure

JSON is the primary communication data structure between the local computer and the BuildSim server. The JSON can be easily created using python dict data structure (dictionary).

Now let's try to assemble a example script.

Define meta data:

There are three metadata a user can specify.

1. type: Required metadata. The type is used to specify which level of data a request want to display. The choice for this field should be either zone or surface.
2. unit: Optional metadata. When this field is used, the unit will be displayed on the geometry viewer along with the data.
3. color_scale: Optional metadata. If gave yes, then the color scale will be automatically calculated based on the data given in the display_data. The user can also supply their own color by checking this field to no.

display_json = dict()  
display_json['type'] = 'zone' # required: surface or zone  
display_json['unit'] = 'Watt'  # optional
display_json['color_scale'] = 'yes' # optional, if color is presented, color scale will be set to no.

Data - {Required}

Data key carries the data - for example, room air temperature or peak loads. The data should also be arranged in JSON format. Similarly, we can use python dictionary to achieve the same effect.

data = dict()
# if we define the type is surface, then the key in data should be the surface names
data['SPACE1-1'] = 26627.78  
data['SPACE2-1'] = 11233.23  
data['SPACE3-1'] = 25892.06  
data['SPACE4-1'] = 11233.23  
data['SPACE5-1'] = 21035.68 
# Once complete, insert the data to the main JSON 
display_json['data'] = data  # required 

data is a required input. If the data is missing, you will likely to receive an error message from the server like the one below:

find the track token...1-948-16001
Error:  supplied data is incomplete

Color {Optional}

Color is optional but very useful if the user has their own coloring rule. To activate the customized color option, we first need to check the color_scale field to no. This action tells the server to stop auto-scaling the colors, instead, using the provided color for display.

The color data can also be structured using the python dictionary. It should be noted that API color format should be 0x + RGB hex code. For example, the RGB of red color is (255,0,0). Its hex code is ff0000. To supply this hex code to a specific zone or surface, we need to define it as 0xff0000.

# you can pick your own color if the color_scale is set to no  
color = dict()  
color['SPACE1-1'] = '0x1A535C' # color format is 0x + RGB hex code  
color['SPACE2-1'] = '0x4ECDC4'  
color['SPACE3-1'] = '0xF7FFF7'  
color['SPACE4-1'] = '0xFF6B6B'  
color['SPACE5-1'] = '0xFFE66D'  
display_json['color'] = color  

Above image shows the comparison between rendering with the color field and without the color field. It should be noticed that if there is color data provided, the color scale will be hidden.

info - {optional}

Info is the information a zone or a surface can display whenever it is selected. The info is presented under the selection bars such as the one below:

The info is also structured in a JSON format / python dictionary. The only difference is it is in a dict - list - dict format.

info = dict()
info['SPACE2-1'] = [{'key': 'sensorId', 'value': 'x2642'}, {'key': 'thermostat', 'value': 32}]

The above code initiates a info in dict, and then add data to the key SPACE2-1 in the info. The data is a list - dict format. The dict should only contain two keys: key and value . In the above example, we want to show the sensor ID and thermostat value in zone SPACE2-1, we and add these data into the info. Rerun the code, we can examine the zone SPACE2-1 again. The data is now displaying on the 3D geometry visualizer!

Future Dev.

Access 3D geometry viewer through API gives maximum flexibility on the data displaying. In the same time, it is also easier for integration on the user's own applications.

The future development around the 3D visualizer includes:

1. More flexibilities on integrating the 3D visualizer
2. Data display at HVAC system level (air-side)
3. Multi-data display

If you'd like to provide suggestions and comments, please ensure to submit a ticket at Github BuildSimHubAPI library.