SBDocument

SBDocument#

This class describes a document. A document may contain various types of nodes: cameras, structural nodes, dynamical models, simulators, visual models, notes, labels, folders, etc.

There is always one active document - the one visible in the Document view.

You can access the active document through samson.SAMSON:

activeDocument = SAMSON.getActiveDocument()

The set of selected nodes is accessible from the document:

selectedNodesIndexer = activeDocument.getSelectedNodes()

This node indexer is a copy of an internal node indexer of the selected nodes and any you can modify this node - it does not affect the selection. Note, that if the selection has been modified this node indexer is not updated and you need to call the samson.SBDocument.getSelectedNodes() function again.

You can access nodes in the node indexer to perform some actions e.g. remove them from the selection:

for node in selectedNodesIndexer:
  node.selectionFlag = False

You can also add nodes to selection and remove them from the selection yourself by modifying the selection flag of a node:

node.selectionFlag = True                     # the node is selected
node.selectionFlag = False                    # the node is deselected

or by modifying the document selection itself:

activeDocument.addNodeToSelection(node)       # the node is selected
activeDocument.removeNodeFromSelection(node)  # the node is deselected

Note that you should always turn the “Undo system” on when modifying the selection:

SAMSON.beginHolding("Modify selection")       # turn the undo system on
SAMSON.getActiveDocument().clearSelection()   # clear the selection
SAMSON.endHolding()                           # turn the undo system off

This allows for undoing:

SAMSON.undo()                                 # go back to before clearing

See also

SAMSON SDK: SBDDocument

class samson.SBDocument(*args, **kwargs)#

Bases: SBFolder

This class describes a document.

Overloaded function.

__init__(self: samson.SBDocument) -> None

Constructs a document.

__init__(self: samson.SBDocument, name: str) -> None

Constructs a document with a name.

addGroupNodesToSelection(self: samson.SBDocument, group: samson.SBNodeGroup) → None#

Adds the group nodes to the document selection.

Parameters:: samson.SBNodeGroup – A node group.

addNodeToSelection(self: samson.SBDocument, node: samson.SBNode) → None#: Adds a node to the selection

clearHighlighting(self: samson.SBDocument) → None#

Clears the highlighting in the document.

Examples

Clear the highlighting in the active document

>>> document = SAMSON.getActiveDocument()
>>> document.clearHighlighting()

clearSelection(self: samson.SBDocument) → None#

Clears the selection in the document.

Examples

Clear the selection in the active document

>>> document = SAMSON.getActiveDocument()
>>> document.clearSelection()

createGroup(self: samson.SBDocument, name: str, selectionString: str = '*', visitString: str = '*') → samson.SBNodeGroup#

Create a group with its name based on a selectionString and a visitString.

This function traverses the node’s sub-tree for which a predicate based on the visitString is True (depth-first), and creates a node group for nodes for which the selectionString is True. Precisely, if the predicate based on the visitString returns false, the node is not visited, and neither are its descendants. If the predicate based on the visitString returns True, the node is visited, and this visit predicate will be used to decide whether its children are visited or not. Note that the node itself must satisfy the predicate based on the visitString else nothing is visited.

This function internally creates a node group in an undoable way, adds it to the document, and returns the just created node group.

Notes

A node group does not directly contain nodes but only refers to them.

Parameters:

name (str) – A name of the group.
selectionString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be selected.
visitString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be visited.

Returns:

The resulting node group.

Return type:

samson.SBNodeGroup

Examples

Create a group for water nodes and make this operation undoable.

>>> document = SAMSON.getActiveDocument()
>>> SAMSON.beginHolding('Create node group')
>>> nodeGroup = document.createGroup('Water nodes', 'water')
>>> SAMSON.endHolding()

See also

groupSelection, getSelectedNodes

getActiveCamera(self: samson.SBDocument) → samson.SBCamera#

Returns the active camera in the document.

Returns:: The active camera in the document
Return type:: samson.SBCamera

Notes

A created document always has at least one camera.

Examples

Go to the back view with the active camera.

>>> active_document = SAMSON.getActiveDocument()
>>> active_camera = active_document.getActiveCamera()
>>> active_camera.backView()

See also

setActiveCamera

getActivePresentation(self: samson.SBDocument) → samson.SBPresentation#

Returns the active presentation of the document.

Returns:: The active presentation in the document, if any, else return None
Return type:: samson.SBPresentation

Examples

Get the active presentation in the document.

>>> active_document = SAMSON.getActiveDocument()
>>> active_presentation = active_document.getActivePresentation()

See also

setActivePresentation

getActiveStructuralModel(self: samson.SBDocument) → samson.SBStructuralModel#

Returns the active structural model in the document.

Returns:: The active structural model in the document, if any, else return None
Return type:: samson.SBStructuralModel

Examples

Get the active structural model in the document.

>>> active_document = SAMSON.getActiveDocument()
>>> active_structural_model = active_document.getActiveStructuralModel()

See also

setActiveStructuralModel

getNextDocument(self: samson.SBDocument) → samson.SBDocument#

Returns the next document.

Notes

SAMSON might have multiple documents open at the same time.

getNumberOfSelectedNodes(*args, **kwargs)#

Overloaded function.

getNumberOfSelectedNodes(self: samson.SBDocument, proxy: samson.SBProxy) -> int

Returns the number of selected nodes corresponding to the given proxy.

Parameters:: proxy (samson.SBProxy) – A proxy.
Returns:: A number of selected nodes.
Return type:: int

getNumberOfSelectedNodes(self: samson.SBDocument, classUUID: samson.SBUUID, extensionUUID: samson.SBUUID) -> int

Returns the number of selected nodes corresponding to the given classUUID and extensionUUID.

Parameters:

classUUID (samson.SBUUID) – A class UUID.
extensionUUID (samson.SBUUID) – An extension UUID.

Returns:

A number of selected nodes.

Return type:

int

getPreviousDocument(self: samson.SBDocument) → samson.SBDocument#

Returns the previous document.

Notes

SAMSON might have multiple documents open at the same time.

getSelectedNodes(*args, **kwargs)#

Overloaded function.

getSelectedNodes(self: samson.SBDocument) -> samson.SBNodeIndexer

Returns an indexer of the selected nodes.

Returns:: An indexer of selected nodes.
Return type:: samson.SBNodeIndexer

Examples

Print the number of selected nodes in the active document.

>>> document = SAMSON.getActiveDocument()
>>> print(len(document.getSelectedNodes()))
0

getSelectedNodes(self: samson.SBDocument, type: samson.SBNode.Type) -> samson.SBNodeIndexer

Returns an indexer of the selected nodes of the given type.

Parameters:: type (samson.SBNode.Type) – A node type.
Returns:: An indexer of selected nodes.
Return type:: samson.SBNodeIndexer

Examples

Print the number of selected atoms in the active document.

>>> document = SAMSON.getActiveDocument()
>>> print(len(document.getSelectedNodes(SBNode.Atom)))
0

getSelectedNodes(self: samson.SBDocument, selectionString: str) -> samson.SBNodeIndexer

Returns an indexer of the selected nodes satisfying the given selectionString.

Parameters:: selectionString (str) – A Node Specification Language expression (SAMSON API: Node Specification Language).
Returns:: An indexer of selected nodes.
Return type:: samson.SBNodeIndexer

Examples

Print the number of selected atoms and bonds in the active document.

>>> document = SAMSON.getActiveDocument()
>>> print(len(document.getSelectedNodes('n.t a or n.t b')))
0

groupSelection(self: samson.SBDocument, name: str) → samson.SBNodeGroup#

Stores the selected nodes into a group with the given name.

This function internally creates a node group in an undoable way, adds it to the document, and returns the just created node group.

Notes

A node group does not directly contain nodes but only refers to them.

Parameters:: name (str) – A name of the group.
Returns:: The resulting node group.
Return type:: samson.SBNodeGroup

Examples

Create a group for the currently selected nodes and make this operation undoable.

>>> document = SAMSON.getActiveDocument()
>>> if len(document.getSelectedNodes()):
...     SAMSON.beginHolding('Create node group')
...     nodeGroup = document.groupSelection('Group name')
...     SAMSON.endHolding()

See also

createGroup, getSelectedNodes

hasSelectedNodes(self: samson.SBDocument) → bool#

Returns whether the document has any nodes selected.

Return type:: bool

Examples

Print whether there are any nodes selected in the active document.

>>> document = SAMSON.getActiveDocument()
>>> print(document.hasSelectedNodes())
False

intersectGroupNodesWithSelection(self: samson.SBDocument, group: samson.SBNodeGroup) → None#

Keeps in the document selection only the nodes stored in this group.

Parameters:: samson.SBNodeGroup – A node group.

removeGroupNodesFromSelection(self: samson.SBDocument, group: samson.SBNodeGroup) → None#

Removes the group nodes from the document selection.

Parameters:: samson.SBNodeGroup – A node group.

removeNodeFromSelection(self: samson.SBDocument, node: samson.SBNode) → None#: Removes a node from the selection

selectGroupNodes(self: samson.SBDocument, group: samson.SBNodeGroup) → None#

Clears the document selection and select the group nodes.

Parameters:: samson.SBNodeGroup – A node group.

setActiveCamera(self: samson.SBDocument, camera: samson.SBCamera) → None#

Sets the active camera for the document.

Parameters:: camera (samson.SBCamera) – A camera in the document

Notes

A created document always has at least one camera.

Examples

Set the 1st camera in the document as the active one

>>> active_document = SAMSON.getActiveDocument()
>>> camera_indexer = active_document.getNodes('node.type camera')
>>> active_document.setActiveCamera(camera_indexer[0])

See also

getActiveCamera

setActivePresentation(self: samson.SBDocument, presentation: samson.SBPresentation) → None#

Sets the active presentation for the document.

Parameters:: presentation (samson.SBPresentation) – A presentation in the document

Examples

Set the 1st presentation in the document as the active one

>>> active_document = SAMSON.getActiveDocument()
>>> presentation_indexer = active_document.getNodes('node.type presentation')
>>> if presentation_indexer.size:
...         active_document.setActivePresentation(presentation_indexer[0])

See also

getActivePresentation

setActiveStructuralModel(self: samson.SBDocument, structuralModel: samson.SBStructuralModel) → None#

Sets the active structural model.

Parameters:: structuralModel (samson.SBStructuralModel) – A structural model in the document

Examples

Set the 1st structural model in the document as the active one

>>> active_document = SAMSON.getActiveDocument()
>>> structural_model_indexer = active_document.getNodes('node.type structuralModel')
>>> if structural_model_indexer.size:
...         active_document.setActiveStructuralModel(structural_model_indexer[0])

See also

getActiveStructuralModel

property fileName#: The name of the file associated to the document

property isSaved#: Returns whether the document is saved

property isTrusted#: Returns whether the document is trusted

SBDocument

Contents

SBDocument#