Stack class

class substance_painter.textureset.

Stack

Stack(stack_id: Optional[int] = None)

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:

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

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

See also

TextureSet, Texture Set documentation.

static

from_name

from_name(texture_set_name: str, stack_name: str = '')

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.

See also

TextureSet.all_stacks(), TextureSet.get_stack().

name

name() → str

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

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.

See also

TextureSet, all_texture_sets().

all_channels

all_channels() → Dict[ChannelType, Channel]

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.

See also

Stack.add_channel(), Stack.remove_channel().

add_channel

add_channel(channel_type: ChannelType, channel_format: ChannelFormat, label: Optional[str] = None) → 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.

See also

Stack.all_channels(), Stack.remove_channel(), Stack.edit_channel().

remove_channel

remove_channel(channel_type: ChannelType) → None

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.

See also

Stack.all_channels(), Stack.add_channel(), Stack.edit_channel().

edit_channel

edit_channel(channel_type: ChannelType, channel_format: ChannelFormat, label: Optional[str] = None) → None

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.

See also

Stack.add_channel(), Stack.remove_channel().

has_channel

has_channel(channel_type: ChannelType) → bool

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.

See also

Stack.add_channel(), Stack.remove_channel().

get_channel

get_channel(channel_type: ChannelType) → 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.

See also

Stack.has_channel(), Stack.add_channel(), Stack.remove_channel().