Substance 3D Painter Python API

https://helpx.adobe.com/substance-3d-painter-python/
Admin
Substance 3D Painter Python API provides access to Substance 3D Painter functionalities through...
Tokens:51,360
Snippets:449
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### List and Start a Plugin

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/substance-painter-plugins.html

This snippet demonstrates how to get a list of all available plugin names, iterate through them, and then load and start a specific plugin named 'hello_plugin'. Ensure the 'hello_plugin' is accessible in the plugin path.

```python
import importlib 
import substance_painter_plugins 

# Get the list of available Plugin names: 
all_plugins_names = substance_painter_plugins.plugin_module_names()
for name in all_plugins_names:
    print(name)

# Load the "hello world" Plugin: 
plugin = importlib.import_module("hello_plugin")

# Start the Plugin if it wasn't already:
if not substance_painter_plugins.is_plugin_started(plugin):
    substance_painter_plugins.start_plugin(plugin)
```

--------------------------------

### Full JSON Configuration Example

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/export.html

This example demonstrates a comprehensive JSON configuration for exporting assets, including detailed settings for texture sets, output maps, UV tiles, and parameter overrides.

```json
{
    "exportPath" : "C:/export",
    "exportShaderParams" : true,
    "defaultExportPreset" : "preset1",
    "exportList" : [
        {
            "rootPath" : "02_Body/Mask",
            "filter" : {
                "outputMaps" : ["$textureSet_color"],
                "uvTiles" : [[1, 1]]
            },
            "exportPreset" : "preset1"
        }
    ],
    "exportParameters" : [
        {
            "filter" : {
                "dataPaths": ["01_Head", "02_Body/Mask"],
                "outputMaps": ["$textureSet_color"],
                "uvTiles" : [[1, 1]]
            },
            "parameters" : {
                "sizeLog2" : 11
            }
        }
    ]
}
```

--------------------------------

### Full JSON Export Configuration Example

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/export.html

This example demonstrates the complete structure of a JSON configuration for texture export, including export path, shader parameters, default preset, and a detailed export preset with map definitions and parameters.

```json
{
// Path to the root folder where texture files will be exported. 
"exportPath" : "C:/export", 
// Whether to export shader instances to a JSON file. 
"exportShaderParams" : true, 
// (optional) Export preset to be used when no export preset is provided in
// "exportList.exportPreset". 
// The value can be the name of a preset defined in the "exportPresets" part 
// of the configuration JSON:
"defaultExportPreset" : "preset1", 
// Alternatively the value can be a URL to an existing preset file (see 
// substance_painter.resource) listed in the export dialog: 
// "defaultExportPreset" : substance_painter.resource.ResourceID(
// context="starter_assets", 
// name="PBR Metallic Roughness").url(), 
// (optional) List of export presets definitions. 
"exportPresets" : [{
// Defines the name of the export preset. This name can be referenced in
// "defaultExportPreset" and/or "exportList.exportPreset". 
"name" : "preset1", 
// List of maps making up this export preset. 
"maps" : [{
// Filename of the texture file written to disk; may contain wildcards 
// resolved at export time. 
// (e.g. "$project_$mesh_$textureSet_$udim_$sceneMaterial_BaseColor")
// 
// $project: Project name. 
// $mesh: Filename of the imported mesh. 
// $textureSet: Current Texture Set. 
// $sceneMaterial: Current material name, as found in the imported 
// mesh. 
// $udim: Current UV Tile (e.g. 1001).
"fileName" : "$textureSet_color", 
// List of source/destination defining which channels will make up the 
// texture file. 
"channels" : [{
// Channel to write to. 
// L (Luminance), R (Red), G (Green), B (Blue), A (Alpha)
// 
// In addition to alpha channel, either R+G+B must be specified, or
// either L only. 
"destChannel" : "R", 
// Channel to read from. 
// L, R, G, B, A 
// 
// When the source map is color, L will generate a mix of R+G+B. 
"srcChannel" : "R", 
// The type of map to read from: 
// documentMap: Maps present in the document (e.g. "baseColor"). 
// meshMap: Baked mesh maps (e.g. "normal"). 
// virtualMap: Generated map (e.g. "f0"). 
// defaultMap: Constant color (e.g. "black"). 
"srcMapType" : "documentMap", 
// Name of the map of type scrMapType. 
// 
// For type documentMap: 
// basecolor, height, specular, opacity, emissive, displacement, 
// glossiness, roughness, anisotropylevel, anisotropyangle, 
// transmissive, scattering, reflection, ior, metallic, normal, 
// ambientOcclusion, diffuse, specularlevel, blendingmask, user0, 
// user1, user2, user3, user4, user5, user6, user7. 
// 
// For type meshMap: 
// ambient_occlusion, id, curvature, normal_base, 
// world_space_normals, position, thickness. 
// 
// For type virtualMap: 
// Normal_OpenGL, Normal_DirectX, AO_Mixed, Diffuse, Specular, 
// Glossiness, Unity4Diff, Unity4Gloss, reflection, 1/ior, 
// Glossiness2, f0, View_2D. 
// 
// For type defaultMap: 
// black, white. 
"srcMapName" : "baseColor"
}], 
// (optional) Export parameters to be used for this export preset map. 
// 
// When "parameters" is not provided, the existing parameters are used. 
// When "parameters" is provided, it overrides the existing parameters. 
// 
// Each individual parameter is optional and, when defined, overrides 
// previously defined parameters. See in exportList.parameters how the 
// rules are applied. 
// 
// It is important to understand that even though this section is
// optional, if after evaluating all the rules some parameters remain 
// undefined, the configuration is invalid. 
"parameters" : {
// (optional) File format (and file extension) of the generated 
// texture file. 
"fileFormat" : "png", 
// (optional) Bit depth. 
// 
// The bit depth must be supported by the file format. 
"bitDepth" : "16", 
// (optional) Whether to use dithering. 
"dithering" : false, 
// (optional) Size of the texture file in log2. 
// (i.e. 10 means 2^10 = 1024)
// 
// When "sizeLog2" is not provided, the texture size from the project 
// is used. 
// 
// It can either be a single integer, or an array of two integers. 
// 
// If it's a single integer, it represents the biggest of width and 
// height, and will maintain the aspect ratio. 
// (i.e. 10 means a 2048x4086 map will be exported as 512x1024)
// 
// If it's an array of two integers, the original aspect ratio will be 
// ignored. 
// (i.e. [10, 12] means a 2048x4086 map will be exported as 1024x4096)
"sizeLog2" : 10, 
// (optional) Padding algorithm used to fill holes in rendered 
// texture. 
// 
// The possible values are: 
// passthrough, color, transparent, diffusion, infinite. 
"paddingAlgorithm" : "diffusion", 
// (optional) When padding algorithm needs it, distance in pixels used 
// by the padding algorithm. 
// 
// Dilation distance is needed for transparent, color and diffusion 
// padding algorithms. 
"dilationDistance" : 16
}
}]
}], 
// List of subparts of the document to export. 
"exportList" : [{
// Root path of the document structure this subpart applies to. 
// 

```

--------------------------------

### load_startup_modules

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/substance-painter-plugins.html

Loads all modules that are set to start automatically.

```APIDOC
## load_startup_modules

### Description
Loads all startup modules.

### Method
Not applicable (Python function call)

### Endpoint
Not applicable (Python function call)

### Parameters
None

### Request Example
```python
substance_painter_plugins.load_startup_modules()
```

### Response
None (function call)

### Error Handling
Not specified
```

--------------------------------

### Initialize Versioning Plugin

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/versioning-plugin.html

Starts the Versioning Plugin by creating an instance of the VersioningPlugin class.

```python
VERSIONING_PLUGIN = Nonedef start_plugin():
    """This method is called when the plugin is started."""
    global VERSIONING_PLUGIN
    VERSIONING_PLUGIN = VersioningPlugin()
```

--------------------------------

### Get and Set Texture Set Resolution

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset.html

Demonstrates how to get the resolution of the current texture set's material and how to change it. Also shows how to change the resolution for all texture sets.

```python
import substance_painter.textureset

# Show the resolution of the current Texture Set: 
active_stack = substance_painter.textureset.get_active_stack()
material_resolution = active_stack.material().get_resolution()
print("Resolution: {0}x{1}".format(material_resolution.width, material_resolution.height))

# Change the resolution of the current Texture Set: 
new_resolution = substance_painter.textureset.Resolution(512, 512)
active_stack.material().set_resolution(new_resolution)

# Change the resolution of all Texture Sets: 
all_texture_sets = substance_painter.textureset.all_texture_sets()
substance_painter.textureset.set_resolutions(all_texture_sets, new_resolution)
```

--------------------------------

### Install NumPy using pip

Source: https://helpx.adobe.com/substance-3d-painter-python/tutorials/loading-external-python-modules.html

Use pip to install external Python modules. Ensure the module is compatible with the application's Python version.

```bash
> pip install numpy 
Defaulting to user installation because normal site-packages is not writeable 
Collecting numpy 
Downloading numpy-1.21.0-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (15.7 MB)
|████████████████████████████████| 15.7 MB 2.5 MB/s 
Installing collected packages: numpy 
Successfully installed numpy-1.21.0
```

--------------------------------

### Plugin Initialization and Closing

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/versioning-plugin.html

Functions to start and close the plugin, managing the global plugin instance.

```python
VERSIONING_PLUGIN = None
def start_plugin(): 
    """This method is called when the plugin is started."""
    global VERSIONING_PLUGIN 
    VERSIONING_PLUGIN = VersioningPlugin()
def close_plugin(): 
    """This method is called when the plugin is stopped."""
    global VERSIONING_PLUGIN 
    del VERSIONING_PLUGIN
if __name__ == "__main__": 
    start_plugin()
```

--------------------------------

### Create a 'Hello World' Plugin in Python

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/hello-plugin.html

This script creates a simple text widget and adds it as a dockable element to the Substance 3D Painter interface. It includes functions to start and close the plugin, managing UI elements for cleanup.

```python
from PySide2 import QtWidgets
import substance_painter.ui

plugin_widgets = []
"""Keep track of added ui elements for cleanup"""

def start_plugin():
    """This method is called when the plugin is started."""
    # Create a simple text widget
    hello_widget = QtWidgets.QTextEdit()
    hello_widget.setText("Hello from python scripting!")
    hello_widget.setReadOnly(True)
    hello_widget.setWindowTitle("Hello Plugin")
    # Add this widget as a dock to the interface
    substance_painter.ui.add_dock_widget(hello_widget)
    # Store added widget for proper cleanup when stopping the plugin
    plugin_widgets.append(hello_widget)

def close_plugin():
    """This method is called when the plugin is stopped."""
    # We need to remove all added widgets from the UI.
    for widget in plugin_widgets:
        substance_painter.ui.delete_ui_element(widget)
    plugin_widgets.clear()

if __name__ == "__main__":
    start_plugin()
```

--------------------------------

### Initialize Versioning Plugin

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/versioning-plugin.html

Starts the VersioningPlugin by creating an instance and assigning it to the global VERSIONING_PLUGIN variable. This function is called when the plugin is loaded.

```python
def start_plugin():
    """This method is called when the plugin is started."""
    global VERSIONING_PLUGIN
    VERSIONING_PLUGIN = VersioningPlugin()
```

--------------------------------

### List, Search, and Show Resources

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Demonstrates how to get all resources from a specific shelf, search for resources by name, and display them in the Substance Painter UI. Ensure the 'myshelf' exists or adjust the shelf name accordingly.

```python
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)
```

--------------------------------

### Complete Project Management Example

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Demonstrates a comprehensive workflow for creating, saving, managing, and closing Substance 3D Painter projects using the Python API. This includes creating a project from a mesh, saving it, saving a copy, closing it, reopening it, and creating a template.

```python
import substance_painter.project 

# A few declarations used in this example: 
workFolder = "C:/MyWorkDir"
meshFile = workFolder+"/MeetMat.FBX"
templateFile = workFolder+"/MyTemplate.spt"
mySettings = substance_painter.project.Settings(
import_cameras=True, 
normal_map_format=substance_painter.project.NormalMapFormat.OpenGL)

# This should print nothing if you just opened Substance 3D Painter, 
# since no project is opened: 
if substance_painter.project.is_open(): 
print("There is already a project opened!")

# Create a project from a file, import cameras from the file, and set up 
# the project for OpenGL: 
substance_painter.project.create(mesh_file_path=meshFile, settings=mySettings)

# Show the current state of the project: 
if substance_painter.project.is_open(): 
print("The project was successfully created.")
if substance_painter.project.needs_saving(): 
print("The project hasn't been saved yet.")

# At this stage the file path is empty: 
print("The file path of the project is: '{0}'"
.format(substance_painter.project.file_path()))

# Save the project to a file: 
substance_painter.project.save_as(workFolder+"/MyNewProject.spp") # No errors 

if not substance_painter.project.needs_saving(): 
print("As expected, there is nothing to save since this was just done.")
print("The file path of the project is now: '{0}'"
.format(substance_painter.project.file_path()))
print("The name of the project is now: '{0}'"
.format(substance_painter.project.name()))

# ... 
# Do some painting here. 
# ... 

# Create a backup copy of the project, but keep on working on the initial project: 
substance_painter.project.save_as_copy(workFolder+"/MyBackupProject.spp")

if not substance_painter.project.needs_saving(): 
print("Even though a back copy was made, the project still has to be saved.")
print("The file path of the project is still: '{0}'"
.format(substance_painter.project.file_path()))

# ... 
# Do some more painting here. 
# Suppose you make a terrible mistake and want to revert to the backup copy. 
# ... 

# Close the current project; all unsaved changes are lost! 
substance_painter.project.close()

if not substance_painter.project.is_open(): 
print("No project is opened anymore.")

# Open the backup copy: 
substance_painter.project.open(workFolder+"/MyBackupProject.spp")

if substance_painter.project.is_open()
print("Our project is back!")

# We can save a template from the project: 
substance_painter.project.save_as_template(templateFile, "01_Head")
substance_painter.project.close()

# We can now create a new project with that template file: 
substance_painter.project.create(mesh_file_path=meshFile, 
template_file_path=templateFile)

```

--------------------------------

### Resource.usages

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Gets the list of usages for a resource, indicating how it can be applied within Substance Painter.

```APIDOC
## Resource.usages

### Description
Get the usages of this resource.

### Method
`usages() → List[Usage]`

### Raises
**RuntimeError** – If the resource is invalid.

### Returns
the usages of this resource

### Return type
List[Usage]
```

--------------------------------

### Import and Use an External Module (NumPy)

Source: https://helpx.adobe.com/substance-3d-painter-python/tutorials/loading-external-python-modules.html

Once the path is verified, you can import and use external modules like NumPy. This example shows how to import NumPy and display its version.

```python
import numpy
numpy.__version__
```

--------------------------------

### Export About to Start Event Handler

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/versioning-plugin.html

Logs a message when the export process is about to begin. This method can be extended for custom integration logic.

```python
def on_export_about_to_start(self, export_configuration):
    self.log.append("Export textures.")
################################## 
# Add custom integration code here
```

--------------------------------

### Get and Set Texture Set Resolution

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset.html

Demonstrates how to retrieve the resolution of the active Texture Set and how to change it. Also shows how to set resolutions for all Texture Sets in the project.

```python
import substance_painter.textureset 
# Show the resolution of the current Texture Set: 
active_stack = substance_painter.textureset.get_active_stack()
material_resolution = active_stack.material().get_resolution()
print("Resolution: {0}x{1}".format(material_resolution.width, material_resolution.height))
# Change the resolution of the current Texture Set: 
new_resolution = substance_painter.textureset.Resolution(512, 512)
active_stack.material().set_resolution(new_resolution)
# Change the resolution of all Texture Sets: 
all_texture_sets = substance_painter.textureset.all_texture_sets()
substance_painter.textureset.set_resolutions(all_texture_sets, new_resolution)
```

--------------------------------

### Full JSON Configuration for Export

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/export.html

This is a comprehensive example of the `json_config` dictionary, illustrating all possible keys and their nested structures for controlling texture export, including paths, shader parameters, and detailed export presets.

```json
{
  "exportPath": "C:/export",
  "exportShaderParams": true,
  "defaultExportPreset": "preset1",
  "exportPresets": [
    {
      "name": "preset1",
      "maps": [
        {
          "fileName": "$textureSet_color",
          "channels": [
            {
              "destChannel": "R",
              "srcChannel": "R",
              "srcMapType": "documentMap",
              "srcMapName": "baseColor"
            }
          ],
          "parameters": {
            "fileFormat": "png",
            "bitDepth": "16",
            "dithering": false,
            "sizeLog2": 10,
            "paddingAlgorithm": "diffusion",
            "dilationDistance": 16
          }
        }
      ]
    }
  ],
  "exportList": [
    {
      "exportPath": "O1_Head"
    }
  ]
}
```

--------------------------------

### Setup Project Color Management with PAINTER_ACE_CONFIG

Source: https://helpx.adobe.com/substance-3d-painter-python/api/changelog.html

The `substance_painter.project.create()` function supports the `PAINTER_ACE_CONFIG` environment variable for setting up project color management mode. This was added in version 0.2.5.

```python
substance_painter.project.create()
```

--------------------------------

### Resource Methods

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Provides methods to get information about a resource, such as its GUI name, type, tags, internal properties, children, and parent. It also includes methods to reset previews and show the resource in the UI.

```APIDOC
## 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

## 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.
```

--------------------------------

### ShelfCrawlingStarted

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/event.html

Event triggered when a shelf starts reading the file system to discover new resources. It includes the name of the shelf that is crawling.

```APIDOC
## ShelfCrawlingStarted

Event triggered when a shelf starts reading the file system to discover new resources.
See also `Shelf.is_crawling()`.

### Parameters

- **_shelf_name** (str) - Required - Name of the shelf discovering resources.

### Type

`substance_painter.event.ShelfCrawlingStarted`
```

--------------------------------

### Get and Set Environment Map

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/display.html

Retrieves the current environment map resource and shows how to set a new one by specifying its context and name. Prints the URL of the environment map.

```python
# Show the currently used environment map:
envmap = substance_painter.display.get_environment_resource()
print(envmap.url())

# Set a different environment map:
new_envmap = substance_painter.resource.ResourceID(context="starter_assets", 
                                                   name="Bonifacio Street")
substance_painter.display.set_environment_resource(new_envmap)
```

--------------------------------

### Get and Set Color Profile (LUT)

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/display.html

Retrieves the currently used color profile (LUT) and demonstrates how to set a new one using its ResourceID. Handles cases where no color profile is active.

```python
import substance_painter.display 

# Show the currently used color profile: 
color_lut = substance_painter.display.get_color_lut_resource()
if (color_lut != None):
    print(color_lut.url())
else:
    print("No color profile is used.")

# Set a different color profile: 
new_color_lut = substance_painter.resource.ResourceID(context="starter_assets", 
                                                      name="sepia") 
substance_painter.display.set_color_lut_resource(new_color_lut)
```

--------------------------------

### TextureSet Operations

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset.html

This snippet demonstrates common operations for managing Texture Sets, including getting and setting resolutions, listing Texture Sets, and handling UV Tiles.

```APIDOC
## TextureSet Operations

### Description
Demonstrates how to interact with Texture Sets, including retrieving and setting resolutions for individual Texture Sets and all Texture Sets, listing all available Texture Sets, and managing UV Tiles.

### Methods
- `substance_painter.textureset.get_active_stack()`: Retrieves the currently active stack.
- `active_stack.material().get_resolution()`: Gets the resolution of the material associated with the active stack.
- `substance_painter.textureset.Resolution(width, height)`: Creates a resolution object.
- `active_stack.material().set_resolution(new_resolution)`: Sets the resolution for the material of the active stack.
- `substance_painter.textureset.all_texture_sets()`: Returns a list of all Texture Sets in the project.
- `substance_painter.textureset.set_resolutions(texture_sets, new_resolution)`: Sets a uniform resolution for a list of Texture Sets.
- `texture_set.name()`: Gets the name of a Texture Set.
- `texture_set.is_layered_material()`: Checks if a Texture Set is a layered material.
- `texture_set.all_uv_tiles()`: Retrieves all UV Tiles for a given Texture Set.
- `uvtile.v`: Accesses the V coordinate of a UV Tile.
- `uvtile.u`: Accesses the U coordinate of a UV Tile.
- `uvtile.get_resolution()`: Gets the resolution of a UV Tile.
- `uvtile.set_resolution(new_resolution)`: Sets the resolution for a UV Tile.
- `texture_set.reset_uvtiles_resolution(uv_tiles)`: Resets the resolution of specified UV Tiles.

### Example Usage
```python
import substance_painter.textureset

# Show the resolution of the current Texture Set
active_stack = substance_painter.textureset.get_active_stack()
material_resolution = active_stack.material().get_resolution()
print(f"Resolution: {material_resolution.width}x{material_resolution.height}")

# Change the resolution of the current Texture Set
new_resolution = substance_painter.textureset.Resolution(512, 512)
active_stack.material().set_resolution(new_resolution)

# Change the resolution of all Texture Sets
all_texture_sets = substance_painter.textureset.all_texture_sets()
substance_painter.textureset.set_resolutions(all_texture_sets, new_resolution)

# List all the Texture Sets
for texture_set in substance_painter.textureset.all_texture_sets():
    print(f"Texture Set '{texture_set.name()}': {'layered' if texture_set.is_layered_material() else 'not layered'}")

# Get all uv tiles in the first row
row0 = [uvtile for uvtile in substance_painter.textureset.all_uv_tiles() if uvtile.v == 0]

# Set their resolution to 2k
new_resolution_2k = substance_painter.textureset.Resolution(2048, 2048)
resolutions = {uvtile: new_resolution_2k for uvtile in row0}
substance_painter.textureset.set_uvtiles_resolution(resolutions)

# Set 1001 in 4k if its width is not high enough
uvtile_1001 = next((uvtile for uvtile in row0 if uvtile.u == 0), None)
new_resolution_4k = substance_painter.textureset.Resolution(4096, 4096)
if uvtile_1001 and uvtile_1001.get_resolution().width < new_resolution_4k.width:
    uvtile_1001.set_resolution(new_resolution_4k)

# Reset all uv tiles resolution
all_uv_tiles = substance_painter.textureset.all_uv_tiles()
# Assuming 'texture_set' is defined elsewhere or obtained via all_texture_sets()
# For demonstration, let's assume we are operating on the first texture set's uv tiles
if all_texture_sets:
    first_texture_set = all_texture_sets[0]
    first_texture_set.reset_uvtiles_resolution(first_texture_set.all_uv_tiles())
```
```

--------------------------------

### Export Parameters Override Rule

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/export.html

This example demonstrates how to define rules to override export parameters for specific texture files. It includes filtering by data paths and output maps, and setting specific parameters like `sizeLog2`.

```json
{
  "exportParameters": [
    {
      "filter": {
        "dataPaths": ["01_Head", "02_Body/Mask"],
        "outputMaps": ["$textureSet_color"],
        "uvTiles": [[1, 1]]
      },
      "parameters": {
        "sizeLog2": 11
      }
    }
  ]
}
```

--------------------------------

### Create and Save Project

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Demonstrates creating a new project from a mesh file with specific settings, saving it, and checking its status.

```python
import substance_painter.project

# A few declarations used in this example:
workFolder = "C:/MyWorkDir"
meshFile = workFolder+"/MeetMat.FBX"
templateFile = workFolder+"/MyTemplate.spt"
mySettings = substance_painter.project.Settings(
    import_cameras=True,
    normal_map_format=substance_painter.project.NormalMapFormat.OpenGL)

# This should print nothing if you just opened Substance 3D Painter,
# since no project is opened:
if substance_painter.project.is_open():
    print("There is already a project opened!")# Create a project from a file, import cameras from the file, and set up
# the project for OpenGL:
substance_painter.project.create(mesh_file_path=meshFile, settings=mySettings)

# Show the current state of the project:
if substance_painter.project.is_open():
    print("The project was successfully created.")
if substance_painter.project.needs_saving():
    print("The project hasn't been saved yet.")
# At this stage the file path is empty:
print("The file path of the project is: '{0}'"
    .format(substance_painter.project.file_path()))# Save the project to a file:
substance_painter.project.save_as(workFolder+"/MyNewProject.spp") # No errors
if not substance_painter.project.needs_saving():
    print("As expected, there is nothing to save since this was just done.")
print("The file path of the project is now: '{0}'"
    .format(substance_painter.project.file_path()))
print("The name of the project is now: '{0}'"
    .format(substance_painter.project.name()))
```

--------------------------------

### Get Last Imported Mesh Path

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Retrieves the file path of the most recently imported mesh. This function requires an open project and that Substance Painter services have started.

```python
last_mesh_path = substance_painter.project.last_imported_mesh_path()
```

--------------------------------

### Create and Display a Hello World Widget

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/hello-plugin.html

This Python snippet demonstrates how to create a simple text widget with a 'Hello World' message and add it as a dockable element to the Substance 3D Painter interface. It also includes logic for cleaning up the widget when the plugin is stopped.

```python
########################################################################## 
# ADOBE CONFIDENTIAL 
# 
_ 
# Copyright 2010-2020 Adobe 
# All Rights Reserved. 
# NOTICE: All information contained herein is, and remains 
# the property of Adobe and its suppliers, if any. The intellectual 
# and technical concepts contained herein are proprietary to Adobe 
# and its suppliers and are protected by all applicable intellectual 
# property laws, including trade secret and copyright laws. 
# Dissemination of this information or reproduction of this material 
# is strictly forbidden unless prior written permission is obtained 
# from Adobe. 
########################################################################## 
"""The hello world of python scripting in Substance 3D Painter 
"""
from PySide2 import QtWidgets 
import substance_painter.ui 
plugin_widgets = []
"""Keep track of added ui elements for cleanup"""
def start_plugin(): 
"""This method is called when the plugin is started."""
# Create a simple text widget 
hello_widget = QtWidgets.QTextEdit()
hello_widget.setText("Hello from python scripting!")
hello_widget.setReadOnly(True)
hello_widget.setWindowTitle("Hello Plugin")
# Add this widget as a dock to the interface 
substance_painter.ui.add_dock_widget(hello_widget)
# Store added widget for proper cleanup when stopping the plugin 
plugin_widgets.append(hello_widget)
def close_plugin(): 
"""This method is called when the plugin is stopped."""
# We need to remove all added widgets from the UI. 
for widget in plugin_widgets: 
substance_painter.ui.delete_ui_element(widget)
plugin_widgets.clear()
if __name__ == "__main__": 
start_plugin()
```

--------------------------------

### close_all_plugins

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/substance-painter-plugins.html

Closes all plugins that have been started.

```APIDOC
## close_all_plugins

### Description
Closes all started plugins.

### Method
Not applicable (Python function call)

### Endpoint
Not applicable (Python function call)

### Parameters
None

### Request Example
```python
substance_painter_plugins.close_all_plugins()
```

### Response
None (function call)

### Error Handling
Not specified
```

--------------------------------

### Resource.identifier

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Gets the unique identifier for a resource.

```APIDOC
## Resource.identifier

### Description
Get this resource identifier.

### Method
`identifier() → ResourceID`

### Raises
**RuntimeError** – If the resource is invalid.

### Returns
The resource identifier.

### Return type
ResourceID
```

--------------------------------

### Save Project as Template and Create New Project

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Illustrates saving the current project as a template and then creating a new project using that template.

```python
# We can save a template from the project: 
substance_painter.project.save_as_template(templateFile, "01_Head")
substance_painter.project.close()

# We can now create a new project with that template file:
substance_painter.project.create(mesh_file_path=meshFile, template_file_path=templateFile)

# End of our little example...
substance_painter.project.close()
```

--------------------------------

### Create Project Backup

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Shows how to create a backup copy of the current project without affecting the active project.

```python
# ...
# Do some painting here.
# ...

# Create a backup copy of the project, but keep on working on the initial project:
substance_painter.project.save_as_copy(workFolder+"/MyBackupProject.spp")
if not substance_painter.project.needs_saving():
    print("Even though a back copy was made, the project still has to be saved.")
print("The file path of the project is still: '{0}'"
    .format(substance_painter.project.file_path()))
```

--------------------------------

### Resource.category

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Gets the category of a resource, such as 'wood' for a material.

```APIDOC
## Resource.category

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

### Method
`category() → str`

### Raises
**RuntimeError** – If the resource is invalid.

### Returns
the category of this resource

### Return type
str
```

--------------------------------

### Save Project as Template and Create New Project

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Shows how to save the current project as a template and then create a new project using that template. This is useful for establishing project standards or reusing configurations.

```python
# We can save a template from the project:
substance_painter.project.save_as_template(templateFile, "01_Head")
substance_painter.project.close()

# We can now create a new project with that template file:
substance_painter.project.create(mesh_file_path=meshFile,
                                 template_file_path=templateFile)
```

--------------------------------

### Resource.location

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Gets the location of a resource on the file system or within the application.

```APIDOC
## Resource.location

### Description
Get the location of this Resource.

### Method
`location() → ResourceLocation`

### Raises
**RuntimeError** – If the resource is invalid.

### Returns
The location of this resource.

### Return type
ResourceLocation
```

--------------------------------

### Listing Plugin Names

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/substance-painter-plugins.html

Retrieve the names of available startup and plugin modules.

```APIDOC
## Listing Plugin Names

### `substance_painter_plugins.startup_module_names()`

**Description**: Lists the names of the available startup modules.

**Returns**:
- A list of strings representing the names of all available startup modules.

**Return type**:
- `list[str]`

### `substance_painter_plugins.plugin_module_names()`

**Description**: Lists the names of the available plugins modules.

**Returns**:
- A list of strings representing the names of all available plugins modules.

**Return type**:
- `list[str]`
```

--------------------------------

### Get ResourceID from Session

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Retrieves the ResourceID for a resource that was imported into the current session.

```python
import substance_painter.resource
envmap6_id = substance_painter.resource.ResourceID.from_session(
    name="Bonifacio Street")
```

--------------------------------

### Close and Reopen Project with Backup

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Demonstrates closing the current project, checking if it's closed, and then reopening a backup copy. This is useful for recovery or reverting to a previous state.

```python
substance_painter.project.close()
if not substance_painter.project.is_open():
    print("No project is opened anymore.")

# Open the backup copy:
substance_painter.project.open(workFolder+"/MyBackupProject.spp")
if substance_painter.project.is_open()
    print("Our project is back!")
```

--------------------------------

### Get Parent Texture Set

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset/stack.html

Retrieves the Texture Set to which this stack belongs.

```APIDOC
##### 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()`.
```

--------------------------------

### Get Channel Type

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset/channel.html

Retrieves the type of the channel (e.g., BaseColor, Roughness, User0).

```python
channel_type = channel.type()
```

--------------------------------

### Get and Print Active Stack

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset.html

Retrieves and prints the currently active texture set stack.

```python
import substance_painter.textureset

# Show the current active stack: 
print(substance_painter.textureset.get_active_stack())
```

--------------------------------

### Close and Reopen Project

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Demonstrates closing the current project and then reopening a previously saved backup copy.

```python
# ...
# Do some more painting here.
# Suppose you make a terrible mistake and want to revert to the backup copy.
# ...

# Close the current project; all unsaved changes are lost!
substance_painter.project.close()
if not substance_painter.project.is_open():
    print("No project is opened anymore.")

# Open the backup copy:
substance_painter.project.open(workFolder+"/MyBackupProject.spp")
if substance_painter.project.is_open()
    print("Our project is back!")
```

--------------------------------

### List and Activate Stacks

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset.html

Demonstrates how to list all stacks within a Texture Set's material and how to find and set a specific stack as the active one.

```python
# List all the stacks of the current Texture Set: 
for stack in active_stack.material().all_stacks(): 
if stack.name(): 
print("Stack '{0}'".format(stack.name()))
else:
print("Stack has no name")
# Find a stack called "Mask1" and set it as active: 
mask_stack = substance_painter.textureset.Stack.from_name("DefaultMaterial", "Mask1")
if mask_stack != None:
substance_painter.textureset.set_active_stack(mask_stack)
```

--------------------------------

### Get Current Project Name

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Retrieves the name of the currently open project. Returns None if the project has not been saved.

```python
substance_painter.project.name()
```

--------------------------------

### Get Resource Category

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Retrieves the category assigned to a resource, such as 'wood' for a material. This can be used for filtering or organizing resources.

```python
Resource.category()
```

--------------------------------

### Shelves.all

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Lists all currently available shelves, including custom ones added during the session and default shelves.

```APIDOC
## Shelves.all

### Description
List all shelves.

### Method
GET

### Endpoint
/shelves/all

### Returns
- **List[Shelf]**: List of existing shelves.
```

--------------------------------

### Get Resource Identifier

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Retrieves the unique identifier for a given resource. This identifier can be used later to retrieve the resource itself.

```python
Resource.identifier()
```

--------------------------------

### List Project Metadata Keys

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Returns a list of all keys for metadata stored in the current project. This operation requires an open project and running services.

```python
keys = metadata.list()
```

--------------------------------

### Main Execution Block

Source: https://helpx.adobe.com/substance-3d-painter-python/api/plugins/versioning-plugin.html

Ensures that the start_plugin function is called when the script is executed directly.

```python
if __name__ == "__main__":
    start_plugin()
```

--------------------------------

### Get Channel Bit Depth

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset/channel.html

Retrieves the number of bits used per component for the channel's data.

```python
bit_depth = channel.bit_depth()
```

--------------------------------

### Get ResourceID from Project

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Retrieves the ResourceID for a resource embedded within the current project. This refers to an actual, existing resource.

```python
import substance_painter.resource
envmap5_id = substance_painter.resource.ResourceID.from_project(
    name="Bonifacio Street")
```

--------------------------------

### Get Stack Name

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset/stack.html

Retrieves the name of the stack. Returns an empty string if the Texture Set uses material layering.

```APIDOC
##### 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.
```

--------------------------------

### Manage UV Tile Resolutions

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/textureset.html

Shows how to retrieve UV Tiles, set their resolutions individually or in batches, and reset them to their default settings.

```python
# Get all uv tiles in the first row 
row0 = [uvtile for uvtile in textureset.all_uv_tiles() if uvtile.v == 0]
# Set their resolution to 2k 
new_resolution = substance_painter.textureset.Resolution(2048, 2048)
resolutions = {uvtile:new_resolution for uvtile in row0}
textureset.set_uvtiles_resolution(resolutions)
# Set 1001 in 4k if its width is not high enough 
uvtile_1001 = next((uvtile for uvtile in row0 if uvtile.u == 0), None)
new_resolution = substance_painter.textureset.Resolution(4096, 4096)
if uvtile_1001.get_resolution().width < new_resolution.width: 
uvtile_1001.set_resolution(new_resolution)
# Reset all uv tiles resolution: 
all_uv_tiles = texture_set.all_uv_tiles()
texture_set.reset_uvtiles_resolution(all_uv_tiles)
```

--------------------------------

### Set PYTHONPATH and launch application with Python

Source: https://helpx.adobe.com/substance-3d-painter-python/tutorials/loading-external-python-modules.html

Use a Python script to set the PYTHONPATH environment variable and then launch the application using subprocess.

```python
import os 
import subprocess 
# Add the environment variable 
os.environ["PYTHONPATH"] = "C:/Python/lib/site-packages/"
```

--------------------------------

### Get Resource Usages

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Retrieves a list of all intended usages for a resource. This indicates how the resource is meant to be applied within Substance Painter.

```python
Resource.usages()
```

--------------------------------

### Manipulating Resources

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

This section demonstrates how to list all resources within a specific shelf, search for resources by name, and display them in the Substance 3D Painter UI.

```APIDOC
## Manipulating Resources

This section demonstrates how to list all resources within a specific shelf, search for resources by name, and display them in the Substance 3D Painter UI.

### Overview

The `resource` module exposes the `Resource` class, which represents a resource available in Substance 3D Painter. Resources can be in the shelf or embedded in a project. Functions like `Shelf.resources()`, `search()`, `Resource.show_in_ui()`, and `show_resources_in_ui()` are available for manipulation.

### Usage Examples

```python
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)
```
```

--------------------------------

### Get Resource Location

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/resource.html

Retrieves the file system location of a resource. This is useful for accessing the resource's file path directly.

```python
Resource.location()
```

--------------------------------

### create

Source: https://helpx.adobe.com/substance-3d-painter-python/api/substance-painter/project.html

Creates a new Substance Painter project. This function supports setting up color management via environment variables (OCIO or ACE) and allows for detailed project configuration through the Settings object. It can also load a mesh and associated map files, or use a template.

```APIDOC
## create

### Description
Creates a new Substance Painter project. This function supports setting up color management via environment variables (OCIO or ACE) and allows for detailed project configuration through the Settings object. It can also load a mesh and associated map files, or use a template.

### Method
create

### Parameters
#### Path Parameters
- **_mesh_file_path** (string) - Required - File path of the mesh to edit. Supported file formats: fbx, obj, dae, ply.
- **_mesh_map_file_paths** (list of string) - Optional - Paths to the additional mesh maps.
- **_template_file_path** (string) - Optional - Template file path to use to create the project.
- **_settings** (Settings) - Optional - Configuration options of the new project.

### Raises
- ProjectError – If Substance 3D Painter cannot create the project.
- ProjectError – If there is already an opened project.
- ProjectError – If an `OCIO` environment variable is set to an invalid configuration.
- ProjectError – If an `PAINTER_ACE_CONFIG` environment variable is set to an invalid preset.
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
- TypeError – If `settings` is not an instance of Settings.
- ValueError – If the file format of `mesh_file_path` is not supported.
- ValueError – If the mesh file `mesh_file_path` does not exist.
- ValueError – If any of the mesh map files in `mesh_map_file_paths` do not exist.
- ValueError – If the template file `template_file_path` doesn’t exist.
- ValueError – If the template file `template_file_path` is invalid.
- ValueError – If `settings` are not valid project settings (see documentation of `Settings`).
- ValueError – If `settings.default_texture_resolution` is not a valid resolution.
```
Tokens:
Raw