User Guide Cancel

export | Substance 3D Painter Python API

export

export module

This module exposes functions to export assets from a project under a variety of formats. It is the scripting equivalent of the “Export textures” window.

The export configuration is defined with a JSON file, but can also use existing export presets.

Example

import substance_painter.export 
 
# Open a project we want to export from (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") 
 
# Choose an export preset to use (see substance_painter.resource). This 
# step is not mandatory as you can alternatively describe the export 
# preset entirely in JSON (see the full example at the bottom of the 
# page). 
# Note: in this example the preset file format and bit depth are 
# overridden below, but you can remove these settings to follow the 
# preset configuration instead. 
import substance_painter.resource 
export_preset = substance_painter.resource.ResourceID( 
    context="starter_assets", name="Arnold (AiStandard)") 
 
# Set the details of the export (a comprehensive example of all the 
# configuration options is presented at the bottom of the page): 
export_config = { 
    "exportShaderParams": False, 
    "exportPath": "C:/export", 
    "defaultExportPreset" : export_preset.url(), 
    "exportList": [ 
        { 
            "rootPath": "01_Head" 
        }, 
        { 
            "rootPath": "02_Body" 
        }, 
        { 
            "rootPath": "03_Base" 
        }], 
    "exportParameters": [ 
        { 
            "parameters": { 
                "fileFormat" : "png", 
                "bitDepth" : "8", 
                "dithering": True, 
                "paddingAlgorithm": "infinite" 
            } 
        }] 
    } 
 
# Display the list of textures that should be exported, according to the 
# configuration: 
export_list = substance_painter.export.list_project_textures(export_config) 
for k,v in export_list.items(): 
    print("Stack {0}:".format(k)) 
    for to_export in v: 
        print(to_export) 
 
# Actual export operation: 
export_result = substance_painter.export.export_project_textures(export_config) 
 
# In case of error, display a human readable message: 
if export_result.status != substance_painter.export.ExportStatus.Success: 
    print(export_result.message) 
 
# Display the details of what was exported: 
for k,v in export_result.textures.items(): 
    print("Stack {0}:".format(k)) 
    for exported in v: 
        print(exported) 
class substance_painter.export.

TextureExportResult

TextureExportResult(status: ExportStatus, message: str, textures: Dict[Tuple[str, str], List[str]])

Result of the export process

status
status

Status code.

Type

ExportStatus

message
message

Human readable status message.

Type

str

textures
textures

List of texture files written to disk, grouped by stack (Texture Set name, stack name).

Type

Dict[Tuple[str, str], List[str]]

substance_painter.export.

export_project_textures

export_project_textures(json_config: dict) → TextureExportResult

Export document textures according to the given JSON configuration. The return value contains the list of texture files written to disk.

The status of the return value can never be Error, any error causing the export to fail will raise an exception instead. However if the export fails, the associated event ExportTextureEnded will indeed receive Error as a status. If the export is cancelled by the user, the function return value will have the status Cancelled and contain the list of texture files written to disk before export was cancelled.

Parameters

json_config (dict) – JSON object representing the export configuration to be used.

Returns

Result of the export process.

Return type

TextureExportResult

Raises
  • ProjectError – If no project is opened.
  • ValueError – If json_config is ill-formed, or is invalid in the context of the current project. Contains a human readable message detailing the problem.

See also

substance_painter.event.ExportTexturesAboutToStart, substance_painter.event.ExportTexturesEnded.

substance_painter.export.

list_project_textures

list_project_textures(json_config: dict) → Dict[Tuple[str, str], List[str]]

Get list of textures that would be exported according to the given JSON configuration.

Parameters

json_config (dict) – JSON object representing the export configuration to be used.

Returns

List of texture files that would be exported, grouped by stack (Texture Set name, stack name).

Return type

Dict[Tuple[str, str], List[str]]

Raises
  • ProjectError – If no project is opened.
  • ValueError – If json_config is ill-formed, or is invalid in the context of the current project. Contains a human readable message.

See also

export_project_textures().

Full json_config dict possibilities

{ 
 
    // 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. 
      // 
      // For Texture Sets without stacks, this is a Texture Set name. 
      // (e.g. "O1_Head") 
      // For Texture Sets with stacks, this is Texture Set name + stack name 
      // separated by / 
      "rootPath" : "02_Body/Mask", 
 
      // (optional) In the selected rootPath, which maps to export. 
      // 
      // When "filter" is not provided, export everything. 
      "filter" : { 
 
        // Which maps to export, as an array of map names. 
        // 
        // The map names are to be used as defined in 
        // exportPresets.maps.fileName, including wildcards. 
        // (e.g. ["$textureSet_color", "$textureSet_normal"]) 
        "outputMaps" : ["$textureSet_color"], 
 
        // Which UV Tiles to export, as an array of tile coordinates. 
        // A tile coordinate is a 2 dimensional array of U and V coordinates. 
        // (e.g. [[1, 1], [1, 2]] to export tiles U=1, V=1 and U=1, V=2) 
        "uvTiles" : [[1, 1]] 
 
      }, 
 
      // (optional) Export preset to use. If undefined, fall back to 
      // "defaultExportPreset" value. 
      // The value can be the name of a preset defined in "exportPresets": 
      "exportPreset" : "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(), 
 
    }], 
 
    // List of rules used to override export parameters of texture files. 
    // 
    // For each exported texture file, the export process will go through this 
    // list, in the order they are provided, to override export parameters. 
    // Available export parameters are: 
    //    fileFormat, bitDepth, dithering, sizeLog2, paddingAlgorithm and 
    //    dilationDistance. 
    // (see exportPresets.map.parameters) 
    // 
    // For each possible export parameter of each texture file: 
    // First, the parameter is initialized with the value provided by the 
    // exportPreset.maps.parameters, if any. 
    // Then, the export process iterates the rules of exportParameters and tries 
    // to match the texture file with the filter. 
    // If the filter matches, the parameter is overridden by this rule, else it 
    // stays untouched. 
    // 
    // At the end of the process, every parameter of every texture file must be 
    // defined for the export process to be able to continue. 
    // To achieve this, a good practice may be to define a default value for all 
    // the parameters: 
    // - For each preset map 
    // - With a global exportParameters rule using a filter that always matches 
    "exportParameters" : [{ 
 
      // (optional) Select which texture files match the current rule. 
      // (i.e. for which texture files this rule will override parameters) 
      // 
      // When "filter" is not provided, select everything. 
      // 
      // Examples: 
      //     Filter that matches all: 
      //         "filter" : {} 
      // 
      //     Filter that matches some Texture Sets: 
      //         "filter" : {"dataPaths": ["01_Head", "02_Body"]} 
      // 
      //     Filter that matches some outputMaps: 
      //         "filter" : {"outputMaps": ["$textureSet_color"]} 
      // 
      //     Filter that matches nothing: 
      //         "filter" : {"dataPaths": []} 
      // 
      //     Use of a combined filter to match a Texture Set for some 
      //     outputMaps: 
      //         "filter" : {"dataPaths": ["01_Head"], 
      //     "outputMaps" : ["$textureSet_color"]} 
      "filter" : { 
 
        // List of rootPaths to match. 
        // 
        // This can be a mix of: 
        // - Texture Set names only, even for Texture Sets with stacks 
        // - Stack names, when stacks are used 
        "dataPaths": ["01_Head", "02_Body/Mask"], 
 
        // List of map names to match. 
        // 
        // The map names are to be used as defined in "exportPresets.maps.fileName", 
        // including wildcards. 
        "outputMaps": ["$textureSet_color"], 
 
         // List of UV Tiles to match, as an array of tile coordinates. 
         // A tile coordinate is a 2 dimensional array of U and V coordinates. 
         // (e.g. [[1, 1], [1, 2]] to export tiles U=1, V=1 and U=1, V=2) 
         "uvTiles" : [[1, 1]] 
 
      }, 
 
      // (optional) Parameters to apply to the matched texture files as per the 
      // current rule. 
      // 
      // 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 (coming from the selected preset). 
      // 
      // 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. 
      // 
      // In this example, we're setting a different texture size for the color 
      // map of both 01_Head and 02_Body/Mask, leaving settings on maps and 
      // other data paths, and leaving the other parameters untouched. 
      "parameters" : { 
 
        "sizeLog2" :  11 
 
      } 
    }] 
} 

Events

Exporting textures, whether 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.

ExportTexturesAboutToStart

ExportTexturesAboutToStart(textures: Dict[Tuple[str, str], List[str]])

Event triggered just before a textures export.

textures
textures: Dict[Tuple[str, str], List[str]]

List of texture files to be written to disk, grouped by stack (Texture Set name, stack name).

Type

Dict[Tuple[str, str], List[str]]

class substance_painter.event.

ExportTexturesEnded

ExportTexturesEnded(status: ExportStatus, message: str, textures: Dict[Tuple[str, str], List[str]])

Event triggered after textures export is finished.

message
message: str

Human readable status message.

Type

str

status
status: ExportStatus

Status code.

Type

ExportStatus

textures
textures: Dict[Tuple[str, str], List[str]]

List of texture files written to disk, grouped by stack (Texture Set name, stack name).

Type

Dict[Tuple[str, str], List[str]]

 Adobe

Get help faster and easier

New user?