A common molecular-modeling frustration is that a node appears hidden, selected, or locked even though its own setting seems to say otherwise. In SAMSON, the reason may be the hierarchy: a node can inherit these states from one of its ancestors. Knowing which Node Specification Language (NSL) attribute to query can make the difference between finding the cause and chasing the wrong object.
NSL offers two useful kinds of queries here: one checks a node’s own flag, and the other checks its effective state in the hierarchy. These are related, but they answer different questions.
Visibility: local flag or effective state?
node.visibilityFlag (short form n.vf) checks the node’s own visibility flag. To find nodes whose flag is off, use node.visibilityFlag false. By contrast, node.visible (short form n.v) checks whether a node is actually visible, taking its ancestors into account. A node may have its visibility flag set to true and still not be visible if an ancestor’s visibility flag is false.
For example, compare these queries:
node.visibilityFlag true— finds nodes whose own visibility flag is on.node.visible— finds nodes that are visible, including the effect of their ancestors.node.hidden(short formn.h) — finds nodes hidden because their own or an ancestor’s visibility flag is false.
If an object seems to ignore a visibility change, checking the effective state with node.hidden or node.visible can help reveal whether the cause lies higher in the hierarchy.
Selection works the same way
The distinction is similar for selection. node.selectionFlag (short form n.sf) checks a node’s own selection flag. node.selected (short form n.s) checks whether the node is selected either directly or through a selected ancestor.
So node.selectionFlag false does not necessarily mean the node is effectively unselected. If an ancestor has its selection flag set to true, the node can still match node.selected. When you need to investigate selection behavior, compare the flag query with the effective-state query rather than treating them as interchangeable.
Locked nodes: flag versus inherited lock
Locking follows the same pattern. node.lockedFlag (short form n.lf) checks the node’s own locked flag. node.locked (short form n.l) also accounts for locked ancestors. A node can therefore be locked in practice even when its own flag is not set.
This gives a practical troubleshooting sequence: first query the effective state to identify affected nodes; then inspect the corresponding flag to see whether the state is local. If the effective state and local flag differ, check the node’s ancestors in the data graph.
Narrow the search to relevant nodes
These attributes apply across node types, so you can combine them with node.type to focus on a particular kind of object. For instance, node.type atom and node.hidden looks for hidden atoms, while node.type visualModel and not node.visible narrows the query to visual models that are not visible. NSL also supports short forms, such as n.t a for atoms and n.v for visible nodes.
The key takeaway is simple: a flag describes a node’s own setting; an effective state can also reflect its place in the hierarchy. Keeping that distinction in mind makes visibility, selection, and locking queries much easier to interpret.
For the complete list of node attributes and additional examples, see the SAMSON NSL node attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.