GSoC 2025: Styles support for MDA Universes

[PardhavMaradani]

Hi @BradyAJohnston and @yuxuanzhuang ,

I want to get started on the styles support for MDA universes next. I want to add both the API as well as the GUI at the same time to keep them in sync. Here is the GUI from the prototype that shows various options which will be supported in the API as well:

You might remember from the video in the proposal that all of these are dynamic in nature - style visibility, style type, selection string, uniform vs default colors and all of the style specific properties

Based on what I've learnt from the prototype, here is some relevant information:

Blender will crash if there are any structural changes to the node tree during the render process. This means any of the animated (keyframed) properties cannot make structural changes to the node tree like deleting/adding links/nodes, even muting nodes. Changes to the node inputs and other datapath values are absolutely fine. So, for example if there is a property to control visibility of the style and in the setter of it we are changing some links or muting a node, this will lead to a crash if this property is animated.

The only way I was able to get this working in the prototype was to have a stable node tree that only changed during style creation/deletion/switching (either from the API or GUI). All of the dynamic property changes (like visibility, uniform color, selection string etc) wouldn't change the node tree and hence they were animatable.

I looked through the recent style API changes #779 (API for adding & controlling multiple styles) and #851 (Add Configurable Styles Classes) as well as the code base and tried them out too. I will be able to reuse some of that work here, but there are still some challenges that need to be addressed.

Here are a few things I noted about the current implementation so far: Once a style is added using the add_styles API, only the style node properties can be customized using the GeometryNodeInterface. (mol.styles[0].some_style_property = ). We cannot change the color stuff, selection string or the style type and for this the interface needs to be at a level above the style node than what it is currently. The add_style_branch method only adds the required nodes based on the passed params. To have support for dynamic changes of all the above and not run into crashes later (as described above), we need all the nodes present, with node properties controlling their behavior.

The add_style_branch method will have to change as this is not part of a class that can be extended. We could simplify some of the node setup by adding some of these directly to the nodes themselves or creating new nodes (as part of MN data) - for example, a visibility boolean for each of the style nodes, a boolean to switch between a uniform color or a passed in color in the Set Color node (or a new node with this behavior). If this is not an option, the node setup in the add_style_branch will be a bit more involved that what exists today. Do you guys have any suggestions on which approach to take?

[PardhavMaradani]

Hi Brady, thinking about this a little further, here is another approach that could potentially work and has several benefits:
Given that all the required nodes have to be present (due to render time crashes issue mentioned above), how about we have a new node group called something like Style Branch or Unified Style that encapsulates all of these - color stuff, selection, switch between different supported styles etc and clearly exposing the configurable inputs.

With this, the GeometryNodeInterface for this node exposes all the configurable stuff for any API use (including only selected style specific params) and all of the properties will be animatable (including switching styles) and easily exposable to the GUI as well. This will also significantly reduce the code needed to add style branches and keep things much simpler. Do you see any issues with this approach?

[BradyAJohnston]

Ability to turn on/off the visibility of the style branch
Ability to switch between a uniform color or defined color themes
Ability to change selections (via the named attribute node)
Ability to switch styles

For this point I'd say that switching styles isn't necessarily something that needs to be supported for a branch, as this is the same as just removing and adding a new branch, or turning them on / off. Turning on and off a branch is also the same as adding or removing selections, either with nodes or attributes.

I'm been mulling this over and I think it's a higher level design decision that needs to be made about how we want the API to interact with entities inside of Blender. I'm still of the opinion that we should go with the node spread out approach. I'd like opinions from some others before we totally commit @yuxuanzhuang. @zachcp I think you'd have some good insight and opinions here as well.

The broader UX / design of Blender and the node-based systems are that options exposed on the UI of the node are intended interaction by the user and internal values are considered constant / not to be interacted with. I agree it would be easier to program with in terms of limiting nodes to iterate & interact with, but I don't think we should break the existing UX convention. The way to have to align with Blender's UX would be to expose every value onto the node's UI. This would be less bad now that nested panels exist, and I believe coming in 4.5 there is potential to hide / unhide sockets based on menu selections.

There is currently no way to identify which nodes correspond to which style branch - in other words, there is no unified view of what comprises of a style branch

The current approach is taking each connection into the Join Geometry node which signals the end of a branch and everything connected into it counts. This currently isn't handled as well as it could, there are lots of improvements to be made in this aspect, and these improvements in handling / programming with node graphs would benefit other aspects of MN as well. This isn't something that needs to be handled by this GSoC project solely, and is something that can be improved alongside it.

For changing colors, changing selections or any other attributes, these could be changed by changing the attributes on the mesh. For an API, these are easily 'viewable' to a user as arrays or data that exist on the mesh, that they can then interact and alter through any arbitrary functions that a user would like to use. This approach doesn't directly support keyframing, but is more powerful in terms of custom functions for varying values over time (color, selections, radii etc).

Sorry to answer your questions with maybe some more questions & unknowns, but I think it's worth trying to get some more opinions and thoughts before we commit more down one path or another.

[PardhavMaradani]

I will wait for further clarity. However, a couple of quick points on the comment above:

• It is too bad we will lose support for switching styles. I remember this being the first thing I wanted to try in a regular MN setup. Seeing this particular part working in the prototype showed how powerful it can be to iterate and customize styles. This also came in very handy during eventual animation setups
• About the UX convention - users can at any time use Ctrl G to group (ie., to create a node group) and Ctrl Alt G to ungroup - including the cases when we have it as a node group or laid out as separate nodes - I was only recommending the node group approach because it gives us better organization to begin with. Starting by appending a node group from the data file and ungrouping it gives exactly what you are suggesting with a laid out tree, but requiring a lot more book keeping

[BradyAJohnston]

It is too bad we will lose support for switching styles.

This is already possible by right-clicking and using Change Node. This operator could also be used elsewhere in the UI such as a panel to replicate what you are after.

CleanShot.2025-06-12.at.21.36.51.mp4

users can at any time use Ctrl G to group (ie., to create a node group)

This is of course true, but the general usage is to create a node group that contains internals that are re-used across multiple iterations of the node with values that change exposed to the interface of the node, as I have been saying. I'm not suggesting we append and ungroup a node. We continue with the current approach of creating new branches of a node tree as required.

[PardhavMaradani]

This is already possible by right-clicking and using Change Node. This operator could also be used elsewhere in the UI such as a panel to replicate what you are after.

This will however not be animatable.

My point about grouping and ungrouping is that users are free to use these features any way they want as per their respective use cases.

[BradyAJohnston]

This will however not be animatable.

Not through the changing of the node, but it is animateable through changing of selections (either through nodes, attributes or keyframed inputs to nodes) or through using switch nodes on different branches for different styles. The functionality will all still be possible.

[PardhavMaradani]

After thinking about this again in a lot more detail, I have a fundamental question:

Are we expecting users to interact with the Geometry Node tree that is managed by the API / GUI?

It seems like the answer is yes. If so, this to me seems to be the root of the problem.

External tools like ggmolvis, bmda or others like them in the future don't have this limitation. Of course in the headless mode there is no interaction with the MN trees and even in their GUI modes the expectation would be that the users will never have to interact with MN trees. Any features that require changes or enhancements to the underlying nodes will trickle down through the API/GUI changes. They are not burdened by any requirements of legacy support and hence are free to pursue their respective visions.

We here however, could be significantly limiting ourselves if we don't pick the right approach. I think the warning signs of that are already showing in our own self imposed restrictions. For example, it is true that the switch styles support can be achieved through other ways - the same argument can be extended to visibility and even at a meta level, why even have style branches because we get the equivalent of it with individual objects and their single styles etc - the way ggmolvis has it today. I think we can all see the issues with all of those arguments. It is also not necessarily about a particular feature - what if we needed to support this later - what would we do? Could we do it? How extensible is our design to accomodate that request etc etc. It seems like we are making it harder for ourselves and boxing ourselves in (at least to me).

It is practically infeasible to manage a tree that users can mess with. I can see several ways this can just go wrong - having thought through how this would impact the GUI etc from different scenarios. Do we really want to go down this path? There just doesn't seem to be two ways about this.

I will wait to hear more thoughts from all of you folks and the approach we pick and guidance on how to move forward, because at this time it isn't quite clear to me and I really need help.

[BradyAJohnston]

I think this is the right question to be asking, and the answer varies depending on the situation.

A situation that was entirely run through a script, as part of a larger pipeline or just a small render script / part of a jupyter notebook that has no UI / GUI component, then you can be pretty confident and expect that a user wouldn't interact directly with a node tree. If we were just dealing with that situation then I agree that your node-encapsulated version is the better way to go.

For the situation where a user is using Blender / MN via Blender's GUI, then yes I would expect a user to interact with the node tree. Even if we wanted to try and encourage them not to, there is no way within Blender to limit a user from interacting with a node tree themselves and going in to adjust values. We could encourage users not to, but we would want to potentially handle a situation in which they did so. Regardless of how we built it, to made it robust we would have to build and be ready to handled changes the node tree node coming directly from the API. This is ultimately just one of the pain points of programming within Blender or a GUI application.

More importantly, the overall message should be that we want users to try and interact with the node trees. Programming with node trees is unfamiliar to most the first time they come across it, and common feedback I get from some users is a desire for a more traditional UI like the one you have been building. I think that's a worthwhile addition and can help do some things faster than through interacting directly with the node tree.

Ultimately though, the power of Blender, Geometry Nodes and Molecular Nodes IS the node tree. What sets it apart from other molecular visualisation programs is the power of a node tree. None of this would be possible without the node tree, and there is so much more that is possible than we can hope to directly support through API & UI in terms of bespoke node trees that users can build. Part of the ethos of Molecular Nodes is to encourage users to use the node tree, so that they have the potential to build much more powerful and bespoke setups than we could hope to think of and support ahead of time.

When dealing with anything GUI, I think it's worth having some common operations possible through one-click buttons, but I believe we should be encouraging users to potentially use the node tree directly.

You do raise a very good point that it's hard to handle node trees that a user might be interacting with, in terms of building an additional menu / UI or altering the state of the node tree. This requires us to try and have better tools for dealing with node trees, but this isn't a bad thing. Without better tools for dealing with node trees, then the system is extremely fragile anyway and the whole thing breaks the second a user does something that isn't expected. We should always try and build as safely as possible, expecting from the beginning to have to handle these kinds of cases.

[PardhavMaradani]

I will go ahead with the changes as agreed upon at the end of this discussion. These are just some of my thoughts based on the comment above:

I think there could be ways to decouple these in such a way that it works best for both cases.

The same reasons about the fragility of managing the node tree work in favor of having something like a node group as a unit - which offers far better manageability and protection from tampering etc. For users who want to customize the node tree, again, having simpler entities, I believe would help - they could just remove that node and re-create as they see fit. If we need better tools for users to manage the node tree (which I agree will help a lot), we should really have them as separate options or operators under the n-panel for Geometry Nodes - right next to where the action is. These options could include stuff like resetting the node tree, setting up template node trees based on user choices (wizard like), adding set of nodes at once that bring in other functionality blocks etc. All of these would be independent and decoupled from the API or the main GUI, while still adding usability options for users wanting to manage the node tree manually. With an approach like this, we could get best of both the worlds - have the API/main GUI not limited by the node tree setup, tools for users that wish to manually manage custom node trees that don't interfere with the API/GUI.

[PardhavMaradani]

If all of the above discussion is too disruptive at the moment - and in the interest of unblocking myself and actually making some progress, I can make the following changes:

• Add a add_style method to the Trajectory class - following the lead of what already exists in Molecule entity. No changes to the common add_style_branch method
• Listing, get and remove are already supported by the returned GeometryNodeInterFace
• Add a new tab called Styles (next to Object and Session) in the existing MN UI
• List the styles added and show the corresponding style configuration - same as what is returned by GeometryNodeInteFace for API
• Add an option to add a style from the GUI, which takes in the same inputs as what is possible from the GUI
• Add an option to remove a style from the GUI (will correspond to the same remove from the API)
• The content in the Styles tab will work for both Molecule and Trajectory that current support style branches

Please let me know if I can go ahead with the above. Thanks

[BradyAJohnston]

Yes please go ahead with this approach. The GUI that becomes the Styles tab I think would also be well suited for the a menu / panel in the viewport that you previously demonstrated. For now go with putting in the current MN panel, but UI code is very portable and we can always potentially move it into a "viewport" panel for the kinds of quick style changes and adjustments that users might want to make.

[PardhavMaradani]

I made the changes as per my comment above. The GUI is in the new Styles panel that is part of the entities UI - PR #887 .

Here is a short clip as to how it looks:

entity-styles-ui.mp4

I will create a PR on the pre-requisite PR #877 is merged.

[PardhavMaradani]

Created PR #888 with the above discussed changes.

[yuxuanzhuang]

I don’t have much experience tinkering with the Geometry Nodes, so I may not have a lot to contribute here, but I do agree with @BradyAJohnston that while the Unified Style approach is appealing for its simplicity and being less error prone, it might lack the flexibility needed for more advanced use cases involving modifying the node tree.

I’m thinking in terms of different types of users:

• Advanced users who want to create bespoke renderings -> the current node tree structure is likely better.
• Users who don’t interact with Geometry Nodes at all -> for them, I suppose the underlying structure doesn’t matter.
• Developers using MolecularNodes to build higher-level rendering tools (e.g., ggmolvis) -> they (I) can either call API functions to modify the node tree or create individual objects with different styles (for scenerios a single object doesn't work), so they likely won’t care much about how the node tree is implemented either.

So from my perspective, as long as you can implement the desired features (e.g., dynamic style switching) with the current node tree structure, it makes sense to stick with it. It would also help a lot on the long run to implement the functions you mentioned to reset and/or fix a broken node tree for users.

[yuxuanzhuang]

Also, the way to update the exposed properties when the Geometry Node tree is modified manually (I may be repeating what you’ve already mentioned.)

[PardhavMaradani]

... as long as you can implement the desired features (e.g., dynamic style switching) with the current node tree structure,

We cannot have dynamic style switching (within the same style branch) in the current model because it would lead to additional style nodes etc breaking current behavior. We can however have any number of style branches.

Also, the way to update the exposed properties when the Geometry Node tree is modified manually

The current API model that Brady has for Molecule already exposes any changes to the style node inputs (even manually) to the API. The ones for Trajectory follow the same model - they are exposed to the GUI as well

[PardhavMaradani]

Closing this as PR #888 is merged. We could revisit some of the discussions here at a later point.