Visible on the node, hidden in the hierarchy: a practical guide to SAMSON visibility queries

A node can have its own visibility flag set to true and still be hidden in the scene. The reason is hierarchy: if one of its ancestors is hidden, the node is hidden too. This difference between a node’s local state and its effective state is a common source of confusion when inspecting a molecular model.

SAMSON’s Node Specification Language (NSL) lets you query both. Knowing which attribute to use makes it easier to distinguish “this node is marked visible” from “this node is actually visible.”

Local flag versus effective visibility

node.visibilityFlag (short form n.vf) checks the visibility flag on the node itself. For example:

  • node.visibilityFlag false or n.vf false matches nodes whose own visibility flag is false.
  • node.visibilityFlag true or n.vf true matches nodes whose own visibility flag is true.

By contrast, node.visible (short form n.v) describes effective visibility: the node’s flag must be true, and its ancestors must also be visible. Use n.v when you want to query nodes that are visible through the hierarchy, rather than merely marked visible themselves.

The related node.hidden attribute, abbreviated n.h, matches nodes hidden because their own visibility flag is false or because an ancestor’s flag is false. In practice, these queries answer different diagnostic questions:

  • n.vf false: Which nodes have been explicitly flagged as not visible?
  • n.h: Which nodes are hidden, including those affected by a hidden ancestor?
  • n.v: Which nodes are visible, taking their ancestors into account?

Why the distinction matters

Imagine a molecular structure organized into groups. A group’s visibility flag is turned off, while a child node inside it still has its own flag set to true. A query for n.vf true can still match that child: the query reports its local flag. But the child is not effectively visible because an ancestor is hidden. A query for n.v reflects that hierarchical condition.

This distinction helps avoid a misleading conclusion during model inspection. If you are trying to find objects that should currently appear, query effective visibility. If you are investigating which nodes have a visibility flag set directly, query the flag instead. If you are looking for everything hidden in the hierarchy, use n.h.

The same pattern applies to selection and locking

Visibility is part of a broader NSL pattern: some attributes report a node’s own flag, while others describe a state that can be inherited from an ancestor.

  • node.selectionFlag (n.sf) checks a node’s selection flag. node.selected (n.s) also matches nodes selected through an ancestor.
  • node.lockedFlag (n.lf) checks a node’s locked flag. node.locked (n.l) also matches nodes locked through an ancestor.

So when a child appears selected or locked, checking only its own flag may not explain the state. Compare the flag-specific attribute with the effective-state attribute to tell local settings apart from inherited ones.

A simple way to choose a query

Before writing an NSL expression, ask: “Do I mean the flag on this node, or the state this node experiences in the hierarchy?” Use n.vf for the former and n.v or n.h for the latter. The same decision applies to selection (n.sf versus n.s) and locking (n.lf versus n.l).

For the full list of node attributes and examples, see the SAMSON node attributes reference.

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

Comments are closed.