User Guide Cancel

resource | Substance 3D Painter Python API

Last updated on May 16, 2023

Substance 3D Painter Pyhton

Open app

Substance 3D home
Painter Python API
API
1. API overview
2. changelog
3. plugins
4. substance_painter
  1. substance_painter overview
  2. display
  3. event
  4. exception
  5. export
  6. js
  7. logging
  8. project
  9. resource
  10. textureset
  11. ui
Tutorials

resource

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).

Overview

Manipulating resources

The resource module exposes the 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:

See also:

Adding content via the import window.

Resources used by a project

It is possible to list the resources used by the layer stacks and mesh maps of a project with list_layer_stack_resources(), and to update them with update_layer_stack_resource().

There may be other resources referenced by a project outside of the layer stack and mesh maps: see the substance_painter.display module to query and modify them.

Example:

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:

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:

Resources

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

A Substance 3D Painter resource.

identifier identifier() → ResourceID

Get this resource identifier.

Returns: The resource identifier.
Return type: ResourceID
Raises: RuntimeError – If the resource is invalid.

See also

ResourceID.

location location() → ResourceLocation

Get the location of this Resource.

Returns: The location of this resource.
Return type: ResourceLocation
Raises: RuntimeError – If the resource is invalid.

static retrieve retrieve(identifier: ResourceID)

Retrieve a list of resources matching the given identifier.

Parameters

identifier (ResourceID) – A resource identifier.

Raises

ValueError – If the name of the identifier is empty or if the context of the identifier doesn’t exists.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

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 set_custom_preview(preview_image: str) → None

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

ValueError – If the resource metadata cannot be modified.
ValueError – If preview_image is not a valid path to a valid image.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

Note

The preview image can be a JPEG, a PNG or an XPM.

category category() → str

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 usages() → List[Usage]

Get the usages of this resource.

Raises: RuntimeError – If the resource is invalid.
Returns: the usages of this resource
Return type: List[Usage]

See also

Usage

gui_name gui_name() → str

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() → Type

Get the type of this resource.

Raises: RuntimeError – If the resource is invalid.
Returns: the type of this resource
Return type: Type

See also

Type

tags tags() → List[str]

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 internal_properties() → dict

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 children() → List[Resource]

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 parent() → Optional[Resource]

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 reset_preview() → None

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

Raises

ValueError – If the resource metadata cannot be modified.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

show_in_ui show_in_ui() → None

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

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

See also

show_resources_in_ui().

class substance_painter.resource. ResourceID ResourceID(context: str, name: str, version: Optional[str] = None)

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.

Note

A ResourceID object is only an identifier. It provides no guarantees that the resource actually exists.

See also

substance_painter.display.

classmethod from_project from_project(name: str, version: Optional[str] = None)

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

Parameters

name (str) – The resource name.
version (str, optional) – The resource version (hash-like string).

Returns

The resource corresponding to the given name.

Return type

ResourceID

classmethod from_session from_session(name: str, version: Optional[str] = None)

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

Parameters

name (str) – The resource name.
version (str, optional) – The resource version (hash-like string).

Returns

The resource corresponding to the given name.

Return type

ResourceID

classmethod from_url from_url(url: str)

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

ValueError – If url is not a valid URL.
ValueError – If the URL scheme is not resource://.
ValueError – If the resource name is invalid.

location location() → ResourceLocation

Get the location of this ResourceID.

Returns: The location of this resource.
Return type: ResourceLocation

url url() → str

Get the URL form of this ResourceID.

Returns

The URL of the resource.

Return type

str

Raises

ValueError – If the ResourceID doesn’t have a context.
ValueError – If the ResourceID doesn’t have a name.

context context: str

Context of the resource.

Type: str

name name: str

Name of the resource.

Type: str

version version: str = None

Hash identifying the version of the resource.

Type: str

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

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.

See also

StandardQuery.

substance_painter.resource. list_layer_stack_resources list_layer_stack_resources() → List[ResourceID]

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

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

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

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.

Note

The new resource must be of the same type as the resources it replaces. For example a base material resource cannot be updated with a smart material resource.

Moreover:

If the resource is a Substance material, it must have the same number and names of outputs.
If the resource is a Substance filter, it must have the same number and names of inputs and outputs.

Returns

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

Return type

List[ResourceID]

Parameters

old_resource_id (ResourceID) – The identifier of the resource(s) to update.
new_resource (Resource) – The new resource to use instead.

Raises

ProjectError – If no project is opened.
TypeError – If old_resource_id is not a ResourceID.
TypeError – If new_resource is not a Resource.
RuntimeError – If new_resource is not a valid resource.
RuntimeError – If new_resource cannot be used in place of old_resource_id.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

substance_painter.resource. import_project_resource import_project_resource(file_path: str, resource_usage: Usage, name: Optional[str] = None, group: Optional[str] = None) → Resource

Import a resource into the current opened project.

Parameters

file_path (str) – The file path to the resource to be imported.
resource_usage (Usage) – The resource usage.
name (str, optional) – The name of the resource if different from the file name.
group (str, opional) – An optional group name, can be used in resource queries.

Returns

The imported resource object.

Return type

Resource

Raises

ProjectError – If no project is opened.
ValueError – If parameters validation failed.
RuntimeError – If import failed.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

substance_painter.resource. import_session_resource import_session_resource(file_path: str, resource_usage: Usage, name: Optional[str] = None, group: Optional[str] = None) → Resource

Import a resource into the current session.

Parameters

file_path (str) – The file path to the resource to be imported.
resource_usage (Usage) – The resource usage.
name (str, optional) – The name of the resource if different from the file name.
group (str, opional) – An optional group name, can be used in resource queries.

Returns

The imported resource object.

Return type

Resource

Raises

ValueError – If parameters validation failed.
RuntimeError – If import failed.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

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

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.

See also

Resource.show_in_ui().

Shelves

See also:: Shelf configuration.

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

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

can_import_resources can_import_resources() → bool

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 import_resource(file_path: str, resource_usage: Usage, name: Optional[str] = None, group: Optional[str] = None, uuid: Optional[str] = None) → Resource

Import a resource into this shelf.

Parameters

file_path (str) – The file path to the resource to be imported.
resource_usage (Usage) – The resource usage.
name (str, optional) – The name of the resource if different from the file name.
group (str, opional) – An optional group name, can be used in resource queries.
uuid (str, opional) – An optional uuid. If a resource already exists with the same uuid, it will be replaced.

Returns

The imported resource object.

Return type

Resource

Raises

ValueError – If parameters validation failed.
RuntimeError – If import failed.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

is_crawling is_crawling() → bool

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 name() → str

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

path path() → str

Returns

The associated path

Raises

ValueError – If the shelf doesn’t exist anymore.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

resources resources(query: str = '') → List[Resource]

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.

See also

search().

class substance_painter.resource. Shelves Shelves

Collection of static methods to manipulate shelves.

static add add(name: str, path: str) → Shelf

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

name (str) – Name of the new shelf. This name must be unique and must only contain lowercase letters, numbers, underscores or hyphens. Use Shelves.exists() to check if name is already used.
path (str) – Folder path to monitor.

Returns

Newly added shelf.

Return type

Shelf

Raises

ValueError – If name or str are invalid. See logs for details.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

See also

Shelves.exists().

static all all() → List[Shelf]

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 application_shelf() → Shelf: This is the shelf containing the default content shipped with the application.

static exists exists(name: str) → bool

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 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 remove(name: str)

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

ProjectError – If a project is opened.
ValueError – If the shelf doesn’t exist.
ValueError – If the shelf was not created with the Python API.
ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

See also

Shelves.exists().

static user_shelf user_shelf() → 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.

See also

Default shelf documentation.

Events

Project related operations, whether they are initiated through the Python API or in the UI, can trigger the following events. See substance_painter.event for more details.

class substance_painter.event. ShelfCrawlingStarted ShelfCrawlingStarted(shelf_name: str)

Event triggered when a shelf starts reading the file system to discover new resources.

See also

Shelf.is_crawling().

shelf_name shelf_name: str

Name of the shelf discovering resources.

Type: str

class substance_painter.event. ShelfCrawlingEnded ShelfCrawlingEnded(shelf_name: str)

Event triggered when a shelf has finished discovering new resources and loading their thumbnails.

See also

Shelf.is_crawling().

shelf_name shelf_name: str

Name of the shelf that has finished discovering resources.

Type: str

Adobe

Get help faster and easier

New user?

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online

resource | Substance 3D Painter Python API

resource

resource module

Overview

Manipulating resources

Importing resources

Resources used by a project

Custom preview

Resource crawling

Resources

Resource

identifier

location

retrieve

set_custom_preview

category

usages

gui_name

type

tags

internal_properties

children

parent

reset_preview

show_in_ui

ResourceID

from_project

from_session

from_url

location

url

context

name

version

search

list_layer_stack_resources

update_layer_stack_resource

import_project_resource

import_session_resource

show_resources_in_ui

Shelves

Shelf

can_import_resources

import_resource

is_crawling

name

path

resources

Shelves

add

all

application_shelf

exists

refresh_all

remove

user_shelf

Events

ShelfCrawlingStarted

shelf_name

ShelfCrawlingEnded

shelf_name

Get help faster and easier