When a Model Looks Missing: A Careful Guide to Visual-State Queries

A molecular model can be hard to inspect when visual models have different visibility or selection states. The first challenge is often not changing anything—it is finding the right nodes to examine. In SAMSON, the Node Specification Language (NSL) provides a focused way to query visual model nodes and their attributes.

This guide covers a small but useful set of visual-state attributes: visible, hidden, visibilityFlag, selected, and selectionFlag. The goal is to help you make precise queries without treating similar-sounding properties as interchangeable.

Start with the visual model attribute space

Visual model attributes live in the visualModel attribute space, whose short name is vm. This space matches visual model nodes. Using vm at the start of an expression makes the intended node type explicit and keeps your query focused.

For example, vm.v queries visual models with the visible attribute set to true, while not vm.v queries those for which it is false. The full attribute name can also be used: vm.visible and not vm.visible. The short name is convenient for repeated use; the full name can be easier to read when you are learning or sharing a query with a colleague.

Keep visibility attributes distinct

The reference lists three related attributes: visible (v), hidden (h), and visibilityFlag (vf). Each accepts true or false. The documentation identifies them as separate attributes, so it is safer to query the property you actually want to inspect rather than assume that one is simply the inverse of another.

For instance, use vm.v to query the visible attribute, and vm.h to query hidden. To explicitly look for a false flag, the documented form is vm.vf false; the shorter vm.vf form corresponds to true. These expressions give you a way to examine each attribute independently. If a visual model is not appearing as expected, checking these properties separately can help you avoid drawing conclusions from a similarly named state.

Selection has its own pair of useful queries

For selection-related inspection, the page lists selected and selectionFlag (sf). You can query the selected attribute with vm.selected or not vm.selected. One detail worth remembering: in the visual model attribute space, selected does not have the short name s. Use the full form rather than assuming the alias available in another context.

The selection flag has a short name: vm.sf selects the true value, and vm.sf false selects the false value. As with visibility, keep selected and selectionFlag as distinct query targets. The reference documents both, but does not say they are interchangeable.

A practical way to build a query

  1. Begin with the node type: use the vm prefix to target visual model nodes.

  2. Choose the specific attribute you need to inspect, such as v, h, vf, selected, or sf.

  3. For Boolean attributes, decide whether you want the true or false value. The documented examples use not for false on attributes such as vm.v, and an explicit false value for forms such as vm.vf false.

  4. Prefer the full attribute name when clarity matters, and the short name when brevity matters. Both styles are shown in the reference for most attributes.

This approach is useful when a scene contains many visual models and you need to narrow your inspection to a particular state. It also makes queries easier to revisit: a precise attribute name is a small safeguard against confusing visibility with a visibility flag, or selection with a selection flag.

For the complete list of visual model attributes, aliases, and examples, see the Visual model attributes reference.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.

Comments are closed.