Presenting and animating#

SAMSON provides a powerful and easy way to create presentations, animations, and movies. Animation capabilities in SAMSON include but are not limited to:

animations of molecules: dock structures, assemble structures, create custom paths, play simulation trajectories;
camera animations: orbit around structures, add standard paths, create custom paths;
various animation effects: entrance, exit, highlight, etc.

A presentation (SBPresentation) is a node that combines animation nodes (SBAnimation) helping you to form a story and show presentations or export them as movies or sets of images.

Presentation and animation nodes are part of documents and are visible in the Document view.

A document might contain multiple presentations, each one of them containing multiple different animations. Presentation and animation nodes are saved with a document, which means that you can easily save, load, and share your presentations and animations.

See: List of available animations.

List of available animations#

Below is the list of animations available by default in SAMSON with their class names in parenthesis. They are available via the Default Animations extension (UUID: “1B8AC667-CCBF-9C80-8E28-A60565955273”).

Animations of molecules#

Public name	Class name	User Guide
Assemble	SEAssemble	Assemble
Disassemble	SEDisassemble	Disassemble
Dock	SEDock	Dock
Undock	SEUndock	Undock
Hold atoms	SEHoldAtoms	Hold atoms
Move atoms	SEMoveAtoms	Move atoms
Play path	SEPlayPath	Play path
Play reverse path	SEPlayReversePath	Play reverse path
Rock	SERock	Rock
Rotate	SERotate	Rotate

Camera animations#

Public name	Class name	User Guide
Dolly camera	SEDollyCamera	Dolly camera
Follow atoms	SEFollowAtoms	Follow atoms
Hold camera	SEHoldCamera	Hold camera
Look at atoms	SELookAtAtoms	Look at atoms
Move camera	SEMoveCamera	Move camera
Orbit camera	SEOrbitCamera	Orbit camera
Pedestal camera	SEPedestalCamera	Pedestal camera
Truck camera	SETruckCamera	Truck camera
Zoom camera	SEZoomCamera	Zoom camera

Animation effects#

Public name	Class name	User Guide
Appear	SEAppear	Appear
Disappear	SEDisappear	Disappear
Conceal atoms	SEConcealAtoms	Conceal atoms
Reveal atoms	SERevealAtoms	Reveal atoms
Flash	SEFlash	Flash
Pulse	SEPulse	Pulse
Hidden	SEHidden	Hidden
Shown	SEShown	Shown
Hide	SEHide	Hide
Show	SEShow	Show
Pause	SEPausePresentation	Pause
Stop	SEStopPresentation	Stop
Set background	SESetBackground	Set background

You can get a dictionary of available public names of animations and their proxies:

Get a dictionary of available public names of animations and their proxies#

animation_proxy_map = SAMSON.getAnimationProxyMap()
for public_name, proxy in animation_proxy_map.items():
  # print the proxy information
  print(f"Name: {public_name}\tClass name: {proxy.name},\tExtension UUID: {proxy.elementUUID}")

You can also get the public name from a proxy via proxy.publicName.

How to create a presentation#

A presentation (SBPresentation) is a node and can be added in a document or in a folder:

Create a new presentation and add it in the active document.#

# make the operation undoable
SAMSON.beginHolding("Add presentation")

# construct an instance of a presentation
presentation = SBPresentation('Presentation')
# hold the node for undo/redo
SAMSON.hold(presentation)
# create the node
presentation.create()

# add the presentation in the active document
SAMSON.getActiveDocument().addChild(presentation)

# stop holding the undoable operation
SAMSON.endHolding()

This should add a presentation in the active document and make it in an undoable way.

How to create an animation#

Once you have a presentation, you can add various animations into it.

See: List of available animations.

There are two main ways to create animations: using commands and using proxies.

Create an animation using commands#

You can use SAMSON commands to select nodes to which you would like to apply animations and then to invoke those animations.

For example, let’s assume that there is a single path in the active document and we want to apply the “Play path” animation. Then we select it and we simply invoke the “Play path” command that will create the “Play path” animation and add it into the active presentation.

Add a path animation into a presentation using commands#

# select paths in the active document
# we assume that there is only one path in the active document
# if there is no path in the document, download a pdb with multiple models/conformations, e.g. 2N47
# SAMSON.fetchPDB("2N47")
# and make sure to check "Create paths from multiple models"
SAMSON.runCommand('nsl: node.type path')
# invoke the 'Play path'
SAMSON.runCommand('Play path')

Now the “Play path” animation should have been added to the document and we can move its keyframes.

Note

Not all animation can be created in this way. Please see the section below for the general way.

Create an animation using proxies#

The general way to create an animation is by using the SAMSON.makeAnimation() function. This function requires a node indexer (to which the animation should be applied) and either a public name of the animation or its proxy information (the class name and the extension UUID).

In the example below, we create a presentation and add the Play path animation to it for the last path/trajectory in the active document.

First, open a trajectory in SAMSON or fetch one from RCSB PDB, e.g. SAMSON.fetchPDB('1d3z').

Create a presentation with the Play path animation#

import os
from math import log10

class HaltException(Exception): pass

# get the path from the user
ret, movie_filepath = SAMSON.getPathFromUser(dialogTitle = 'Choose folder to save movie')
if ret:
    # a temporary path to images
    random_uuid = SBRandom(SAMSON.getTime() % 2147483647).randUUID()
    path_to_image_files = movie_filepath + '/tmp/' + str(random_uuid) + '/'
    
    # try to create a temporary folder
    try: os.makedirs(path_to_image_files)
    except: HaltException('Could not create a folder')
    
    camera = SAMSON.getActiveCamera()       # get the active camera
    #camera.frontView()                     # set the view of the camera
    SAMSON.processEvents()                  # process events: updates viewport
    
    # get an indexer of paths from the active document
    path_indexer = SAMSON.getNodes('node.type path')
    
    if len(path_indexer):
        # get the first path from the indexer
        path = path_indexer[0]
        
        ext = '.png'                  # extension of files

        path.forwardFlag = True       # set a change in positions in a forward direction
        path.animationFlag = True     # set the animation flag
        path.animationType = SBPath.AnimationType.Loop   # set Loop type of an animation
        
        # show a progress bar to inform user about the progress
        SAMSON.showProgressBar('steps', 0, path.numberOfSteps)
        
        # store the current step
        current_step = path.currentStep
        path.currentStep = 0

        # go through the trajectory frames
        for i in range(path.numberOfSteps):
             # update the state - change positions to the next step
             path.updateState()
             SAMSON.processEvents()
             i_str = str(i).zfill(int(log10(path.numberOfSteps)) + 1)
             filename = path_to_image_files + i_str + ext
             # save a capture of the viewport in a file with 800x600 resolution
             SAMSON.captureViewportToFile(filename, 800, 600)
             SAMSON.setProgressBarValue(i)             # update the progress bar
             if SAMSON.isProgressBarStopped(): break   # break if the rotation is finished
        
        # restore the current step
        path.currentStep = current_step
        
        # change directory to the directory with images
        os.chdir(path_to_image_files)
        # get the list of created images
        img_files = sorted((fn for fn in os.listdir('.') if fn.endswith('.png')))
        
        # create a gif and mp4 files using imageio
        create_movie_using_imageio(movie_path = movie_filepath, 
                                   image_filenames = img_files, duration = 0.1)
        # create a gif and mp4 files using moviepy
        #create_movie_using_moviepy(movie_path = movie_filepath, 
        #                           image_filenames = img_files, fps = 16)
        
        SAMSON.hideProgressBar()

Note

You can find the animation class names in List of available animations. Currently, all the default animations available in SAMSON are provided via the Default Animations extension (UUID: “1B8AC667-CCBF-9C80-8E28-A60565955273”).

Exporting a movie#

You can export a presentation from SAMSON into a movie using the SAMSON.exportToFile() function:

Export a presentation as a movie#

# get an indexer of presentations in the active document
presentationIndexer = SAMSON.getNodes('node.type presentation')

# the last [] indicates that the default parameters for exporting into a movie should be used
SAMSON.exportToFile(presentationIndexer, "/path/to/movie.mp4", [])

Note

You can modify the presentation export settings in the Preferences.

Presenting and animating

Contents

Presenting and animating#

List of available animations#

Animations of molecules#

Camera animations#

Animation effects#

How to create a presentation#

How to create an animation#

Create an animation using commands#

Create an animation using proxies#

Exporting a movie#