- Substance 3D home
- Painter Python API
- API
- Tutorials
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
-
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
- 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
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
-
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]]
-