A common source of confusion in a molecular scene is that a node can have its visibility turned on and still not appear. In a hierarchical model, a parent’s visibility state can affect everything beneath it. That makes it useful to distinguish a node’s own visibility flag from its effective visibility in the scene.
SAMSON’s Node Specification Language (NSL) provides three related node attributes for investigating this: visibilityFlag, visible, and hidden. They answer different questions, so choosing the right one can save time when you are checking a structure, organizing a model, or trying to understand why part of a scene is absent.
Start with the question you need to answer
Use node.visibilityFlag when you want to inspect the flag set on the node itself. Its short form is n.vf. For example, n.vf false finds nodes whose own visibility flag is false. It does not, by itself, describe the full visibility outcome caused by ancestors.
Use node.visible, short form n.v, when you want nodes that are actually visible: their visibility flag is true and their ancestors are visible too. The query n.v therefore asks about the effective state in the hierarchy, rather than only a local setting.
Use node.hidden, short form n.h, to find nodes that are hidden either because their own visibility flag is false or because an ancestor’s visibility flag is false. This is often the most helpful query when you are looking for the reason a node does not show up.
A quick troubleshooting sequence
-
Find effectively hidden nodes. Try
n.h. This gathers nodes hidden by their own state or by a hidden ancestor. -
Check local flags. Try
n.vf falseto identify nodes whose own visibility flag is off. If a node is hidden but does not match this query, its visibility may be affected by an ancestor. -
Check what is currently visible. Use
n.vto match nodes whose own flag and ancestor visibility states allow them to be visible.
These queries apply to nodes across the data graph, not just atoms. If you need to narrow the result to a particular node type, combine the visibility query with a type condition. For instance, n.t a and n.h expresses a search for hidden atoms. NSL also allows readable attribute names, so the equivalent can be written as node.type atom and node.hidden. Use the form supported by your search context if you are unsure about combining conditions.
Don’t confuse “hidden” with “flag off”
The distinction matters most in nested structures. Imagine a group whose visibility flag is false and an atom inside it whose own flag is true. The atom is still hidden because its ancestor is hidden. In that case, n.vf false identifies the group’s local state, while n.h identifies the effective hidden state of the group and its affected descendants. Conversely, changing or inspecting only a child’s flag does not tell you whether a parent is preventing it from appearing.
This same local-versus-inherited pattern appears in other node attributes. For example, node.selected can match nodes selected through their own selection flag or an ancestor’s, whereas node.selectionFlag examines the flag itself. Keeping that distinction in mind makes hierarchy-based searches easier to interpret.
For day-to-day work, the practical rule is simple: query n.vf to inspect a local setting, and query n.v or n.h to understand effective visibility. This helps separate “the node is turned off” from “something above it is keeping it out of view.”
For the full 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.