A molecular model can be confusing to inspect when an atom appears hidden, selected, or locked even though its own setting seems to say otherwise. The key is that some SAMSON node attributes describe a node’s effective state, while others report only the flag set on that node. Keeping those two ideas separate makes it easier to diagnose what is happening in a hierarchy.
In SAMSON, nodes can sit inside larger structures, and a node’s ancestors can affect how it behaves. An atom, for example, may be part of a residue, chain, or molecule. When querying with the Node Specification Language (NSL), you can ask either about the resulting state of a node or about its individual flag.
Effective state versus local flag
Consider visibility. node.visible (short form n.v) matches nodes that are visible: their visibility flag is true and their ancestors are visible. Conversely, node.hidden (n.h) matches nodes hidden because their own visibility flag is false or an ancestor’s flag is false.
By contrast, node.visibilityFlag (n.vf) checks the flag on the node itself. So the queries below answer different questions:
n.h— Which nodes are hidden, including through an ancestor?n.vf false— Which nodes have their own visibility flag set to false?n.v— Which nodes are effectively visible, considering their ancestors?
This distinction is useful when a child’s own flag is true, yet it is still not visible because an ancestor’s flag is false. A query for n.vf false looks for locally disabled visibility; it is not a substitute for checking effective visibility with n.v or n.h.
The same pattern applies to selection and locking
Selection has a similar pair of attributes. node.selected (n.s) matches nodes selected either directly or because an ancestor’s selection flag is true. node.selectionFlag (n.sf) checks a node’s own selection flag.
For example, use n.s when you want to find nodes that are selected in effect. Use n.sf true when you want to inspect which nodes have the selection flag set directly. A selected parent can make descendants match n.s even when their individual flags are not set.
Locking follows the same logic: node.locked (n.l) includes nodes locked through an ancestor, while node.lockedFlag (n.lf) checks the node’s own flag. To diagnose an unexpectedly locked part of a structure, compare the effective query n.l with the local-flag query n.lf true.
A practical troubleshooting sequence
- Describe the symptom. Is the node hidden, selected, or locked in the effective hierarchy?
- Query the effective state. Try
n.h,n.s, orn.l, depending on the symptom. - Check local flags. Compare with
n.vf false,n.sf true, orn.lf true. - Inspect the hierarchy. If the effective state does not match the node’s own flag, check its ancestors for the flag that can propagate the state.
These attributes are also useful when building more focused searches. For example, n.t a and n.h expresses a search for atoms that are effectively hidden; n.t a and n.v expresses a search for effectively visible atoms. Combining node type with state can help narrow a large scene to the elements relevant to a particular troubleshooting task.
The useful mental shortcut is: visible, hidden, selected, and locked describe effective state; their corresponding *Flag attributes describe the node’s own flag. When a result seems contradictory, compare both kinds of query and remember to account for ancestors.
For the complete node-attribute reference and additional NSL examples, see the SAMSON node attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.