Visible, Hidden, or Just Flagged? A Practical Guide to SAMSON Node Visibility

A molecular scene can become hard to work with when parts of a structure disappear—or appear to be hidden—even though you did not change the node you are inspecting. In SAMSON, visibility is hierarchical: a node’s own visibility flag matters, but so do the flags of its ancestors. Knowing the difference between a flag and effective visibility makes it easier to diagnose what is happening and build more reliable searches.

Two different questions

It helps to separate these questions:

• What is this node’s own visibility setting? Use node.visibilityFlag, short form n.vf.
• Is this node visible in the hierarchy? Use node.visible, short form n.v.

node.visible is true when the node’s visibility flag is true and its ancestors are visible. So a node can have its own flag set to true but still not be visible because an ancestor’s visibility flag is false. That distinction is often the key to understanding why a node is not showing up.

Diagnose the scene in small steps

Start by searching for nodes whose own visibility flag is off:

node.visibilityFlag false

The short form is n.vf false. This finds nodes with a false visibility flag, but it does not by itself answer whether a node is effectively visible through its hierarchy.

Next, search for nodes that are currently visible:

node.visible

This is equivalent to n.v. To search for nodes that are not visible, use:

not node.visible

Comparing these searches helps separate a node’s local setting from the outcome of its place in the hierarchy. If a node has a true visibility flag but is not visible, inspect its ancestors: an ancestor with a false visibility flag can make descendants hidden as well.

“Hidden” describes the effective state

The node.hidden attribute, short form n.h, matches nodes that are hidden because their own visibility flag is false or because an ancestor’s visibility flag is false. For example:

node.hidden

Use this when the practical question is simply, “Which nodes are hidden?” Use node.visibilityFlag when you want to investigate the local flag itself. These queries answer related, but not identical, questions.

A quick troubleshooting routine

1. Search for node.hidden to identify nodes whose effective state is hidden.
2. Search for node.visibilityFlag false to find nodes with their own flag turned off.
3. For a node that has a true flag but is not visible, check the ancestors in the data graph for a false visibility flag.
4. Use node.visible to focus on nodes that are visible through the hierarchy.

This approach is useful when cleaning up a complex scene, checking a group before presentation, or trying to understand why a particular part of a model is absent. It also helps avoid changing a child node’s setting when the actual cause is higher in the hierarchy.

Visibility is not selection

Selection follows a similar distinction. node.selectionFlag checks a node’s own selection flag, while node.selected also accounts for a selected ancestor. In short, the flag describes the node; the effective state can reflect its hierarchy. Keeping these pairs straight—visibilityFlag versus visible, and selectionFlag versus selected—makes NSL searches easier to interpret.

For the full list of node attributes and additional examples, see the SAMSON Node Specification Language node reference.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.