SourceSubstance

SourceSubstance is a type of source where you can connect a substance resource.

For more information, see modules resource and colormanagement.

Example

import substance_painter as sp

# Get the currently displayed stack
stack = sp.textureset.get_active_stack()

# Insert a fill layer
position = sp.layerstack.InsertPosition.from_textureset_stack(stack)
fill = sp.layerstack.insert_fill(position)

# Apply "Graphic to Material" in `Material` mode
graphic_to_material = sp.resource.search("s:starterassets "
                                         "u:substance "
                                         'n:"graphictomaterial"')[0]
source = fill.set_material_source(graphic_to_material.identifier())

# Substances can have image inputs which are sources themselves
# In this case, we use the input identifier instead of the channel type to query and edit the source
logo = sp.resource.search("s:starterassets "
                          "u:alpha "
                          'n:"logo painter"')[0]

assert "custom_image" in source.image_inputs
input_source = source.set_source("custom_image", logo)

# `input_source` is now a BitmapSource
# see BitmapSource example for further information on its interface

# In `Material` mode, you can specify how the outputs of the substance are plugged in the fill's channels
default_mapping = {
    sp.textureset.ChannelType.BaseColor: "basecolor",
    sp.textureset.ChannelType.Metallic: "metallic",
    sp.textureset.ChannelType.Roughness: "roughness",
    sp.textureset.ChannelType.Height: "height"
}
for dst_chn, identifier in default_mapping.items():
    assert identifier in source.image_outputs
    source.output_mapping[dst_chn] = identifier

# If not in `Material` mode, choose which output of the substance is active
# source.active_output = "basecolor"

# Retrieve and edit the substance parameters
params = source.get_parameters()
for prop_name in params.keys():
    print(prop_name)

new_params = {
    "outline_color": sp.colormanagement.Color(0.9, 0.7, 0.4),
    "roughness": params["roughness"] / 2,
    # Boolean parameters are treated as integer, if you use `True` or `False` you will get an error message:
    # >>> Bad value for property 'channel_roughness': expected value of type <int32> but got <bool>
    "channel_roughness": 1,
}
source.set_parameters(new_params)

# Query embedded presets and apply the first one
presets = source.get_preset_list()
for preset_name in presets:
    print(preset_name)

if presets:
    source.apply_preset(presets[0])

# Select the Fill layer
sp.layerstack.set_selected_nodes([fill])

class substance_painter.source.SourceSubstance(uid) substance_painter.source.SourceSubstance

A class that represents a procedural source.

property resource_id: ResourceID substance_painter.source.SourceSubstance.resource_id

The current substance resource of the source.

Getter: Returns the resource of the source.

property output_mapping: OutputMapping substance_painter.source.SourceSubstance.output_mapping

The output mapping property in multiple output context.

Getter: Returns the output mapping property.

Setter: Sets the output mapping property.

property active_output: str substance_painter.source.SourceSubstance.active_output

The active output of the source in single output context.

Getter: Returns the output identifier.

Setter: Sets the output identifier.

property mask_output: str substance_painter.source.SourceSubstance.mask_output

The mask output identifier of the source in multiple output context.

Getter: Returns the mask output identifier.

Setter: Sets the mask output identifier.

property image_inputs: List[str] substance_painter.source.SourceSubstance.image_inputs

The list of image inputs identifier from the current graph.

Getter: Returns the list of image inputs identifier.

property image_outputs: List[str] substance_painter.source.SourceSubstance.image_outputs

The list of image outputs identifier from the current graph.

Getter: Returns the list of image outputs identifier.

get_source(identifier: str) -> SourceUniformColor | SourceBitmap | SourceVectorial | SourceSubstance | SourceReference | SourceFont substance_painter.source.SourceSubstance.get_source

Get the source for the given input identifier.

Parameters: identifier (str) – The input identifier.

Returns: the source for the input.

Return type: SourceUniformColor | SourceBitmap | SourceVectorial | SourceSubstance | SourceReference | SourceFont

set_source(identifier: str, source: ResourceID | Color | AnchorPointEffectNode) -> SourceUniformColor | SourceBitmap | SourceVectorial | SourceSubstance | SourceReference | SourceFont substance_painter.source.SourceSubstance.set_source

Set the source for the given input identifier.

Parameters:

Returns: The source for the input.

Return type: SourceUniformColor | SourceBitmap | SourceVectorial | SourceSubstance | SourceReference | SourceFont

reset_source(identifier: str) -> None substance_painter.source.SourceSubstance.reset_source

Reset the source for the given input identifier.

Parameters: identifier (str) – The input identifier.

Return type: None

remove_source(identifier: str) -> None substance_painter.source.SourceSubstance.remove_source

Remove the source for the given input identifier.

Parameters: identifier (str) – The input identifier.

Return type: None

get_parameters() -> Dict[str, bool | int | Tuple[int, int] | Tuple[int, int, int] | Tuple[int, int, int, int] | float | Tuple[float, float] | Tuple[float, float, float] | Color | Tuple[Color, float] | Tuple[float, float, float, float] | str] substance_painter.source.SourceSubstance.get_parameters

Get source procedural parameters. For each property of the source,
the resulting dictionnary holds an entry with the property name as key
and the property value as value.

Returns: The source procedural parameters.

Return type: Dict[str, bool | int | Tuple[int, int] | Tuple[int, int, int] | Tuple[int, int, int, int] | float | Tuple[float, float] | Tuple[float, float, float] | Color | Tuple[Color, float] | Tuple[float, float, float, float] | str]

set_parameters(property_values: Dict[str, bool | int | Tuple[int, int] | Tuple[int, int, int] | Tuple[int, int, int, int] | float | Tuple[float, float] | Tuple[float, float, float] | Color | Tuple[Color, float] | Tuple[float, float, float, float] | str]) -> None substance_painter.source.SourceSubstance.set_parameters

Set source procedural parameters.

Parameters: property_values (Dict*[str,* bool | int | Tuple*[int,* int*]* | Tuple*[int,* int*,* int*]* | Tuple*[int,* int*,* int*,* int*]* | float | Tuple*[float,* float*]* | Tuple*[float,* float*,* float*]* | Color | Tuple*[Color,* float*]* | Tuple*[float,* float*,* float*,* float*]* | str*]*) – A dict of properties to be set with their corresponding values.

Return type: None

get_properties() -> Dict[str, Property] substance_painter.source.SourceSubstance.get_properties

Get source procedural properties.

Returns: The source procedural properties.

Return type: Dict[str, Property]

get_preset_list() -> List[str] substance_painter.source.SourceSubstance.get_preset_list

Get the list of all available presets for this source.

Returns: An array of all preset’s names available.

Return type: List[str]

apply_preset(name: str) substance_painter.source.SourceSubstance.apply_preset

Apply a preset given its name. If no preset is found with this name nothing is done.

Parameters: name (str) – The name of the preset to apply.

property resolution: ResolutionOverride substance_painter.source.SourceSubstance.resolution

The resolution parameters for this substance.

Getter: Returns the resolution parameters.

Setter: Sets the resolution parameters.

Raises:

ValueError – if the source is used in a
substance_painter.layerstack.FilterEffectNode.

class substance_painter.source.OutputMapping(uid) substance_painter.source.OutputMapping

This class gives access to the output mapping of a source procedural in a dict-like fashion.
See output_mapping property.

Example:

import substance_painter as sp
mapping = a_substance_source.output_mapping
mapping[sp.textureset.ChannelType.BaseColor] = sp.textureset.ChannelType.Specular
for channel in mapping:
    print(mapping[channel])