Visible on the Flag, Hidden in the Scene: Understanding Molecular Visibility

A molecular scene can be confusing when a structure appears to have visibility enabled but still cannot be seen. The reason may be hierarchy: a node can inherit visibility behavior from an ancestor. In SAMSON, the Node Specification Language (NSL) provides two related ways to ask about visibility: the visibility flag on a node itself, and whether the node is actually visible in the scene.

This distinction is useful when troubleshooting a large model. Rather than checking nodes one by one, you can use NSL expressions to find nodes by their visibility state and compare the results.

Flag state is not the same as effective visibility

node.visibilityFlag (short name n.vf) reports a node’s own visibility flag. For example, node.visibilityFlag false matches nodes whose flag is set to false. The short form is n.vf false.

node.visible (short name n.v) describes whether a node is visible after accounting for its ancestors. A node is visible when its own visibility flag is true and its ancestors are visible. Use node.visible to match visible nodes, or not node.visible to match nodes that are not visible.

The complementary query node.hidden (short name n.h) matches nodes that are hidden because their own visibility flag is false or because an ancestor’s visibility flag is false. In other words, a child may have its own flag set to true and still be hidden by a parent.

A practical check for an unexpected disappearance

  1. Check node.visibilityFlag false to find nodes with their own visibility flag turned off.

  2. Check node.hidden to find nodes that are hidden, including those affected by an ancestor.

  3. Check node.visible to identify nodes that are currently visible according to both their own state and the hierarchy.

Comparing these results helps narrow down whether the cause is local to a node or inherited from somewhere higher in the data graph. For example, if a node’s visibility flag is true but it matches node.hidden, the documentation’s definition points to an ancestor’s visibility flag as a possible explanation.

Keep the question precise

When writing a query, decide whether you want the stored flag or the effective state. Use node.visibilityFlag when you are investigating a node’s own setting. Use node.visible or node.hidden when you care about what the hierarchy means for visibility in the scene. The short forms—n.vf, n.v, and n.h—make repeated searches quicker to type.

This same distinction appears in other node states: for example, node.selected can reflect a selection flag on an ancestor, while node.selectionFlag refers to the node’s own flag. Remembering the difference between a local flag and an inherited state makes scene inspection less guesswork-heavy.

For the complete list of node attributes and additional examples, see the SAMSON node attributes reference.

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

Comments are closed.