Find the Light You’re Looking For: A Practical Guide to SAMSON’s Light Queries

When a molecular scene contains several lights, a small bit of housekeeping can become a distraction: Which lights are hidden? Which are visible? What was that light called? SAMSON’s Node Specification Language (NSL) lets you describe light nodes with concise attribute queries, so you can narrow your attention without searching through every node manually.

This guide focuses on the light-specific attribute space. Its short name is li, and it matches light nodes. The attributes listed here are inherited from the general node attribute space, but the li prefix gives you a way to express that your query concerns lights.

Start with the question you need answered

For a quick visibility check, use the short forms h for hidden and v for visible. For example:

  • li.h describes lights whose hidden attribute is true.
  • not li.h describes lights whose hidden attribute is false.
  • li.v and not li.v express the corresponding true and false tests for visible.

These are useful starting points when you want to focus on one group of lights at a time—for instance, when checking a scene with lights that are not currently shown. The positive and negated forms make the intended boolean value explicit, which can also make a saved or shared query easier to understand later.

Use names when visibility is not enough

If your lights have meaningful names, the name attribute can help distinguish them. Its short form is n, and values are written in quotes. The documented examples are:

  • li.n "A"
  • li.n "L*"

These examples show the query form for supplying a name value. If you are unsure what a particular expression matches in your scene, test it there rather than assuming how a name pattern is interpreted. Consistent, descriptive light names make this kind of filtering more useful—especially when a project is revisited or passed to a collaborator.

Keep related attributes distinct

The light attribute list includes hidden, visible, visibilityFlag, selected, and selectionFlag. They are separate attributes in the reference, so do not treat their names as interchangeable. The documented short forms are h for hidden, v for visible, vf for visibilityFlag, and sf for selectionFlag. The boolean examples include li.vf false, li.sf false, and their bare forms li.vf and li.sf.

One detail that is easy to miss: selected has no short name in the light attribute space. Use li.selected or not li.selected; the short name s available for the inherited node attribute is explicitly not provided for lights here.

A simple light-filtering routine

  1. Begin with the kind of light state you want to inspect: try li.h or li.v.
  2. If names help identify the relevant lights, use the quoted li.n form.
  3. When you need to check selection-related or visibility-flag attributes, query them by their own names rather than assuming they mean the same thing as selected or visible.
  4. Use the full attribute names when readability matters, and short names when you prefer compact expressions.

The main benefit is not a complicated query: it is having a clear vocabulary for describing the light nodes you mean. That makes routine scene inspection more deliberate and reduces the chance of confusing a light’s name, visibility, and selection state.

For the complete attribute list and additional examples, see the SAMSON light attributes reference.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON at samson-connect.net.

Comments are closed.