A common source of confusion in molecular modeling is that a node’s state can depend on more than its own setting. A group may be hidden, locked, or selected, and that state can affect nodes beneath it in the hierarchy. So a query that checks a node’s local flag may not answer the same question as one that checks its effective state.
SAMSON’s Node Specification Language (NSL) makes this distinction explicit. For visibility, node.visibilityFlag—short form n.vf—checks the flag on the node itself. By contrast, node.visible—n.v—matches nodes whose visibility flag is true and whose ancestors are visible. A node can therefore have a true visibility flag and still not be visible if an ancestor’s flag is false.
That difference is useful when diagnosing a scene. To query nodes whose own visibility flag is off, use n.vf false. To query nodes that are not effectively visible, use not n.v. The first asks about a local setting; the second asks about visibility in the hierarchy. These expressions are not interchangeable, and choosing the right one can save time when a structure seems to disappear “for no reason.”
The same local-versus-inherited distinction applies to selection. node.selectionFlag (short form n.sf) checks the node’s selection flag. node.selected (short form n.s) also matches nodes whose own selection flag is true, but it can match a node when one of its ancestors has a true selection flag. For example, n.sf true asks which nodes have their own flag set; n.s asks which nodes are selected, including through an ancestor.
Locking follows the same pattern. node.lockedFlag, or n.lf, checks the local locked flag. node.locked, or n.l, matches nodes locked either by their own flag or by a locked ancestor. This distinction helps separate “this node is locked” from “this node is affected by a lock higher in the hierarchy.”
A practical way to troubleshoot an unexpected result is to compare the local and effective queries:
n.vf falseversusnot n.vfor visibilityn.sf trueversusn.sfor selectionn.lf trueversusn.lfor locking
If the results differ, that difference can point to an ancestor’s state rather than a setting on the node you inspected. In other words, the hierarchy is not just an organizational tree: it can affect how visibility, selection, and locking are evaluated.
These queries are especially useful when you need to inspect many nodes consistently instead of checking them one at a time. NSL also provides short names for concise expressions, while the full attribute names can be easier to read when you are first learning the language.
For the complete list of node attributes and more examples, see the SAMSON node attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
