When molecular modelers build or import complex systems in SAMSON, they often need to programmatically filter or organize their structures. One common challenge is determining whether a structural component is actually shown in the viewport—and it’s not as straightforward as simply checking if it’s “visible.” There are multiple visibility-related attributes in SAMSON’s Node Specification Language (NSL), and understanding how they work together can save time and confusion. 🔍
In this post, we shed some light on three key attributes related to visibility in structural models:
visible(sm.v)visibilityFlag(sm.vf)hidden(sm.h)
Why This Matters
You might encounter a structure that appears on screen as hidden or shown even though your script or plugin marked it otherwise. That’s because SAMSON supports both high-level (e.g., user-interaction-driven hiding) and low-level (e.g., rendering control flags) visibility properties. These state combinations allow fine-grained control, but they can also create confusion if misunderstood.
1. visible: A derived state
The visible attribute (sm.v) tells you whether a structural model is currently visible in the viewport. However, this doesn’t mean it was explicitly marked as visible. This state is derived from other properties, including visibilityFlag and hidden. Therefore, querying sm.v is useful for answering questions like: “Will the user currently see this model?”
Examples:
sm.v: model is currently visiblenot sm.v: model is currently hidden from view
2. visibilityFlag: Rendering control switch
sm.vf controls whether rendering is allowed for the model. It acts like a low-level control flag: when off (false), the model is forcefully hidden regardless of other states. Setting this to false is often used when filtering visual noise from large systems.
Examples:
sm.vf: visibility flag is set (rendering allowed)sm.vf false: rendering disabled
3. hidden: Manual hiding
sm.h is a manually set flag that allows users to hide models through GUI actions or scripts. Unlike vf, it doesn’t disable rendering as forcefully—it’s more reversible and intended for intuitive model management.
Examples:
sm.h: currently marked as hiddennot sm.h: manual hiding is not enabled
Putting It All Together
To determine whether a model is truly visible, SAMSON evaluates a combination of these state flags. If any of the conditions block rendering—such as sm.vf being false or sm.h being true—the model won’t be displayed. Thus, querying only sm.v gives you a quick yes/no, but checking all flags gives you the full context.
You can even construct complex queries to filter models based on visibility logic. For example:
|
1 |
sm.vf and not sm.h |
This query matches all models that are not manually hidden and have visibilityFlag set—in short, those that can be visible. Useful for batch-selection or when preparing models before rendering or export.
Learning when and how to use each flag helps molecular modelers control what’s shown, hidden, or exported—especially in large, detailed simulations.
📄 Learn more in the official documentation.
SAMSON and all SAMSON Extensions are free for non-commercial use. Download it at https://www.samson-connect.net.