Node icon

[jonnew]

The library needs to have an SVG icon that is applied on top of the nodes in the Bonsai IDE. @glopesdev keeps hinting that there is some logic or underlying meaning to the icons rather than just 'branding'. I would like to understand this strategy and try to respect it. I will guess that one thing the icons fulfill is they serve as an indication of the namespace an operator belongs to. So, e.g., Reactive.Concact and Dsp.Concat get some functional, visual distinction between them via their icons.

In this vein, I'm attaching the standard Open Ephys icon since this projects namespace is OpenEphys.

(white so might only be visible in dark mode)

[glopesdev]

I'm tagging @jfrazao here so he has the chance to feedback directly. We've been discussing this for several years and the main worry with the top-level namespace interpretation is that it tends to push the information content of individual icons close to zero.

For example, if we had just placed the Bonsai tree logo on all nodes of every package in the bonsai-rx org, there would almost be no point in having node icons since they would convey no functional meaning.

Instead we decided to never actually use the tree logo in any operator and have converged and @jfrazao carefully designed a family of 16 functional element icon nodes which are baked into the editor to be used by any package: https://github.com/bonsai-rx/bonsai/tree/main/Bonsai.Editor/Resources/ElementIcon

Even though not every icon will be appropriate in every single case, and we certainly will need new icons in the future, I think it still increases readability over having the same icon replicated across all packages.

Example: functional data families in Onix1

For example in the case of this library, we could have custom icons but they might for example represent functional families of ONI devices, e.g. BNO, cameras, ephys, microscopes, and/or differentiated Data nodes which could tell you something about the "family" of data coming out.

Example for functionally differentiated data nodes. I'm mindful of the inconsistencies, my only point for now is it gives us a chance to differentiate information content.

Legend	Icon	Name	Description
	Daq	Create, configure or initialize general data acquisition devices
	Dsp	General IO signal source or processor
	Neuro	Continuous neural signal source

Example: functional device families in Onix1

We could also introduce a visual language for "device families" (probes, miniscopes, cameras, stimulators, IO boards) which would each have their own icon.

Alternatively we could also differentiate per package, so it becomes possible to tell visually whether you are using Onix1 or Onix2 system in the future for example.

[jonnew]

Yep, I hear all these arguments. Our main counter point is not really arguing in opposition to this, but just a time allocation issue. We don't have the resources to produce a new icon for every piece of hardware that won't look like 💩 and will be distinguishable enough to be useful, I fear.

That said, I will document an opinion I have: The icons are useful, especially for distinguishing operators with common names from different namespaces. I think namespace distinctions are the lowest hanging fruit for the utility of the icon. The next level conveys something about functionality as your post explains. But, IMO, there are more clear and powerful ways to do this that supersede the icons and should have effort put into them instead:

1. Proper and clear documentation that is clearly linked (in a psychological sense) to what the user is seeing in the editor and that provides straightforward guidance on how to use an operator.
2. Some visual distinction concerning the data type of a connection rather than the operator itself. This might mean some pop up icon or even just text box when you hover over a line in the graph that shows the inner type of the observable sequence.
3. Real-time changes to the workflow's presentation depending on ongoing edits. For example, when a click and drag is started, greying out all nodes that the drag cannot connect to due to IO type conflict (hard) or at least disallowing connections between nodes that result in a compilation error.

[jonnew]

@glopesdev, just to be clear, were you suggesting in your comment that as an intermediate solution we could actually use the existing icons from other packages? If that's the case, it makes sense to me to just reuse the standard icons.

However, I always figured that those icons were not for third-party use. e.g. the DSP icon was reserved for operators that operated on sequences of cv.Mats and basically represented the Bonsai.DSP namespace.

[glopesdev]

@jonnew Yes, that was exactly the suggestion. To be fair, it is entirely on us that we didn't document and clarify the intended use of the standard icons to the community, and this is something we want to improve, but indeed those icons were designed to be reused in any library.

We are planning on promoting a community discussion around these icons soon, and potentially review requests for new icons. Perhaps once we gather feedback from that conversation we could revisit this?

[jonnew]

@glopesdev Got it. I didn't appreciate that in your original suggestion.

I think my issues with this approach are still valid though: for better or worse, when I see e.g. the DSP icon, what I am assuming in my head is that i came from the DSP namespace. And frankly, IMO, I think its for the better. Why?

I can think of 3 major things I feel should be knowable about a node at a glance:

1. The IO type and compatible upstream and downstream connections. You've told me how hard it is the do this correctly (e.g. when you click and drag muting all nodes that would result in a compilation error). The icon might provide a hint, but its not expressive enough to serve this purpose correctly I don't think.
2. The operator category. Already given by the color and little flourishes for indicating that a connection is available. This seems right to me already.
3. Namespace the package belongs to and or the package itself. We know this is useful information because the programmer went through great pains to categorize functionality into discrete packages, and decide what belongs in a particular package and what does not. This information is accessible by clicking on a node and looking at the namespace, but its not knowable by looking at the workflow as whole and seeing which packages are responsible for which nodes in the way that the operator category (2) is.

I think the icons really are best suited for 3. I think its important information to convey and the right job for the icons. This would still not be a branding thing. e.g. the Miniscope logo I made does not show the UCLA miniscope logo but something more general, I hope at least:

In the case of this issue, the icon should probably not show the OE logo, but some simple visual summary of the package theme seems valuable.

[glopesdev]

In the case of this issue, the icon should probably not show the OE logo, but some simple visual summary of the package theme seems valuable.

This notion of "theme" is exactly what we were going for.

Currently, if you see a "camera" node on a green background, you know that the node is going to somehow stream frames from a device or file, or network source somewhere. It's not associated with a specific type, it might be a DataFrame or a Bitmap instead of an IplImage, but you will know the main output is video related. The main advantage of having a small set of common icons is that it increases the chances you will remember the "theme" and not be misled by possible misinterpretations of the icon.

We definitely do not associate the "camera" icon with a specific package, as all video acquisition packages use it, not just Bonsai.Vision. Its counterpart, the "camera" sink for video files, is also widely used for video encoding packages such as FFmpeg, etc.

If we start to mix and match vendor, and namespace, and theme in the same package, IMO this would be the most confusing of all worlds, since suddenly people will have to learn not only the provenance of each node, but also the visual "glossary" of how that particular vendor understands themes, which will make the iconography degrade further in value. We can discuss whether a microscope frame grabber and a webcam frame grabber are so different to merit splitting the concept into a different category, but even in that case having a single icon for "microscope" would be preferable in our opinion.

For example, stripped out of context I can imagine the current miniscope icon could also be seen as an LED. Of course this is true of all icons, and this is why we believe having a small, recognizable set, is valuable as it increases chances of retention.

Me and @jfrazao have been having these debates for years and we would very much welcome community input on this and arrive at some sort of consensus. Since this is such a fundamental part of the visual language, it feels like we should investigate what opportunities might be gained or wasted by going one direction or the other at this stage.

[jfrazao]

Hi jonh Nice we are converging.

Namespace is a hint for defining icons, but The main useful thing of the icons and the rest of iconography is to increase readability of the workflows for the programmers, to identify at a glance what the parts of workflow are dedicated to do.

Part of the nodes visual elements is like identation and syntax higlighting in normal languages, And the high order operator icons are just like the operator keyword. The objectif is again to helps to read and make sense of the programatic expression tree.

For that It is also usefull to somehow identify the type data that goes throught the tree, because it helps read the program. but in one side of the sprectum everthing is bytes, and in the oposite side, everthing has its own type, and neither end of the sprectrum would be usefull to read a program, so we went to the MOST USEFFULL ONE. Unfortunatly is the messy gray area between between both. the one where is hard to decide, where no rules can be written. where discussions like this need to happen.

Probably we are missing a couple of icons, for some of the non-nested high order operators, and the ones more strange like materialise. catch. and so on.

probably we are missing a way to assign a icon, for the group workflows. like you can when you define a code operator, you could also assign one of the language icons for a nested one, in reallity anything you can assign programaticly there shuld be a way to do it in a consistent way when you define a operator in visual code. like the most recent way to define visualizers programatlly in visual code..

[jonnew]

OK. I understand now. Given this:

1. Is there a list of standard icons somewhere and some process for adding them?
2. Is there a set of documentation for in which situations these icons should be used?
3. Instructions for how to use an icon or set of them in package? This one is important because I've only ever used icons by creating an SVG with the same name as the package and including as embedded resource. However, the proposals above would require many different icons to be used in this library.

This could be a bonsai-icons repo with a verbose README and icons reviewed through issues and pull requests. I think that this is going to be required if the community is going to create packages that use icons correctly.

In any case, I'm happy to try to follow this way of doing things!

[glopesdev]

1. Is there a list of standard icons somewhere and some process for adding them?

Probably the best list is in the editor resources folder and the other sister folders.

2. Is there a set of documentation for in which situations these icons should be used?

No, and it should definitely exist, this one is completely on us and we will work to add it to the docs before the dev conference.

3. Instructions for how to use an icon or set of them in package?

Also no explicit docs for this other than examples, but at least they all follow the same logic if you pick the names from the list above, e.g. see FileCapture

This could be a bonsai-icons repo with a verbose README and icons reviewed through issues and pull requests.

We do have exactly this repo at bonsai-rx/bonsai-icons, but it needs to be better organized and documented. With a bit of work it could become the central repository for reusable community grown icons.

In any case, I'm happy to try to follow this way of doing things!

Great, that's awesome, we're happy to discuss problems, pros and cons of when to use one icon family versus another one, and consider the need for new icons.

[bparks13]

I'm not sure if these images were used as inspiration for the icons already, since a couple of them look quite similar, but I found Bootstrap icons while working with Docfx. It's an open-source list of icons that we could probably utilize, which might help so we don't have to generate new icons from scratch.