User Guide Cancel

project | Substance 3D Painter Python API

Search
Substance 3D Painter Pyhton

Substance 3D Painter Pyhton

Open app

project

project module

This module allows to open, create, save and close projects, and change some of their properties.

First, here is a complete example showing how to use this module:

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) 
 
# End of our little example... 
substance_painter.project.close()
substance_painter.project.

execute_when_not_busy

execute_when_not_busy(callback: Callable[[], None]) → None

Execute the given callback when Substance 3D Painter is not busy.

Parameters

callback (Callable[[], None]) – The callback to be executed.

See also

is_busy(), substance_painter.event.BusyStatusChanged.

substance_painter.project.

file_path

file_path() → Optional[str]

Return the file path of the current project. This is the path where the project will be written to when it is saved.

Returns

The file path of the current project, or None if the project hasn’t been saved yet.

Return type

str

Raises

See also

save(), save_as().

substance_painter.project.

is_busy

is_busy() → bool

Check if Substance 3D Painter is currently busy. If busy, the project cannot be saved at the moment. The application may be busy because no project is in edition state, or a long process such as baking/export/unwrap process is ongoing. The corresponding BusyStatusChanged event is fired when the busy state changes.

Returns

True if the project is ready to be saved, False otherwise.

Return type

bool

See also

execute_when_not_busy(), substance_painter.event.BusyStatusChanged.

substance_painter.project.

is_in_edition_state

is_in_edition_state() → bool

Check if the current project is ready to work with.

Raises
Returns

True if the project is ready to work with, False otherwise.

Return type

bool

See also

substance_painter.event.ProjectEditionEntered, substance_painter.event.ProjectEditionLeft.

substance_painter.project.

name

name() → Optional[str]

Return the name of the current project.

Returns

The name of the current project, or None if the project hasn’t been saved yet.

Return type

str

Raises

Creating a project

Example:

substance_painter.project.

create

create(mesh_file_path: str, mesh_map_file_paths: Optional[List[str]] = None, template_file_path: Optional[str] = None, settings: Settings = Settings(default_save_path=None, normal_map_format=None, tangent_space_mode=None, project_workflow=None, export_path=None, default_texture_resolution=None, import_cameras=None, mesh_unit_scale=None))

Create a new project. If an OCIO environment variable is set, pointing to a .ocio configuration file, the project is setup to use the OCIO color management mode defined by that file. If the configuration defined by that file is invalid, a ProjectError is raised and no project is created. Similary, if a PAINTER_ACE_CONFIG environment variable is set, pointing to a .json preset file, the project is setup to use the ACE color management mode defined by that file. If the preset defined in that file is invalid, a ProjectError is raised and no project is created. If both environment variables are set, OCIO will be used. If there is not such environment variable, the project uses the Legacy color management mode.

Note

Project settings override the template parameters.

Parameters
  • mesh_file_path (string) – File path of the mesh to edit. Supported file formats: fbx, obj, dae, ply.
  • mesh_map_file_paths (list of string) – Paths to the additional mesh maps.
  • template_file_path (string) – Template file path to use to create the project.
  • settings (Settings) – 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.

See also

Settings, Project creation documentation.

class substance_painter.project.

Settings

Settings(default_save_path: Optional[str] = None, normal_map_format: Optional[NormalMapFormat] = None, tangent_space_mode: Optional[TangentSpace] = None, project_workflow: Optional[ProjectWorkflow] = None, export_path: Optional[str] = None, default_texture_resolution: Optional[int] = None, import_cameras: Optional[bool] = None, mesh_unit_scale: Optional[float] = None)

Project configuration options. All options can be set to None to use the default values.

This corresponds to the options that are available in the “New project” dialog.

See also

NormalMapFormat, TangentSpace, ProjectWorkflow, create(), Project configuration documentation.

default_save_path
default_save_path: str = None

The default save path.

default_texture_resolution
default_texture_resolution: int = None

Default resolution for all the Texture Sets.

export_path
export_path: str = None

Use this path as the default map export path.

import_cameras
import_cameras: bool = None

Import cameras from the mesh file.

mesh_unit_scale
mesh_unit_scale: float = None

Use custom unit scale for input mesh. Painter unit is centimeters. If set to 0 or None, use mesh file internal unit scale. This setting is necessary for .obj meshes that use units other than centimeters.

normal_map_format
normal_map_format: NormalMapFormat = None

Normal map system coordinates. OpenGL or DirectX format.

project_workflow
project_workflow: ProjectWorkflow = None

Project workflow, selected at project creation time.

tangent_space_mode
tangent_space_mode: TangentSpace = None

Per vertex or per fragment tangent space.

Opening and closing a project

Example:

substance_painter.project.

is_open

is_open() → bool

Check if a project is already opened.

Returns

True if a project is opened, False otherwise.

Return type

bool

Raises

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

substance_painter.project.

open

open(project_file_path: str) → None

Open the project located at project_file_path.

Parameters

project_file_path (str) – The path to the project file (with the extension .spp).

Raises
  • ProjectError – If Substance 3D Painter cannot open the file project_file_path.
  • ProjectError – If there is already an opened project.
  • ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
substance_painter.project.

close

close() → None

Close the current project.

Warning

Any unsaved data will be lost.

Raises

Saving a project

Saving a project is disabled when Substance 3D Painter is busy and will throw a substance_painter.exception.ProjectError.

Example:

substance_painter.project.

needs_saving

needs_saving() → bool

Check if the current project needs to be saved.

Raises
Returns

True if the project has modifications and needs to be saved, False otherwise.

Return type

bool

substance_painter.project.

save

save(mode: ProjectSaveMode = ProjectSaveMode.Incremental) → None

Save the current project by overwriting the previous save.

Note

Save is disabled when Substance 3D Painter is busy and will throw a ProjectError.

Parameters

mode (ProjectSaveMode) – The save mode (Incremental or Full).

Raises

See also

ProjectSaveMode, save_as(), save_as_copy(). is_busy().

substance_painter.project.

save_as

save_as(project_file_path: str, mode: ProjectSaveMode = ProjectSaveMode.Incremental) → None

Save the current project by writing it to the file path project_file_path.

Note

If the path project_file_path doesn’t exist yet, new folders will be created as needed. Save is disabled when Substance 3D Painter is busy and will throw a ProjectError.

Parameters
  • project_file_path (string) – The file path to save the project to.
  • mode (ProjectSaveMode) – The save mode (Incremental or Full).
Raises

See also

ProjectSaveMode, save(), save_as_copy(). is_busy().

substance_painter.project.

save_as_copy

save_as_copy(backup_file_path: str, mode: ProjectSaveMode = ProjectSaveMode.Incremental) → None

Save a copy of the current project by writing it to the file path backup_file_path. This can be used to save backups of the opened project without modifying the original file.

After save_as_copy the project is still considered to be located at the location it was previously saved to. If the project was not saved, it is still considered to not have a saved location.

Note

If the path backup_file_path doesn’t exist yet, new folders will be created as needed. Save is disabled when Substance 3D Painter is busy and will throw a ProjectError.

Parameters
  • backup_file_path (string) – The path to write the copy of the project to.
  • mode (ProjectSaveMode) – The save mode (Incremental or Full).
Raises

See also

ProjectSaveMode, save(), save_as(). is_busy().

substance_painter.project.

save_as_template

save_as_template(template_file_path: str, texture_set_name: str) → ProjectSaveMode

Save a template based of the current Texture Set or the one specified.

Note

New folders will be created if they are missing. Save is disabled when Substance 3D Painter is busy and will throw a ProjectError.

Warning

If the file already exists, it will be overwritten.

Parameters
  • template_file_path (string) – The save path.
  • texture_set_name (string) – Name of the Texture Set used as a template.
Raises

See also

is_busy().

Reloading a mesh

Example:

substance_painter.project.

reload_mesh

reload_mesh(mesh_file_path: str, settings: MeshReloadingSettings, loading_status_cb: Callable[[ReloadMeshStatus], Any])

Import a new mesh to the current project, using the given settings. Uses the automatic UV unwrapping settings defined at the project level.

The loading is asynchronous: this function returns immediately; when the loading attempt is finished loading_status_cb is called with an argument indicating if loading was successful.

Parameters
  • mesh_file_path (string) – File path of the mesh to edit. Supported file formats: fbx, obj, dae, ply.
  • settings (MeshReloadingSettings) – Configuration options for the mesh loading.
  • loading_status_cb (Callable[[ReloadMeshStatus], Any]) – Loading status notification callback.
Raises

See also

ReloadMeshStatus, MeshReloadingSettings, Project creation documentation.

substance_painter.project.

last_imported_mesh_path

last_imported_mesh_path() → str

Return the path to the last imported mesh.

Returns

The file path of the mesh that was last imported to the project.

Return type

str

Raises
class substance_painter.project.

MeshReloadingSettings

MeshReloadingSettings(import_cameras: bool = True, preserve_strokes: bool = True)

Settings used when reloading a mesh.

This corresponds to the mesh related options that are available in the “Project configuration” dialog.

See also

reload_mesh(), Project configuration documentation.

import_cameras
import_cameras: bool = True

Import cameras from the mesh file.

preserve_strokes
preserve_strokes: bool = True

Preserve strokes positions on mesh.

class substance_painter.project.

ReloadMeshStatus

ReloadMeshStatus(value)

Reload mesh status, used in mesh reload asynchronous callback.

See also

reload_mesh(),

ERROR
ERROR = 2

Mesh reload failed, see application log for details.

SUCCESS
SUCCESS = 0

Mesh reload was successful.

Project metadata

class substance_painter.project.

Metadata

Metadata(context: str)

Project metadata are arbitrary data that can be attached to a Substance Painter project. When the project is saved, the metadata are saved with it, so it is still available the next time the project is loaded.

Metadata can only be accessed when a project is opened. If no project is opened, the methods will raise an exception.

The constructor of the Metadata takes a context name as an argument. This context name can be for example the name of your plugin. It should be unique, to avoid conflict with other plugins.

Example

list
list() → list

Return the list of project metadata keys.

Raises
get
get(key: str)

Retrieve the project metadata under the given key.

The supported data types are:
  • Primitive types: bool, int, float, str.
  • list
    • Items can be any of the supported data types.
  • dict
    • Keys must be of type str.
    • Values can be any of the supported data types.
Parameters

key (str) – The key identifying the metadata to retrieve.

Raises
  • ProjectError – If no project is opened.
  • RuntimeError – If the metadata under key use a type that is not supported.
  • ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
set
set(key: str, value)

Store project metadata under the given key.

The supported data types are:
  • Primitive types: bool, int, float, str.
  • list
    • Items can be any of the supported data types.
  • dict
    • Keys must be of type str.
    • Values can be any of the supported data types.
Parameters
  • key (str) – The key identifying the metadata to store.
  • value – The metadata to store.
Raises
  • ProjectError – If no project is opened.
  • RuntimeError – If value uses a type that is not supported.
  • ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.

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.

Note

Project loading is done asynchronously. When the event ProjectOpened or ProjectCreated is triggered, the project may still be loading. The event ProjectEditionEntered is triggered when the project is ready to work with.

class substance_painter.event.

ProjectOpened

ProjectOpened

Event triggered when an existing project has been opened.

class substance_painter.event.

ProjectCreated

ProjectCreated

Event triggered when a new project has been created.

class substance_painter.event.

ProjectAboutToClose

ProjectAboutToClose

Event triggered just before closing the current project.

class substance_painter.event.

ProjectAboutToSave

ProjectAboutToSave(file_path: str)

Event triggered just before saving the current project.

file_path
file_path: str

The destination file.

Type

str

class substance_painter.event.

ProjectSaved

ProjectSaved

Event triggered once the current project is saved.

class substance_painter.event.

ProjectEditionEntered

ProjectEditionEntered

Event triggered when the project is fully loaded and ready to work with.

When edition is entered, it is for example possible to query/edit the project properties, to bake textures or do project export.

class substance_painter.event.

ProjectEditionLeft

ProjectEditionLeft

Event triggered when the current project can non longer be edited.

Get help faster and easier

New user?

Quick links

View all your plans Manage your plans
View quick links
Hide quick links

Legal Notices    |    Online Privacy Policy