Suggestions for Edits to Ladybug Graphic Standards

[chriswmackey]

Ladybug Community,
This issue has been created so that those who want to question or challenge the Ladybug Graphic Standards have a forum to do so. Also, if there is an important standard or guideline that we are forgetting, please also post that here.

Generally, I think a lot of us would agree that specifics of the standards don't matter as much as the fact that we have a consistent way of communicating as a community (ie. driving on the right or left side of the road does not matter as much as everyone driving on the same side of the road). Therefore, to give us a timeline with this, I think that we should aim to have the standards finalized in written format by the end of November and have them implemented on all components for the stable release in January. So here is the chance to speak now on the standards or forever hold your peace.

[chriswmackey]

I will venture a bet that many of us agree with majority of these standards but there are really only a few that we might discuss here. I am going to post some thoughts of @stgeorges here to get the conversation going (numbers refer to the points in the standard):

6. I somehow feel that coloring the whole component in a color different than working one, until the required inputs are supplied, is still a more valid way of saying to the user: "something is missing, do something", then letting it read the white speech balloon and readMe!. Of course, that's the sole purpose of these two, but coloring the component in different color while required inputs are still not supplied is definitively a more powerful way of informing the user that something is not ok.
   I think I would support the rule of usage of Remark (in cases of required inputs) if it would color the component to a different color (does not have to be orange), other than regular working one.
   I the end each grasshopper component when pulled down to the canvas uses Warning level, not Remark.

7. I understand the principle of having components which do not generate the geometry turned off. But at the same time I somehow perceive the feature of hiding some of the outputs for geometry generating components, a bit bizarre to be honest. One either shows every generated geometry or he simply hides them all. And sometimes it is not possible to show them all even if component's preview is turned on: some outputs (like "Sunpath shading" component's: quadrantShadingPercents, quadrantACenergyPercents, hoursPositions) require "Text tag" grasshopper component. Their results can not be seen independently.
   In my opinion, from a perspective of a regular user, it would be much simpler to turn off the whole component which generates geometry. And then use the appropriate parameters to "see" the one he likes. From this principle I derived the counter one - of having non-geometry generating components.

To give my response counter to @stgeorges , here are my original reasons for following these standards:

6. I recognize that the native GH components do not have a consistent method for dealing with colors when inputs are not connected. For example, the addition component remains grey while the multiplication component turns orange and gives a warning:
   
   Still, I do not think the example of GH team should stop us from setting a standard for ourselves. I prefer having the component remain grey when nothing is connected because the fact that the component is not running is not something that is wrong or that I feel the user needs to be warned about. If I connect something incorrect, then I want to know about it but, especially when I get canvases with tons of components on them, it gets distracting if I have orange components that are not actually malfunctioning. The second reason why I prefer to have the components remain grey is that I send out screenshots of components regularly and even publish these screenshots of components in papers like this:
   
   or this:
   
   So I know that this does not apply to all developers but, if anyone has the aim of publishing images of components, it is probably in your favor to have a default gre color when nothing is connected.

7. @stgeorges , I think that is is just going to be a mess for a large number of our components if we have to display ALL of the geometric outputs (the radiation study, sunlight hours, and view analysis will become almost unreadable without the user's help, for example). This would be a major problem for new users who are just learning how to use the empty geometry parameter components to turn the preview on/off of specific outputs. If you are arguing that we should just not ouput things like test points from these components, then I think you are too severely limiting the post-processing capabilities for advanced users. I appreciate your reasoning but, unless you can come up with a decent way of satisfying both the beginner and advanced user with the preview on/off capability, this seems like a major uphill battle.

-Chris

[mostaphaRoudsari]

Here is one more from Anders.

..., why is it that you guys set your components to always have icons on? When I use ladybug I always go in and set them back to the default component setting :D

I think he is right. We should probably follow the standards and let the user decide between icons and/or text. We can fix this automatically by adding ghenv.Component.IconDisplayMode = ghenv.Component.IconDisplayMode.application to the header.

[mostaphaRoudsari]

@chriswmackey and @stgeorges . Here is my 2 cents:

1. I agree that to have the component turn orange as soon as you drop it on the canvas is distracting but at the same time there are couple of issues with many of our components staying gray through the whole process. I would say that once user start connecting the inputs and one or some of the required inputs are missing component should turn orange. We can use Grasshoppers built-in functionalities for this to avoid extra work. Here is where '_' will be pretty important. By default GHPython inputs are set to optional but we should be able to change it with a script like this.

for param in ghenv.Component.Params.Input:
    if param.NickName.startswith("_") and not param.NickName.endswith("_"):
        param.Optional = False

I also have a comment about using the remark balloon in general. It overwrites warning/error balloons on the same component. This is very confusing and I have seen it frequently happening with Run Energy Simulation component. Here is an example. I even tried to change the order and it doesn't really help.

1. There are examples in Grasshopper that outputs are set to Hidden regardless of component's preview such as meshRay. Although I agree that in the first try it can be very confusing not to see the geometry while having the preview on for the component, on the long run it's a very helpful strategy to have them off. This saves everyone from extra unnecessary effort for hiding outputs and connecting selected ones to custom preview. At the end of the day, once you know this is the case it's easy to deal with it so I don't see it as a major issue.

[chriswmackey]

@mostaphaRoudsari and @stgeorges ,

A lot of your arguments have won me over to realizing that we should change a bunch of things. I have run into the issue a lot of times where I am teaching some new users how to use the components and they have not connected a required input but the component remains grey so they don't notice the problem. So I agree with your logic, @mostaphaRoudsari that we should have some code to check required inputs once an input is connected but have it remain grey until an input is connected. To propose a new version of this bullet point, I have re-written it be the following:

6. Components will remain grey when dropped on the canvas but, once any input is connected, the component should use Grasshopper's "Warning" capability (orange component) any time that there is a missing required input or incorrect type of input. Ideally, all of these warnings are given either before or within the input-checking function of the component (so all warnings are given before getting to the main function).

You are right that the over-writing of the Warning with the Remark is a big issue. After thinking about it, it does not seem to be worth waiting for the GH team to fix this. Like the native GH components, we should probably just stop being so sensitive and not be afraid to use the red "Error" feature if something really has gone horribly wrong. Therefore, I would agree that all information that is currently given out as a Remark should become either a warning or information that is printed out of the "ReadMe". This also means that some things that are currently warnings should be errors. To propose a new version of this bullet point, I have rewritten it as the following:

7. If a component gets to its main function but fails to run to completion, Grasshopper's "Error" capability should be used (ie. an energy simulation was started but failed because of incorrect inputs). If the component is running to completion and you you only want to give the user information about how the process has run, please use the "readMe!" output (by printing the message) and not any warnings, errors, or remarks. Grasshopper's "Remark" capability should never be used because it over-rides the color of the component in the case of warnings or errors.

Mostapha, I guess Anders right that we should give the user the choice of displaying the icons or not. Accordingly, I have taken this bullet point out of the standards but I think that this means that we should probably do some revising of the component names right before the next stable release since our current names that are 4 words long are not going to fly in a text display mode. I think this also means that I should just get used to working in GH in icon mode.

Finally, I added a clause at the end of the points that will give us all a little liberty and make clear that these rules should not stop anyone from going above and beyond:

10. No one understands best what a specific component should be telling its user better than the developer and those trying to apply it. Therefore, these standards should be seen as a minimum of what is required and any additional warnings, errors, or information that you realize should be given to the user is desirable and encouraged as long as you are not violating the general structure outlined in this document.

I suggest allowing another 2 weeks for people to see the revised standards and agree on them:
https://github.com/mostaphaRoudsari/ladybug/blob/master/resources/Ladybug%20Grahpic%20Standards.md
So, if you have any disagreements, you should speak now or forever hold your peace. After the 2 weeks, we will begin the process of implementing all of the standards across all of the components so that everything is good to go by the next stable release in January.

-Chris

[mostaphaRoudsari]

@chriswmackey and @stgeorges when I was trying to address this isseu (ttps://github.com/ladybug-tools/honeybee-legacy/issues/418) I found it tricky the component to stay gray once it's dropped on the canvas and start giving warnings as soon as there is one of the required inputs are connected. It's possible but needs some extra check that may not be really necessary. What is your input on that?

[chriswmackey]

@mostaphaRoudsari ,
With the code that you had put on this thread earlier, it seems like it will only take an extra 10 lines or so to accomplish what we are thinking with remaining grey until something is connected. You can see these 10 lines of code in the template file that I have just updated in resources:
https://github.com/mostaphaRoudsari/ladybug/blob/master/resources/Ladybug_Component_Template.py#L111-L130
We know that we need some type of extra check to put in this feature but it seems so short that I don't really see many issue with it.
Let me know if your thoughts,
-Chris

[stgeorges]

@chriswmackey and @mostaphaRoudsari ,
I apologize for taking me too long to reply.
I am having some personal issues and work to do, and still haven't resolved either of these. I will try to read up all this topic on Sunday.

[mostaphaRoudsari]

@chriswmackey thank you for the feedback. Looks like you really think it's necessary. Well, in that case I think it should be implemented in Honeybee/Ladybug check instead of having the user write it for every single component. Here is the implementation for Honeybee (https://github.com/mostaphaRoudsari/Honeybee/blob/a19e6888feaf42a8c7fd63a7a9aa8a5bc20d2fd1/src/Honeybee_Honeybee.py#L298-L318) which should be called after checking for version compatibility. Here is my suggestion for the template

#Honeybee check.
if not sc.sticky.has_key('honeybee_release') == True:
    print "You should first let Honeybee fly..."
    ghenv.Component.AddRuntimeMessage(w, "You should first let Honeybee fly...")
    return -1
else:
    try:
        if not sc.sticky['honeybee_release'].isCompatible(ghenv.Component): return -1
        if sc.sticky['honeybee_release'].isInputMissing(ghenv.Component): return -1
    except:
        warning = "You need a newer version of Honeybee to use this compoent." + \
        "Use updateHoneybee component to update userObjects.\n" + \
        "If you have already updated userObjects drag Honeybee_Honeybee component " + \
        "into canvas and try again."
        ghenv.Component.AddRuntimeMessage(w, warning)
        return -1

[mostaphaRoudsari]

PS: Check radiance material components as an example for implementation.

PSS: @stgeorges no worries. There is no rush for this.

[chriswmackey]

@mostaphaRoudsari ,
The plan looks good and I agree that a function like this should be living in LB_LB and HB_HB. I have changed the new component template to reference this function and put in a similar function into LB_LB:
50f4a1e
-Chris

[stgeorges]

Hi @chriswmackey , @mostaphaRoudsari,

Thank you for the replies. Apologies for taking me too long to reply.

I recognize that the native GH components do not have a consistent method for dealing with colors when inputs are not connected. For example, the addition component remains grey while the multiplication component turns orange and gives a warning.

They do have consistency. Standards sometimes break when they get to the extremes. Here's David explanation on why "Addition" currently does not turn orange when dragged to the canvas.
There is definitively a similar explanation for a couple of more which do not comply to this rule.
But the fact that there are exceptions to rules, does not mean we need to take the rules down. And this is why the rest majority of Grasshopper default components comply to this rule.
Every Grasshopper Primer released, on its very beginning explains the basics of Grasshopper by dealing with its component color coding system, and why components are orange when dragged to the canvas.

Still, I do not think the example of GH team should stop us from setting a standard for ourselves.

I agree that we do not have to follow each GH team standard.
But this is an important standard, and it is essential for the way Grasshopper components work. Again, yes, there are exceptions as we saw, but these exceptions do not mean we have to make it tottaly confusing, and reverse this standard.

I prefer having the component remain grey when nothing is connected because the fact that the component is not running is not something that is wrong or that I feel the user needs to be warned about. If I connect something incorrect, then I want to know about it but, especially when I get canvases with tons of components on them, it gets distracting if I have orange components that are not actually malfunctioning.

And this is exactly what the user should be informed about when he drags the component to the canvas: it requires a certain input, and that component does not contribute to the solution until a required input(s) is supplied. It's such a simple, and yet, useful standard.

The second reason why I prefer to have the components remain grey is that I send out screenshots of components regularly and even publish these screenshots of components in papers like this: So I know that this does not apply to all developers but, if anyone has the aim of publishing images of components, it is probably in your favor to have a default gre color when nothing is connected.

You can open each of those and simply add some code (e.g. "print"). That would last a couple of seconds.
You do not make screenshots of components each day, and it is far important to condider the impact some feature has on users, than something we do personally.

There are examples in Grasshopper that outputs are set to Hidden regardless of component's preview such as meshRay.

I have just checked "Mesh | Ray" component and its outputs are not hidden. I may be wrong, but to my knowledge no such default grasshopper component experiences this kind of behavior.

I will comply with both of your opinions, and I already implemented them in the newest edits of Photovoltaics components.

I acknowledge that my opinion on point 9) may be problematic.
I would still mention that the current solution for point 6): components which have required inputs, not turning orange when dropped to the canvas, is a very bad revision of default Grasshopper method.

[mostaphaRoudsari]

@stgeorges thank you for the post. It was nostalgic to see the old Grasshopper Primer- Very informative at the same time. I'm convinced that the components should turn orange if any of the required input is missing. I agree (and have seen it so many times) that it makes confusion for new users of Grasshopper. Experienced users know enough to handle warnings like this so I would vote for components to turn to orange once they are dropped on the canvas.

Back to number 9 for the same reason (not making users confused) I still think we should keep them hidden and users can make them visible by choice. Just imagine if Ladybug Radiation analysis shows testPts, testMesh, etc at the same time. IMO that would make a mess. You're also right about MehsRay component. I just checked and it shows up!

Again, all these rules are for making it easier for users to use the tool. If you think that showing all the results in your component will make it easier for users to work with the component then I think it will be totally fine as it is mentioned under number 10:

10. No one understands best what a specific component should be telling its user better than the developer and those trying to apply it. Therefore, these standards should be seen as a minimum of what is required and any additional warnings, errors, or information that you realize should be given to the user is desirable and encouraged as long as you are not violating the general structure outlined in this document.