Working with documents and nodes#

SAMSON documents are hierarchies of nodes in a data graph. Many scripts start by getting the active document, then retrieving, selecting, creating, or modifying nodes. See Python scripting mental model for the broader scripting map.

Documents#

SAMSON documents are hierarchies of SAMSON nodes. The hierarchy of the active document is visible in the Document view.

SAMSON documents (SBDocument) may contain cameras (SBCamera), folders (SBFolder), files (SBFile), structural nodes (e.g. molecules, residues, groups, atoms, bonds, conformations, paths, etc.), labels (SBLabel), notes (SBNote), visual models (SBVisualModel), simulators (SBSimulator), etc. SAMSON maintains the information about models (structural nodes, visual models, etc), cameras, simulators, etc., in the document’s data graph. See User guide - Node types for the description of types of nodes in SAMSON documents.

In one SAMSON instance, you can have multiple open documents at the same time, but only one document is active at any given moment: the one you currently see in the Document view. The loaded or created molecules are placed in the active document.

Get the active document#
document = SAMSON.getActiveDocument()

Common operations#

Goal

Typical API

Read next

Get the active document

SAMSON.getActiveDocument()

This page

Get the active camera

SAMSON.getActiveCamera()

Moving around

Inspect child nodes

document.getChildren()

Getting nodes

Retrieve nodes with NSL

SAMSON.getNodes(...)

Getting nodes

Add child nodes undoably

with SAMSON.holding(...): and addChild(...)

Building

See also

User Guide: Documents

User Guide: Node types

User Guide: Building molecules

Moving around#

Each document has at least one camera (SBCamera). A camera provides a 3D view of visualizable objects. Basically, you may consider your screen as a camera pointing into the viewport and yourself as an operator seeing through the camera.

Cameras and their positions and properties are saved and loaded together with a document.

Change the active camera’s view using commands#
SAMSON.runCommand("Top view")
Change the active camera’s view directly via its functionality#
# get the active camera
camera = SAMSON.getActiveCamera()

# change the view of the camera
camera.topView()

Having multiple cameras in a document can be useful if you want to switch quickly between different views (e.g., positions, projections, close-up views, and a full view) in the same document. To switch between cameras in the document:

Change the active camera in a document#
# get all cameras in the document
cameraIndexer = document.getNodes("node.type camera")

# make the operation undoable
with SAMSON.holding("Change camera"):
    # change the document's active camera to the first camera in the document
    SAMSON.getActiveDocument().setActiveCamera(cameraIndexer[0])

You can also access and modify other camera’s attributes. See SBCamera for more information and examples.

See also

User Guide: Camera

samson.SBCamera

Working with nodes#

Each node has one and only one parent, and possibly some children or references to other nodes. See the following sections to learn how to work with nodes:

See also

User Guide: Node types

Common mistakes#

  • Assuming the active document always contains the nodes your script expects.

  • Modifying document nodes without using SAMSON.holding when the operation should be undoable.

  • Confusing selection with retrieval: selected nodes are highlighted in SAMSON, while SAMSON.getNodes() returns nodes for Python processing.