A molecular scene can be confusing for a simple reason: a node’s own setting is not always the same as its effective state in the scene. An atom may have its visibility flag turned on and still be hidden because an ancestor is hidden. The same kind of inheritance applies to selection and locking. If you query only the flag, you may miss the state that matters when inspecting a model.
SAMSON’s Node Specification Language (NSL) makes this distinction queryable. The useful habit is to choose between an effective-state attribute and a flag attribute, depending on what you are trying to find.
Effective state versus local flag
For visibility, node.visible asks whether a node is visible considering both its own visibility flag and its ancestors. Its short form is n.v. By contrast, node.visibilityFlag (or n.vf) checks the node’s own flag.
n.v— find nodes that are visible in the hierarchy.not n.v— find nodes that are effectively hidden.n.vf false— find nodes whose own visibility flag is false.n.vf— find nodes whose own visibility flag is true.
These queries answer different questions. A node returned by not n.v could be hidden because its own flag is false, or because an ancestor’s flag is false. If you are diagnosing a display issue, checking both the effective state and the local flag helps distinguish those possibilities.
The same distinction applies to selection and locking
node.selected (n.s) matches nodes selected either directly or through a selected ancestor. node.selectionFlag (n.sf) checks the node’s own selection flag. So n.s is useful when you want to find everything that is selected in the hierarchy, while n.sf true narrows the question to nodes with their own selection flag set.
Likewise, node.locked (n.l) includes nodes locked through an ancestor, whereas node.lockedFlag (n.lf) checks the node’s own locked flag. When a node behaves as locked, but you are unsure where that state comes from, comparing these attributes can help clarify whether the node itself or a parent in the hierarchy has the flag set.
A quick troubleshooting routine
- Start with the state you experience. For example, use
not n.vto query nodes that are effectively hidden. - Check the local flag. Use
n.vf falseto find nodes whose own visibility flag is off. - Compare the results. If a node is effectively hidden but its own flag is true, an ancestor’s visibility flag may explain the difference.
- Repeat the pattern for selection or locking. Compare
n.swithn.sf true, orn.lwithn.lf true.
This approach is useful when a large scene has nested groups and the visible result does not match the setting you inspect on an individual node. It also helps prevent a common mix-up: treating a local flag as if it described the entire hierarchy.
Keep the query focused
NSL also lets you narrow a search by node type. For instance, n.t a matches atoms, while n.t b matches bonds. Node categories can further focus a query: n.c lig matches ligands, and the documented expression a.s N in n.c lig matches nitrogen atoms in ligands. Combining a clear target with the right state attribute makes it easier to inspect a specific part of a model without confusing node identity, local flags, and inherited state.
When troubleshooting, ask two questions: “What is the node’s effective state?” and “What is its own flag?” In a hierarchical scene, those answers may differ—and that difference is often the clue.
For the full list of node attributes and examples, see the SAMSON NSL node reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.