resource module

This module allows to manipulate Substance 3D Painter resources and shelves.

Substance 3D Painter treats textures, materials, brushes, etc. as resources,
and uses URLs to identify them. Resources can be in the shelf, or can be
embedded directly in a project (like a baked ambient occlusion texture for
example).

class substance_painter.resource.Type(value) substance_painter.resource.Type

Enumeration describing the type of a given resource.

Members:

class substance_painter.resource.UpdateProjectError(old_resource_id: ResourceID, new_resource_id: ResourceID, details: List[str]) substance_painter.resource.UpdateProjectError

Error that occurred during the replace_project_resources() operation.

Parameters:

Overview

Manipulating resources

The resource module exposes the class Resource, which represents a
resource currently available in Substance 3D Painter (either in the current
project, current session, or in a shelf).

Listing all the resources of a shelf can be done with Shelf.resources(),
while search() allows to search for specific resources. Specific resources
can be shown with a filter directly in the Assets window with
Resource.show_in_ui() and show_resources_in_ui().

import substance_painter.resource

# Get all the resources of a shelf:
my_shelf = substance_painter.resource.Shelf("myshelf")
all_shelf_resources = my_shelf.resources()

for resource in all_shelf_resources:
    print(resource.identifier().name)

# Find all resources that match a name:
aluminium_resources = substance_painter.resource.search("aluminium")

for resource in aluminium_resources:
    print(resource.identifier().name)

# Show a single resource in the shelf:
aluminium_resources[0].show_in_ui()

# Show the list of resources found in the shelf:
substance_painter.resource.show_resources_in_ui(aluminium_resources)

Internally, resources are identified with a URL; ResourceID contains
that URL. It can be manipulated directly, with no guaranty that the URL is
referring to an actual resource.

import substance_painter.resource

# Display the URL of a resource:
envmap_resources = substance_painter.resource.search("bonifacio")
for envmap in envmap_resources:
    envmap_id = envmap.identifier()
    print("The URL of the resource `{0}` is {1}"
        .format(envmap_id.name, envmap_id.url()))
    print("The location of the resource `{0}` is {1}"
        .format(envmap_id.name, envmap_id.location()))

# It is possible to create a ResourceID from a URL. If there is no
# resource corresponding to the URL, the ResourceID is still valid
# but refers to a resource that doesn't exist.
envmap2_id = substance_painter.resource.ResourceID.from_url(
    "resource://starter_assets/Bonifacio Street");

# It is possible to create a ResourceID from a context, a name and
# a version (optional). This is equivalent to the above, with the
# same caveat.
envmap3_id = substance_painter.resource.ResourceID(
    context="starter_assets", name="Bonifacio Street")
envmap4_id = substance_painter.resource.ResourceID(
    context="starter_assets", name="Bonifacio Street",
    version="d30facd8d860fc212f864065641cdca4e8006510.image");

# It is possible to get the ResourceID of a resource embedded in the
# current project. This time it refers to an actual resource.
envmap5_id = substance_painter.resource.ResourceID.from_project(
    name="Bonifacio Street");

# Finally, it is possible to get the ResourceID of a resource that
# was imported in the current session:
envmap6_id = substance_painter.resource.ResourceID.from_session(
    name="Bonifacio Street");

If the resource exists, it can be retrieved from its identifier with
Resource.retrieve(). When there are several versions of the same resource,
Resource.retrieve() will return the entire list, starting with the most
recent one. On the contrary, if the resource doesn’t exist or was deleted,
Resource.retrieve() will return an empty list.

import substance_painter.resource

# Create a ResourceID:
envmap_id = substance_painter.resource.ResourceID(context="starter_assets",
                                                    name="Bonifacio Street")

# Get the resources corresponding to the ResourceID. There can be 0 if there
# is no such resource, or more than 1 if there are multiple versions of the
# resource.
envmap_resources = substance_painter.resource.Resource.retrieve(envmap_id)
print("{} resource(s) with that ID".format(len(envmap_resources)))

Importing resources

New resources can be imported, either
to the current project with import_project_resource(),
to the current session with import_session_resource(),
or to a shelf with Shelf.import_resource().
All three functions take a path to the resource to be imported, a Usage
indicating the type of that resource, and optionally a name and a group.
This feature corresponds to the “Import resources” window.

Resources can be imported into a shelf, as long as it is not a read-only shelf.
The Substance shelf, installed along the application, is read-only.
A shelf is also read-only if its path on the file system is read-only.
This can be checked with Shelf.can_import_resources().

Example:

import substance_painter.resource

# Open a project we want to import into (see substance_painter.project
# for details). This step is not necessary if there is already a project
# opened in Substance 3D Painter.
import substance_painter.project
substance_painter.project.open("C:/projects/MeetMat.spp")

# Import a normal map to the project:
new_resource = substance_painter.resource.import_project_resource(
    "C:/textures/MyBakedNormalMap.png",
    substance_painter.resource.Usage.TEXTURE)

# Import a color LUT to the session:
new_color_lut = substance_painter.resource.import_session_resource(
    "C:/textures/sepia.exr",
    substance_painter.resource.Usage.COLOR_LUT)

# Set that color LUT (see substance_painter.display for details).
# This step is unrelated to import, and just meant to show how the
# imported resource can be used.
import substance_painter.display
substance_painter.display.set_color_lut_resource(new_color_lut.identifier())

# Import an environment map to the shelf.
my_shelf = substance_painter.resource.Shelf("myshelf")
if my_shelf.can_import_resources():
    new_resource = my_shelf.import_resource(
        "C:/textures/Bonifacio Street.exr",
        substance_painter.resource.Usage.ENVIRONMENT)
else:
    print("The shelf is read-only.")

• See also:

  Adding content via the import window.

Resource crawling

When Substance 3D Painter is opened, it will browse the different shelves
to discover and index resources, and display their thumbnail. When it regains
focus after switching to another application, it will do so again, in case
the user added a new asset to their shelf folder. This process is referred
to as resource crawling.

When a shelf starts crawling, an event
substance_painter.event.ShelfCrawlingStarted is emitted for that
shelf. When crawling is finished, an event
substance_painter.event.ShelfCrawlingEnded is emitted for that
shelf. At any time, Shelf.is_crawling() will tell if a shelf is
crawling or not.

It is possible from a Python script to explicitly trigger a new resource
crawling with Shelves.refresh_all().

Example:

import substance_painter.resource
import substance_painter.event

# Two event handlers to show when crawling starts and ends:
def on_start_crawl(e):
    print("Shelf `{}` started crawling.".format(e.shelf_name))

def on_end_crawl(e):
    print("Shelf `{}` finished crawling.".format(e.shelf_name))

# Use the event handler to listen to ShelfCrawlingStarted and
# ShelfCrawlingEnded:
substance_painter.event.DISPATCHER.connect(
    substance_painter.event.ShelfCrawlingStarted,
    on_start_crawl)

substance_painter.event.DISPATCHER.connect(
    substance_painter.event.ShelfCrawlingEnded,
    on_end_crawl)

# At this point, the event handlers may or may not print something,
# depending on what the shelves are doing. It is possible to trigger
# a crawling by switching to another application, and coming back
# to Substance 3D Painter.

# It is also possible to trigger a crawling with this call:
substance_painter.resource.Shelves.refresh_all()

my_shelf = substance_painter.resource.Shelf("myshelf")

# Running this bloc at different moments will give different
# results:
if my_shelf.is_crawling():
    print("The shelf is crawling...")
else:
    print("The shelf is idle.")

Resource reloading

Once a resource has been imported in a shelf, in the session or in the project, modifying the
imported file has no effect because Substance 3D Painter keeps a copy of the file to be able to
work with it.

By reloading a resource, the original file is imported again and the resource gets updated in the
shelf, session or project.
Note that this does not update the resources currently used in the project document (layerstack,
shader, env map, etc.).
To update the resources currently used in the project document, use the resource updating feature by
calling substance_painter.event.replace_project_resources().

The resource reloading is triggered by calling
substance_painter.event.reload_modified_resources_async().

Because this process might take some time, it is asynchronous.
The substance_painter.event.ReloadResourcesStarted event is fired when the process starts, and
gives information on the scope of the operation.
The substance_painter.event.ReloadResourcesEnded event is fired when the process ends, and gives
information about the resulting resources status.
No concurrent resource reloading process are allowed. One can check if some process is already
running by calling substance_painter.event.is_reload_modified_resources_running().

Example

import substance_painter as sp

# Two event handlers to show when reloading starts and ends
def on_reload_started(e: sp.event.ReloadResourcesStarted):
    print("Resource reloading asynchronous process started")
    if isinstance(e.filter, sp.resource.ResourcesListFilter):
        print("Reloading specific resources:")
        for res_id in e.filter.resources:
            print(res_id.url())
    else:
        # Also possible to have other types of filters, see documentation
        print("Examine filter if needed")

def on_reload_ended(e):
    print("Resource reloading asynchronous process ended")
    for reloaded in e.reloaded_resources:
        print(f"Resource {reloaded.old_resource_id.url()} updated to {reloaded.new_resource_id.url()}")

    for errors in e.resource_errors:
        print(f"Resource {errors.resource_id.url()} was not reloaded: {errors.error_msg}")

# Use the event handlers to listen to ReloadResourcesStarted and ReloadResourcesEnded events
sp.event.DISPATCHER.connect(sp.event.ReloadResourcesStarted, on_reload_started)
sp.event.DISPATCHER.connect(sp.event.ReloadResourcesEnded, on_reload_ended)

# Find some resources in the current opened project and reload them
resources_to_reload = []
for project_resource_id in sp.resource.list_project_resources():
    if project_resource_id.name == "a":
        print(f"Will reload {project_resource_id.url()}")
        resources_to_reload.append(project_resource_id)

sp.resource.reload_modified_resources_async(sp.resource.ResourcesListFilter(resources_to_reload))

Resources used by a project

Update outdated resources in a project

It is possible to list the outdated resources of a project with
list_project_outdated_resources(), and to update them with
replace_project_resources().
Project resources are all the resources used in the project
(in the layerstack, shaders, environment map, etc.).

Example

import substance_painter as sp

# Before running this example, open a project with some outdated resources
# or modify a resource and reimport it in the shelf.

# Retrieve the list of outdated resources
outdated_resources = sp.resource.list_project_outdated_resources()
# Filter the list to keep only specific resources
resources_to_update = {}
for old_res, new_res in outdated_resources.items():
    # Here the filter is based on the name of the resource
    if old_res.name == 'my_resource':
        resources_to_update[old_res] = new_res

# Print the list of filtered resources
for res in resources_to_update:
    print(res)

# Update the resources in the project
# This call might take some time and can provoke a freeze of the application, depending on:
#   - the number of resources to update and
#   - the number of uses in the project
status = sp.resource.replace_project_resources(resources_to_update)

# Print the result of the update
print(f'status: {status}')

Replace resources in a project

It is possible to list the resources used by in
a project with list_project_resources(), and to replace them with
replace_project_resources().

Example

import substance_painter as sp

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

# Get top position of the Stack
position_stack_top = sp.layerstack.InsertPosition.from_textureset_stack(stack)

# Insert a material
metal_material = sp.resource.search("s:starterassets "
                                    "u:basematerial "
                                    "n:Metal Brushed ")[0]
my_fill = sp.layerstack.insert_fill(position_stack_top)
my_fill.set_material_source(metal_material.identifier())

# List all the resources referenced by the project:
used_resources_ids = sp.resource.list_project_resources()
for resource_id in used_resources_ids:
    print(resource_id.name)

# Get the new resource
new_resource = sp.resource.search("s:starterassets "
                                  "u:basematerial "
                                  "n:Fabric ")[0]

# Find the resource to update:
resource_to_replace = None
for resource_id in used_resources_ids:
    if 'metal_brushed' in resource_id.name:
        resource_to_replace = resource_id
        break

# Replace the old resources by the new one:
status = sp.resource.replace_project_resources(
    {resource_to_replace: new_resource.identifier()})

# Print the result of the update
print(f'status: {status}')

Custom preview

When a resource is imported, a thumbnail is automatically generated for it.
It is possible to replace that thumbnail with a custom preview by using
Resource.set_custom_preview(), or reset the preview with
Resource.reset_preview().

Example:

import substance_painter.resource

aluminium_resources = substance_painter.resource.search("aluminium")
resource = aluminium_resources[0]

# Set the custom preview:
resource.set_custom_preview("C:/textures/MyCustomPreview.png")

# Remove the custom preview:
resource.reset_preview()

Resources

class substance_painter.resource.Resource(handle: _substance_painter.resource.ResourceHandle) substance_painter.resource.Resource

A Substance 3D Painter resource.

Parameters: handle (_substance_painter.resource.ResourceHandle)

identifier() -> ResourceID substance_painter.resource.Resource.identifier

Get this resource identifier.

Returns: The resource identifier.

Return type: ResourceID

Raises: RuntimeError – If the resource is invalid.

location() -> ResourceLocation substance_painter.resource.Resource.location

Get the location of this Resource.

Returns: The location of this resource.

Return type: ResourceLocation

Raises: RuntimeError – If the resource is invalid.

static retrieve(identifier: ResourceID) substance_painter.resource.Resource.retrieve

Retrieve a list of resources matching the given identifier.

Parameters: identifier (ResourceID) – A resource identifier.

Raises:

Returns:

The list of resources matching the given identifier.
If the identifier has a valid version, this method will return only one or
zero resources, otherwise the list may contain several resources. In case
of several resources are returned, the most up to date resource will be at
the begining of the list.

Return type: List[Resource]

set_custom_preview(preview_image: str) -> None substance_painter.resource.Resource.set_custom_preview

Replace the current preview of this resource with a custom image.

Parameters:

preview_image (str) – File path to an image on the disk to use as the new
preview.

Raises:

Return type: None

category() -> str substance_painter.resource.Resource.category

Get the category of this resource, ex: “wood” for a material.

Raises: RuntimeError – If the resource is invalid.

Returns: the category of this resource

Return type: str

usages() -> List[Usage] substance_painter.resource.Resource.usages

Get the usages of this resource.

Raises: RuntimeError – If the resource is invalid.

Returns: the usages of this resource

Return type: List[Usage]

gui_name() -> str substance_painter.resource.Resource.gui_name

Get the GUI name of this resource.

Raises: RuntimeError – If the resource is invalid.

Returns: the GUI name of this resource

Return type: str

type() -> Type substance_painter.resource.Resource.type

Get the type of this resource.

Raises: RuntimeError – If the resource is invalid.

Returns: the type of this resource

Return type: Type

tags() -> List[str] substance_painter.resource.Resource.tags

Get the tags of this resource.

Raises: RuntimeError – If the resource is invalid.

Returns: the tags of this resource

Return type: List[str]

internal_properties() -> dict substance_painter.resource.Resource.internal_properties

Get a dictionnary of the resource internal properties.
The current implementation only extracts metadata on Substance resources.

Raises: RuntimeError – If the resource is invalid.

Returns: a dictionnary containing internal properties about this resource

Return type: dict

children() -> List[Resource] substance_painter.resource.Resource.children

Get child resources.
For example substance graphs of a substance package.

Raises: RuntimeError – If the resource is invalid.

Returns: Resources contained in this resource.

Return type: List[Resource]

parent() -> Resource | None substance_painter.resource.Resource.parent

Get parent resource.
For example the substance package a substance graph is originating from.

Raises: RuntimeError – If the resource is invalid.

Returns: The parent resource that owns this resource.

Return type: Optional[Resource]

reset_preview() -> None substance_painter.resource.Resource.reset_preview

Remove any custom preview for this resource and resets to the default one.

Raises:

Return type: None

show_in_ui() -> None substance_painter.resource.Resource.show_in_ui

Highlight this resource in the application shelf UI (Assets window).

Raises:

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

Return type: None

class substance_painter.resource.ResourceID(context: str, name: str, version: str | None = None) substance_painter.resource.ResourceID

A Substance 3D Painter resource identifier.

The resource is identified by a context, a name, and a version. The context
and the name are mandatory while the version is optional. The version is a
string that looks like a hash, and may also contain an extension.

Parameters:

classmethod from_project(name: str, version: str | None = None) substance_painter.resource.ResourceID.from_project

Create a ResourceID object for a resource located in the current project.

Parameters:

Returns: The resource corresponding to the given name.

Return type: ResourceID

classmethod from_session(name: str, version: str | None = None) substance_painter.resource.ResourceID.from_session

Create a ResourceID object for a resource located in the current session.

Parameters:

Returns: The resource corresponding to the given name.

Return type: ResourceID

classmethod from_url(url: str) substance_painter.resource.ResourceID.from_url

Create a ResourceID object from its URL.
URLs must have resource:// as a scheme. The version is encoded as a query
string, that looks like a hash.

A resource URL looks like this:

resource://context/name?version=0123456789abcdef0123456789abcdef01234567.image

Parameters: url (str) – The resource URL.

Returns: The resource corresponding to the given URL.

Return type: ResourceID

Raises:

location() -> ResourceLocation substance_painter.resource.ResourceID.location

Get the location of this ResourceID.

Returns: The location of this resource.

Return type: ResourceLocation

url() -> str substance_painter.resource.ResourceID.url

Get the URL form of this ResourceID.

Returns: The URL of the resource.

Return type: str

Raises:

context: str substance_painter.resource.ResourceID.context

Context of the resource.

Type: str

name: str substance_painter.resource.ResourceID.name

Name of the resource.

Type: str

version: str = None substance_painter.resource.ResourceID.version

Hash identifying the version of the resource.

Type: str

class substance_painter.resource.ResourceLocation(value) substance_painter.resource.ResourceLocation

Each resource has a location determined by where its data lives.

Members:

Example

import substance_painter.resource

# For a resource from the default shelf
aluminium = substance_painter.resource.ResourceID(
    context="starter_assets", name="Aluminium Insulator");

# This will print:
# ResourceLocation.SHELF
print(aluminium.location())

# For an embedded resource, like a baked map
aomap = substance_painter.resource.ResourceID.from_project(
    name="ambient_occlusion");

# This will print:
# ResourceLocation.PROJECT
print(aomap.location())

# Finally, for a temporary resource
test_envmap = substance_painter.resource.ResourceID.from_session(
    name="Test Envmap");

# This will print:
# ResourceLocation.SESSION
print(test_envmap.location())

class substance_painter.resource.StandardQuery substance_painter.resource.StandardQuery

Standard resource queries.

Members:

class substance_painter.resource.Usage(value) substance_painter.resource.Usage

Enumeration describing how a given resource is meant to be used.

Members:

substance_painter.resource.search(query: str) -> List[Resource] substance_painter.resource.search

List Substance 3D Painter resources that match the given query.

Parameters: query (str) – A resource query string. See text query documentation.

Returns: The list of resources that match the given query.

Return type: List[Resource]

Raises:

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

substance_painter.resource.list_project_resources() -> List[ResourceID] substance_painter.resource.list_project_resources

List the resources used in the current project. Project resources are all
the resources used in the project (in the layerstack, shaders, environment map, etc.).

Returns: The list of resource identifiers.

Return type: List[ResourceID]

Raises:

substance_painter.resource.list_project_outdated_resources() -> Dict[ResourceID, ResourceID] substance_painter.resource.list_project_outdated_resources

List the resources used in the current project that are outdated. Project resources are all
the resources used in the project (in the layerstack, shaders, environment map, etc.).
An outdated resource is a resource that has been reloaded in the application, but not yet
updated in the project.

Returns:

A dictionary with the old resources identifier as key and
the new resources identifier as value.

Return type: Dict[ResourceID,ResourceID]

Raises:

substance_painter.resource.replace_project_resources(ids: Dict[ResourceID, ResourceID], allow_parameters_mismatch: bool = False) -> UpdateProjectResult substance_painter.resource.replace_project_resources

Replace resources in the current project. Project resources are all
the resources used in the project (in the layerstack, shaders, environment map, etc.).

Given a pair of resource identifiers:

The operation will replace any resource having the same identifier
with the new resource. The new resource must be compatible with the ones it
replaces (see note); otherwise, the operation will fail.

If an error occurs during the update, no operation is performed on the project
and the UpdateProjectStatus provides a list of errors.

Parameters:

Returns: The result of the operation.

Return type: UpdateProjectResult

Raises:

class substance_painter.resource.UpdateProjectResult(status: UpdateProjectStatus, errors: List[UpdateProjectError]) substance_painter.resource.UpdateProjectResult

Result of the replace_project_resources() operation.

Parameters:

class substance_painter.resource.UpdateProjectStatus(value) substance_painter.resource.UpdateProjectStatus

Status of the replace_project_resources() operation.

Members:

substance_painter.resource.import_project_resource(file_path: str, resource_usage: Usage, name: str | None = None, group: str | None = None) -> Resource substance_painter.resource.import_project_resource

Import a resource into the current opened project.

Parameters:

Returns: The imported resource object.

Return type: Resource

Raises:

substance_painter.resource.import_session_resource(file_path: str, resource_usage: Usage, name: str | None = None, group: str | None = None) -> Resource substance_painter.resource.import_session_resource

Import a resource into the current session.

Parameters:

Returns: The imported resource object.

Return type: Resource

Raises:

substance_painter.resource.show_resources_in_ui(resources: List[Resource]) -> None substance_painter.resource.show_resources_in_ui

Highlight a list of resources in the application shelf UI (Assets window).

Parameters: resources (List*[Resource]*) – Resources to highlight

Raises:

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

Return type: None

substance_painter.resource.is_reload_modified_resources_running() -> bool substance_painter.resource.is_reload_modified_resources_running

Check if a reload modified resources operation is currently running.

Raises:

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

Return type: bool

substance_painter.resource.reload_modified_resources_async(resource_filter: AllResourcesFilter | ProjectFilter | ResourcesListFilter | ResourcesUsedByProjectFilter | SessionFilter | ShelvesListFilter) -> bool substance_painter.resource.reload_modified_resources_async

Triggers a reload of the modified resources found using the given filter. Outdated resources
are excluded.

If a reload operation is already running, this function will return False.
One can check if a reload operation is already running with
is_reload_modified_resources_running().

This function being asynchronous, events will be sent to notify the progress of the operation:

Parameters:

resource_filter (AllResourcesFilter|ResourcesListFilter|ShelvesListFilter) – A filter
identifying which modified resources to reload.

Returns: True if the reload operation has started, False if it is already running.

Return type: bool

Raises:

Reload filters

class substance_painter.resource.AllResourcesFilter substance_painter.resource.AllResourcesFilter

Filter used to reload all modified resources known to Substance 3D Painter, which includes
resources in all shelves, session-scoped resources, and project-scoped resources.

class substance_painter.resource.ProjectFilter substance_painter.resource.ProjectFilter

Filter used to reload modified resources contained in the project context.
This does not include resources used by the project (in the layerstack, shaders, environment
map, etc.) if they are contained in a shelf or the session.

class substance_painter.resource.ResourcesListFilter(resources: List[ResourceID]) substance_painter.resource.ResourcesListFilter

Filter used to reload modified resources amongst a given list of resources.

Parameters: resources (List*[ResourceID]*) – The list of reources to reload.

class substance_painter.resource.ResourcesUsedByProjectFilter substance_painter.resource.ResourcesUsedByProjectFilter

Filter used to reload modified resources currently in use by the project.
This includes resources from any contexts (project, shelves, session), as long as they are
currently referenced by the project.

class substance_painter.resource.SessionFilter substance_painter.resource.SessionFilter

Filter used to reload modified resources contained in the session.

class substance_painter.resource.ShelvesListFilter(shelves: List[Shelf]) substance_painter.resource.ShelvesListFilter

Filter used to reload modified resources contained in designated shelves.

Parameters: shelves (List*[Shelf]*) – The list of Shelves to reload.

Shelves

• See also:

  Shelf configuration.

class substance_painter.resource.Shelf(_name: str) substance_painter.resource.Shelf

Class providing information on a given Substance 3D Painter shelf. A shelf
is identified by a unique name.

Parameters: _name (str)

can_import_resources() -> bool substance_painter.resource.Shelf.can_import_resources

Check if resources can be imported into this shelf.
Resources can be imported into a shelf, as long as it is not a read-only shelf.
The Substance shelf, installed along the application, is read-only. A shelf is
also read-only if its path on the file system is read-only.

Returns: True if resources can be imported.

Return type: bool

Raises:

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

import_resource(file_path: str, resource_usage: Usage, name: str | None = None, group: str | None = None, uuid: str | None = None) -> Resource substance_painter.resource.Shelf.import_resource

Import a resource into this shelf.

Parameters:

Returns: The imported resource object.

Return type: Resource

Raises:

is_crawling() -> bool substance_painter.resource.Shelf.is_crawling

Check if this shelf is currently discovering resources in folders.

Returns: True if this shelf is discovering resources, False otherwise.

Return type: bool

Raises:

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

name() -> str substance_painter.resource.Shelf.name

Returns:

The shelf name.
Each shelf is identified by a unique name.

Return type: str

path() -> str substance_painter.resource.Shelf.path

Returns: The associated path

Raises:

Return type: str

refresh() substance_painter.resource.Shelf.refresh

Forces discovering of resources in shelf folders.
Discovering is also done automatically when the application window gets focus.

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

resources(query: str = ‘’) -> List[Resource] substance_painter.resource.Shelf.resources

Get resources contained in this shelf. An optional query string can be given
to narrow the results.

Parameters: query (str*,* optional) – A resource query string.

Returns: This shelf’s list of resources.

Return type: List[Resource]

class substance_painter.resource.Shelves substance_painter.resource.Shelves

Collection of static methods to manipulate shelves.

static add(name: str, path: str) -> Shelf substance_painter.resource.Shelves.add

Add a new shelf. This shelf will only be valid during the application session.
The shelf will not be visible from application general settings menu.

Parameters:

Returns: Newly added shelf.

Return type: Shelf

Raises:

static all() -> List[Shelf] substance_painter.resource.Shelves.all

List all shelves.

Returns: List of existing shelves.

Return type: List[Shelf]

Raises:

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

static application_shelf() -> Shelf substance_painter.resource.Shelves.application_shelf

This is the shelf containing the default content shipped with the application.

Return type: Shelf

static exists(name: str) -> bool substance_painter.resource.Shelves.exists

Tell whether a shelf with the given name exists.

Parameters: name (str) – Shelf name to searh for.

Returns: True if a shelf with the given name exists.

Return type: bool

Raises:

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

static refresh_all() substance_painter.resource.Shelves.refresh_all

Forces discovering of resources in all shelves folders.
Discovering is also done automatically when the application window gets focus.

Raises:

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

static remove(name: str) substance_painter.resource.Shelves.remove

Removes a shelf.
No project must be opened.
Deleting a shelf which was not created by the Python API is not possible and
will raise an exception.

Parameters:

name (str) – Name of the shelf to delete.
Use Shelves.exists() to check if a shelf exists.

Raises:

static user_shelf() -> Shelf substance_painter.resource.Shelves.user_shelf

This is the shelf located in the user Documents folder where new resources
are created by default. The user can select a different default shelf in the
settings, and this will be reflected when using this function.

Raises:

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

Return type: Shelf

Deprecated

The following functions are deprecated, they are kept for retrocompatibility and should not be used in new code.

substance_painter.resource.list_layer_stack_resources() -> List[ResourceID] substance_painter.resource.list_layer_stack_resources

List the resources referenced by the layer stacks and mesh maps of the current
project.

Returns: The list of resource identifiers referenced.

Return type: List[ResourceID]

Raises:

substance_painter.resource.update_layer_stack_resource(old_resource_id: ResourceID, new_resource: Resource) -> List[ResourceID] substance_painter.resource.update_layer_stack_resource

Replace resources from the layer stacks and mesh maps in the current project.

Given a resource identifier, replace any resource having the same identifier
with the new resource. The new resource must be compatible with the ones it
replaces (see note); otherwise, an error is thrown.

Returns:

The list of identifiers of all the resources that have
been replaced.

Return type: List[ResourceID]

Parameters:

Raises: