- Substance 3D home
- Painter Python API
- API
- Tutorials
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
- 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
-
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
- ProjectError – If no project is opened.
See also
- 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
-
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
- ProjectError – If no project is opened.
- 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
-
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
- ProjectError – If no project is opened.
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, aProjectError
is raised and no project is created. Similary, if aPAINTER_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, aProjectError
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 ofSettings
). - ValueError – If
settings.default_texture_resolution
is not a valid resolution.
See also
- 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.
- ProjectError – If Substance 3D Painter cannot open the file
- substance_painter.project.
close
close() → None -
Close the current project.
Warning
Any unsaved data will be lost.
- Raises
-
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
- ProjectError – If no project is opened.
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
-
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
- ProjectError – If no project is opened.
- 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
-
- ProjectError – If Substance 3D Painter cannot save the project.
- ProjectError – If no project is opened.
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
See also
- 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
-
- ProjectError – If Substance 3D Painter cannot save the project.
- ProjectError – If no project is opened.
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
See also
- 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
-
- ProjectError – If Substance 3D Painter cannot save the copy.
- ProjectError – If no project is opened.
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
See also
- 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
-
- ProjectError – If Substance 3D Painter cannot save the template.
- ProjectError – If no project is opened.
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
See also
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
-
- ProjectError – If no project is opened.
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
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
-
- ProjectError – If no project is opened.
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
- 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
-
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
-
- ProjectError – If no project is opened.
- ServiceNotFoundError – If Substance 3D Painter has not started all its services yet.
-
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.