Stack class

class substance_painter.textureset.Stack(stack_id: int | None = None) {#substance_painter.textureset.Stack}

A Substance 3D Painter paintable stack.

A stack can contain a number of channels (BaseColor, Specular, Roughness,
etc.), that correspond to the material. The stack belongs to a Texture Set,
which may contain one or more stacks.

Typically, only one stack is used and that stack is transparent to the user.
Selecting the Texture Set will select its stack. However, a Texture Set can
use layered materials with custom shaders, in which case a specific stack
needs to be selected.

If the Texture Set doesn’t use material layering, you can retrieve its stack
as follows:

import substance_painter.textureset

# Get the unnamed stack of "TextureSetName":
paintable_stack = substance_painter.textureset.Stack.from_name("TextureSetName")

# Alternatively, get the stack from a Texture Set instance:
my_texture_set = substance_painter.textureset.TextureSet.from_name("TextureSetName")
paintable_stack = my_texture_set.get_stack()

If the Texture Set does use material layering, you can retrieve its stacks
as follows:

import substance_painter.textureset

# Get the stack called "Mask1" from the Texture Set "TextureSetName":
paintable_stack = substance_painter.textureset.Stack.from_name("TextureSetName",
                                                               "Mask1")

# Alternatively, get the stack from a Texture Set instance:
my_texture_set = substance_painter.textureset.TextureSet.from_name("TextureSetName")
paintable_stack = my_texture_set.get_stack("Mask1")

# Show the name of the stack:
print(paintable_stack.name())

It is possible to query, add, remove or edit the channels of a stack:

import substance_painter.textureset

# Get the unnamed stack of "TextureSetName":
paintable_stack = substance_painter.textureset.Stack.from_name("TextureSetName")

# List all the channels of the "TextureSetName" Texture Set:
for k,v in paintable_stack.all_channels().items():
    print("{0}: {1}".format(k, str(v.format())))

# Add a scattering channel to the "TextureSetName" Texture Set:
paintable_stack.add_channel(substance_painter.textureset.ChannelType.Scattering,
                            substance_painter.textureset.ChannelFormat.L8)

# Query details of the added scattering channel:
if paintable_stack.has_channel(substance_painter.textureset.ChannelType.Scattering):
    channel = paintable_stack.get_channel(
        substance_painter.textureset.ChannelType.Scattering)
    print("The Texture Set now has a scattering channel with {0} bits per pixel."
        .format(channel.bit_depth()))

# Change the scattering channel to 16 bits inside the "TextureSetName" Texture Set:
paintable_stack.edit_channel(
    channel_type = substance_painter.textureset.ChannelType.Scattering,
    channel_format = substance_painter.textureset.ChannelFormat.L16)

# Remove the scattering channel from "TextureSetName":
paintable_stack.remove_channel(substance_painter.textureset.ChannelType.Scattering)

[!TIP]

See also:
TextureSet,
Texture Set documentation.

Parameters: stack_id (int)

static from_name(texture_set_name: str, stack_name: str = ‘’) {#substance_painter.textureset.Stack.from_name}

Get a stack from its name.

Parameters:

• texture_set_name (str) – Texture Set name.

• stack_name (str) – Stack name.
  Leave empty if the Texture Set does not use material layering.

[!NOTE]

The Texture Set and stack names are case sensitive.

Raises:

• ProjectError – If no project is opened.
• ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
• ValueError – If texture_set_name is not string.
• ValueError – If there is no Texture Set with the name texture_set_name.
• ValueError – If there is no stack with the name stack_name.

Parameters:

• texture_set_name (str)

• stack_name (str)

[!TIP]

See also:
TextureSet.all_stacks(),
TextureSet.get_stack().

name() -> str {#substance_painter.textureset.Stack.name}

Get the stack name.
A stack name is empty if the Texture Set it belongs to uses material layering.

Returns: The stack name.

Return type: str

Raises:

• ProjectError – If no project is opened.
• ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
• ValueError – If the stack is invalid.

material() {#substance_painter.textureset.Stack.material}

Get the Texture Set this stack belongs to.

Returns: The Texture Set this stack belongs to.

Return type: TextureSet

Raises:

• ProjectError – If no project is opened.

• ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

• ValueError – If the stack is invalid.

[!TIP]

See also:
TextureSet,
all_texture_sets().

all_channels() -> Dict[ChannelType, Channel] {#substance_painter.textureset.Stack.all_channels}

List all the channels of a stack.

Returns: Map of all the channels of the stack.

Return type: dict[ChannelType, Channel]

Raises:

• ProjectError – If no project is opened.

• ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

[!TIP]

See also:
Stack.add_channel(),
Stack.remove_channel().

add_channel(channel_type: ChannelType, channel_format: ChannelFormat, label: str | None = None) -> Channel {#substance_painter.textureset.Stack.add_channel}

Add a new channel to a stack.

[!NOTE]

add_channel is not available with material layering.

Parameters:

• channel_type (ChannelType) – The channel type.
• channel_format (ChannelFormat) – The texture format of the new channel.
• label (str*,* optional) – The label of the channel in case of User channel as type.

Returns: The created channel.

Return type: Channel

Raises:

• ProjectError – If no project is opened.

• ValueError – If a channel of type channel_type already exists in this Texture Set.

• ValueError – If a label was provided but channel_type is not a user type.
  Standard channel types have fixed labels.

• ValueError – If the stack is invalid.

• ValueError – If the Texture Set uses material layering.

[!TIP]

See also:
Stack.all_channels(),
Stack.remove_channel(),
Stack.edit_channel().

remove_channel(channel_type: ChannelType) -> None {#substance_painter.textureset.Stack.remove_channel}

Remove a channel from a stack.

[!NOTE]

remove_channel is not available with material layering.

Parameters: channel_type (ChannelType) – The channel type.

Raises:

• ProjectError – If no project is opened.
• ValueError – If there is no channel of type channel_type in this Texture Set.
• ValueError – If the stack is invalid.
• ValueError – If the Texture Set uses material layering.

Return type: None

[!TIP]

See also:
Stack.all_channels(),
Stack.add_channel(),
Stack.edit_channel().

edit_channel(channel_type: ChannelType, channel_format: ChannelFormat, label: str | None = None) -> None {#substance_painter.textureset.Stack.edit_channel}

Change the texture format and label of a channel.

Parameters:

• channel_type (ChannelType) – The channel type.
• channel_format (ChannelFormat) – The new texture format of the channel.
• label (str*,* optional) – The label of the channel in case of User channel as type.

Raises:

• ProjectError – If no project is opened.
• ValueError – If there is no stack labeled stack_id in this Texture Set.
• ValueError – If there is no channel of type channel_type in this Texture Set.
• ValueError – If a label was provided but channel_type is not a user type.
  Standard channel types have fixed labels.
• ValueError – If the stack is invalid.

Return type: None

[!TIP]

See also:
Stack.add_channel(),
Stack.remove_channel().

has_channel(channel_type: ChannelType) -> bool {#substance_painter.textureset.Stack.has_channel}

Check if a channel exists in a stack.

Parameters: channel_type (ChannelType) – The channel type.

Returns: True if the stack has a channel of the given type, False otherwise.

Return type: bool

Raises:

• ProjectError – If no project is opened.

• ValueError – If the stack is invalid.

[!TIP]

See also:
Stack.add_channel(),
Stack.remove_channel().

get_channel(channel_type: ChannelType) -> Channel {#substance_painter.textureset.Stack.get_channel}

Get an existing channel from its type.

Parameters: channel_type (Channel) – The channel type.

Returns: The channel.

Return type: Channel

Raises:

• ProjectError – If no project is opened.

• ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

• ValueError – If the channel doesn’t exists.

[!TIP]

See also:
Stack.has_channel(),
Stack.add_channel(),
Stack.remove_channel().