Unhiding Insights: Mastering Node Visibility in SAMSON

Molecular modeling projects often become complex quickly, especially when managing large biomolecules with multiple layers of information. One common source of inefficiency is trying to locate or interact with nodes that are unexpectedly invisible. Whether it’s visualizing a hidden ligand or editing a buried hydrogen atom, understanding how visibility works in SAMSON can dramatically improve your workflow.

Thankfully, SAMSON provides a well-structured and powerful mechanism for controlling visibility through the Node Specification Language (NSL). This blog post demystifies how the hidden, visible, and visibilityFlag attributes work together, helping you efficiently control the appearance of molecular components.

Why Does Node Visibility Matter?

If you’re working on structural biology problems or designing new ligands, you’ve likely encountered situations where a node (e.g., an atom, bond, or group) seems to have disappeared. It’s not deleted—just not shown. The root cause could be its own visibility flag, or the state of one of its parent nodes.

This can make troubleshooting models especially frustrating. Are you adjusting the right settings? Why isn’t your ligand showing up after loading a new structure?

The good news is that NSL gives you an exact, readable way to investigate and manage visibility.

Understanding NSL Visibility Attributes

The three key visibility-related attributes in NSL are:

• hidden (n.h): This matches nodes that are effectively hidden, either because their own visibility flag is false or because one of their ancestors is hidden.
• visible (n.v): Matches nodes that are visible based on their own visibility flag and their visible ancestors.
• visibilityFlag (n.vf): Targets the underlying flag itself, regardless of hierarchical visibility.

Examples in Practice

Let’s look at several NSL expressions and what they do:

• n.h — Selects all hidden nodes.
• not n.h — Selects all nodes that are not currently hidden (i.e., visible).
• n.v — Selects only those nodes that are truly visible, with no hidden ancestors.
• n.vf false — Selects nodes with their visibility flag turned off, even if they are visible due to their parent structure.

This granularity allows you to debug your scene accurately. For instance, if a ligand is not appearing, you can run:

This will show all hidden ligand nodes, giving you a quick way to locate and unhide what you need.

Using Visibility Logs for Clean Visual Output

If you’re preparing figures or animations, you might want to hide everything except a particular region of interest. First, hide all nodes:

Then selectively show what you want:

Or even force them visible:

Practical Tip: Combine with Other Filters

Visibility becomes even more powerful when combined with other filters. Want to find all hidden glycan atoms?

This lets you pinpoint exact hiding issues in complex molecular systems, especially when working collaboratively or across multiple revisions of a model.

Final Thoughts

Rather than using trial-and-error or manually clicking through elements in a large hierarchy, learning how to query visibility in SAMSON with NSL gives you precise control. It reduces confusion, improves modeling speed, and ensures your visual results are exactly what you intend.

To learn more about visibility and other attributes, visit the full documentation at SAMSON NSL Node Attributes Documentation.

SAMSON and all SAMSON Extensions are free for non-commercial use. You can get SAMSON at https://www.samson-connect.net.