Colorizing nodes#

In SAMSON, you can colorize visual models, meshes, labels, and structural nodes (atoms, residues, molecules, structural models, etc.) using various color schemes (see Color Scheme). Python Scripting provides an easy way for custom colorization of the data graph nodes.

When a color scheme is applied to a node, all the node’s descendants are affected if they do not have their own color schemes. You can apply different color schemes to different nodes. Color schemes are stored as part of the material (SBNodeMaterial) property of a node.

Note

Materials (and, hence, color schemes that are part of materials) take precedence based on hierarchy: if the node has a material applied directly to it, then it will be colorized based on this material’s color scheme, else it will be colorized based on a color scheme of its parent node’s material. If none of the node’s parents has a material with a color scheme then a default colorization will be applied, e.g. CPK colors for atoms.

To remove materials from a node and its descendants call the SBNode.removeMaterialsFromDescendants() function on the node.

See the List of color schemes page for the list of all the available color schemes.

List of color schemes#

Below is the list of color schemes available by default:

Constant: SBColorSchemeConstant - the same color is uniformly applied.
Constant illustrative: SBColorSchemeConstantIllustrate - applies a constant color (illustrative). It helps to depict molecules in a style similar to David S. Goodsell’s artwork.
CPK: SBColorSchemeCPK - the classic Corey-Pauling-Koltun (CPK) color scheme.
Per attribute: the color is determined based on an atom attribute (e.g. temperature factor, residue, etc.):
- SBColorSchemePerChainID - colorizes each chain in a different color.
- SBColorSchemePerChainIllustrate - colorizes each chain in a different color (illustrative). It uses a style similar to David S. Goodsell’s artwork.
- SBColorSchemePerFormalCharge - colorizes atoms based on their formal charge.
- SBColorSchemePerOccupancy - colorizes atoms based on their occupancy values.
- SBColorSchemePerPartialCharge - colorizes atoms based on their partial charge.
- SBColorSchemePerResidueHydrophobicity - colorizes residues based on their hydrophobicity. Several scales are available via the Inspector or via SBResidue functionality.
- SBColorSchemePerResidueSequenceNumber - colorizes residues based on their sequence number.
- SBColorSchemePerResidueType - colorizes residues based on their type (types of amino and nucleic acids).
- SBColorSchemePerSecondaryStructureType - colorizes residues based on their secondary structure (helices, sheets, loops).
- SBColorSchemePerSideChainCharge - colorizes residues based on their side chain charge.
- SBColorSchemePerSideChainPolarity - colorizes residues based on their side chain polarity.
- SBColorSchemePerTemperatureFactor - colorizes atoms based on their temperature factor.

Apply color#

To colorize a node with a constant color (SBColor), you need to create the color you want and apply it to the node:

Apply color to a node#

# create an RGB color
orange = SBColor(255, 128, 0)
# apply color to a node
node.setColor(orange)

# or the same in one line:
node.setColor(SBColor(255, 128, 0))

Note

Internally, the SBNode.setColor() function creates a material with the constant color scheme (SBColorSchemeConstant) based on the given color and applies it to the node.

If you would like to make this operation undoable, then you need to wrap it in SAMSON.beginHolding() and SAMSON.endHolding:

Apply color to a node (undoable)#

# make the operation undoable
SAMSON.beginHolding("Colorize node")

# apply a color to the node
node.setColor(SBColor(255, 128, 0))

# stop holding the operation
SAMSON.endHolding()

Example: colorize atoms based on their x-coordinate.

Colorize atoms based on their X coordinate#

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

if len(atomIndexer):
    # set initial min and max values
    min_x = max_x = atomIndexer[0].getX().value
    # get min and max x-coordinates
    for atom in atomIndexer:
        x = atom.getX().value
        if x > max_x: max_x = x
        elif x < min_x: min_x = x
    
    # make the operation undoable
    SAMSON.beginHolding("Colorize atoms")
    
    # colorize each atom according to its coordinate
    for atom in atomIndexer:
        # get RGB color for a node based on HSV color
        # here we go through the hue parameter in the HSV color space to change the color
        h = (atom.getX().value - min_x) / (max_x - min_x)
        color = SBColor.fromHSV(239.5 / 360.0 * h, 205.0/255.0, 1.0)
        # set the color of the node
        atom.setColor(color)
    
    # stop holding the undoable operation
    SAMSON.endHolding()

Get color from user#

You can also get a color from the user:

Get color from user#

# this function returns a tuple: (state, SBColor)
# where state is True if OK was clicked, else False
res, color = SAMSON.getColorFromUser('Choose a color')
if res: print(color)

Apply color from color palette#

Color palettes (SBPalette) provide a possibility to generate colors along some trajectory in a color space. For example, going from red to blue through white.

You can get an RGB color from a palette along the [0, 1] range using the SBPalette.getColor() function.

Color palettes are available in the following color spaces:

HSV (Hue-Saturation-Value) color space. SBPalette, by default, implements an HSV color palette:

Create the default HSV color palette#

# create the default HSV color palette
palette = SBPalette()
# get color along the [0, 1] range
color = palette.getColor(0.5)

HCL (Hue-Chroma-Luminance) color space. SAMSON provides a set of pre-defined HCL color palettes in the SBPaletteDefaultPalette.

The following color palette types are available in SAMSON by default:

Qualitative color palettes - for coding categorical information, i.e., where no particular ordering of categories is available and every color should receive the same perceptual weight. See SBPaletteQualitative, SBPaletteQualitativeHCL.
Sequential color palettes - for coding ordered/numeric information, i.e., going from high to low (or vice versa). See SBPaletteSequential, SBPaletteSequentialHCL.
Diverging color palettes - for coding ordered/numeric information around a central neutral value, i.e., where colors diverge from neutral to two extremes. See SBPaletteDiverging, SBPaletteDivergingHCL.
Flexible diverging color palettes - for coding ordered/numeric information around a central neutral value, i.e., where colors diverge from neutral to two extremes. See SBPaletteFlexibleDivergingHCL.

Use default HCL color palettes#

# get color from 'qualitativeHCLRed2Blue' color palette along the [0, 1] range
color = SBPaletteDefaultPalette.qualitativeHCLRed2Blue.getColor(0.2)

Using the default HSV color palette, the example where we colorize nodes based on the HSV color can also be done as follows:

Colorize atoms based on their X coordinate using a color palette#

# get all atoms in the active document
atomIndexer = SAMSON.getNodes('node.type atom')

if len(atomIndexer):
    # set initial min and max values
    min_x = max_x = atomIndexer[0].getX().value
    # get min and max x-coordinates
    for atom in atomIndexer:
        x = atom.getX().value
        if x > max_x: max_x = x
        elif x < min_x: min_x = x

    # create the default HSV color palette
    palette = SBPalette()

    # make the operation undoable
    SAMSON.beginHolding("Colorize atoms")

    # colorize each atom according to its coordinate
    for atom in atomIndexer:
        # get the color 'intensity' value, which should be in the [0, 1] range
        h = 1 - (atom.getX().value - min_x) / (max_x - min_x)
        # get RGB color from the palette
        color = palette.getColor(h)
        # set the color of the node
        atom.setColor(color)

    # stop holding the undoable operation
    SAMSON.endHolding()

Get color palette from user#

You can also get a color palette from the user:

Get color palette from user#

# this function returns a tuple: (state, SBPalette)
# where state is True if OK was clicked, else False
res, palette = SAMSON.getPaletteFromUser('Choose a color palette')
if res and palette != None: print(palette.type)

Apply color scheme#

There is a number of various color schemes (SBNodeColorScheme) available by default in SAMSON, see List of color schemes.

A data graph node (SBNode) has the SBNode.setColorScheme() function which allows you to directly apply a color scheme to this node.

Note

Nodes in SAMSON are colorized by applying to them a material (SBNodeMaterial) with a color scheme. When you call the SBNode.setColor() function, it internally creates a material (if the node didn’t already have a material) with the constant color scheme (SBColorSchemeConstant) based on the given color and applies it to the node. When you call the SBNode.setColorScheme() function, it also applies a material with this color scheme if the node didn’t already have a material, else it changes the color scheme of the existing material.

Most of the color schemes receive a node indexer upon their construction to determine a range of color scheme specific values (depending on the color scheme).

The usual steps to apply a color scheme are as follows:

Get an indexer of nodes to which you would like to apply a color scheme.
Create a color scheme based on this node indexer such that the color scheme could compute the range of values/colors (if applicable to the color scheme).
Apply the color scheme to each node of the node indexer.

Example: colorize all molecules in the active document with a color scheme based on the residue sequence number. For that we will use the SBColorSchemePerResidueSequenceNumber color scheme.

Colorize based on residue sequence number#

# get all structural models (top structural nodes in the document hierarchy)
nodeIndexer = SAMSON.getNodes('node.type structuralModel')

# create a color scheme per residue sequence number
# we need to provide a node indexer of residues to the color scheme constructor
# for it to determine a range of residue sequence numbers
colorScheme = SBColorSchemePerResidueSequenceNumber(nodeIndexer)

# Hold - Make the operation undoable
SAMSON.beginHolding("Colorize nodes")

# apply the color scheme to nodes
for node in nodeIndexer:
  # [optional] remove materials from all the descendants if they have any materials
  node.removeMaterialsFromDescendants()
  # set the color scheme
  node.setColorScheme(colorScheme)

# stop holding the operation
SAMSON.endHolding()

Example: colorize all molecules in the active document with a color scheme based on the temperature factor of atoms. For that we will use the SBColorSchemePerTemperatureFactor color scheme.

Colorize based on temperature factor#

# get all structural models
# 'n.t sm' is short for 'node.type structuralModel'
nodeIndexer = SAMSON.getNodes('n.t sm')

# create a color scheme per temperature factor
# we need to provide a node indexer of structural models to the color scheme constructor
# for it to determine a range temperature factors in the system
colorScheme = SBColorSchemePerTemperatureFactor(nodeIndexer)

# Hold - Make the operation undoable
SAMSON.beginHolding("Colorize nodes")

# apply the color scheme to nodes
for node in nodeIndexer:
  # [optional] remove materials from all the descendants if they have any materials
  node.removeMaterialsFromDescendants()
  # set the color scheme
  node.setColorScheme(colorScheme)

# stop holding the operation
SAMSON.endHolding()

Apply a color scheme with a color palette#

Color schemes have their own default color palettes (SBPalette) based on which they create colorization. If you want, you can also specify a color palette for a color scheme:

Colorize with a special color palette#

# get all structural models
nodeIndexer = SAMSON.getNodes('node.type sm')

# create a color scheme per residue sequence number with the given color palette
colorScheme = SBColorSchemePerResidueSequenceNumber(nodeIndexer, SBPaletteDefaultPalette.sequentialHCLViridis)

# Hold - Make the operation undoable
SAMSON.beginHolding("Colorize nodes")

# apply the color scheme to nodes
for node in nodeIndexer:
  # [optional] remove materials from all the descendants if they have any materials
  node.removeMaterialsFromDescendants()
  # set the color scheme
  node.setColorScheme(colorScheme)

# stop holding the operation
SAMSON.endHolding()

Colorizing nodes

Contents

Colorizing nodes#

List of color schemes#

Apply color#

Get color from user#

Apply color from color palette#

Get color palette from user#

Apply color scheme#

Apply a color scheme with a color palette#