Node¶

The data graph contains everything directly or indirectly added by the user through SAMSON’s user interface, plugins, etc. A data graph node has basic pre-defined data and functionalities to manage the data (models, apps, etc.).

All nodes in SAMSON’s data graph, e.g. atoms (samson.Modeling.StructralModel.Atom), bonds (samson.Modeling.StructralModel.Bond), etc., derive from samson.DataModel.DataGraph.Node.

Topology¶

SAMSON’s data graph is a directed graph, where each node has one and only one parent (with the exception of documents (samson.DataModel.Document.Document), which have no parent), and possibly some children. The parent of a node can never be directly set, but can be retrieved using the samson.DataModel.DataGraph.Node.getParent() function. Children are managed using the samson.DataModel.DataGraph.Node.addChild() and samson.DataModel.DataGraph.Node.removeChild() functions.

Node lifecycle¶

In SAMSON, a data graph node may go through four lifecycle stages:

C++ object creation
Node creation (using the samson.DataModel.DataGraph.Node.create() function)
Node destruction (using the samson.DataModel.DataGraph.Node.erase() function)
C++ object destruction (usually automatically, or forced)

Node identity¶

Each node in the data graph has a type, which may be retrieved using the ref getType function. For example, the type returned by the samson.Modeling.StructralModel.Atom class, which derives from the Node class, is Atom, while the type returned by the samson.Modeling.StructuralModel.StructuralModel class is StructuralModel. The samson.DataModel.DataGraph.Node.getTypeString() function is a convenience function that may be used to obtain a type of a node as a string.

# get a data graph node's type
node.type

# get a data graph node's type as a string
node.typeString

# the same as before
sam.DataModel.DataGraph.Node.getTypeString(node.type)

You can also check for a particular type of a node e.g. whether it is a visual model, an interaction mode, a structural particle, etc.

Let’s, for example, erase all visual models in the current selection:

# loop over all currently selected nodes in the active document
for node in SAMSON.getActiveDocument().getSelectedNodes():

        # check if this node is a visual model
        if node.isVisualModel():

                # turn the undo system on
                SAMSON.beginHolding("Erase selected visual models")

                # erase the node
                node.erase()

                # turn the undo system off
                SAMSON.endHolding()

Each data graph node also has a unique index, that is managed internally by SAMSON. All indices are contiguous unsigned integers between 0 and n-1, where n is the number of data graph nodes. As a result, the node index is not permanent: when node i is deleted (and i is different from n-1), then node n-1 becomes node i. Node indices are used for example when picking objects in a viewport, by writing integers into the framebuffer instead of colors. The unique node index can be retrieved using samson.DataModel.DataGraph.Node.getNodeIndex().

Flags¶

Each data graph node has four flags:

The samson.DataModel.DataGraph.Node.isCreated flag indicates whether the node is created or not
The samson.DataModel.DataGraph.Node.isVisible flag indicates whether the renderer should display the node in the viewport
The samson.DataModel.DataGraph.Node.highlightingFlag whether the renderer should highlight the node in the viewport
The samson.DataModel.DataGraph.Node.selectionFlag indicates whether the node is “selected” or not

These flags are accessed through functions of samson.DataModel.DataGraph.Node and, except for the highlighting flag which has temporary purposes, changing these flags’ values is “undoable”.

The samson.DataModel.DataGraph.Node.getFlags() function returns an integer that combines the highlighting and selection flags, as well as the “mobility flag” (samson.Modeling.StructuralModel.Particle.mobilityFlag) of particles (atoms and pseudo-atoms).

Color schemes¶

Each data graph node may have a material (samson.DataModel.DataGraph.Material), which may affect its rendering in the viewport. A material may be applied to a node with the samson.DataModel.DataGraph.Node.setMaterial() function. When a material is added to a node, it affects the node itself and all its descendants (unless they have a material themselves, which then has priority). Precisely, the samson.DataModel.DataGraph.Node.getMaterial() function returns the material directly applied to the node, or determines the deepest ancestor that has a material applied (by examining the node’s parent, then its parent’s parent, etc.). If no material is found, the samson.DataModel.DataGraph.Node.getMaterial() function returns 0.

Each material has a color scheme (samson.DataModel.DataGraph.ColorScheme) which may be modified and used to associate a color to a node or a spatial position (samson.DataModel.Type.position3).

Please refer to samson.DataModel.DataGraph.ColorScheme.

Getting nodes¶

You can get an indexer of child nodes using the samson.DataModel.DataGraph.Node.getNodes() function and the Node Specification Language.

Let’s, for example, select all node’s children atoms:

# get all node's children atoms
atomIndexer = node.getNodes('node.type atom')

# the same using short names
atomIndexer = node.getNodes('n.t a')

# you can check the size of the indexer
atomIndexer

Printing info¶

For many node types, you can print some information on them:

atomIndexer = SAMSON.getNodes('node.type atom')

for atom in atomIndexer:
        print(atom)

atom = atomIndexer[0]
atom    # prints an information on atom