SBNodeMaterial#

Data graph nodes in SAMSON may have materials that apply to themselves and their descendants (if the descendants do not have their own materials). Materials are used to modify the visual appearance of data graph nodes. Each material has:

  • an associated color scheme (SBNodeColorScheme) to color nodes in a specific way, e.g. by residue, chain, or based on some node properties (e.g., charge, temperature factor, occupancy, etc.), or no color scheme to apply the default colorization;

  • appearance properties used when rendering nodes using path tracing (the Trace command) .

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

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

# apply the color scheme to nodes
for node in nodeIndexer:
    # [optional] remove existing materials from the descendants
    node.removeMaterialsFromDescendants()

    # create a color scheme per residue type
    # by providing the node indexer of residues to the color scheme constructor
    # we allow it to determine the color range based on the min and max residue types
    colorScheme = SBColorSchemePerResidueType(nodeIndexer)

    # create a material with the color scheme
    material = SBNodeMaterial()
    material.setColorScheme(colorScheme)

    # set the material to the node
    node.setMaterial(material)

# stop holding
SAMSON.endHolding()

You can set the appearance properties based on available appearance presets using the SBNodeMaterial.setAppearance() function:

Apply appearance preset to a material#
material.setAppearance('Metallic: Copper')

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.

List of appearance presets for materials#

Below is the table of appearance presets for materials available by default:

Appearance presets#

Name

metallic

roughness

specular

clearcoat

transmission

transmission roughness

transmission IOR

emission strength

Metallic: Carbon Fiber

1

0.2

0.5

0

0

0

2.42

0

Metallic: Carbon Steel

0.8

0.5

0.5

0

0

0

2.5

0

Metallic: Copper

1

0.3

0.5

0

0

0

1.98

0

Metallic: Gold

1

0.1

0.5

0

0

0

0.47

0

Metallic: Paint

1

0.2

0.5

0.8

0

0

1.45

0

Metallic: Silver

1

0

0.5

0

0

0

0.18

0

Metallic: Steel

1

0.5

0.5

0

0

0

2.5

0

Metallic: Zinc

0.9

0.4

0.5

0

0

0

2.5

0

Semi-metallic: Brass

0.65

0.65

0.6

0

0

0

1.7

0

Semi-metallic: Bronze

0.75

0.4

0.6

0

0

0

2.5

0

Semi-metallic: Epoxy

0.2

0.4

0.6

0.1

0

0

1.6

0

Semi-metallic: Pearl

0.1

0.1

0.8

0.2

0

0

1.53

0

Semi-metallic: Rust

0.6

0.8

0.5

0

0

0

2.5

0

Smooth: Ceramic

0

0.4

0.5

0

0

0

1.6

0

Smooth: Latex

0

0.1

0.8

0

0

0

1.49

0

Smooth: Marble

0

0.2

0.5

0

0

0

1.5

0

Smooth: Paint

0

0.2

0.5

0.8

0

0

1.45

0

Smooth: Paper

0

0.3

0.5

0

0

0

1.52

0

Smooth: Plastic

0

0.4

0.5

0.2

0

0

1.46

0

Smooth: Polystyrene

0

0.1

0.5

0

0

0

1.59

0

Smooth: Satin

0

0.2

0.6

0

0

0

1.54

0

Smooth: Shiny plastic

0

0.1

0.8

0.1

0

0

1.52

0

Rough: Concrete

0

0.9

0.2

0

0

0

1.5

0

Rough: Feather

0

0.9

0.5

0.1

0

0

1.56

0

Rough: Granite

0

0.7

0.5

0

0

0

1.54

0

Rough: Velvet

0

0.9

0.3

0

0

0

1.5

0

Rough: Wood

0

0.6

0.5

0.1

0

0

1.52

0

Emissive: Faint (0.1)

0

0.5

0.5

0

0

0

1.5

0.1

Emissive: Soft (1)

0

0.5

0.5

0

0

0

1.5

1

Emissive: Glowing (10)

0

0.5

0.5

0

0

0

1.5

10

Emissive: Shining (100)

0

0.5

0.5

0

0

0

1.5

100

Emissive: Bright (1000)

0

0.5

0.5

0

0

0

1.5

1000

Emissive: Strong (10000)

0

0.5

0.5

0

0

0

1.5

10000

Emissive: Intense (100000)

0

0.5

0.5

0

0

0

1.5

100000

Transparent: Ice

0

0

0.5

0

0.98

0.1

1.31

0

Transparent: Glass

0

0

0.5

0

1

0

1.52

0

Transparent: Jade

0

0.3

0.5

0

0.2

0

1.66

0

Transparent: Obsidian

0

0.07

0.5

0

0.1

0.1

1.5

0

Transparent: Water

0

0

0.5

0

0.95

0

1.33

0

Transparent: Wax

0

0.1

0.5

0

0.3

0

1.46

0

See also

Colorizing nodes

SAMSON SDK: SBDDataGraphNodeMaterial

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

Bases: SBReferenceTarget

This class describes a material.

Overloaded function.

  1. __init__(self: samson.SBNodeMaterial) -> None

Constructs a material with default parameters and no color scheme.

  1. __init__(self: samson.SBNodeMaterial, colorScheme: samson.SBNodeColorScheme) -> None

Constructs a material based on the given color scheme. The color scheme is cloned internally, since the material owns the color scheme.

Parameters:

colorScheme (samson.SBNodeColorScheme) – The color scheme

  1. __init__(self: samson.SBNodeMaterial, color: samson.SBColor) -> None

Constructs a material based on the given color. The color is set via the constant color scheme (SBColorSchemeConstant).

Parameters:

color (samson.SBColor) – The color

clone(self: samson.SBNodeMaterial) → samson.SBNodeMaterial#

Returns a copy of the material

copyAppearanceFromMaterial(self: samson.SBNodeMaterial, anotherMaterial: samson.SBNodeMaterial) → bool#

Copies material appearance settings from another material

static getAppearancePresetList() → list[str]#

Returns a list of names of available appearance presets. You can also find the list with the corresponding parameters in the documentation.

getColorScheme(self: samson.SBNodeMaterial) → samson.SBNodeColorScheme#

Returns the material’s color scheme. The material always has a color scheme.

Returns:

The material’s color scheme.

Return type:

samson.SBNodeColorScheme

getEmissionColor(self: samson.SBNodeMaterial) → samson.SBColor#

Returns the emission color

getNode(self: samson.SBNodeMaterial) → samson.SBNode#

Returns the node that owns the material

getSubsurfaceColor(self: samson.SBNodeMaterial) → samson.SBColor#

Returns the subsurface color

getSubsurfaceRadius(self: samson.SBNodeMaterial) → samson.SBPhysicalVector3#

Returns the subsurface radius

static hasAppearancePreset(name: str) → bool#

Returns whether there is an appearance preset with the given name.

Parameters:

name (str) – The appearance preset name. The name is case insensitive.

Examples

>>> material.hasAppearancePreset("Rough: Granite")
True
setAppearance(self: samson.SBNodeMaterial, name: str) → bool#

Sets the appearance preset based on the appearance preset name name.

Parameters:

name (str) – The appearance preset name. The name is case insensitive.

Returns:

Returns True if it could find the appearance preset with the given name and apply it, else returns False.

Return type:

bool

Examples

Set the ‘Metallic: Copper’ appearance preset

>>> material.setAppearance("Metallic: Copper")
setColor(self: samson.SBNodeMaterial, color: samson.SBColor) → bool#

Sets the color for the material. The color is set via the constant color scheme (SBColorSchemeConstant).

Parameters:

color (samson.SBColor) – A color.

Returns:

Returns True if it could set the color, else returns False.

Return type:

bool

setColorScheme(self: samson.SBNodeMaterial, colorScheme: samson.SBNodeColorScheme) → bool#

Sets the color scheme. The color scheme is cloned internally, since the material owns the color scheme.

Parameters:

colorScheme (samson.SBNodeColorScheme) – The color scheme.

Returns:

Returns True if it could set the color scheme, else returns False.

Return type:

bool

setEmissionColor(self: samson.SBNodeMaterial, emissionColor: samson.SBColor) → None#

Sets the emission color

setSubsurfaceColor(self: samson.SBNodeMaterial, emissionColor: samson.SBColor) → None#

Sets the subsurface color

setSubsurfaceRadius(self: samson.SBNodeMaterial, subsurfaceRadius: samson.SBPhysicalVector3) → None#

Sets the subsurface radius

property anisotropicCoefficient#

The anisotropic coefficient.

property anisotropicRotation#

The anisotropic rotation.

property clearcoatCoefficient#

The clearcoat coefficient.

property clearcoatRoughness#

The clearcoat roughness.

property emissionStrength#

The emission strength.

property isSerializable#

Returns True when the class is serializable

property metallicCoefficient#

The metallic coefficient.

property roughnessCoefficient#

The roughness coefficient.

property sheenCoefficient#

The sheen coefficient.

property sheenTint#

The sheen tint.

property specularCoefficient#

The specular coefficient.

property specularTint#

The specular tint.

property subsurfaceAnisotropy#

The subsurface anisotropy.

property subsurfaceCoefficient#

The subsurface coefficient.

property subsurfaceIOR#

The subsurface index of refraction (IOR).

property transmissionCoefficient#

The transmission coefficient.

property transmissionIOR#

The transmission index of refraction (IOR).

property transmissionRoughness#

The transmission roughness.

property transparency#

The transparency.