Honeybee Schema and Dragonfly schema questions

[theo-armour]

I am looking at the Honeybee and Dragonfly schemas From looking at the API documents and the sample files - briefly - the schemas appear to be more alike than different.

1. Which of the two following missions looks like being the better short term plan?
   • Build a single app that browses, loads, displays and edits files from either schema
   • Build two apps with customizations tailored specifically for each schema
2. Apart from loading the whole file and searching for a string like "room_2ds", is there a way of identifying which schema and which version of the chema a JSON file adheres to?
   • I note that users easily believe that any file with the extension they are looking for also contains data in the format they are looking for. Thus it is important for me in building a viewer to find ways of "shooing away the stray cats" quickly and easily
3. Is there a set standard or rule for the organization of vertices in faces, doors, apertures, shades or whatever?
   • Creating polygons with holes is a bit of a tricky business. Any "business" is possible, but the greater the number of possibilities the greater the number of required input checks. In order to reduce the lines of code, I think I am correct in assuming there there will never be things like a series of top and bottom pairs of vertices, or all the top vertices then all the bottom vertices, or intersections and so on. In order words, all vertices will always run around their borders sequentially.
4. Is there a standard or rule for the clockwise or counterclockwise order of faces, doors and apertures?
   • Three,js triangulates vertices using the Earcut polygon triangulation algorithm. The clockwise-ness of all boundaries needs to be set correctly for all openings in a face in order for the algorithm to complete without error. I am finding that rules I create for one sample file do not always work for other sample files. Any guidance will be appreciated. Even knowing there are no rules would help because then I would start with every boundary needs checking - apertures and doors may have any combination of directions.
5. Will shades need checking for apertures?
6. Where should items such as latitude, longitudes, address, revisions and similar items be added?
   • I have looked at the documents for the two schemas and looked at https://github.com/ladybug-tools/queenbee. I have not yet found suitable locations

Please let me know if you would like any of these items to be submitted as separate, individual issues because there may need to te discussion.

[mostaphaRoudsari]

Hi @theo-armour, Thank you for posting these questions. I give it a try and @chriswmackey will add more details for what I will miss.

1. I prefer one application for both. Dragonfly-schema is a simplified version of honeybee-schema when it comes to geometry. They both share the metadata for different simulation properties. A detailed documentation of the honeybee-schema can be find here: https://github.com/ladybug-tools/honeybee-schema/wiki

2. Our schema is currently missing a meta data section to include such information. I agree that we should add one.

3. See the 5 golden rules of honeybee geometry here: https://github.com/ladybug-tools/honeybee-schema/wiki/2.1-Face3D-Schema#the-5-golden-rules-of-honeybee-schema-geometry

4. same link as 3.

5. Not sure about the answer to this one.

6. Location is not currently part of the model. In honeybee / ladybug buildings are separated from location. This separation provides the flexibility to locate the same model in different locations for running different studies. For instance one can run a model in 5 different locations with 5 different climate zones for a comparative study. We identify the location as part of the "recipe". I understand that you will need a location for shadow studies. I also understand the buildings are in a certain location when they are built. We probably will need a different way to let the user to provide that information. For instance, if it is desired the user can set the location from the viewer itself after loading the model?

[chriswmackey]

Thanks for the question, @theo-armour and thanks for taking a stab at them @mostaphaRoudsari .

1. I think it might be best if the honeybee schema is the only one that we build a viewer for right now. All dragonfly models can be converted to honeybee models and so building a viewer for Honeybee essentially means that we have a viewer for both Dragonfly and Honeybee. The inverse is not true, though, (many honeybee models are not convert-able into dragonfly models) so a dragonfly viewer is a bit less useful than a honeybee viewer. If you add to this the fact that Dragonfly is really a 2D schema and an ideal dragonfly viewer/editor is probably more like a geoJSON viewer or an interface where you can browse each story of a building in plan view, I am inclined to think that a Three.js viewer for dragonfly is a future add-on to the honeybee viewer rather than its own interface. If you were to build a 2D-plan viewer/editor for dragonfly, @theo-armour , then the Dragonfly viewer could be its own separate thing but, as I said, I think this is a lower priority.

2. A metadata tag would be a good idea and maybe we can add this as a property of the Model in the schema. Normally, you could use the '"type"' key that all objects in the schema have in order to identify if something is a model. But the "type" key of both the honeybee model and the dragonfly model are the same (it's "Model" for both). So I guess we will have to add some other properties to make this info clear.

3. Mostapha pointed you to the right resource here. And yes, all vertices always run around their borders sequentially.

4. You may need to elaborate here. In the Python libraries, we enforce the right-hand rule and so all models exported from the Python libraries will have counter-clockwise boundary vertices with respect to their plane. Also, the order of child Aperture/Door vertices will match that of the parent Face when exported from the Python libraries. So all of the samples in this repo should follow these rules. HOWEVER, we are trying to not require all of the schema users to enforce these rules because it gets very tedious and we know that this will limit the number of exporters that other developers are able to build for the schema. So, if a schema user supplies a Plane object for a Face3D that results in clockwise vertices instead of counterclockwise ones, we still count it as a valid schema object and, when the JSON eventually gets imported to our Python libraries, we reverse the vertices so that they are counter-clockwise in the plane that the user supplied. BTW, there is no enforcement of any vertex order for holes within Face3Ds. It's only the boundary vertices of the Face3D that are coordinated with the Plane normal.

5. Definitely need some elaboration here. What type of check are you talking about and are you only referring to Aperture-assigned shades or shades assigned anywhere in the model?

6. Mostapha got this one

[chriswmackey]

I also just realized that the 4 large JSON samples that I gave you on the google drive are probably pretty bad given a bug that I just discovered in the export process from Rhino. Let me re-export them now.

[theo-armour]

@chriswmackey

They mostly seem OK to me

https://glitch.com/~honeybee-viewer-lt-2020-05-03

Though I'm having some issues interpreting things

[mostaphaRoudsari]

Hey @chriswmackey, thanks! Is there a reason that we don't put them on GitHub instead of Google Drive? Thank you for fixing them. Then there is a good chance that the viewer works fine just as is.

[chriswmackey]

Well, I can at least say that the lab complex and my mother and law's house had way more vertices than they should have. I just uploaded two new versions of them. The urban one should be all good and it looks beautiful in your viewer!

[chriswmackey]

The reason why I didn't push them to github is because of issues like the one I just encountered. They are going to be outdated and incorrect fast because I have manually re-export them each time.

[chriswmackey]

If it's critical that we have some reliable samples of large models, I can invest some time into making Python scripts that we can automatically re-run every time there is an update to the schema. But I don't want to put samples on github unless we can reliably and automatically re-make them every time we change stuff.

[chriswmackey]

It seems like it's going to be worthwhile to have regularly-updated large models to help with the viewer development so I opened an issue (https://github.com/ladybug-tools/honeybee-schema/issues/123) and I will try to get to it soon.

[theo-armour]

The Wiki at https://github.com/ladybug-tools/honeybee-schema/wiki looks like it could really help. I did not know or had forgotten its existence. Kindly add a big link in the Read Me and in the API docs.

---

@mostaphaRoudsari @chriswmackey

Thank for the detailed and thoughtful feedback. You have clarified and simplified my thinking. Do the following points sound OK to you?

Recapitulation

1. The Honeybee Viewer will be a single suite of app that can browse, open. parse, edit, display and save any combination of Honeybee and Dragonfly data - ranging from embeddable bare-bones viewers to full 3D IDEs (in your dreams).

2. Meta data: For the time being I will add meta data as userData. Something like "schema": "dragonfly".

3. Boundary vertices: sequential around the planar boundary.

4. Sub-face boundary vertices: ditto and allow for them to be either clockwise or counter-clockwise.

5. Shades with sub-faces: not illustrated in any of the diagrams in the wiki. Therefore will not allow for shades with holes - for the time being.

6. Location, revision and other instance data: Until details of the "recipes" become clear, I will add and fetch this kind of data in as userData

[mostaphaRoudsari]

I very much like the idea of using user_data field for now for model and version until we have an standard way to distinct the models from each other.

[theo-armour]

I think all issues here have been dealt with well enough for now