Labels can be useful when inspecting a molecular scene—and easy to lose track of when a project contains many of them. A label left hidden, a visible label that distracts from a close-up, or several similarly named annotations can make it harder to focus on the structure you are working on. SAMSON’s Node Specification Language (NSL) lets you describe label nodes using their names and visibility or selection-related attributes, so you can target labels by what you know about them instead of relying only on visual inspection.
This guide focuses on a small, practical part of NSL: the label attribute space. It is useful when your immediate task is to identify labels—not atoms, residues, or other node types.
Start with the label namespace
Label attributes belong to the label attribute space, abbreviated la. That namespace matches only label nodes. For example, la.v is a label query for the visible attribute; it is not a general query for every visible object in the scene.
Several label attributes are inherited from the general node attribute space. This means familiar node properties can also be used when describing labels, while the la prefix keeps the query focused on labels.
Find labels by name
If you remember a label’s name, start with name, whose short name is n. The documented examples are la.n "A" and la.n "L*". The quotes matter: the reference lists strings in quotes as the possible values for this attribute. The second example is a convenient pattern to try when a label name begins with a known prefix; check the results in your scene to confirm that they identify the labels you intended.
This is particularly helpful when labels are visually crowded or obscured. Rather than scanning the viewport for a name, you can express the name you are looking for in the label namespace. If you are unsure of a label’s exact name, the documented "L*" example gives you another form to test.
Check visibility and hidden state
Labels expose both visible (short name v) and hidden (short name h). The reference shows la.v and not la.v for visible, and la.h and not la.h for hidden. In practical terms, these examples let you ask for labels with a true or false value for the attribute you specify.
Keep the attribute names precise when writing a query. The reference lists visible and hidden as separate attributes, so use the one that matches the condition you want to inspect rather than assuming one is simply another spelling of the other. For details about their inherited behavior, follow the links to node.visible and node.hidden.
Selection attributes are not all the same name
There are also two selection-related entries: selected and selectionFlag. For labels, selected has no short name; use la.selected or not la.selected. selectionFlag has the short name sf, with examples la.sf and la.sf false.
The similar wording can make these easy to mix up. Treat them as distinct attributes in the reference and use the name or short name shown for the specific property you intend to query. The same approach applies to visibilityFlag, abbreviated vf, for which the examples are la.vf and la.vf false. These are separate queryable attributes; do not substitute them for visible or hidden without checking the relevant node-attribute description.
A quick label-query checklist
- Use
lawhen you want the query to match label nodes. - Use
la.nwith a quoted string when identifying labels by name. - Use
la.vornot la.vto describe the visible attribute’s true or false state. - Use
la.hornot la.hfor the hidden attribute. - Check the exact attribute name:
selected,selectionFlag, andvisibilityFlagare distinct entries, and their short names differ.
These small distinctions help turn a vague search—“where did that annotation go?”—into a query about a specific label property. For the complete label attribute reference and its examples, see the SAMSON label NSL documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.