Working with complex molecular scenes often means juggling dozens or even hundreds of visual models — each bringing its own style, data, and purpose. If you’ve ever felt overwhelmed trying to declutter your molecular workspace, you’re not alone. Fortunately, SAMSON’s Node Specification Language (NSL) offers a tidy and efficient way to manage what’s visible and what’s not, using a set of intuitive attributes known as visibility flags.
In this post, we’ll look at how to use vm.v (visibility), vm.vf (visibilityFlag), and their usefulness in scripting and searching. Whether you’re a researcher building a clean rendering for a paper or just trying to make sense of a crowded project, this feature of the NSL can be a time-saver.
The Core Attributes
Visual models in SAMSON can be filtered based on a few visibility-related attributes:
vm.v: Checks whether the visual model is visiblevm.vf: The internal visibility flagvm.h: Indicates if a visual model is hidden
The attribute vm.v is particularly useful because it evaluates the overall visibility state, considering both user control and visibility inheritance through the hierarchical scene graph. Unlike vm.h, which is directly controlled, vm.v reflects whether the model is actually being displayed at the moment.
Why This Matters
Imagine you have several molecules loaded, with various models representing surfaces, molecular orbitals, and secondary structures — and you need to render only a subset for a visual presentation. Instead of toggling visibility manually for each node, you can use quick NSL queries.
|
1 |
vm.v |
Finds all models currently visible.
|
1 |
not vm.v |
Finds all visual models that are not presently visible (useful for debugging).
|
1 |
vm.vf false |
Finds models whose visibility flag is disabled — even if they might otherwise be visible from parent nodes. This is particularly useful to troubleshoot why a certain model isn’t appearing.
Examples in Action
Let’s say you want to re-enable visibility on all hidden visual models:
|
1 |
not vm.v |
This identifies all models that are currently not displayed.
From there, you could select them and manually toggle their visibility, or write a script to do so programmatically — making large-scale visual adjustments faster.
Hidden vs. Visible: A Subtle Difference
It’s worth noting the subtle but important distinction between vm.h and vm.v:
vm.h: This is explicitly controlled by the user and reflects whether the node has been marked as hidden.vm.v: This is the effective visibility — it can befalseeven ifvm.hisfalse, depending on parent node visibility or flags.
This means you might encounter cases where a visual model is not hidden (not vm.h), yet it’s also not visible (not vm.v). These cases happen when its parent is hidden, or when flags override its status. If you’ve ever wondered “why isn’t this model showing up?”, now you know where to look!
When to Use Visibility Flags
- Prepare figures by temporarily hiding irrelevant parts
- Focus on a substructure in a large assembly
- Debug complex visual scripts or automation workflows
With a few simple NSL queries, you can clean up and take control of your scene — no more cluttered visuals, and no more manual toggling.
To explore all visual model attributes and syntax, visit the official NSL documentation for visual models: https://documentation.samson-connect.net/users/latest/nsl/visualModel/
SAMSON and all SAMSON Extensions are free for non-commercial use. You can download SAMSON at https://www.samson-connect.net.