diff --git a/src/pages/api/changelog.md b/src/pages/api/changelog.md new file mode 100644 index 0000000..77f6f61 --- /dev/null +++ b/src/pages/api/changelog.md @@ -0,0 +1,401 @@ +--- +title: changelog - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +Changelog — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + +
Test 1
Test 2
+ + + + + + + +Changelog +========= + + + +0.2.12 (Substance 3D painter 9.1.1) +----------------------------------- + + +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + Add [`substance_painter.project.get_uuid()`](substance_painter/project.html#substance_painter.project.get_uuid "substance_painter.project.get_uuid") to query the project UUID. + + + + +0.2.11 (Substance 3D painter 9.1.0) +----------------------------------- + + +* [`substance_painter.application`](substance_painter/application.html#module-substance_painter.application "substance_painter.application") + + Add ability to disable engine computations + + Add [`substance_painter.application.close()`](substance_painter/application.html#substance_painter.application.close "substance_painter.application.close") to close Substance 3D Painter. +* [`substance_painter.display`](substance_painter/display.html#module-substance_painter.display "substance_painter.display") + + Add [`substance_painter.display.Camera`](substance_painter/display.html#substance_painter.display.Camera "substance_painter.display.Camera") to manipulate camera settings. +* [`substance_painter.event`](substance_painter/event.html#module-substance_painter.event "substance_painter.event") + + Add a new event [`substance_painter.event.EngineComputationsStatusChanged`](substance_painter/event.html#substance_painter.event.EngineComputationsStatusChanged "substance_painter.event.EngineComputationsStatusChanged") to be notified when engine computations status changes. + + Add a new event [`substance_painter.event.CameraPropertiesChanged`](substance_painter/event.html#substance_painter.event.CameraPropertiesChanged "substance_painter.event.CameraPropertiesChanged") to be notified when the properties of a camera change. +* [`substance_painter.export`](substance_painter/export.html#module-substance_painter.export "substance_painter.export") + + Add ability to export the mesh of the current project. + + Add ability to get the default export path used for exporting textures. +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + Add [`substance_painter.project.BoundingBox`](substance_painter/project.html#substance_painter.project.BoundingBox "substance_painter.project.BoundingBox") and [`substance_painter.project.get_scene_bounding_box()`](substance_painter/project.html#substance_painter.project.get_scene_bounding_box "substance_painter.project.get_scene_bounding_box") to query dimensions of the scene. + + + + +0.2.10 (Substance 3D painter 9.0.0) +----------------------------------- + + +* [`substance_painter.export`](substance_painter/export.html#module-substance_painter.export "substance_painter.export") + + Fix textures exported in EXR with 32f bit depth were incorrectly saved in 16f. +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + Add [`substance_painter.project.UsdSettings`](substance_painter/project.html#substance_painter.project.UsdSettings "substance_painter.project.UsdSettings") in [`substance_painter.project.Settings`](substance_painter/project.html#substance_painter.project.Settings "substance_painter.project.Settings") to support USD parameters for project creation. + + Add [`substance_painter.project.UsdSettings`](substance_painter/project.html#substance_painter.project.UsdSettings "substance_painter.project.UsdSettings") in [`substance_painter.project.MeshReloadingSettings`](substance_painter/project.html#substance_painter.project.MeshReloadingSettings "substance_painter.project.MeshReloadingSettings") to support USD parameters for mesh reloading. + + + + +0.2.9 (Substance 3D Painter 8.3.1) +---------------------------------- + + +* [`substance_painter.async_utils`](substance_painter/async_utils.html#module-substance_painter.async_utils "substance_painter.async_utils") + + New module to expose primitives used in async computations. +* [`substance_painter.event`](substance_painter/event.html#module-substance_painter.event "substance_painter.event") + + Add a new event [`substance_painter.event.BakingProcessProgress`](substance_painter/event.html#substance_painter.event.BakingProcessProgress "substance_painter.event.BakingProcessProgress") to be notified about baking process progress. + + Add a new event [`substance_painter.event.BakingProcessAboutToStart`](substance_painter/event.html#substance_painter.event.BakingProcessAboutToStart "substance_painter.event.BakingProcessAboutToStart") to be notified of the start of a baking process. + + Allow to configure throttling period for [`substance_painter.event.TextureStateEvent`](substance_painter/event.html#substance_painter.event.TextureStateEvent "substance_painter.event.TextureStateEvent"). +* [`substance_painter.baking`](substance_painter/baking.html#module-substance_painter.baking "substance_painter.baking") + + Add [`substance_painter.baking.bake_selected_textures_async()`](substance_painter/baking.html#substance_painter.baking.bake_selected_textures_async "substance_painter.baking.bake_selected_textures_async") to bake all selected texture set. + + Fix [`substance_painter.baking.bake_async()`](substance_painter/baking.html#substance_painter.baking.bake_async "substance_painter.baking.bake_async") to take UV Tiles selection into account. + + Now async functions return a [`substance_painter.async_utils.StopSource`](substance_painter/async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource") to allow for cancellation. + + + + +0.2.8 (Substance 3D Painter 8.3.0) +---------------------------------- + + +* [`substance_painter.application`](substance_painter/application.html#module-substance_painter.application "substance_painter.application") + + New module to expose functionnalities on the application level. + + Add [`substance_painter.application.version_info()`](substance_painter/application.html#substance_painter.application.version_info "substance_painter.application.version_info") to query Substance 3D Painter version as a tuple. + + Add [`substance_painter.application.version()`](substance_painter/application.html#substance_painter.application.version "substance_painter.application.version") to query Substance 3D Painter version as a string. +* [`substance_painter.event`](substance_painter/event.html#module-substance_painter.event "substance_painter.event") + + Add a new event [`substance_painter.event.BakingProcessEnded`](substance_painter/event.html#substance_painter.event.BakingProcessEnded "substance_painter.event.BakingProcessEnded") to be notified of the end of the baking process. +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + Add [`substance_painter.project.last_saved_substance_painter_version()`](substance_painter/project.html#substance_painter.project.last_saved_substance_painter_version "substance_painter.project.last_saved_substance_painter_version") to query wich Substance 3D + Painter version was used to last save the project. +* [`substance_painter.textureset`](substance_painter/textureset/index.html#module-substance_painter.textureset "substance_painter.textureset") + + Add [`substance_painter.textureset.TextureSet.uv_tile()`](substance_painter/textureset/textureset.html#substance_painter.textureset.TextureSet.uv_tile "substance_painter.textureset.TextureSet.uv_tile") to get a specific UV Tile. +* [`substance_painter.ui`](substance_painter/ui.html#module-substance_painter.ui "substance_painter.ui") + + Add Baking to [`substance_painter.ui.UIMode`](substance_painter/ui.html#substance_painter.ui.UIMode "substance_painter.ui.UIMode"). + + Add [`substance_painter.ui.get_current_mode()`](substance_painter/ui.html#substance_painter.ui.get_current_mode "substance_painter.ui.get_current_mode") to query the current UI mode. + + Add [`substance_painter.ui.switch_to_mode()`](substance_painter/ui.html#substance_painter.ui.switch_to_mode "substance_painter.ui.switch_to_mode") to switch to some UI mode. + + +This version introduces the modules: + + +* [`substance_painter.baking`](substance_painter/baking.html#module-substance_painter.baking "substance_painter.baking") +* [`substance_painter.properties`](substance_painter/properties.html#module-substance_painter.properties "substance_painter.properties") + + + + +0.2.7 (Substance 3D Painter 8.2.0) +---------------------------------- + + +* [`substance_painter.resource`](substance_painter/resource.html#module-substance_painter.resource "substance_painter.resource") + + Add new values to [`substance_painter.resource.Type`](substance_painter/resource.html#substance_painter.resource.Type "substance_painter.resource.Type") enumeration. + + Add [`substance_painter.resource.Resource.children()`](substance_painter/resource.html#substance_painter.resource.Resource.children "substance_painter.resource.Resource.children") to query child resources of a resource. + + Add [`substance_painter.resource.Resource.parent()`](substance_painter/resource.html#substance_painter.resource.Resource.parent "substance_painter.resource.Resource.parent") to query parent resource of a resource. +* [`substance_painter.textureset`](substance_painter/textureset/index.html#module-substance_painter.textureset "substance_painter.textureset") + + Add [`substance_painter.textureset.MeshMapUsage`](substance_painter/textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage") to enumerate possible Mesh map usages. + + Add [`substance_painter.textureset.TextureSet.get_mesh_map_resource()`](substance_painter/textureset/textureset.html#substance_painter.textureset.TextureSet.get_mesh_map_resource "substance_painter.textureset.TextureSet.get_mesh_map_resource") to query the resource set as some Mesh map usage. + + Add [`substance_painter.textureset.TextureSet.set_mesh_map_resource()`](substance_painter/textureset/textureset.html#substance_painter.textureset.TextureSet.set_mesh_map_resource "substance_painter.textureset.TextureSet.set_mesh_map_resource") to replace the resource for some Mesh map usage. +* [`substance_painter.ui`](substance_painter/ui.html#module-substance_painter.ui "substance_painter.ui") + + Add [`substance_painter.ui.get_layout()`](substance_painter/ui.html#substance_painter.ui.get_layout "substance_painter.ui.get_layout") to save UI layout state. + + Add [`substance_painter.ui.get_layout_mode()`](substance_painter/ui.html#substance_painter.ui.get_layout_mode "substance_painter.ui.get_layout_mode") to query the UI mode of a saved state. + + Add [`substance_painter.ui.set_layout()`](substance_painter/ui.html#substance_painter.ui.set_layout "substance_painter.ui.set_layout") to restore a saved UI state. + + Add [`substance_painter.ui.reset_layout()`](substance_painter/ui.html#substance_painter.ui.reset_layout "substance_painter.ui.reset_layout") to reset UI state to default. +* [`substance_painter.event`](substance_painter/event.html#module-substance_painter.event "substance_painter.event") + + Add a new event [`substance_painter.event.TextureStateEvent`](substance_painter/event.html#substance_painter.event.TextureStateEvent "substance_painter.event.TextureStateEvent") to be notified of document textures edition. + + + + +0.2.6 (Substance 3D Painter 8.1.2) +---------------------------------- + + +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + [`substance_painter.project.create()`](substance_painter/project.html#substance_painter.project.create "substance_painter.project.create") and [`substance_painter.project.Settings`](substance_painter/project.html#substance_painter.project.Settings "substance_painter.project.Settings") + now supports using a custom unit scale for mesh size. +* [`substance_painter.textureset`](substance_painter/textureset/index.html#module-substance_painter.textureset "substance_painter.textureset") + + Add [`substance_painter.textureset.TextureSet.all_mesh_names()`](substance_painter/textureset/textureset.html#substance_painter.textureset.TextureSet.all_mesh_names "substance_painter.textureset.TextureSet.all_mesh_names") to query the list of mesh names used in a Texture Set. + + Add [`substance_painter.textureset.UVTile.all_mesh_names()`](substance_painter/textureset/uvtile.html#substance_painter.textureset.UVTile.all_mesh_names "substance_painter.textureset.UVTile.all_mesh_names") to query the list of mesh names used in a UV Tile. +* [`substance_painter.resource`](substance_painter/resource.html#module-substance_painter.resource "substance_painter.resource") + + Add [`substance_painter.resource.Usage`](substance_painter/resource.html#substance_painter.resource.Usage "substance_painter.resource.Usage") enumeration to describe resource usages. + + Add [`substance_painter.resource.Type`](substance_painter/resource.html#substance_painter.resource.Type "substance_painter.resource.Type") enumeration to describe resource types. + + Add [`substance_painter.resource.Resource.category()`](substance_painter/resource.html#substance_painter.resource.Resource.category "substance_painter.resource.Resource.category") to query the category of a resource. + + Add [`substance_painter.resource.Resource.usages()`](substance_painter/resource.html#substance_painter.resource.Resource.usages "substance_painter.resource.Resource.usages") to query the usages of a resource. + + Add [`substance_painter.resource.Resource.gui_name()`](substance_painter/resource.html#substance_painter.resource.Resource.gui_name "substance_painter.resource.Resource.gui_name") to query the name of a resource. + + Add [`substance_painter.resource.Resource.type()`](substance_painter/resource.html#substance_painter.resource.Resource.type "substance_painter.resource.Resource.type") to query the type of a resource. + + Add [`substance_painter.resource.Resource.tags()`](substance_painter/resource.html#substance_painter.resource.Resource.tags "substance_painter.resource.Resource.tags") to query the tags of a resource. + + Add [`substance_painter.resource.Resource.internal_properties()`](substance_painter/resource.html#substance_painter.resource.Resource.internal_properties "substance_painter.resource.Resource.internal_properties") to query a dictionnary of a resource internal properties. + + + + +0.2.5 (Substance 3D Painter 8.1.0) +---------------------------------- + + +This version upgrades to Python 3.9.9. + + +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + [`substance_painter.project.create()`](substance_painter/project.html#substance_painter.project.create "substance_painter.project.create") supports PAINTER_ACE_CONFIG + environment variable, to setup the project color management mode. + + [`substance_painter.project.create()`](substance_painter/project.html#substance_painter.project.create "substance_painter.project.create") now raise an error if OCIO + or PAINTER_ACE_CONFIG environment variable is set to an invalid + configuration. + + + + +0.2.4 (Substance 3D Painter 7.4.3) +---------------------------------- + + +This version exposes the tone mapping operator to the Python API, and adds +a hook to execute code when Substance 3D Painter is not busy. + + +* [`substance_painter.display`](substance_painter/display.html#module-substance_painter.display "substance_painter.display") + + Add [`substance_painter.display.get_tone_mapping()`](substance_painter/display.html#substance_painter.display.get_tone_mapping "substance_painter.display.get_tone_mapping") to query the + project tone mapping. + + Add [`substance_painter.display.set_tone_mapping()`](substance_painter/display.html#substance_painter.display.set_tone_mapping "substance_painter.display.set_tone_mapping") to set the + project tone mapping. +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + Add [`substance_painter.project.execute_when_not_busy()`](substance_painter/project.html#substance_painter.project.execute_when_not_busy "substance_painter.project.execute_when_not_busy") to execute + code when Substance 3D Painter is no longer busy. + + + + +0.2.3 (Substance 3D Painter 7.4.0) +---------------------------------- + + +This version makes it possible to work with JavaScript from the Python API. +It also allows creating projects with OCIO color management capabilities. + + +* [`substance_painter.js`](substance_painter/js.html#module-substance_painter.js "substance_painter.js") + + Add [`substance_painter.js.evaluate()`](substance_painter/js.html#substance_painter.js.evaluate "substance_painter.js.evaluate") to evaluate some JavaScript code. +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + [`substance_painter.project.create()`](substance_painter/project.html#substance_painter.project.create "substance_painter.project.create") supports OCIO environment variable, + to setup the project color management mode. + + + + +0.2.2 (Substance 3D Painter 7.3.0) +---------------------------------- + + +This version adds functions to help with scripted project loading, project +mesh reloading and UV Tiles manipulation. It also improves error handling +in several modules. + + +* [`substance_painter.display`](substance_painter/display.html#module-substance_painter.display "substance_painter.display") + + [`substance_painter.display.set_color_lut_resource()`](substance_painter/display.html#substance_painter.display.set_color_lut_resource "substance_painter.display.set_color_lut_resource") and + [`substance_painter.display.set_environment_resource()`](substance_painter/display.html#substance_painter.display.set_environment_resource "substance_painter.display.set_environment_resource") throw a + TypeError instead of a ValueError when an argument has a type different + from expected. +* [`substance_painter.event`](substance_painter/event.html#module-substance_painter.event "substance_painter.event") + + Add [`substance_painter.event.Dispatcher.connect_strong()`](substance_painter/event.html#substance_painter.event.Dispatcher.connect_strong "substance_painter.event.Dispatcher.connect_strong") to connect + strong reference callbacks to the event dispatcher. +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + Add [`substance_painter.project.is_busy()`](substance_painter/project.html#substance_painter.project.is_busy "substance_painter.project.is_busy") to query whether Substance + 3D Painter is busy. + + Project saving functions are disabled when Substance 3D Painter is + busy. + + Add [`substance_painter.project.last_imported_mesh_path()`](substance_painter/project.html#substance_painter.project.last_imported_mesh_path "substance_painter.project.last_imported_mesh_path") to query the + path to the last imported mesh. + + Add [`substance_painter.project.reload_mesh()`](substance_painter/project.html#substance_painter.project.reload_mesh "substance_painter.project.reload_mesh") to load a new mesh in the + current opened project. + + [`substance_painter.project.create()`](substance_painter/project.html#substance_painter.project.create "substance_painter.project.create") throws a TypeError instead + of a ValueError when its settings argument has a type different from + expected. +* [`substance_painter.resource`](substance_painter/resource.html#module-substance_painter.resource "substance_painter.resource") + + Add [`substance_painter.resource.show_resources_in_ui()`](substance_painter/resource.html#substance_painter.resource.show_resources_in_ui "substance_painter.resource.show_resources_in_ui") to highlight a + list of resources in the aplication UI. + + [`substance_painter.resource.update_layer_stack_resource()`](substance_painter/resource.html#substance_painter.resource.update_layer_stack_resource "substance_painter.resource.update_layer_stack_resource") throws + a TypeError when an argument has a type different from expected. +* [`substance_painter.textureset`](substance_painter/textureset/index.html#module-substance_painter.textureset "substance_painter.textureset") + + Add [`substance_painter.textureset.UVTile`](substance_painter/textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile") to interact with UV Tiles. + Add ability to manipulate UV Tiles resolutions. + + [`substance_painter.textureset.TextureSet.from_name()`](substance_painter/textureset/textureset.html#substance_painter.textureset.TextureSet.from_name "substance_painter.textureset.TextureSet.from_name") throws a + TypeError instead of a ValueError when its argument has a type different + from expected. + + + + +0.2.1 (Substance 3D Painter 7.2.1) +---------------------------------- + + +This version adds functions to list and update resources used by the layer +stack. + + +* [`substance_painter.resource`](substance_painter/resource.html#module-substance_painter.resource "substance_painter.resource") + + Add [`substance_painter.resource.list_layer_stack_resources()`](substance_painter/resource.html#substance_painter.resource.list_layer_stack_resources "substance_painter.resource.list_layer_stack_resources") to + list resources used by the layer stack and mesh maps. + + Add [`substance_painter.resource.update_layer_stack_resource()`](substance_painter/resource.html#substance_painter.resource.update_layer_stack_resource "substance_painter.resource.update_layer_stack_resource") to + update resources used by the layer stack and mesh maps. + + + + +0.2.0 (Substance 3D Painter 7.2.0) +---------------------------------- + + +* [`substance_painter.resource`](substance_painter/resource.html#module-substance_painter.resource "substance_painter.resource") + + Add [`substance_painter.resource.Resource.show_in_ui()`](substance_painter/resource.html#substance_painter.resource.Resource.show_in_ui "substance_painter.resource.Resource.show_in_ui") to highlight + a resource in the UI. + + Modify [`substance_painter.resource.Shelves.user_shelf()`](substance_painter/resource.html#substance_painter.resource.Shelves.user_shelf "substance_painter.resource.Shelves.user_shelf") to take + user settings into account. +* [`substance_painter.textureset`](substance_painter/textureset/index.html#module-substance_painter.textureset "substance_painter.textureset") + + Modify [`substance_painter.textureset.ChannelType`](substance_painter/textureset/index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType") to include + the new available texture channels. +* [`substance_painter.ui`](substance_painter/ui.html#module-substance_painter.ui "substance_painter.ui") + + Add [`substance_painter.ui.add_plugins_toolbar_widget()`](substance_painter/ui.html#substance_painter.ui.add_plugins_toolbar_widget "substance_painter.ui.add_plugins_toolbar_widget") to add + a widget to the plugins toolbar. + + + + +0.1.0 (Substance Painter 7.1.0) +------------------------------- + + +This version adds several features to manage resources, shelves and UV Tiles. + + +* [`substance_painter.event`](substance_painter/event.html#module-substance_painter.event "substance_painter.event") + + Add [`substance_painter.event.ProjectEditionEntered`](substance_painter/event.html#substance_painter.event.ProjectEditionEntered "substance_painter.event.ProjectEditionEntered") event. + + Add [`substance_painter.event.ProjectEditionLeft`](substance_painter/event.html#substance_painter.event.ProjectEditionLeft "substance_painter.event.ProjectEditionLeft") event. + + Add [`substance_painter.event.ShelfCrawlingStarted`](substance_painter/event.html#substance_painter.event.ShelfCrawlingStarted "substance_painter.event.ShelfCrawlingStarted") event. + + Add [`substance_painter.event.ShelfCrawlingEnded`](substance_painter/event.html#substance_painter.event.ShelfCrawlingEnded "substance_painter.event.ShelfCrawlingEnded") event. +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + Add [`substance_painter.project.is_in_edition_state()`](substance_painter/project.html#substance_painter.project.is_in_edition_state "substance_painter.project.is_in_edition_state"). +* [`substance_painter.resource`](substance_painter/resource.html#module-substance_painter.resource "substance_painter.resource") + + Add [`substance_painter.resource.Resource`](substance_painter/resource.html#substance_painter.resource.Resource "substance_painter.resource.Resource") to manipulate substance + painter resources. + + Add [`substance_painter.resource.search()`](substance_painter/resource.html#substance_painter.resource.search "substance_painter.resource.search") to search for available + resources. + + Add [`substance_painter.resource.Shelf`](substance_painter/resource.html#substance_painter.resource.Shelf "substance_painter.resource.Shelf"). + + Add [`substance_painter.resource.Shelves`](substance_painter/resource.html#substance_painter.resource.Shelves "substance_painter.resource.Shelves") for shelves manipulation + facilities. +* [`substance_painter.textureset`](substance_painter/textureset/index.html#module-substance_painter.textureset "substance_painter.textureset") + + Add [`substance_painter.textureset.TextureSet.all_uv_tiles()`](substance_painter/textureset/textureset.html#substance_painter.textureset.TextureSet.all_uv_tiles "substance_painter.textureset.TextureSet.all_uv_tiles"). + + Add [`substance_painter.textureset.TextureSet.has_uv_tiles()`](substance_painter/textureset/textureset.html#substance_painter.textureset.TextureSet.has_uv_tiles "substance_painter.textureset.TextureSet.has_uv_tiles"). + + Add [`substance_painter.textureset.UVTile`](substance_painter/textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile"). + + + + +0.0.3 (Substance Painter 6.2.2) +------------------------------- + + +* [`substance_painter.export`](substance_painter/export.html#module-substance_painter.export "substance_painter.export") + + Document the use of existing export presets. + + Add a module overview example. +* [`substance_painter.textureset`](substance_painter/textureset/index.html#module-substance_painter.textureset "substance_painter.textureset") + + Add [`substance_painter.textureset.Channel.type()`](substance_painter/textureset/channel.html#substance_painter.textureset.Channel.type "substance_painter.textureset.Channel.type"). + + Add [`substance_painter.textureset.Stack.all_channels()`](substance_painter/textureset/stack.html#substance_painter.textureset.Stack.all_channels "substance_painter.textureset.Stack.all_channels"). + + + + +0.0.2 (Substance Painter 6.2.0) +------------------------------- + + +This version adapts the module [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") to the new +UV Tile workflow. + + +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") + + Add [`substance_painter.project.ProjectWorkflow`](substance_painter/project.html#substance_painter.project.ProjectWorkflow "substance_painter.project.ProjectWorkflow"). + + Change the constructor of [`substance_painter.project.Settings`](substance_painter/project.html#substance_painter.project.Settings "substance_painter.project.Settings"). + + + + +0.0.1 (Substance Painter 6.1.0) +------------------------------- + + +Initial version of the Substance Painter Python API. + + +It uses Python 3.7.6 and introduces the modules: + + +* [`substance_painter`](substance_painter/index.html#module-substance_painter "substance_painter") +* [`substance_painter.display`](substance_painter/display.html#module-substance_painter.display "substance_painter.display") +* [`substance_painter.event`](substance_painter/event.html#module-substance_painter.event "substance_painter.event") +* [`substance_painter.exception`](substance_painter/exception.html#module-substance_painter.exception "substance_painter.exception") +* [`substance_painter.export`](substance_painter/export.html#module-substance_painter.export "substance_painter.export") +* [`substance_painter.logging`](substance_painter/logging.html#module-substance_painter.logging "substance_painter.logging") +* [`substance_painter.project`](substance_painter/project.html#module-substance_painter.project "substance_painter.project") +* [`substance_painter.resource`](substance_painter/resource.html#module-substance_painter.resource "substance_painter.resource") +* [`substance_painter.textureset`](substance_painter/textureset/index.html#module-substance_painter.textureset "substance_painter.textureset") +* [`substance_painter.ui`](substance_painter/ui.html#module-substance_painter.ui "substance_painter.ui") +* [`substance_painter_plugins`](plugins/substance_painter_plugins.html#module-substance_painter_plugins "substance_painter_plugins") + + + + + + + + + + + diff --git a/src/pages/api/plugins/hello_plugin.md b/src/pages/api/plugins/hello_plugin.md new file mode 100644 index 0000000..e07740d --- /dev/null +++ b/src/pages/api/plugins/hello_plugin.md @@ -0,0 +1,97 @@ +--- +title: hello_plugin - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +Hello Plugin — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +Hello Plugin +============ + + + +hello_plugin.py + +```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() + +``` + + + + + + + + + + + diff --git a/src/pages/api/plugins/substance_painter_plugins.md b/src/pages/api/plugins/substance_painter_plugins.md new file mode 100644 index 0000000..74d1ed1 --- /dev/null +++ b/src/pages/api/plugins/substance_painter_plugins.md @@ -0,0 +1,272 @@ +--- +title: substance_painter_plugins - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +substance_painter_plugins module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +substance_painter_plugins module +================================ + + +This module allows to manage the Substance 3D Painter Plugins: listing existing +Plugins, loading or unloading a given Plugin, etc. + + +A Substance 3D Painter Plugin is a standard Python module, placed in a path added +to [`substance_painter_plugins.path`](#substance_painter_plugins.path "substance_painter_plugins.path"), which can use the Substance 3D Painter +Python API to do certain tasks. + + +Example + + + +```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) + +``` + + + + +substance_painter_plugins.path *= []* +A list of strings that specifies the search path for plugins. +Initialized from `SUBSTANCE_PAINTER_PLUGINS_PATH` environment variable, Substance 3D Painter +installation directory and Substance 3D Painter user resources directory. + + +You need to call explicitly [`substance_painter_plugins.update_sys_path`](#substance_painter_plugins.update_sys_path "substance_painter_plugins.update_sys_path") after updating this +variable. + + +A plugins directory is expected to contain three subdirectories, automatically added to +`sys.path`: + + + +> +> * **plugins** : Modules that are loaded as optional components. +> * **startup** : Modules that are always loaded at application startup. +> * **modules** : Utility modules, shared across plugins. +> +> +> + + +Modules in `plugins/` and `startup/` directories are expected to have a `start_plugin()` and +a `close_plugin()` methods, respectively called after loading the module and before unloading it. +Modules added in `plugins/` directory take precedence over modules added in `startup/` +directory. + + + +Type: +list + + + + + + + +substance_painter_plugins.plugins *= {}* +Currently started plugins. + + + +Type: +dict + + + + + + + +substance_painter_plugins.start_plugin(*module*) +Start the given Substance 3D Painter plugin. + + + +Parameters: +**module** – A Python module that is expected to have a `start_plugin` method. + + + + + + + +substance_painter_plugins.close_plugin(*module*, *gc_collect=True*) +Close the given Substance 3D Painter plugin. + + + +Parameters: +* **module** – A Python module that is expected to have a `close_plugin` method. +* **gc_collect** – Run a full garbage collection if set to True. + + + + + + + +substance_painter_plugins.is_plugin_started(*module*) +Check if the given plugin is currently started. + + + +Parameters: +**module** – A Python module. + + + +Returns: +`True` if the given module is currently started, `False` otherwise. + + + + + + + +substance_painter_plugins.reload_plugin(*module*) +Reload a plugin and start it. + + +Read [importlib.reload(module) documentation](https://docs.python.org/3/library/importlib.html#importlib.reload) for possible caveats. See [`start_plugin()`](#substance_painter_plugins.start_plugin "substance_painter_plugins.start_plugin") +and [`close_plugin()`](#substance_painter_plugins.close_plugin "substance_painter_plugins.close_plugin") for details about starting and closing a plugin. If the plugin has +a `reload_plugin` method, it will be executed after closing and before restarting the plugin. +The purpose of `reload_plugin` method is to reload manually all sub-modules the plugin +depends on (in case the plugin is a Python package for example). + + + +Parameters: +**module** – A Python module. + + + +Returns: +The reloaded plugin module. + + + + + +See also + + +[`start_plugin()`](#substance_painter_plugins.start_plugin "substance_painter_plugins.start_plugin"), [`close_plugin()`](#substance_painter_plugins.close_plugin "substance_painter_plugins.close_plugin"), [importlib.reload(module) documentation](https://docs.python.org/3/library/importlib.html#importlib.reload). + + + + + + +substance_painter_plugins.startup_module_names() +List the names of the available *startup* modules. + + + +Returns: +The names of all the available *startup* modules. + + + +Return type: +list[str] + + + + + + + +substance_painter_plugins.plugin_module_names() +List the names of the available *plugins* modules. + + + +Returns: +The names of all the available *plugins* modules. + + + +Return type: +list[str] + + + + + + + +substance_painter_plugins.load_startup_modules() +Load all startup modules. + + + + + +substance_painter_plugins.close_all_plugins() +Close all started plugins. + + + + + +substance_painter_plugins.update_sys_path() +Update `sys.path` according to [`substance_painter_plugins.path`](#substance_painter_plugins.path "substance_painter_plugins.path") and +`SUBSTANCE_PAINTER_PLUGINS_PATH` environment variable. + + + + + + + + + + + diff --git a/src/pages/api/plugins/versioning_plugin.md b/src/pages/api/plugins/versioning_plugin.md new file mode 100644 index 0000000..b74b82d --- /dev/null +++ b/src/pages/api/plugins/versioning_plugin.md @@ -0,0 +1,232 @@ +--- +title: versioning_plugin - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +Versioning Plugin — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +Versioning Plugin +================= + + + +versioning_plugin.py + +```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. +########################################################################## +"""This is a skeleton for a plugin to integrate Substance 3D Painter with a versioning system. + +This plugin listens for project events and provides a custom export action. All methods +whose name starts with ``on_`` can be customized to integrate the application with a +versioning system. +""" + +from PySide2 import QtWidgets, QtCore +import substance_painter.export +import substance_painter.project +import substance_painter.textureset +import substance_painter.ui + + +class VersioningPlugin: + def __init__(self): + # Create a dock widget to report plugin activity. + self.log = QtWidgets.QTextEdit() + self.log.setReadOnly(True) + self.log.setWindowTitle("Projects Versioning") + substance_painter.ui.add_dock_widget(self.log) + # Create a custom export action in the FILE application menu. + self.export_action = QtWidgets.QAction("Versioned Export...") + self.export_action.triggered.connect(self.export_textures) + substance_painter.ui.add_action( + substance_painter.ui.ApplicationMenu.File, + self.export_action + ) + # Subscribe to project related events. + connections = { + substance_painter.event.ProjectOpened: self.on_project_opened, + substance_painter.event.ProjectCreated: self.on_project_created, + substance_painter.event.ProjectAboutToClose: self.on_project_about_to_close, + substance_painter.event.ProjectAboutToSave: self.on_project_about_to_save, + substance_painter.event.ProjectSaved: self.on_project_saved, + } + for event, callback in connections.items(): + substance_painter.event.DISPATCHER.connect(event, callback) + + def __del__(self): + # Remove all added UI elements. + substance_painter.ui.delete_ui_element(self.log) + substance_painter.ui.delete_ui_element(self.export_action) + + def on_project_opened(self, e): + self.log.append("Project `{}` opened.".format(substance_painter.project.name())) + ################################## + # Add custom integration code here + + def on_project_created(self, e): + self.log.append("New project created.") + ################################## + # Add custom integration code here + + def on_project_about_to_close(self, e): + self.log.append("Project `{}` closed.".format(substance_painter.project.name())) + ################################## + # Add custom integration code here + + def on_project_about_to_save(self, e): + self.log.append("Project will be saved in `{}`.".format(e.file_path)) + ################################## + # Add custom integration code here + + def on_project_saved(self, e): + self.log.append("Project `{}` saved.".format(substance_painter.project.name())) + ################################## + # Add custom integration code here + + def on_export_about_to_start(self, export_configuration): + self.log.append("Export textures.") + ################################## + # Add custom integration code here + + def on_export_finished(self, res): + self.log.append(res.message) + self.log.append("Exported files:") + for file_list in res.textures.values(): + for file_path in file_list: + self.log.append(" {}".format(file_path)) + ################################## + # Add custom integration code here + + def on_export_error(self, err): + self.log.append("Export failed.") + self.log.append(repr(err)) + ################################## + # Add custom integration code here + + @QtCore.Slot() + def export_textures(self): + """Export base color of all Texture Sets to a location choosen by the user.""" + json_config = dict() + # Set export directory. + export_path = QtWidgets.QFileDialog.getExistingDirectory( + substance_painter.ui.get_main_window(), + "Choose export directoty") + if not export_path: + # Export aborted. + return + json_config["exportPath"] = export_path + "/" + substance_painter.project.name() + # Export configuration. + json_config["exportShaderParams"] = False + channels = [] + for channel in "RGBA": + channels.append({ + "destChannel": channel, + "srcChannel": channel, + "srcMapType": "DocumentMap", + "srcMapName": "BaseColor" + }) + json_config["exportPresets"] = [{ + "name": "OnlyBaseColorExamplePreset", + "maps": [{ + "fileName": "$textureSet_BaseColor", + "channels": channels, + }] + }] + json_config["exportParameters"] = [{ + "parameters": { + "fileFormat" : "png", + "bitDepth" : "8", + "dithering": True, + "paddingAlgorithm": "infinite" + } + }] + # Create the list of Texture Sets to export. + json_config["exportList"] = [] + for texture_set in substance_painter.textureset.all_texture_sets(): + try: + stack = texture_set.get_stack() + channel = stack.get_channel(substance_painter.textureset.ChannelType.BaseColor) + if channel.is_color(): + json_config["exportList"].append({ + "rootPath": texture_set.name(), + "exportPreset" : "OnlyBaseColorExamplePreset", + }) + except: + pass + # Do the export. + self.on_export_about_to_start(json_config) + try: + res = substance_painter.export.export_project_textures(json_config) + self.on_export_finished(res) + except ValueError as err: + self.on_export_error(err) + + +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() + +``` + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/application.md b/src/pages/api/substance_painter/application.md new file mode 100644 index 0000000..66ef765 --- /dev/null +++ b/src/pages/api/substance_painter/application.md @@ -0,0 +1,152 @@ +--- +title: application - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +application module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +application module +================== + + +This module contains application wide functionnalities. + + + + +substance_painter.application.version_info() → Tuple[int, int, int] +Get the version_info of Substance 3D Painter. Ie a tuple containing major, minor, patch. + + + +Returns: +The major, minor and patch version of Substance 3D Painter. + + + +Return type: +Tuple[int, int, int] + + + + + + + +substance_painter.application.version() → str +Get the version of Substance 3D Painter. Do not extract version information out of it, +rather use [`version_info()`](#substance_painter.application.version_info "substance_painter.application.version_info"). + + + +Returns: +Version of Substance 3D Painter. + + + +Return type: +str + + + + + + + +substance_painter.application.engine_computations_status() → bool +Check whether engine computations are enabled. + + + +Returns: +Whether engine computations are enabled. + + + +Return type: +bool + + + + + + + +substance_painter.application.enable_engine_computations(*enable: bool*) +Enable or disable engine computations. + + + + + +substance_painter.application.disable_engine_computations() +Context manager to disable engine computations. +Allows to regroup computation intensive tasks without triggerring the engine so that textures +are not computed or updated in the layer stack or the viewport. +This is equivalent to disabling and then reenabling the engine by calling +[`enable_engine_computations()`](#substance_painter.application.enable_engine_computations "substance_painter.application.enable_engine_computations"). + + +Example: + + + +```python +import substance_painter.application as mapplication + +with mapplication.disable_engine_computations(): + # Do some computation intensive tasks + pass + +``` + + + + + +substance_painter.application.close() +Close Susbtance 3D Painter. + + + +Warning + + +Any unsaved data will be lost. + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/async_utils.md b/src/pages/api/substance_painter/async_utils.md new file mode 100644 index 0000000..ef1cea4 --- /dev/null +++ b/src/pages/api/substance_painter/async_utils.md @@ -0,0 +1,96 @@ +--- +title: async_utils - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +async_utils module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +async_utils module +================== + + +The `async_utils` module provide primitives used in async computations. + + + + + +------ + + +*class* substance_painter.async_utils.StopSource(*stop_source: _substance_painter.async_utils.StopSource*) +An object that can be used to cancel an asynchronous computation. + + + + +request_stop() → bool +Makes a top request. + + + +Returns: +True if the stop request was possible. + + + +Return type: +bool + + + + + + + +stop_requested() → bool +Check if a stop request as been made. + + + +Returns: +True if a stop request has been made. + + + +Return type: +bool + + + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/baking.md b/src/pages/api/substance_painter/baking.md new file mode 100644 index 0000000..d0fd2d3 --- /dev/null +++ b/src/pages/api/substance_painter/baking.md @@ -0,0 +1,857 @@ +--- +title: baking - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +baking module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +baking module +============= + + +The `baking` module allows to set baking parameters and launch baking +of mesh maps. + + +Example + + + +```python +import substance_painter.baking as baking +import substance_painter.textureset as textureset +from substance_painter.baking import BakingParameters, MeshMapUsage, CurvatureMethod + +# set baking parameters +baking_params = BakingParameters.from_texture_set_name("Name for ts") +texture_set = baking_params.texture_set() +common_params = baking_params.common() +ao_params = baking_params.baker(MeshMapUsage.AO) +BakingParameters.set({ + common_params['OutputSize'] : (10,10), + ao_params['Distribution'] : ao_params['Distribution'].enum_value('Cosine')}) + +# check if common parameters are shared between Texture Sets (True at project creation) +common_params_are_shared = bool(baking.get_link_group_common_parameters()) + +# unlink common parameters. The common parameters for all Texture Sets become independent +baking.unlink_all_common_parameters() + +# recheck whether common parameters are shared between Texture Sets (now False) +common_params_are_linked = bool(baking.get_link_group_common_parameters()) + +ts1 = textureset.TextureSet.from_name("Name for ts1") +ts2 = textureset.TextureSet.from_name("Name for ts2") + +# get the list of Texture Sets which are linked for AO with ts1 +# it's not yet linked, so returns only [ts1] +linked_with_ts1 = baking.get_linked_texture_sets(ts1, MeshMapUsage.AO) + +# link AO baking parameters for ts1 and ts2 together into a group, +# keeping ts1 parameters for both +baking.set_linked_group([ts1,ts2], ts1, MeshMapUsage.AO) + +# get the new list of Texture Sets which are linked with ts1 +# now they are linked, so it returns [ts1, ts2] +linked_with_ts1 = baking.get_linked_texture_sets(ts1, MeshMapUsage.AO) + +# finally unlink AO baking parameters +baking.unlink_all(MeshMapUsage.AO) + +# get curvature method +curvature_method = baking_params.get_curvature_method() + +# set curvature method +baking_params.set_curvature_method(CurvatureMethod.FromMesh) + +# check whether the baking is enabled on the Texture Set level and enable it +baking_params.is_textureset_enabled() +baking_params.set_textureset_enabled(True) + +# check if AO usage is enabled for baking and enable it +baking_params.is_baker_enabled(MeshMapUsage.AO) +baking_params.set_baker_enabled(MeshMapUsage.AO, True) + +# get all usages enabled for baking +baking_params.get_enabled_bakers() + +# set usages enabled for baking +baking_params.set_enabled_bakers([MeshMapUsage.AO, MeshMapUsage.Normal]) + +# check if one UV Tile is enabled for baking, disable it +baking_params.is_uv_tile_enabled(texture_set.uv_tile(0,0)) +baking_params.set_uv_tile_enabled(texture_set.uv_tile(0,0), False) + +# get all UV Tiles enabled for baking +baking_params.get_enabled_uv_tiles() +# set UV Tiles enabled for baking +baking_params.set_enabled_uv_tiles([texture_set.uv_tile(0,0), texture_set.uv_tile(0,1)]) + +``` + + + +See also + + +[`substance_painter.textureset.TextureSet`](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet"), +[`substance_painter.textureset.MeshMapUsage`](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage") +[`substance_painter.textureset.UVTile`](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile") + + + + + + +------ + + +*class* substance_painter.baking.BakingStatus(*value*) +Status code of the baking process. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `Success` | The baking was successful. | +| `Cancel` | The baking was cancelled by the user. | +| `Fail` | The baking could not complete; the cause is detailed in the log. | + + + + + + +------ + + +*class* substance_painter.baking.CurvatureMethod(*value*) +Members: + + +`FromMesh`, `FromNormalMap` + + + + + + +------ + + +*class* substance_painter.baking.BakingParameters(*material_id: int*) +Baking parameters for a given texture set. + + + +See also + + +[`substance_painter.textureset.TextureSet`](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet"), +[`substance_painter.textureset.MeshMapUsage`](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage") + + + + + +*static* from_texture_set(*texture_set: [TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")*) → [BakingParameters](#substance_painter.baking.BakingParameters "substance_painter.baking.BakingParameters") +Get the baking parameters for the given texture set object. + + + +Parameters: +**texture_set** ([*TextureSet*](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")) – The texture set. + + + +Returns: +The baking parameters for the given texure set. + + + +Return type: +[BakingParameters](#substance_painter.baking.BakingParameters "substance_painter.baking.BakingParameters") + + + + + +See also + + +[`substance_painter.textureset.TextureSet`](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet") + + + + + + +*static* from_texture_set_name(*texture_set_name: str*) → [BakingParameters](#substance_painter.baking.BakingParameters "substance_painter.baking.BakingParameters") +Get the baking parameters for the given texture set name. + + + +Parameters: +**texture_set_name** (*str*) – The texture set name. + + + +Returns: +The baking parameters for the given texure set. + + + +Return type: +[BakingParameters](#substance_painter.baking.BakingParameters "substance_painter.baking.BakingParameters") + + + + + +See also + + +[`substance_painter.properties.Property`](properties.html#substance_painter.properties.Property "substance_painter.properties.Property") + + + + + + +texture_set() → [TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet") +Get the associated texture set. + + + +Returns: +The texture set associated with this BakingParameters instance. + + + +Return type: +[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet") + + + + + +See also + + +[`substance_painter.textureset.TextureSet`](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet") + + + + + + +common() → Dict[str, [Property](properties.html#substance_painter.properties.Property "substance_painter.properties.Property")] +Get the parameters common to all bakers, like baking resolution. + + + +Returns: +The common parameters. + + + +Return type: +Dict[str, [Property](properties.html#substance_painter.properties.Property "substance_painter.properties.Property")] + + + + + +See also + + +[`substance_painter.properties.Property`](properties.html#substance_painter.properties.Property "substance_painter.properties.Property") + + + + + + +baker(*baked_map: [MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*) → Dict[str, [Property](properties.html#substance_painter.properties.Property "substance_painter.properties.Property")] +Get the parameters specific to a given baked map. + + + +Parameters: +**baked_map** ([*MeshMapUsage*](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")) – The baked map usage. + + + +Returns: +The corresponding baked map parameters. + + + +Return type: +Dict[str, [Property](properties.html#substance_painter.properties.Property "substance_painter.properties.Property")] + + + + + +See also + + +[`substance_painter.textureset.MeshMapUsage`](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage"), +[`substance_painter.properties.Property`](properties.html#substance_painter.properties.Property "substance_painter.properties.Property") + + + + + + +*static* set(*property_values: Dict[[Property](properties.html#substance_painter.properties.Property "substance_painter.properties.Property"), bool | int | Tuple[int, int] | Tuple[int, int, int] | Tuple[int, int, int, int] | float | Tuple[float, float] | Tuple[float, float, float] | Tuple[float, float, float, float] | str]*) → None +Set property values in batch. + + + +Parameters: +* **property_values** (*Dict**[*[*Property*](properties.html#substance_painter.properties.Property "substance_painter.properties.Property")*,* *PropertyValue**]*) – A dict of properties +* **values.** (*to be set with their corresponding new*) – + + + + + +See also + + +[`substance_painter.properties.Property`](properties.html#substance_painter.properties.Property "substance_painter.properties.Property") + + + + + + +get_curvature_method() → [CurvatureMethod](#substance_painter.baking.CurvatureMethod "substance_painter.baking.CurvatureMethod") +Get the curvature method used for baking + + + +Returns: +The curvature method used for baking + + + +Return type: +[CurvatureMethod](#substance_painter.baking.CurvatureMethod "substance_painter.baking.CurvatureMethod") + + + + + +See also + + +set_curvature_method + + + + + + +set_curvature_method(*method: [CurvatureMethod](#substance_painter.baking.CurvatureMethod "substance_painter.baking.CurvatureMethod")*) +Set the curvature method to use for baking + + + +Parameters: +**method** ([*CurvatureMethod*](#substance_painter.baking.CurvatureMethod "substance_painter.baking.CurvatureMethod")) – The new method to use for baking + + + + + +See also + + +get_curvature_method + + + + + + +is_baker_enabled(*usage: [MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*) → bool +Whether some usage is enabled for baking. + + + +Parameters: +**usage** ([*MeshMapUsage*](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")) – The baked map usage. + + + +Returns: +True if the corresponding usage is enabled for baking. + + + +Return type: +bool + + + + + + + +set_baker_enabled(*usage: [MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*, *enable: bool*) → None +Enable or disable a usage for baking. + + + +Parameters: +* **usage** ([*MeshMapUsage*](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")) – The baked map usage. +* **enable** (*bool*) – Enable or disable. + + + + + + + +get_enabled_bakers() → List[[MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")] +Get all usages enabled for baking. + + + +Returns: +Enabled usages. + + + +Return type: +List[[MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")] + + + + + + + +set_enabled_bakers(*enabled_usages: List[[MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")]*) → None +Set usages enabled for baking. Usages not in this list will be disabled. + + + +Parameters: +**enabled_usages** (*List**[*[*MeshMapUsage*](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*]*) – Enabled usages. + + + + + + + +is_textureset_enabled() → bool +Whether this Texture Set is enabled for baking. + + + +Returns: +True if this Texture Set is enabled for baking. + + + +Return type: +bool + + + + + + + +set_textureset_enabled(*enable: bool*) → None +Enable or disable this Texture Set for baking. + + + +Parameters: +**enable** (*bool*) – Enable or disable. + + + + + + + +is_uv_tile_enabled(*uv_tile: [UVTile](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")*) → bool +Whether a UV Tile is enabled for baking. + + + +Parameters: +**tile** ([*UVTile*](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")) – The UV Tile. + + + +Returns: +True if the UV Tile is enabled for baking. + + + +Return type: +bool + + + + + +See also + + +[`substance_painter.textureset.TextureSet`](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet"), +[`substance_painter.textureset.UVTile`](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile") + + + + + + +set_uv_tile_enabled(*uv_tile: [UVTile](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")*, *enable: bool*) → None +Enable or disable an UV Tile for baking. + + + +Parameters: +* **uv_tile** ([*UVTile*](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")) – The UV Tile. +* **enable** (*bool*) – Enable or disable. + + + + + +See also + + +[`substance_painter.textureset.TextureSet`](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet"), +[`substance_painter.textureset.UVTile`](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile") + + + + + + +get_enabled_uv_tiles() → List[[UVTile](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")] +Get all UV Tiles enabled for baking. + + + +Returns: +Enabled UV Tiles. + + + +Return type: +List[[UVTile](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")] + + + + + +See also + + +[`substance_painter.textureset.TextureSet`](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet"), +[`substance_painter.textureset.UVTile`](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile") + + + + + + +set_enabled_uv_tiles(*enabled_uv_tiles: List[[UVTile](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")]*) → None +Set UV Tiles enabled for baking. All other tiles will be disabled. + + + +Parameters: +**enabled_uv_tiles** (*List**[*[*UVTile*](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")*]*) – Enabled UV Tiles. + + + + + +See also + + +[`substance_painter.textureset.TextureSet`](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet"), +[`substance_painter.textureset.UVTile`](textureset/uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile") + + + + + + + +substance_painter.baking.set_linked_group(*group: List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")]*, *reference: [TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")*, *usage: [MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*) → None +Make a group of Texture Sets share the same baking parameters for the given ‘usage’. After that, +editing the ‘usage’ parameters of one of the group’s Texture Set will impact the whole group. + + + +Parameters: +* **group** (*List**[*[*TextureSet*](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")*]*) – Texture Sets to be included in the new group. +* **reference** ([*TextureSet*](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")) – Texture Set which parameters are applied to the whole group. +* **usage** ([*MeshMapUsage*](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")) – Usage of the group. + + + + + + + +substance_painter.baking.set_linked_group_common_parameters(*group: List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")]*, *reference: [TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")*) → None +Make a group of Texture Sets share the same baking common parameters. After that, editing a +common parameter of one of the group’s Texture Set will impact the whole group. + + + +Parameters: +* **group** (*List**[*[*TextureSet*](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")*]*) – Texture Sets to be included in the new group. +* **reference** ([*TextureSet*](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")) – Texture Set which parameters are applied to the whole group. + + + + + + + +substance_painter.baking.unlink_all(*usage: [MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*) → None +Unlink all Texture Sets for a given usage. That is, remove the group if it exists, so that all +Texture Sets have their own copy of the parameters. + + + +Parameters: +**usage** ([*MeshMapUsage*](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")) – Usage to unlink. + + + + + + + +substance_painter.baking.unlink_all_common_parameters() → None +Unlink all Texture Sets for common parameters. That is, remove the group if exists, so that all +Texture Sets have their own copy of the parameters. + + + + + +substance_painter.baking.get_link_group(*usage: [MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*) → List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")] +Get the list of Texture Sets that share baking parameters for a given usage. + + + +Parameters: +**usage** ([*MeshMapUsage*](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")) – Usage to query. + + + +Returns: +All linked Texture Sets for the usage. Empty list if no Texture Set are +linked. + + + +Return type: +List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")] + + + + + + + +substance_painter.baking.get_link_group_common_parameters() → List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")] +Get the list of Texture Sets that share common baking parameters. + + + +Returns: +All linked Texture Sets for common parameters. Empty list if no Texture +Set are linked. + + + +Return type: +List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")] + + + + + + + +substance_painter.baking.get_linked_texture_sets(*texture_set: [TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")*, *usage: [MeshMapUsage](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*) → List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")] +Get the list of Texture Sets that share the same parameters as some Texture Set, for a given +usage. + + + +Parameters: +* **texture_set** ([*TextureSet*](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")) – The Texture Set to query +* **usage** ([*MeshMapUsage*](textureset/index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")) – The usage to query + + + +Returns: +The list of Texture Sets sharing parameters with the input Texture Set. +Contains at least the input Texture Set if no group exists for the usage. + + + +Return type: +List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")] + + + + + + + +substance_painter.baking.get_linked_texture_sets_common_parameters(*texture_set: [TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")*) → List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")] +Get the list of Texture Sets that share the same parameters as some Texture Set, for common +parameters. + + + +Parameters: +**texture_set** ([*TextureSet*](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")) – The Texture Set to query + + + +Returns: +The list of Texture Sets sharing common parameters with the input Texture +Set. Contains at least the input Texture Set if no group exists for common parameters. + + + +Return type: +List[[TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")] + + + + + + + +substance_painter.baking.bake_async(*texture_set: [TextureSet](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")*) → [StopSource](async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource") +Launch the baking process for a Texture Set, using the current baking configuration. +The configuration is set by setting baking parameters, enabling Texture Set, selecting UV Tiles +for baking, setting curvature method etc. +This function is asynchronous. When the baking process is finished, the +[`substance_painter.event.BakingProcessEnded`](event.html#substance_painter.event.BakingProcessEnded "substance_painter.event.BakingProcessEnded") event is sent. + + + +Parameters: +**texture_set** ([*TextureSet*](textureset/textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet")) – The Texture Set to bake. + + + +Returns: +Can be used to cancel the asynchronous computation. + + + +Return type: +[StopSource](async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource") + + + + + +See also + + +[`BakingParameters`](#substance_painter.baking.BakingParameters "substance_painter.baking.BakingParameters") +[`substance_painter.event.BakingProcessAboutToStart`](event.html#substance_painter.event.BakingProcessAboutToStart "substance_painter.event.BakingProcessAboutToStart") +[`substance_painter.event.BakingProcessProgress`](event.html#substance_painter.event.BakingProcessProgress "substance_painter.event.BakingProcessProgress") +[`substance_painter.event.BakingProcessEnded`](event.html#substance_painter.event.BakingProcessEnded "substance_painter.event.BakingProcessEnded") +[`substance_painter.async_utils.StopSource`](async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource") + + + + + + +substance_painter.baking.bake_selected_textures_async() → [StopSource](async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource") +Launch the baking process, using the current baking configuration. +The configuration is set by setting baking parameters, enabling Texture Set, selecting UV Tiles +for baking, setting curvature method etc. +This function is asynchronous. When the baking process is finished, the +[`substance_painter.event.BakingProcessEnded`](event.html#substance_painter.event.BakingProcessEnded "substance_painter.event.BakingProcessEnded") event is sent. + + + +Returns: +Can be used to cancel the asynchronous computation. + + + +Return type: +[StopSource](async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource") + + + + + +See also + + +[`BakingParameters`](#substance_painter.baking.BakingParameters "substance_painter.baking.BakingParameters") +[`substance_painter.event.BakingProcessAboutToStart`](event.html#substance_painter.event.BakingProcessAboutToStart "substance_painter.event.BakingProcessAboutToStart") +[`substance_painter.event.BakingProcessProgress`](event.html#substance_painter.event.BakingProcessProgress "substance_painter.event.BakingProcessProgress") +[`substance_painter.event.BakingProcessEnded`](event.html#substance_painter.event.BakingProcessEnded "substance_painter.event.BakingProcessEnded") +[`substance_painter.async_utils.StopSource`](async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource") + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/display.md b/src/pages/api/substance_painter/display.md new file mode 100644 index 0000000..c1a7a5a --- /dev/null +++ b/src/pages/api/substance_painter/display.md @@ -0,0 +1,670 @@ +--- +title: display - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +display module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +display module +============== + + +This module exposes functions that change how the model of a project is presented +in the viewports. They correspond to settings available in the “Display +Settings” window. + + +The Environment Map used to light the scene can be retrieved with +[`get_environment_resource()`](#substance_painter.display.get_environment_resource "substance_painter.display.get_environment_resource"), or set with [`set_environment_resource()`](#substance_painter.display.set_environment_resource "substance_painter.display.set_environment_resource"). +The look up table (LUT) used as a Color Profile can be retrieved with +[`get_color_lut_resource()`](#substance_painter.display.get_color_lut_resource "substance_painter.display.get_color_lut_resource"), or set with [`set_color_lut_resource()`](#substance_painter.display.set_color_lut_resource "substance_painter.display.set_color_lut_resource"). + + +Example + + + +```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) + + +# 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) + + +# Show the currently active tone mapping operator: +try: + tone_mapping = substance_painter.display.get_tone_mapping() + print(tone_mapping) +except RuntimeError: + print("The project is color managed; tone mapping is not available") + +# Set a different tone mapping: +try: + new_tone_mapping = substance_painter.display.ToneMappingFunction.ACES + substance_painter.display.set_tone_mapping(new_tone_mapping) +except RuntimeError: + print("The project is color managed; tone mapping is not available") + +``` + + + +See also + + +[`substance_painter.resource`](resource.html#module-substance_painter.resource "substance_painter.resource"), +[Color Profile documentation](https://www.adobe.com/go/painter-color-profile), +[Environment Settings documentation](https://www.adobe.com/go/painter-environment-settings), +[Camera Settings documentation](https://substance3d.adobe.com/documentation/spdoc/camera-settings-172818743.html). + + + + + + +------ + + +*class* substance_painter.display.ToneMappingFunction(*value*) +Tone mapping function used in display. + + +This corresponds to the “Tone mapping” list in the “Camera settings” section +of the “Display settings” view. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `Linear` | Transformation from linear to sRGB without any color remapping. +Color values above 1 are clamped. | +| `ACES` | Use the standard color remapping from the Academy Color Encoding +System (ACES). | + + + + + +substance_painter.display.get_environment_resource() → [ResourceID](resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") | None +Get the environment map resource of the active project. + + + +Returns: +The environment map resource or None. + + + +Return type: +[ResourceID](resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +substance_painter.display.set_environment_resource(*new_env_map: [ResourceID](resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")*) → None +Set the environment map resource of the active project. + + + +Parameters: +**new_env_map** ([*ResourceID*](resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")) – The new environment map resource. + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* **TypeError** – If `new_env_map` is not a ResourceID. +* [**ResourceNotFoundError**](exception.html#substance_painter.exception.ResourceNotFoundError "substance_painter.exception.ResourceNotFoundError") – If the environment map `new_env_map` is not found. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +substance_painter.display.get_color_lut_resource() → [ResourceID](resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") | None +Get the color profile LUT resource of the active project. + + + +Returns: +The color profile LUT resource or None. + + + +Return type: +[ResourceID](resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +substance_painter.display.set_color_lut_resource(*new_color_lut: [ResourceID](resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")*) → None +Set the color profile LUT resource of the active project. + + + +Parameters: +**new_color_lut** ([*ResourceID*](resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")) – The new color profile LUT. + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* **TypeError** – If `new_color_lut` is not a ResourceID. +* [**ResourceNotFoundError**](exception.html#substance_painter.exception.ResourceNotFoundError "substance_painter.exception.ResourceNotFoundError") – If the color profile `new_color_lut` is not found. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +substance_painter.display.get_tone_mapping() → [ToneMappingFunction](#substance_painter.display.ToneMappingFunction "substance_painter.display.ToneMappingFunction") +Get the tone mapping operator used to display the current project. + + + +Note + + +The tone mapping function is disabled when color management is enabled. +In that case trying to call get_tone_mapping will throw a RuntimeError. + + + + +Returns: + +The tone mapping function currently used bythe project. + + + + + + + + +Return type: +[ToneMappingFunction](#substance_painter.display.ToneMappingFunction "substance_painter.display.ToneMappingFunction") + + + +Raises: +* **RuntimeError** – If the project is color managed. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +substance_painter.display.set_tone_mapping(*new_tone_mapping: [ToneMappingFunction](#substance_painter.display.ToneMappingFunction "substance_painter.display.ToneMappingFunction")*) → None +Set the tone mapping operator to display the current project. + + + +Note + + +The tone mapping function is disabled when color management is enabled. +In that case trying to call set_tone_mapping will throw a RuntimeError. + + + + +Parameters: +**new_tone_mapping** ([*ToneMappingFunction*](#substance_painter.display.ToneMappingFunction "substance_painter.display.ToneMappingFunction")) – The new tone mapping function +to use in the project. + + + +Raises: +* **TypeError** – If `new_tone_mapping` is not a ToneMappingFunction. +* **RuntimeError** – If the project is color managed. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + + +------ + + +*class* substance_painter.display.CameraProjectionType(*value*) +Camera projection type. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `Perspective` | Objects appear smaller when they are far from the camera. | +| `Orthographic` | Preserves relative size of objects regardless its distance from the camera. | + + + + + + +------ + + +*class* substance_painter.display.Camera(*_camera_id: int*) +Allows the manipulation of the properties of an existing Camera. +Coordinates of the camera are defined in the scene space. + + +Example + + + +```python +import substance_painter.display +import substance_painter.project + +substance_painter.project.open("C:/projects/MeetMat.spp") + +# Get the dimensions of the scene +bounding_box = substance_painter.project.get_scene_bounding_box() + +# Get the main camera +camera = substance_painter.display.Camera.get_default_camera() + +# Update camera properties +camera.projection_type = substance_painter.display.CameraProjectionType.Perspective +# Move the camera away from the center of the scene +camera.position = [ + bounding_box.center[0] + 15, + bounding_box.center[1], + bounding_box.center[2] + 15] +# Rotate the camera (45° of Y-axis) +camera.rotation = [0, 45, 0] +# Update the camera field of view (in degrees) +camera.field_of_view = 50 + +``` + + + +See also + + +[Camera Settings documentation](https://substance3d.adobe.com/documentation/spdoc/camera-settings-172818743.html). +[`substance_painter.project.get_scene_bounding_box()`](project.html#substance_painter.project.get_scene_bounding_box "substance_painter.project.get_scene_bounding_box") + + + + + +*static* get_default_camera() → [Camera](#substance_painter.display.Camera "substance_painter.display.Camera") +Get the default camera. + + + +Returns: +The default (main) camera. + + + +Return type: +[Camera](#substance_painter.display.Camera "substance_painter.display.Camera") + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* **RuntimeError** – If no camera has been found. + + + + + + + +*property* position*: List[float]* +The position (x,y,z) of the camera. + + + +Getter: +Returns the position of the camera. + + + +Setter: +Sets the position of the camera. + + + +Type: +List[float] + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +*property* rotation*: List[float]* +The rotation (x,y,z) of the camera as Euler angles in degrees. + + + +Getter: +Returns the rotation of the camera. + + + +Setter: +Sets the rotation of the camera. + + + +Type: +List[float] + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +*property* field_of_view*: float* +The field of view of the camera in degrees. +This value is only used if the `CameraProjectionType` is `Perspective`. + + + +Getter: +Returns the field of view of the camera. + + + +Setter: +Sets the field of view of the camera. Value is clamped between 3 and 179. + + + +Type: +float + + + + + +Note + + +Modifing the field of view will change the focal length. + + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +*property* focal_length*: float* +The focal length of the camera in mm. +This value is only used if the `CameraProjectionType` is `Perspective`. + + + +Getter: +Returns the focal length of the camera. + + + +Setter: +Sets the focal length of the camera. Value is clamped between 1 and 500. + + + +Type: +float + + + + + +Note + + +Modifing the focal length will change the field of view. + + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +*property* focus_distance*: float* +The focus distance of the camera. +Defines the distance at which the focus point is located. + + + +Getter: +Returns the focus distance of the camera. + + + +Setter: +Sets the focus distance of the camera. +Value is clamped between 0 and 10 * scene radius. + + + +Type: +float + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +*property* aperture*: float* +The aperture of the camera. Defines how wide the Depth of Field will be. + + + +Getter: +Returns the lens radius. + + + +Setter: +Sets the lens radius. Value is clamped between 0 and 1 * scene radius. + + + +Type: +float + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +*property* orthographic_height*: float* +The orthographic height of the camera. +This value is only used if the `CameraProjectionType` is `Orthographic`. + + + +Getter: +Returns the orthographic height of the camera. + + + +Setter: +Sets the orthographic height of the camera. + + + +Type: +float + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +*property* projection_type*: [CameraProjectionType](#substance_painter.display.CameraProjectionType "substance_painter.display.CameraProjectionType")* +The projection type (perspective or orthographic) of the camera. + + + +Getter: +Returns the projection type of the camera. + + + +Setter: +Sets the projection type of the camera. + + + +Type: +[CameraProjectionType](#substance_painter.display.CameraProjectionType "substance_painter.display.CameraProjectionType") + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/event.md b/src/pages/api/substance_painter/event.md new file mode 100644 index 0000000..b07323c --- /dev/null +++ b/src/pages/api/substance_painter/event.md @@ -0,0 +1,765 @@ +--- +title: event - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +event module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +event module +============ + + +The `event` module defines application events and allows to subscribe to +notifications. + + + + + +------ + + +*class* substance_painter.event.Event +Base event class. + + + + +Event dispatcher +---------------- + + + + +substance_painter.event.DISPATCHER *= * +The event dispatcher instance that will be used by the application. + + + + + + +------ + + +*class* substance_painter.event.Dispatcher +The Event Dispatcher. + + + + +connect(*event_cls: Type[[Event](#substance_painter.event.Event "substance_painter.event.Event")]*, *callback: Callable[[[Event](#substance_painter.event.Event "substance_painter.event.Event")], Any]*) → None +Connect a callback to handle the given event type. + + +The callback is stored as a weak reference, it is automatically disconnected +once the callback gets garbage collected. + + + +Parameters: +* **event_cls** ([*Type*](resource.html#substance_painter.resource.Type "substance_painter.resource.Type")*[*[*Event*](#substance_painter.event.Event "substance_painter.event.Event")*]*) – An event class. +* **callback** (*Callable**[**[*[*Event*](#substance_painter.event.Event "substance_painter.event.Event")*]**,* *Any**]*) – A method or a bound method that will be called when +an instance of the given event class is triggered. + + + + + + + +connect_strong(*event_cls: Type[[Event](#substance_painter.event.Event "substance_painter.event.Event")]*, *callback: Callable[[[Event](#substance_painter.event.Event "substance_painter.event.Event")], Any]*) → None +Connect a callback to handle the given event type. + + +The callback is stored as a strong reference, it is never automatically disconnected. + + + +Parameters: +* **event_cls** ([*Type*](resource.html#substance_painter.resource.Type "substance_painter.resource.Type")*[*[*Event*](#substance_painter.event.Event "substance_painter.event.Event")*]*) – An event class. +* **callback** (*Callable**[**[*[*Event*](#substance_painter.event.Event "substance_painter.event.Event")*]**,* *Any**]*) – A method or a bound method that will be called when +an instance of the given event class is triggered. + + + + + + + +disconnect(*event_cls: Type[[Event](#substance_painter.event.Event "substance_painter.event.Event")]*, *callback: Callable[[[Event](#substance_painter.event.Event "substance_painter.event.Event")], Any]*) → None +Disconnect a previously connected callback. + + +This method can be called to explicitly disconnect a callback. + + + +Parameters: +* **event_cls** ([*Type*](resource.html#substance_painter.resource.Type "substance_painter.resource.Type")*[*[*Event*](#substance_painter.event.Event "substance_painter.event.Event")*]*) – An event class. +* **callback** (*Callable**[**[*[*Event*](#substance_painter.event.Event "substance_painter.event.Event")*]**,* *Any**]*) – A method or a bound method that has been connected +to the given event class. + + + + + + + + +Export events +------------- + + + + + +------ + + +*class* substance_painter.event.ExportTexturesAboutToStart(*textures: Dict[Tuple[str, str], List[str]]*) +Event triggered just before a textures export. + + + + +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(*status: [ExportStatus](export.html#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus")*, *message: str*, *textures: Dict[Tuple[str, str], List[str]]*) +Event triggered after textures export is finished. + + + + +message*: str* +Human readable status message. + + + +Type: +str + + + + + + + +status*: [ExportStatus](export.html#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus")* +Status code. + + + +Type: +[ExportStatus](export.html#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus") + + + + + + + +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]] + + + + + + + + +Project events +-------------- + + + +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 +Event triggered when an existing project has been opened. + + + + + + +------ + + +*class* substance_painter.event.ProjectCreated +Event triggered when a new project has been created. + + + + + + +------ + + +*class* substance_painter.event.ProjectAboutToClose +Event triggered just before closing the current project. + + + + + + +------ + + +*class* substance_painter.event.ProjectAboutToSave(*file_path: str*) +Event triggered just before saving the current project. + + + + +file_path*: str* +The destination file. + + + +Type: +str + + + + + + + + + +------ + + +*class* substance_painter.event.ProjectSaved +Event triggered once the current project is saved. + + + + + + +------ + + +*class* substance_painter.event.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 +Event triggered when the current project can non longer be edited. + + + + + + +------ + + +*class* substance_painter.event.BusyStatusChanged(*busy: bool*) +Event triggered when Substance 3D Painter busy state changed. + + + +See also + + +[`substance_painter.project.execute_when_not_busy()`](project.html#substance_painter.project.execute_when_not_busy "substance_painter.project.execute_when_not_busy"), +[`substance_painter.project.is_busy()`](project.html#substance_painter.project.is_busy "substance_painter.project.is_busy"). + + + + + +busy*: bool* +Whether Substance 3D Painter is busy now. + + + +Type: +bool + + + + + + + + + +------ + + +*class* substance_painter.event.TextureStateEvent(*action: [TextureStateEventAction](#substance_painter.event.TextureStateEventAction "substance_painter.event.TextureStateEventAction")*, *stack_id: int*, *tile_indices: Tuple[int, int]*, *channel_type: [ChannelType](textureset/index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")*, *cache_key: int*) +Event triggered when a document texture is added, removed or updated. + + + + +action*: [TextureStateEventAction](#substance_painter.event.TextureStateEventAction "substance_painter.event.TextureStateEventAction")* +Performed action (add, remove, update). + + + +Type: +[TextureStateEventAction](#substance_painter.event.TextureStateEventAction "substance_painter.event.TextureStateEventAction") + + + + + + + +cache_key*: int* +The texture current cache key. Those cache keys are persistent across sessions. + + + +Type: +int + + + + + + + +*static* cache_key_invalidation_throttling_period() → timedelta +Get the minimum duration between two texture update events (for a given texture). + + + +Returns: +The minimum duration between two update events. + + + +Return type: +datetime.timedelta + + + + + + + +channel_type*: [ChannelType](textureset/index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")* +The document channel type. + + + +Type: +[substance_painter.textureset.ChannelType](textureset/index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType") + + + + + + + +*static* set_cache_key_invalidation_throttling_period(*period: timedelta*) → None +Set the minimum duration between two texture update events (for a given texture). + + +Warning: this setting is global and every work made in a callback associated to this event +may greatly hurt the painting experience. + + + +Parameters: +**period** (*datetime.timedelta*) – The minimum duration between two update events, can’t +be lower than 500ms. + + + +Raises: +**ValueError** – If period is below 500ms. + + + + + + + +stack_id*: int* +The stack the texture bellongs to, can be used to create a +[`substance_painter.textureset.Stack`](textureset/stack.html#substance_painter.textureset.Stack "substance_painter.textureset.Stack") instance. + + + +Type: +int + + + + + + + +tile_indices*: Tuple[int, int]* +The uv tile indices. + + + +Type: +Tuple[int, int] + + + + + + + + + +------ + + +*class* substance_painter.event.TextureStateEventAction(*value*) +The TextureStateEvent possible actions. + + +Members: + + +`ADD`, `UPDATE`, `REMOVE` + + + + + +Shelf events +------------ + + + + + +------ + + +*class* substance_painter.event.ShelfCrawlingStarted(*shelf_name: str*) +Event triggered when a shelf starts reading the file system to discover +new resources. + + + +See also + + +`Shelf.is_crawling()`. + + + + + +shelf_name*: str* +Name of the shelf discovering resources. + + + +Type: +str + + + + + + + + + +------ + + +*class* substance_painter.event.ShelfCrawlingEnded(*shelf_name: str*) +Event triggered when a shelf has finished discovering new resources and +loading their thumbnails. + + + +See also + + +`Shelf.is_crawling()`. + + + + + +shelf_name*: str* +Name of the shelf that has finished discovering resources. + + + +Type: +str + + + + + + + + +Baking events +------------- + + + + + +------ + + +*class* substance_painter.event.BakingProcessAboutToStart(*stop_source: [StopSource](async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource")*) +Event triggered when a baking is about to start. + + + +See also + + +[`substance_painter.baking.bake_async()`](baking.html#substance_painter.baking.bake_async "substance_painter.baking.bake_async") +[`substance_painter.baking.bake_selected_textures_async()`](baking.html#substance_painter.baking.bake_selected_textures_async "substance_painter.baking.bake_selected_textures_async") + + + + + +stop_source*: [StopSource](async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource")* +The baking stop source, can be compared with the StopSource +returned from the baking launch methods to identify the baking process. + + + +Type: +[StopSource](async_utils.html#substance_painter.async_utils.StopSource "substance_painter.async_utils.StopSource") + + + + + + + + + +------ + + +*class* substance_painter.event.BakingProcessProgress(*progress: float*) +Event triggered when baking process progress changes. + + + +See also + + +[`substance_painter.baking.bake_async()`](baking.html#substance_painter.baking.bake_async "substance_painter.baking.bake_async") +[`substance_painter.baking.bake_selected_textures_async()`](baking.html#substance_painter.baking.bake_selected_textures_async "substance_painter.baking.bake_selected_textures_async") + + + + + +progress*: float* +The baking progress, between [0.0, 1.0]. + + + + + + + +------ + + +*class* substance_painter.event.BakingProcessEnded(*status: [BakingStatus](baking.html#substance_painter.baking.BakingStatus "substance_painter.baking.BakingStatus")*) +Event triggered after baking is finished. + + + +See also + + +[`substance_painter.baking.bake_async()`](baking.html#substance_painter.baking.bake_async "substance_painter.baking.bake_async") +[`substance_painter.baking.bake_selected_textures_async()`](baking.html#substance_painter.baking.bake_selected_textures_async "substance_painter.baking.bake_selected_textures_async") + + + + + +status*: [BakingStatus](baking.html#substance_painter.baking.BakingStatus "substance_painter.baking.BakingStatus")* +Status of the baking process + + + +Type: +[BakingStatus](baking.html#substance_painter.baking.BakingStatus "substance_painter.baking.BakingStatus") + + + + + + + + +Layer stack events +------------------ + + + + + +------ + + +*class* substance_painter.event.LayerStacksModelDataChanged +Event triggered whenever the status of the Layer Stacks changes. + + + +See also + + +`substance_painter.layerstack` + + + + + + +Application wide events +----------------------- + + + + + +------ + + +*class* substance_painter.event.EngineComputationsStatusChanged(*engine_computations_enabled: bool*) +Event triggered whenever the status of the engine computations changes. + + + +See also + + +[`substance_painter.application.engine_computations_status()`](application.html#substance_painter.application.engine_computations_status "substance_painter.application.engine_computations_status") + + + + + + +Display events +-------------- + + + + + +------ + + +*class* substance_painter.event.CameraPropertiesChanged(*camera_id: int*) +Event triggered when the camera properties change. + + + +See also + + +[`substance_painter.display.Camera`](display.html#substance_painter.display.Camera "substance_painter.display.Camera") + + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/exception.md b/src/pages/api/substance_painter/exception.md new file mode 100644 index 0000000..a581526 --- /dev/null +++ b/src/pages/api/substance_painter/exception.md @@ -0,0 +1,93 @@ +--- +title: exception - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +exception module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +exception module +================ + + +This module declares Substance 3D Painter specific exceptions. + + + + + +------ + + +*class* substance_painter.exception.ProjectError(*value*) +Raised when an operation or function is incompatible with the current +project, or when the current state of the project is invalid. + + +Trying to save a project when there is no project opened would raise a +[`ProjectError`](#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError"). + + + + + + +------ + + +*class* substance_painter.exception.ResourceNotFoundError(*value*) +Raised when a Substance 3D Painter resource could not be found. + + +Providing an invalid resource ID would raise a [`ResourceNotFoundError`](#substance_painter.exception.ResourceNotFoundError "substance_painter.exception.ResourceNotFoundError"). + + + + + + +------ + + +*class* substance_painter.exception.ServiceNotFoundError(*value*) +Raised when an operation or function relies on a service which could not +be found. It could mean that the service has not been started yet. + + +Trying to execute a command while Substance 3D Painter is starting could +raise [`ServiceNotFoundError`](#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError"). + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/export.md b/src/pages/api/substance_painter/export.md new file mode 100644 index 0000000..87ae23b --- /dev/null +++ b/src/pages/api/substance_painter/export.md @@ -0,0 +1,931 @@ +--- +title: export - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +export module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +export module +============= + + +This module exposes functions to export assets (textures and meshes) from a project under a variety +of formats. It is the scripting equivalent of the “Export textures” and the “Export mesh” windows. + + +For the export textures, the export configuration is defined with a JSON file, but can also use +existing export presets. + + + + + +------ + + +*class* substance_painter.export.ExportStatus(*value*) +Status code of the export process. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `Success` | The export was successful. | +| `Cancelled` | The export was cancelled by the user. | +| `Warning` | The export completed with warnings. | +| `Error` | The export could not complete; the cause is detailed in the log. | + + + + +Export Textures +--------------- + + + + +substance_painter.export.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**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.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()`](#substance_painter.export.export_project_textures "substance_painter.export.export_project_textures"). + + + + + + + +------ + + +*class* substance_painter.export.TextureExportResult(*status: [ExportStatus](#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus")*, *message: str*, *textures: Dict[Tuple[str, str], List[str]]*) +Result of the export textures process + + + + +status +Status code. + + + +Type: +[ExportStatus](#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus") + + + + + + + +message +Human readable status message. + + + +Type: +str + + + + + + + +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(*json_config: dict*) → [TextureExportResult](#substance_painter.export.TextureExportResult "substance_painter.export.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](#substance_painter.export.TextureExportResult "substance_painter.export.TextureExportResult") + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.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`](event.html#substance_painter.event.ExportTexturesAboutToStart "substance_painter.event.ExportTexturesAboutToStart"), +[`substance_painter.event.ExportTexturesEnded`](event.html#substance_painter.event.ExportTexturesEnded "substance_painter.event.ExportTexturesEnded"). + + + +Example: + + + +```python +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 for '03_Base', but otherwise follow the export preset +# configuration. +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": [ + # No filters: those parameters apply to all exported maps + { + "parameters": { + "dithering": True, + "paddingAlgorithm": "infinite" + } + }, + # Force file format and bitDepth for all maps in '03_Base' + { + "filter": {"dataPaths": ["03_Base"]}, + "parameters": { + "fileFormat" : "png", + "bitDepth" : "8" + } + }, + # Force 2K size for all maps in '01_Head' + { + "filter": {"dataPaths": ["01_Head"]}, + "parameters": { + "sizeLog2": 11 + } + }] + } + +# 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) + +``` + + + +See also + + +[`substance_painter.project`](project.html#module-substance_painter.project "substance_painter.project"), +[`substance_painter.resource`](resource.html#module-substance_painter.resource "substance_painter.resource"), +[Export documentation](https://www.adobe.com/go/painter-export). + + + + + + +substance_painter.export.get_default_export_path() → str +Get the default export path used for exporting textures. + + + +Returns: +The default export path. + + + +Return type: +str + + + + + + + +Full json_config dict possibilities +----------------------------------- + + + +```python +{ + + // 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`](event.html#module-substance_painter.event "substance_painter.event") for more details. + + + + + +------ + + +*class* substance_painter.event.ExportTexturesAboutToStart(*textures: Dict[Tuple[str, str], List[str]]*) +Event triggered just before a textures export. + + + + +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(*status: [ExportStatus](#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus")*, *message: str*, *textures: Dict[Tuple[str, str], List[str]]*) +Event triggered after textures export is finished. + + + + +message*: str* +Human readable status message. + + + +Type: +str + + + + + + + +status*: [ExportStatus](#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus")* +Status code. + + + +Type: +[ExportStatus](#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus") + + + + + + + +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]] + + + + + + + + +Export Mesh +----------- + + + + +substance_painter.export.scene_is_triangulated() → bool +Check if the scene has only triangles (polygons with only 3 sides). + + + +Returns: +True if the current scene has only triangles, False otherwise. + + + +Return type: +bool + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +substance_painter.export.scene_has_tessellation() → bool +Check if the scene has displacement/tessellation enabled. + + + +Returns: +True if the current scene has displacement/tessellation, False otherwise. + + + +Return type: +bool + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + + +------ + + +*class* substance_painter.export.MeshExportOption(*value*) +Options available for the mesh export. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `BaseMesh` | Export without displacement/tesselation. | +| `TriangulatedMesh` | Export without displacement/tesselation and apply triangulation. +Triangulation converts all mesh polygons with more than 3 sides +to triangles (but doesn’t change the triangular ones). +Only avaiblable if the mesh contains such polygons. | +| `TessellationNormalsBaseMesh` | Export with displacement/tessellation. Only available if +displacement or tessellation has been used in the shaders. | +| `TessellationRecomputeNormals` | Export with displacement/tessellation and recompute vertex +normals. Only available if displacement or +tessellation has been used in the shaders. | + + + + + + +------ + + +*class* substance_painter.export.MeshExportResult(*status: [ExportStatus](#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus")*, *message: str*) +Result of the export mesh process + + + + +status +Status code. + + + +Type: +[ExportStatus](#substance_painter.export.ExportStatus "substance_painter.export.ExportStatus") + + + + + + + +message +Human readable status message. + + + +Type: +str + + + + + + + + +substance_painter.export.export_mesh(*file_path: str*, *option: [MeshExportOption](#substance_painter.export.MeshExportOption "substance_painter.export.MeshExportOption")*) → [MeshExportResult](#substance_painter.export.MeshExportResult "substance_painter.export.MeshExportResult") +Export the current mesh to the given file path. + + + +Parameters: +* **file_path** (*string*) – The complete file path where to export the mesh. The file format is +deduced from the extension. +Supported extensions are: `.usd`, `.obj`, `.fbx`, `.dae`, `.ply`, `.gltf`. +* **option** ([*MeshExportOption*](#substance_painter.export.MeshExportOption "substance_painter.export.MeshExportOption")) – The export option to use. + + + +Returns: +Result of the export process. + + + +Return type: +[MeshExportResult](#substance_painter.export.MeshExportResult "substance_painter.export.MeshExportResult") + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* **ValueError** – If `file_path` or `option` are invalid in the context + of the current project. Contains a human readable message detailing + the problem. + + + + +Example: + + + +```python +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 option to use +export_option = substance_painter.export.MeshExportOption.BaseMesh +if not substance_painter.export.scene_is_triangulated(): + export_option = substance_painter.export.MeshExportOption.TriangulatedMesh +if substance_painter.export.scene_has_tessellation(): + export_option = substance_painter.export.MeshExportOption.TessellationNormalsBaseMesh + +# Actual export mesh operation: +filename = "C:/projects/MeetMat.obj" +export_result = substance_painter.export.export_mesh(filename, export_option) + +# In case of error, display a human readable message: +if export_result.status != substance_painter.export.ExportStatus.Success: + print(export_result.message) + +``` + + + +See also + + +[`substance_painter.project`](project.html#module-substance_painter.project "substance_painter.project"), +[Export documentation](https://www.adobe.com/go/painter-export). + + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/js.md b/src/pages/api/substance_painter/js.md new file mode 100644 index 0000000..172e889 --- /dev/null +++ b/src/pages/api/substance_painter/js.md @@ -0,0 +1,101 @@ +--- +title: js - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +js module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +js module +========= + + +This module allows to evaluate JavaScript code against the legacy embedded +JavaScript engine. This allows to use all the exposed JavaScript API through +Python scripting. The JavaScript API is described in dedicated help accessible +via the `Help > Scripting documentation > JavaScript API` menu found in +Substance 3D Painter application. + + +Example + + + +```python +import substance_painter.js + +# Get the baking parameters +js_code = 'alg.baking.textureSetBakingParameters("some_texture_set")' +baking_parameters = substance_painter.js.evaluate(js_code) + +# substance_painter.js.evaluate returns JSON, so the result is easy to retrieve and use +material_parameters = baking_parameters['materialParameters'] +apply_diffusion = material_parameters['commonParameters']['Apply_Diffusion'] + +``` + + + + +substance_painter.js.evaluate(*js_code: str*) → str +Evaluate a JavaScript expression. +The JavaScript API is described in dedicated help accessible via the +`Help > Scripting documentation > JavaScript API` menu found in +Substance 3D Painter application. + + + +Parameters: +**js_code** (*str*) – The block of JavaScript code to be evaluated. + + + +Returns: +The JSON formated result of the evaluation. + + + +Return type: +str + + + +Raises: +**RuntimeError** – If the JavaScript exception evaluation returns an error. + + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/logging.md b/src/pages/api/substance_painter/logging.md new file mode 100644 index 0000000..646dfe8 --- /dev/null +++ b/src/pages/api/substance_painter/logging.md @@ -0,0 +1,149 @@ +--- +title: logging - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +logging module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +logging module +============== + + +This module exposes several functions to output messages to the Substance +Painter logger. Depending on the severity of the message, use [`info()`](#substance_painter.logging.info "substance_painter.logging.info"), +[`warning()`](#substance_painter.logging.warning "substance_painter.logging.warning") or [`error()`](#substance_painter.logging.error "substance_painter.logging.error"). + + +For a finer control over the logging parameters, namely severity and channel, +use [`log()`](#substance_painter.logging.log "substance_painter.logging.log"). The functions [`info()`](#substance_painter.logging.info "substance_painter.logging.info"), [`warning()`](#substance_painter.logging.warning "substance_painter.logging.warning") and +[`error()`](#substance_painter.logging.error "substance_painter.logging.error") will output to the ‘Python’ log channel, while [`log()`](#substance_painter.logging.log "substance_painter.logging.log") +allows to specify a different channel. + + +Messages with severity levels `INFO`, `WARNING` and `ERROR` are meant for +the end user, and will appear in the log window of Substance 3D Painter. Messages +with severity levels `DBG_INFO`, `DBG_WARNING` and `DBG_ERROR` are meant +for the developer, and will appear in the log file. + + +Example + + + +```python +import substance_painter.logging + +# Simple log functions: +substance_painter.logging.info("Everyone knows that 2 + 2 is {0}.".format(2+2)) +substance_painter.logging.warning("Maybe the user should look at this.") +substance_painter.logging.error("Letting the user know that something went wrong.") + +# Log function with more options: +substance_painter.logging.log( + substance_painter.logging.INFO, + "Python", + "An informative log message to the 'Python' channel.") + +substance_painter.logging.log( + substance_painter.logging.ERROR, + "MyPlugin", + "An error log message to the 'MyPlugin' channel.") + +``` + + + + +substance_painter.logging.error(*message: str*) +Logs a message with level `ERROR` on the Substance 3D Painter logger. + + + +Parameters: +**message** (*str*) – The error message to log. + + + + + + + +substance_painter.logging.info(*message: str*) +Logs a message with level `INFO` on the Substance 3D Painter logger. + + + +Parameters: +**message** (*str*) – The message to log. + + + + + + + +substance_painter.logging.log(*severity*, *channel: str*, *message: str*) +Logs a message with level severity on the Substance 3D Painter logger. + + + +Parameters: +* **severity** – the severity level, can be `INFO`, `WARNING` or `ERROR` for +messages relevant to the end user, or `DBG_INFO`, `DBG_WARNING` or +`DBG_ERROR` for messages relevant to the developer. +* **channel** (*str*) – the channel to log into. This can be any name allowing to +identify the origin of the message, for example the name of +your plugin. +* **message** (*str*) – the message to log. + + + + + + + +substance_painter.logging.warning(*message: str*) +Logs a message with level `WARNING` on the Substance 3D Painter logger. + + + +Parameters: +**message** (*str*) – The warning message to log. + + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/project.md b/src/pages/api/substance_painter/project.md new file mode 100644 index 0000000..405c793 --- /dev/null +++ b/src/pages/api/substance_painter/project.md @@ -0,0 +1,1599 @@ +--- +title: project - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +project module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +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: + + + +```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) + +# End of our little example... +substance_painter.project.close() + +``` + + + + + +------ + + +*class* substance_painter.project.BoundingBox(*dimensions: List[float]*, *center: List[float]*, *radius: float*) +Axis-aligned bounding box (AABB). + + + + +dimensions +The dimensions (x,y,z) of the bounding box. + + + +Type: +List[float] + + + + + + + +center +The center (x,y,z) of the bounding box.. + + + +Type: +List[float] + + + + + + + +radius +The radius of the bounding box. + + + +Type: +float + + + + + +See also: +[`get_scene_bounding_box()`](#substance_painter.project.get_scene_bounding_box "substance_painter.project.get_scene_bounding_box"), + + + + + +substance_painter.project.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.project.is_busy "substance_painter.project.is_busy"), +[`substance_painter.event.BusyStatusChanged`](event.html#substance_painter.event.BusyStatusChanged "substance_painter.event.BusyStatusChanged"). + + + + + + +substance_painter.project.file_path() → str | None +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**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + +See also + + +[`save()`](#substance_painter.project.save "substance_painter.project.save"), +[`save_as()`](#substance_painter.project.save_as "substance_painter.project.save_as"). + + + + + + +substance_painter.project.get_scene_bounding_box() → [BoundingBox](#substance_painter.project.BoundingBox "substance_painter.project.BoundingBox") +Return the bounding box of the scene. + + + +Returns: +The bounding box of the scene. + + + +Return type: +[BoundingBox](#substance_painter.project.BoundingBox "substance_painter.project.BoundingBox") + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +substance_painter.project.get_uuid() → UUID +Return the UUID of the current project. + + + +Returns: +The UUID of the current project. + + + +Return type: +uuid.UUID + + + +Raises: +[**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +substance_painter.project.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.project.execute_when_not_busy "substance_painter.project.execute_when_not_busy"), +[`substance_painter.event.BusyStatusChanged`](event.html#substance_painter.event.BusyStatusChanged "substance_painter.event.BusyStatusChanged"). + + + + + + +substance_painter.project.is_in_edition_state() → bool +Check if the current project is ready to work with. + + + +Raises: +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.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`](event.html#substance_painter.event.ProjectEditionEntered "substance_painter.event.ProjectEditionEntered"), +[`substance_painter.event.ProjectEditionLeft`](event.html#substance_painter.event.ProjectEditionLeft "substance_painter.event.ProjectEditionLeft"). + + + + + + +substance_painter.project.last_saved_substance_painter_version() → Tuple[int, int, int] | None +Return the version of Substance 3D Painter used to last save the project, or None +if the project is unsaved or was saved with version <= 8.2.0. + + + +Returns: +The concerned version of Substance 3D Painter, as a major/minor/patch +tuple. + + + +Return type: +Tuple(int, int, int) + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. + + + + + + + +substance_painter.project.name() → str | None +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**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + +Creating a project +------------------ + + + +Example: +```python +import substance_painter.project + +# Use OpenGL / right handed normal map format: +ogl_normal_map_format = substance_painter.project.NormalMapFormat.OpenGL + +# Use per vertex tangent space: +per_vertex_tangent = substance_painter.project.TangentSpace.PerVertex + +# Declare the settings for the project: +project_settings = substance_painter.project.Settings( + import_cameras=True, + normal_map_format=ogl_normal_map_format, + tangent_space_mode=per_vertex_tangent) + +# A list of maps to use: +maps = ["C:/Documents/DefaultMaterial_ambient_occlusion.png", + "C:/Documents/DefaultMaterial_id.png"] + +# Create the project with those settings: +substance_painter.project.create( + mesh_file_path = "C:/Documents/my_mesh.fbx", + mesh_map_file_paths = maps, + settings = project_settings) + + +# If this is a project with UDIMs, we need to choose the workflow: +uv_tile_workflow = substance_painter.project.ProjectWorkflow.UVTile + +# Declare the settings for the project: +project_settings = substance_painter.project.Settings( + import_cameras=True, + normal_map_format=ogl_normal_map_format, + tangent_space_mode=per_vertex_tangent, + project_workflow=uv_tile_workflow) + +# A list of maps to use (in this example, the file name indicates a +# a sequence of potentially several UDIMs; the project will load all +# of them without having to list them individually): +maps = ["C:/Documents/DefaultMaterial_ambient_occlusion.1001.png"] + +# Create the project with those settings: +substance_painter.project.create( + mesh_file_path = "C:/Documents/my_mesh_with_UDIMs.fbx", + mesh_map_file_paths = maps, + settings = project_settings) + +``` + + + + + + +substance_painter.project.create(*mesh_file_path: str*, *mesh_map_file_paths: List[str] | None = None*, *template_file_path: str | None = None*, *settings: [Settings](#substance_painter.project.Settings "substance_painter.project.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, usd_settings=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, usd. +* **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*](#substance_painter.project.Settings "substance_painter.project.Settings")) – Configuration options of the new project. + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If Substance 3D Painter cannot create the project. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If there is already an opened project. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If an `OCIO` environment variable is set to an invalid configuration. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If an `PAINTER_ACE_CONFIG` environment variable is set to an invalid preset. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.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`](#substance_painter.project.Settings "substance_painter.project.Settings")). +* **ValueError** – If `settings.default_texture_resolution` is not a valid resolution. + + + + + +See also + + +[`Settings`](#substance_painter.project.Settings "substance_painter.project.Settings"), +[Project creation documentation](https://www.adobe.com/go/painter-project-creation). + + + + + + + +------ + + +*class* substance_painter.project.Settings(*default_save_path: str | None = None*, *normal_map_format: [NormalMapFormat](#substance_painter.project.NormalMapFormat "substance_painter.project.NormalMapFormat") | None = None*, *tangent_space_mode: [TangentSpace](#substance_painter.project.TangentSpace "substance_painter.project.TangentSpace") | None = None*, *project_workflow: [ProjectWorkflow](#substance_painter.project.ProjectWorkflow "substance_painter.project.ProjectWorkflow") | None = None*, *export_path: str | None = None*, *default_texture_resolution: int | None = None*, *import_cameras: bool | None = None*, *mesh_unit_scale: float | None = None*, *usd_settings: [UsdSettings](#substance_painter.project.UsdSettings "substance_painter.project.UsdSettings") | None = 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`](#substance_painter.project.NormalMapFormat "substance_painter.project.NormalMapFormat"), +[`TangentSpace`](#substance_painter.project.TangentSpace "substance_painter.project.TangentSpace"), +[`ProjectWorkflow`](#substance_painter.project.ProjectWorkflow "substance_painter.project.ProjectWorkflow"), +[`create()`](#substance_painter.project.create "substance_painter.project.create"), +[Project configuration documentation](https://www.adobe.com/go/painter-project-configuration). + + + + + +default_save_path*: str* *= None* +The default save path. + + + + + +default_texture_resolution*: int* *= None* +Default resolution for all the Texture Sets. + + + + + +export_path*: str* *= None* +Use this path as the default map export path. + + + + + +import_cameras*: bool* *= None* +Import cameras from the mesh file. + + + + + +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*: [NormalMapFormat](#substance_painter.project.NormalMapFormat "substance_painter.project.NormalMapFormat")* *= None* +Normal map system coordinates. OpenGL or DirectX format. + + + + + +project_workflow*: [ProjectWorkflow](#substance_painter.project.ProjectWorkflow "substance_painter.project.ProjectWorkflow")* *= None* +Project workflow, selected at project creation time. + + + + + +tangent_space_mode*: [TangentSpace](#substance_painter.project.TangentSpace "substance_painter.project.TangentSpace")* *= None* +Per vertex or per fragment tangent space. + + + + + +usd_settings*: [UsdSettings](#substance_painter.project.UsdSettings "substance_painter.project.UsdSettings")* *= None* +Specific settings for USD files. + + + + + + + +------ + + +*class* substance_painter.project.UsdSettings(*scope_name: str = '/'*, *variants: dict | None = None*, *subdivision_level: int = 1*, *frame: int = 0*) +Specific settings for USD files. + + +This corresponds to the options that are available in the File type-specific settings section +in the “New project” and “Project configuration” dialogs. + + + + +frame*: int* *= 0* +The frame to import. +Only available for animated USD files. + + + + + +scope_name*: str* *= '/'* +Scope name of the primitive to load in the hierarchy. The path must be absolute. +Expected syntax: `"/my/path/name"` + + +If not specified, default scope name is the root `"/"`. Only available for USD files. + + + + + +subdivision_level*: int* *= 1* +The subdivision level is applied only on geometry built with subdivision. +Only available for USD files. + + + + + +variants*: dict* *= None* +Define which variant to use for each primitive path. Values are expected in JSON format. + + + +> +> +> ```python +> [ +> { +> "primPath": "/my/path/name", +> "selectionName: "variantName", +> "setName": "variantSetName" +> } +> ] +> +> ``` +> +> +> + + +Only available for USD files. + + + + + + + +------ + + +*class* substance_painter.project.NormalMapFormat(*value*) +The normal map formats that can be used by a Substance 3D Painter project. +A project can have either left handed / OpenGL or right handed / DirectX +normal maps. + + +This corresponds to the menu “Normal Map Format” in the “New project” +dialog. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `OpenGL` | OpenGL tangent space (right handed). | +| `DirectX` | DirectX tangent space (left handed). | + + + + + + +------ + + +*class* substance_painter.project.TangentSpace(*value*) +The options for computing tangent space in a project. Tangent space can +be evaluated at each vertex, or at each fragment. + + +This corresponds to the “Compute Tangent Space Per Fragment” checkbox in +the “New project” dialog. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `PerVertex` | Tangent space computed per vertex. | +| `PerFragment` | Tangent space computed per fragment. | + + + + + + +------ + + +*class* substance_painter.project.ProjectWorkflow(*value*) +The workflow used by a Substance 3D Painter project. + + +By enabling the UV Tiles Workflow for each Texture Set, tiles within the +same Texture Set share a layer stack and can be painted across. By creating +a Texture Set per UV Tile, each tile is placed in a Texture Set of its own. +This is the legacy workflow and does not allow for painting accross tiles. + + +This corresponds to the section “UV Tiles (UDIMs)” in the “New project” +dialog. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `Default` | Default workflow (no udim). | +| `TextureSetPerUVTile` | Udim workflow with one Texture Set per UV Tile (legacy). | +| `UVTile` | Udim workflow with one Texture Set per material containing +multiple UV Tiles. | + + + + + +Opening and closing a project +----------------------------- + + + +Example: +```python +import substance_painter.project + +# Check if a project is already opened: +if substance_painter.project.is_open(): + print("A project is already opened!") +else: + # Open an existing project: + substance_painter.project.open("c:/Documents/project.spp") + +if substance_painter.project.is_open(): + # Close the project currently opened: + substance_painter.project.close() + +``` + + + + + + +substance_painter.project.is_open() → bool +Check if a project is already opened. + + + +Returns: +`True` if a project is opened, `False` otherwise. + + + +Return type: +bool + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. + + + + + + + +substance_painter.project.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**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If Substance 3D Painter cannot open the file `project_file_path`. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If there is already an opened project. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. + + + + + + + +substance_painter.project.close() → None +Close the current project. + + + +Warning + + +Any unsaved data will be lost. + + + + +Raises: +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.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`](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError"). + + + +Example: +```python +import substance_painter.project + +# Check if a project is already opened: +if not substance_painter.project.is_open(): + print("No project is opened!") + +# Check if the project needs to be saved at all: +if not substance_painter.project.needs_saving(): + print("There is nothing to save!") + +# Save the project under the name "project1": +substance_painter.project.save_as("c:/Documents/project1.spp", + substance_painter.project.ProjectSaveMode.Full) +# This should print "c:/Documents/project1.spp": +print(substance_painter.project.file_path()) + +# Change the name of the project to "project2": +substance_painter.project.save_as("c:/Documents/project2.spp") +# This should now print "c:/Documents/project2.spp": +print(substance_painter.project.file_path()) + +# Create a backup copy of the project: +substance_painter.project.save_as_copy("c:/Documents/project2-backup.spp") +# This should still print "c:/Documents/project2.spp": +print(substance_painter.project.file_path()) + +# Save the project incrementally +#(writing to project2.spp, and not project2-backup.spp): +substance_painter.project.save(substance_painter.project.ProjectSaveMode.Incremental) + +# Create a template from the project: +substance_painter.project.save_as_template( + "c:/Documents/Adobe/Substance 3D Painter/assets/templates/template.spt", + "DefaultMaterial") + +``` + + + + + + +substance_painter.project.needs_saving() → bool +Check if the current project needs to be saved. + + + +Raises: +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.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(*mode: [ProjectSaveMode](#substance_painter.project.ProjectSaveMode "substance_painter.project.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*](#substance_painter.project.ProjectSaveMode "substance_painter.project.ProjectSaveMode")) – The save mode (Incremental or Full). + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If Substance 3D Painter cannot save the project. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. + + + + + +See also + + +[`ProjectSaveMode`](#substance_painter.project.ProjectSaveMode "substance_painter.project.ProjectSaveMode"), +[`save_as()`](#substance_painter.project.save_as "substance_painter.project.save_as"), +[`save_as_copy()`](#substance_painter.project.save_as_copy "substance_painter.project.save_as_copy"). +[`is_busy()`](#substance_painter.project.is_busy "substance_painter.project.is_busy"). + + + + + + +substance_painter.project.save_as(*project_file_path: str*, *mode: [ProjectSaveMode](#substance_painter.project.ProjectSaveMode "substance_painter.project.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*](#substance_painter.project.ProjectSaveMode "substance_painter.project.ProjectSaveMode")) – The save mode (Incremental or Full). + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If Substance 3D Painter cannot save the project. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. + + + + + +See also + + +[`ProjectSaveMode`](#substance_painter.project.ProjectSaveMode "substance_painter.project.ProjectSaveMode"), +[`save()`](#substance_painter.project.save "substance_painter.project.save"), +[`save_as_copy()`](#substance_painter.project.save_as_copy "substance_painter.project.save_as_copy"). +[`is_busy()`](#substance_painter.project.is_busy "substance_painter.project.is_busy"). + + + + + + +substance_painter.project.save_as_copy(*backup_file_path: str*, *mode: [ProjectSaveMode](#substance_painter.project.ProjectSaveMode "substance_painter.project.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*](#substance_painter.project.ProjectSaveMode "substance_painter.project.ProjectSaveMode")) – The save mode (Incremental or Full). + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If Substance 3D Painter cannot save the copy. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. + + + + + +See also + + +[`ProjectSaveMode`](#substance_painter.project.ProjectSaveMode "substance_painter.project.ProjectSaveMode"), +[`save()`](#substance_painter.project.save "substance_painter.project.save"), +[`save_as()`](#substance_painter.project.save_as "substance_painter.project.save_as"). +[`is_busy()`](#substance_painter.project.is_busy "substance_painter.project.is_busy"). + + + + + + +substance_painter.project.save_as_template(*template_file_path: str*, *texture_set_name: str*) → [ProjectSaveMode](#substance_painter.project.ProjectSaveMode "substance_painter.project.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**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If Substance 3D Painter cannot save the template. +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. + + + + + +See also + + +[`is_busy()`](#substance_painter.project.is_busy "substance_painter.project.is_busy"). + + + + + + + +------ + + +*class* substance_painter.project.ProjectSaveMode(*value*) +Save strategy enumeration. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `Full` | Save everything in a new file. Slow but creates the smallest possible file. | +| `Incremental` | Save only new or modified data. Fast but the file size is not optimal. | + + + + + +Reloading a mesh +---------------- + + + +Example: +```python +import substance_painter.project + +# Declare the settings for the new mesh loading: +mesh_reloading_settings = substance_painter.project.MeshReloadingSettings( + import_cameras=True, + preserve_strokes=True) + +# Function that will be called when reloading is finished: +def on_mesh_reload(status: substance_painter.project.ReloadMeshStatus): + import substance_painter.project + if status == substance_painter.project.ReloadMeshStatus.SUCCESS: + print("The mesh was reloaded successfully.") + else: + print("The mesh couldn't be reloaded.") + +# Reload the current mesh: +substance_painter.project.reload_mesh( + 'c:/Documents/my_mesh.fbx', + mesh_reloading_settings, + on_mesh_reload) + +``` + + + + + + +substance_painter.project.reload_mesh(*mesh_file_path: str*, *settings: [MeshReloadingSettings](#substance_painter.project.MeshReloadingSettings "substance_painter.project.MeshReloadingSettings")*, *loading_status_cb: Callable[[[ReloadMeshStatus](#substance_painter.project.ReloadMeshStatus "substance_painter.project.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, usd. +* **settings** ([*MeshReloadingSettings*](#substance_painter.project.MeshReloadingSettings "substance_painter.project.MeshReloadingSettings")) – Configuration options for the mesh loading. +* **loading_status_cb** (*Callable**[**[*[*ReloadMeshStatus*](#substance_painter.project.ReloadMeshStatus "substance_painter.project.ReloadMeshStatus")*]**,* *Any**]*) – Loading status notification callback. + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened or Substance 3D Painter is busy. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. + + + + + +See also + + +[`ReloadMeshStatus`](#substance_painter.project.ReloadMeshStatus "substance_painter.project.ReloadMeshStatus"), +[`MeshReloadingSettings`](#substance_painter.project.MeshReloadingSettings "substance_painter.project.MeshReloadingSettings"), +[`is_busy()`](#substance_painter.project.is_busy "substance_painter.project.is_busy"), +[Project creation documentation](https://www.adobe.com/go/painter-project-creation). + + + + + + +substance_painter.project.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**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. + + + + + + + + +------ + + +*class* substance_painter.project.MeshReloadingSettings(*import_cameras: bool = True*, *preserve_strokes: bool = True*, *usd_settings: [UsdSettings](#substance_painter.project.UsdSettings "substance_painter.project.UsdSettings") | None = None*) +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()`](#substance_painter.project.reload_mesh "substance_painter.project.reload_mesh"), +[Project configuration documentation](https://www.adobe.com/go/painter-project-configuration). + + + + + +import_cameras*: bool* *= True* +Import cameras from the mesh file. + + + + + +preserve_strokes*: bool* *= True* +Preserve strokes positions on mesh. + + + + + +usd_settings*: [UsdSettings](#substance_painter.project.UsdSettings "substance_painter.project.UsdSettings")* *= None* +Specific settings for USD files. + + + + + + + +------ + + +*class* substance_painter.project.ReloadMeshStatus(*value*) +Reload mesh status, used in mesh reload asynchronous callback. + + + +See also + + +[`reload_mesh()`](#substance_painter.project.reload_mesh "substance_painter.project.reload_mesh"), + + + + + +ERROR *= 2* +Mesh reload failed, see application log for details. + + + + + +SUCCESS *= 0* +Mesh reload was successful. + + + + + + +Project metadata +---------------- + + + +> +> + + +------ + +> +> *class* substance_painter.project.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 class `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 +> +> +> +> ```python +> import substance_painter +> +> # Instantiate the Metadata utility, for the plugin "MyPlugin". +> metadata = substance_painter.project.Metadata("MyPlugin") +> +> # Store a version number under the key "version". +> plugin_version = { "major": 1, "minor": 0 } +> metadata.set("version", plugin_version) +> +> # List the project's metadata keys. The key "version" is now present. +> keys = metadata.list() +> print(keys) +> +> # Retrieve the metadata "version". +> plugin_version = metadata.get("version") +> print("Version: " + str(plugin_version)) +> +> ``` +> +> +> +> +> list() → list +> Return the list of project metadata keys. +> +> +> +> Raises: +> * [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +> +> +> +> +> +> +> +> 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**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * **RuntimeError** – If the metadata under `key` use a type that is not supported. +> * [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +> +> +> +> +> +> +> +> 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**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * **RuntimeError** – If `value` uses a type that is not supported. +> * [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.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`](event.html#module-substance_painter.event "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 +Event triggered when an existing project has been opened. + + + + + + +------ + + +*class* substance_painter.event.ProjectCreated +Event triggered when a new project has been created. + + + + + + +------ + + +*class* substance_painter.event.ProjectAboutToClose +Event triggered just before closing the current project. + + + + + + +------ + + +*class* substance_painter.event.ProjectAboutToSave(*file_path: str*) +Event triggered just before saving the current project. + + + + +file_path*: str* +The destination file. + + + +Type: +str + + + + + + + + + +------ + + +*class* substance_painter.event.ProjectSaved +Event triggered once the current project is saved. + + + + + + +------ + + +*class* substance_painter.event.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 +Event triggered when the current project can non longer be edited. + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/properties.md b/src/pages/api/substance_painter/properties.md new file mode 100644 index 0000000..dd26653 --- /dev/null +++ b/src/pages/api/substance_painter/properties.md @@ -0,0 +1,220 @@ +--- +title: properties - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +properties module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +properties module +================= + + +The `properties` module introduces the description of dynamic attributes. + + + + + +------ + + +*class* substance_painter.properties.Property(*handle: _substance_painter.data_tweak.PythonTweak*) +Read only access to a property data. + + + + +value() → bool | int | Tuple[int, int] | Tuple[int, int, int] | Tuple[int, int, int, int] | float | Tuple[float, float] | Tuple[float, float, float] | Tuple[float, float, float, float] | str +Get the current porperty value. + + + +Returns: +the current value. + + + +Return type: +PropertyValue + + + + + + + +name() → str +Get the porperty name. + + + +Returns: +The property name. + + + +Return type: +str + + + + + + + +short_name() → str +Get the shortened property name. + + + +Returns: +The property short name. + + + +Return type: +str + + + + + + + +label() → str +Get the property label. + + + +Returns: +The property label. + + + +Return type: +str + + + + + + + +widget_type() → str +Get the widget type that should be used to edit the property. + + + +Returns: +One of: ‘Slider’, ‘Angle’, ‘Color’, ‘Togglebutton’, +‘Combobox’, ‘RandomSeed’, ‘File’, ‘FileList’, ‘LineEdit’, +‘Resource’, ‘TextEdit’. + + + +Return type: +str + + + + + + + +enum_values() → Dict[str, int] +The possible enum values with corresponding text for ‘Combobox’ +widget type. + + + +Returns: +Enum label to enum value dictionary. + + + +Return type: +*Dict*[str, int] + + + + + + + +enum_value(*enum_label: str*) → int +Get the enum value for the given enum label for ‘Combobox’ +widget type. + + + +Parameters: +**enum_label** (*str*) – A valid enum label. + + + +Returns: +The enum value for the corresponding label. + + + +Return type: +*Dict*[str, int] + + + + + + + +properties() → Dict[str, Any] +Get a json object that describes all available meta properties of this +property. For example: value range, editor step, possible values, tooltip, etc. + + + +Returns: +A json object. + + + +Return type: +*Dict*[str, *Any*] + + + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/resource.md b/src/pages/api/substance_painter/resource.md new file mode 100644 index 0000000..8b089c1 --- /dev/null +++ b/src/pages/api/substance_painter/resource.md @@ -0,0 +1,1871 @@ +--- +title: resource - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +resource module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +resource module +=============== + + +This module allows to manipulate Substance 3D Painter resources and shelves. + + +Substance 3D Painter treats textures, materials, brushes, etc. as resources, +and uses URLs to identify them. Resources can be in the shelf, or can be +embedded directly in a project (like a baked ambient occlusion texture for +example). + + + + + +------ + + +*class* substance_painter.resource.Type(*value*) +Enumeration describing the type of a given resource. + + +Members: + + + + +| Name | Usage | +| --- | --- | +| `SCRIPT` | A particle emitter script. | +| `PRESET` | A resource preset. | +| `SMART_MASK` | A smart mask. | +| `IMAGE` | An image. | +| `SUBSTANCE` | A substance. | +| `SHADER` | A shader. | +| `EXPORT` | An export preset. | +| `SMART_MATERIAL` | A smart material. | +| `BRUSH` | A brush. | +| `RESOURCE` | A resource. | +| `SUBSTANCE_PACKAGE` | A substance package. | +| `ABR_PACKAGE` | A photoshop brushes package. | + + + + +Overview +-------- + + + +### Manipulating resources + + +The resource module exposes the class [`Resource`](#substance_painter.resource.Resource "substance_painter.resource.Resource"), which represents a +resource currently available in Substance 3D Painter (either in the current +project, current session, or in a shelf). + + +Listing all the resources of a shelf can be done with [`Shelf.resources()`](#substance_painter.resource.Shelf.resources "substance_painter.resource.Shelf.resources"), +while [`search()`](#substance_painter.resource.search "substance_painter.resource.search") allows to search for specific resources. Specific resources +can be shown with a filter directly in the Assets window with +[`Resource.show_in_ui()`](#substance_painter.resource.Resource.show_in_ui "substance_painter.resource.Resource.show_in_ui") and [`show_resources_in_ui()`](#substance_painter.resource.show_resources_in_ui "substance_painter.resource.show_resources_in_ui"). + + + +> +> +> ```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) +> +> ``` +> +> +> + + +Internally, resources are identified with a URL; [`ResourceID`](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") contains +that URL. It can be manipulated directly, with no guaranty that the URL is +referring to an actual resource. + + + +> +> +> ```python +> import substance_painter.resource +> +> # Display the URL of a resource: +> envmap_resources = substance_painter.resource.search("bonifacio") +> for envmap in envmap_resources: +> envmap_id = envmap.identifier() +> print("The URL of the resource `{0}` is {1}" +> .format(envmap_id.name, envmap_id.url())) +> print("The location of the resource `{0}` is {1}" +> .format(envmap_id.name, envmap_id.location())) +> +> # It is possible to create a ResourceID from a URL. If there is no +> # resource corresponding to the URL, the ResourceID is still valid +> # but refers to a resource that doesn't exist. +> envmap2_id = substance_painter.resource.ResourceID.from_url( +> "resource://starter_assets/Bonifacio Street"); +> +> # It is possible to create a ResourceID from a context, a name and +> # a version (optional). This is equivalent to the above, with the +> # same caveat. +> envmap3_id = substance_painter.resource.ResourceID( +> context="starter_assets", name="Bonifacio Street") +> envmap4_id = substance_painter.resource.ResourceID( +> context="starter_assets", name="Bonifacio Street", +> version="d30facd8d860fc212f864065641cdca4e8006510.image"); +> +> # It is possible to get the ResourceID of a resource embedded in the +> # current project. This time it refers to an actual resource. +> envmap5_id = substance_painter.resource.ResourceID.from_project( +> name="Bonifacio Street"); +> +> # Finally, it is possible to get the ResourceID of a resource that +> # was imported in the current session: +> envmap6_id = substance_painter.resource.ResourceID.from_session( +> name="Bonifacio Street"); +> +> ``` +> +> +> + + +If the resource exists, it can be retrieved from its identifier with +[`Resource.retrieve()`](#substance_painter.resource.Resource.retrieve "substance_painter.resource.Resource.retrieve"). When there are several versions of the same resource, +[`Resource.retrieve()`](#substance_painter.resource.Resource.retrieve "substance_painter.resource.Resource.retrieve") will return the entire list, starting with the most +recent one. On the contrary, if the resource doesn’t exist or was deleted, +[`Resource.retrieve()`](#substance_painter.resource.Resource.retrieve "substance_painter.resource.Resource.retrieve") will return an empty list. + + + +> +> +> ```python +> import substance_painter.resource +> +> # Create a ResourceID: +> envmap_id = substance_painter.resource.ResourceID(context="starter_assets", +> name="Bonifacio Street") +> +> # Get the resources corresponding to the ResourceID. There can be 0 if there +> # is no such resource, or more than 1 if there are multiple versions of the +> # resource. +> envmap_resources = substance_painter.resource.Resource.retrieve(envmap_id) +> print("{} resource(s) with that ID".format(len(envmap_resources))) +> +> ``` +> +> +> + + + + +### Importing resources + + +New resources can be imported, either +to the current project with [`import_project_resource()`](#substance_painter.resource.import_project_resource "substance_painter.resource.import_project_resource"), +to the current session with [`import_session_resource()`](#substance_painter.resource.import_session_resource "substance_painter.resource.import_session_resource"), +or to a shelf with [`Shelf.import_resource()`](#substance_painter.resource.Shelf.import_resource "substance_painter.resource.Shelf.import_resource"). +All three functions take a path to the resource to be imported, a [`Usage`](#substance_painter.resource.Usage "substance_painter.resource.Usage") +indicating the type of that resource, and optionally a name and a group. +This feature corresponds to the “Import resources” window. + + +Resources can be imported into a shelf, as long as it is not a read-only shelf. +The Substance shelf, installed along the application, is read-only. +A shelf is also read-only if its path on the file system is read-only. +This can be checked with [`Shelf.can_import_resources()`](#substance_painter.resource.Shelf.can_import_resources "substance_painter.resource.Shelf.can_import_resources"). + + + +Example: +```python +import substance_painter.resource + +# Open a project we want to import into (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") + +# Import a normal map to the project: +new_resource = substance_painter.resource.import_project_resource( + "C:/textures/MyBakedNormalMap.png", + substance_painter.resource.Usage.TEXTURE) + +# Import a color LUT to the session: +new_color_lut = substance_painter.resource.import_session_resource( + "C:/textures/sepia.exr", + substance_painter.resource.Usage.COLOR_LUT) + +# Set that color LUT (see substance_painter.display for details). +# This step is unrelated to import, and just meant to show how the +# imported resource can be used. +import substance_painter.display +substance_painter.display.set_color_lut_resource(new_color_lut.identifier()) + +# Import an environment map to the shelf. +my_shelf = substance_painter.resource.Shelf("myshelf") +if my_shelf.can_import_resources(): + new_resource = my_shelf.import_resource( + "C:/textures/Bonifacio Street.exr", + substance_painter.resource.Usage.ENVIRONMENT) +else: + print("The shelf is read-only.") + +``` + + + +See also:[Adding content via the import window](https://www.adobe.com/go/painter-adding-content-import-window). + + + + + + +### Resources used by a project + + +It is possible to list the resources used by the layer stacks and mesh maps of +a project with [`list_layer_stack_resources()`](#substance_painter.resource.list_layer_stack_resources "substance_painter.resource.list_layer_stack_resources"), and to update them with +[`update_layer_stack_resource()`](#substance_painter.resource.update_layer_stack_resource "substance_painter.resource.update_layer_stack_resource"). + + +There may be other resources referenced by a project outside of the layer +stack and mesh maps: see the [`substance_painter.display`](display.html#module-substance_painter.display "substance_painter.display") module to +query and modify them. + + + +Example: +```python +import substance_painter.resource + +# Open a project we want to manipulate resources from (see +# substance_painter.project for details). This step is not necessary +# if there is already a project opened in Substance Painter. +import substance_painter.project +substance_painter.project.open("C:/projects/MeetMat.spp") + +# List all the resources referenced by all the layer stacks and +# mesh maps: +used_resources_ids = substance_painter.resource.list_layer_stack_resources() +for resource_id in used_resources_ids: + print(resource_id.name) + +# Import a normal map to the project: +new_resource = substance_painter.resource.import_project_resource( + "C:/textures/MyBakedNormalMap.png", + substance_painter.resource.Usage.TEXTURE) + +# Replace one of the resources with the new imported resource: +substance_painter.resource.update_layer_stack_resource(used_resources_ids[0], new_resource) + +``` + + + + + + +### Custom preview + + +When a resource is imported, a thumbnail is automatically generated for it. +It is possible to replace that thumbnail with a custom preview by using +[`Resource.set_custom_preview()`](#substance_painter.resource.Resource.set_custom_preview "substance_painter.resource.Resource.set_custom_preview"), or reset the preview with +[`Resource.reset_preview()`](#substance_painter.resource.Resource.reset_preview "substance_painter.resource.Resource.reset_preview"). + + + +Example: +```python +import substance_painter.resource + +aluminium_resources = substance_painter.resource.search("aluminium") +resource = aluminium_resources[0] + +# Set the custom preview: +resource.set_custom_preview("C:/textures/MyCustomPreview.png") + +# Remove the custom preview: +resource.reset_preview() + +``` + + + + + + +### Resource crawling + + +When Substance 3D Painter is opened, it will browse the different shelves +to discover and index resources, and display their thumbnail. When it regains +focus after switching to another application, it will do so again, in case +the user added a new asset to their shelf folder. This process is referred +to as **resource crawling**. + + +When a shelf starts crawling, an event +[`substance_painter.event.ShelfCrawlingStarted`](event.html#substance_painter.event.ShelfCrawlingStarted "substance_painter.event.ShelfCrawlingStarted") is emitted for that +shelf. When crawling is finished, an event +[`substance_painter.event.ShelfCrawlingEnded`](event.html#substance_painter.event.ShelfCrawlingEnded "substance_painter.event.ShelfCrawlingEnded") is emitted for that +shelf. At any time, [`Shelf.is_crawling()`](#substance_painter.resource.Shelf.is_crawling "substance_painter.resource.Shelf.is_crawling") will tell if a shelf is +crawling or not. + + +It is possible from a Python script to explicitly trigger a new resource +crawling with [`Shelves.refresh_all()`](#substance_painter.resource.Shelves.refresh_all "substance_painter.resource.Shelves.refresh_all"). + + + +Example: +```python +import substance_painter.resource +import substance_painter.event + +# Two event handlers to show when crawling starts and ends: +def on_start_crawl(e): + print("Shelf `{}` started crawling.".format(e.shelf_name)) + +def on_end_crawl(e): + print("Shelf `{}` finished crawling.".format(e.shelf_name)) + +# Use the event handler to listen to ShelfCrawlingStarted and +# ShelfCrawlingEnded: +substance_painter.event.DISPATCHER.connect( + substance_painter.event.ShelfCrawlingStarted, + on_start_crawl) + +substance_painter.event.DISPATCHER.connect( + substance_painter.event.ShelfCrawlingEnded, + on_end_crawl) + +# At this point, the event handlers may or may not print something, +# depending on what the shelves are doing. It is possible to trigger +# a crawling by switching to another application, and coming back +# to Substance 3D Painter. + +# It is also possible to trigger a crawling with this call: +substance_painter.resource.Shelves.refresh_all() + +my_shelf = substance_painter.resource.Shelf("myshelf") + +# Running this bloc at different moments will give different +# results: +if my_shelf.is_crawling(): + print("The shelf is crawling...") +else: + print("The shelf is idle.") + +``` + + + + + + + +Resources +--------- + + + + + +------ + + +*class* substance_painter.resource.Resource(*handle: _substance_painter.resource.ResourceHandle*) +A Substance 3D Painter resource. + + + + +identifier() → [ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") +Get this resource identifier. + + + +Returns: +The resource identifier. + + + +Return type: +[ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") + + + +Raises: +**RuntimeError** – If the resource is invalid. + + + + + +See also + + +[`ResourceID`](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID"). + + + + + + +location() → [ResourceLocation](#substance_painter.resource.ResourceLocation "substance_painter.resource.ResourceLocation") +Get the location of this Resource. + + + +Returns: +The location of this resource. + + + +Return type: +[ResourceLocation](#substance_painter.resource.ResourceLocation "substance_painter.resource.ResourceLocation") + + + +Raises: +**RuntimeError** – If the resource is invalid. + + + + + + + +*static* retrieve(*identifier: [ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")*) +Retrieve a list of resources matching the given identifier. + + + +Parameters: +**identifier** ([*ResourceID*](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")) – A resource identifier. + + + +Raises: +* **ValueError** – If the name of the identifier is empty + or if the context of the identifier doesn’t exists. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + +Returns: +The list of resources matching the given identifier. +If the identifier has a valid version, this method will return only one or +zero resources, otherwise the list may contain several resources. In case +of several resources are returned, the most up to date resource will be at +the begining of the list. + + + +Return type: +*List*[[Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource")] + + + + + + + +set_custom_preview(*preview_image: str*) → None +Replace the current preview of this resource with a custom image. + + + +Parameters: +**preview_image** (*str*) – File path to an image on the disk to use as the new +preview. + + + +Raises: +* **ValueError** – If the resource metadata cannot be modified. +* **ValueError** – If `preview_image` is not a valid path to a valid image. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +Note + + +The preview image can be a JPEG, a PNG or an XPM. + + + + + + +category() → str +Get the category of this resource, ex: “wood” for a material. + + + +Raises: +**RuntimeError** – If the resource is invalid. + + + +Returns: +the category of this resource + + + +Return type: +str + + + + + + + +usages() → List[[Usage](#substance_painter.resource.Usage "substance_painter.resource.Usage")] +Get the usages of this resource. + + + +Raises: +**RuntimeError** – If the resource is invalid. + + + +Returns: +the usages of this resource + + + +Return type: +*List*[[Usage](#substance_painter.resource.Usage "substance_painter.resource.Usage")] + + + + + +See also + + +[`Usage`](#substance_painter.resource.Usage "substance_painter.resource.Usage") + + + + + + +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](#substance_painter.resource.Type "substance_painter.resource.Type") +Get the type of this resource. + + + +Raises: +**RuntimeError** – If the resource is invalid. + + + +Returns: +the type of this resource + + + +Return type: +[Type](#substance_painter.resource.Type "substance_painter.resource.Type") + + + + + +See also + + +[`Type`](#substance_painter.resource.Type "substance_painter.resource.Type") + + + + + + +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() → 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() → List[[Resource](#substance_painter.resource.Resource "substance_painter.resource.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](#substance_painter.resource.Resource "substance_painter.resource.Resource")] + + + + + + + +parent() → [Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource") | None +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](#substance_painter.resource.Resource "substance_painter.resource.Resource")] + + + + + + + +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**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +show_in_ui() → None +Highlight this resource in the application shelf UI (Assets window). + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[`show_resources_in_ui()`](#substance_painter.resource.show_resources_in_ui "substance_painter.resource.show_resources_in_ui"). + + + + + + + + +------ + + +*class* substance_painter.resource.ResourceID(*context: str*, *name: str*, *version: str | None = None*) +A Substance 3D Painter resource identifier. + + +The resource is identified by a context, a name, and a version. The context +and the name are mandatory while the version is optional. The version is a +string that looks like a hash, and may also contain an extension. + + + +Note + + +A ResourceID object is only an identifier. It provides no guarantees that +the resource actually exists. + + + + +See also + + +[`substance_painter.display`](display.html#module-substance_painter.display "substance_painter.display"). + + + + + +*classmethod* from_project(*name: str*, *version: str | None = None*) +Create a ResourceID object for a resource located in the current project. + + + +Parameters: +* **name** (*str*) – The resource name. +* **version** (*str**,* *optional*) – The resource version (hash-like string). + + + +Returns: +The resource corresponding to the given name. + + + +Return type: +[ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") + + + + + + + +*classmethod* from_session(*name: str*, *version: str | None = None*) +Create a ResourceID object for a resource located in the current session. + + + +Parameters: +* **name** (*str*) – The resource name. +* **version** (*str**,* *optional*) – The resource version (hash-like string). + + + +Returns: +The resource corresponding to the given name. + + + +Return type: +[ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") + + + + + + + +*classmethod* from_url(*url: str*) +Create a ResourceID object from its URL. +URLs must have `resource://` as a scheme. The version is encoded as a query +string, that looks like a hash. + + +A resource URL looks like this: + + +`resource://context/name?version=0123456789abcdef0123456789abcdef01234567.image` + + + +Parameters: +**url** (*str*) – The resource URL. + + + +Returns: +The resource corresponding to the given URL. + + + +Return type: +[ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") + + + +Raises: +* **ValueError** – If `url` is not a valid URL. +* **ValueError** – If the URL scheme is not `resource://`. +* **ValueError** – If the resource name is invalid. + + + + + + + +location() → [ResourceLocation](#substance_painter.resource.ResourceLocation "substance_painter.resource.ResourceLocation") +Get the location of this ResourceID. + + + +Returns: +The location of this resource. + + + +Return type: +[ResourceLocation](#substance_painter.resource.ResourceLocation "substance_painter.resource.ResourceLocation") + + + + + + + +url() → str +Get the URL form of this ResourceID. + + + +Returns: +The URL of the resource. + + + +Return type: +str + + + +Raises: +* **ValueError** – If the ResourceID doesn’t have a context. +* **ValueError** – If the ResourceID doesn’t have a name. + + + + + + + +context*: str* +Context of the resource. + + + +Type: +str + + + + + + + +name*: str* +Name of the resource. + + + +Type: +str + + + + + + + +version*: str* *= None* +Hash identifying the version of the resource. + + + +Type: +str + + + + + + + + + +------ + + +*class* substance_painter.resource.ResourceLocation(*value*) +Each resource has a location determined by where its data lives. + + +Members: + + + + +| Name | Data location | +| --- | --- | +| `SESSION` | Current session; those ressources will be lost after a restart of the application. | +| `PROJECT` | A Substance 3D Painter project; those resources are embedded in the spp file. | +| `SHELF` | One of the Substance 3D Painter Shelves. | + + +Example + + + +```python +import substance_painter.resource + +# For a resource from the default shelf +aluminium = substance_painter.resource.ResourceID( + context="starter_assets", name="Aluminium Insulator"); + +# This will print: +# ResourceLocation.SHELF +print(aluminium.location()) + +# For an embedded resource, like a baked map +aomap = substance_painter.resource.ResourceID.from_project( + name="ambient_occlusion"); + +# This will print: +# ResourceLocation.PROJECT +print(aomap.location()) + +# Finally, for a temporary resource +test_envmap = substance_painter.resource.ResourceID.from_session( + name="Test Envmap"); + +# This will print: +# ResourceLocation.SESSION +print(test_envmap.location()) + +``` + + + + + + +------ + + +*class* substance_painter.resource.StandardQuery +Standard resource queries. + + +Members: + + + + +| Name | Query | +| --- | --- | +| `ALL_RESOURCES` | All resources. | +| `PROJECT_RESOURCES` | Resources that belongs to the current project. | +| `SESSION_RESOURCES` | Resources that belongs to the current session. | +| `SHELVES_RESOURCES` | All shelves resources. | + + + +See also + + +[`search()`](#substance_painter.resource.search "substance_painter.resource.search"). + + + + + + + +------ + + +*class* substance_painter.resource.Usage(*value*) +Enumeration describing how a given resource is meant to be used. + + +Members: + + + + +| Name | Usage | +| --- | --- | +| `BASE_MATERIAL` | A material. | +| `ENVIRONMENT` | An environment map. | +| `ALPHA` | A brush alpha. | +| `TEXTURE` | A UV space map like bakes. | +| `FILTER` | A layer stack filter. | +| `EMITTER` | A particle emitter script. | +| `RECEIVER` | A particle receiver script. | +| `PROCEDURAL` | A procedural substance, like a noise. | +| `BRUSH` | A brush definition. | +| `PARTICLE` | A particles effect. | +| `TOOL` | A painting tool preset. | +| `SHADER` | A shader. | +| `EXPORT` | An export preset. | +| `GENERATOR` | A mask generator. | +| `SMART_MATERIAL` | A smart material. | +| `SMART_MASK` | A smart mask. | +| `COLOR_LUT` | A color look-up table. | + + + +See also + + +[`import_project_resource()`](#substance_painter.resource.import_project_resource "substance_painter.resource.import_project_resource"), +[`import_session_resource()`](#substance_painter.resource.import_session_resource "substance_painter.resource.import_session_resource"), +[`Shelf.import_resource()`](#substance_painter.resource.Shelf.import_resource "substance_painter.resource.Shelf.import_resource"). + + + + + + +substance_painter.resource.search(*query: str*) → List[[Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource")] +List Substance 3D Painter resources that match the given query. + + + +Parameters: +**query** (*str*) – A resource query string. See [text query documentation](https://www.adobe.com/go/painter-filtering-shelf-content). + + + +Returns: +The list of resources that match the given query. + + + +Return type: +List[[Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource")] + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[`StandardQuery`](#substance_painter.resource.StandardQuery "substance_painter.resource.StandardQuery"). + + + + + + +substance_painter.resource.list_layer_stack_resources() → List[[ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")] +List the resources referenced by the layer stacks and mesh maps of the current +project. + + + +Returns: +The list of resource identifiers referenced. + + + +Return type: +List[[ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")] + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[`update_layer_stack_resource()`](#substance_painter.resource.update_layer_stack_resource "substance_painter.resource.update_layer_stack_resource"), +[`substance_painter.display`](display.html#module-substance_painter.display "substance_painter.display"). + + + + + + +substance_painter.resource.update_layer_stack_resource(*old_resource_id: [ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")*, *new_resource: [Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource")*) → List[[ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")] +Replace resources from the layer stacks and mesh maps in the current project. + + +Given a resource identifier, replace any resource having the same identifier +with the new resource. The new resource must be compatible with the ones it +replaces (see note); otherwise, an error is thrown. + + + +Note + + +The new resource must be of the same type as the resources it replaces. +For example a base material resource cannot be updated with a smart +material resource. + + +Moreover: + + +* If the resource is a Substance material, it must have the same number +and names of outputs. +* If the resource is a Substance filter, it must have the same number +and names of inputs and outputs. + + + + +Returns: +The list of identifiers of all the resources that have +been replaced. + + + +Return type: +List[[ResourceID](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")] + + + +Parameters: +* **old_resource_id** ([*ResourceID*](#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")) – The identifier of the resource(s) to update. +* **new_resource** ([*Resource*](#substance_painter.resource.Resource "substance_painter.resource.Resource")) – The new resource to use instead. + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* **TypeError** – If `old_resource_id` is not a ResourceID. +* **TypeError** – If `new_resource` is not a Resource. +* **RuntimeError** – If `new_resource` is not a valid resource. +* **RuntimeError** – If `new_resource` cannot be used in place of + `old_resource_id`. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[`list_layer_stack_resources()`](#substance_painter.resource.list_layer_stack_resources "substance_painter.resource.list_layer_stack_resources"), +[`Usage`](#substance_painter.resource.Usage "substance_painter.resource.Usage"), +[`substance_painter.display`](display.html#module-substance_painter.display "substance_painter.display"). + + + + + + +substance_painter.resource.import_project_resource(*file_path: str*, *resource_usage: [Usage](#substance_painter.resource.Usage "substance_painter.resource.Usage")*, *name: str | None = None*, *group: str | None = None*) → [Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource") +Import a resource into the current opened project. + + + +Parameters: +* **file_path** (*str*) – The file path to the resource to be imported. +* **resource_usage** ([*Usage*](#substance_painter.resource.Usage "substance_painter.resource.Usage")) – The resource usage. +* **name** (*str**,* *optional*) – The name of the resource if different from the +file name. +* **group** (*str**,* *opional*) – An optional group name, can be used in resource +queries. + + + +Returns: +The imported resource object. + + + +Return type: +[Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource") + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* **ValueError** – If parameters validation failed. +* **RuntimeError** – If import failed. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +substance_painter.resource.import_session_resource(*file_path: str*, *resource_usage: [Usage](#substance_painter.resource.Usage "substance_painter.resource.Usage")*, *name: str | None = None*, *group: str | None = None*) → [Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource") +Import a resource into the current session. + + + +Parameters: +* **file_path** (*str*) – The file path to the resource to be imported. +* **resource_usage** ([*Usage*](#substance_painter.resource.Usage "substance_painter.resource.Usage")) – The resource usage. +* **name** (*str**,* *optional*) – The name of the resource if different from the +file name. +* **group** (*str**,* *opional*) – An optional group name, can be used in resource +queries. + + + +Returns: +The imported resource object. + + + +Return type: +[Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource") + + + +Raises: +* **ValueError** – If parameters validation failed. +* **RuntimeError** – If import failed. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +substance_painter.resource.show_resources_in_ui(*resources: List[[Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource")]*) → None +Highlight a list of resources in the application shelf UI (Assets window). + + + +Parameters: +**resources** (*List**[*[*Resource*](#substance_painter.resource.Resource "substance_painter.resource.Resource")*]*) – Resources to highlight + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[`Resource.show_in_ui()`](#substance_painter.resource.Resource.show_in_ui "substance_painter.resource.Resource.show_in_ui"). + + + + + + +Shelves +------- + + + +See also:[Shelf configuration](https://www.adobe.com/go/painter-shelf-configuration). + + + + + + + +------ + + +*class* substance_painter.resource.Shelf(*_name: str*) +Class providing information on a given Substance 3D Painter shelf. A shelf +is identified by a unique name. + + + + +can_import_resources() → bool +Check if resources can be imported into this shelf. +Resources can be imported into a shelf, as long as it is not a read-only shelf. +The Substance shelf, installed along the application, is read-only. A shelf is +also read-only if its path on the file system is read-only. + + + +Returns: +`True` if resources can be imported. + + + +Return type: +bool + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[`substance_painter.event.ShelfCrawlingEnded`](event.html#substance_painter.event.ShelfCrawlingEnded "substance_painter.event.ShelfCrawlingEnded"). + + + + + + +import_resource(*file_path: str*, *resource_usage: [Usage](#substance_painter.resource.Usage "substance_painter.resource.Usage")*, *name: str | None = None*, *group: str | None = None*, *uuid: str | None = None*) → [Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource") +Import a resource into this shelf. + + + +Parameters: +* **file_path** (*str*) – The file path to the resource to be imported. +* **resource_usage** ([*Usage*](#substance_painter.resource.Usage "substance_painter.resource.Usage")) – The resource usage. +* **name** (*str**,* *optional*) – The name of the resource if different from the +file name. +* **group** (*str**,* *opional*) – An optional group name, can be used in resource +queries. +* **uuid** (*str**,* *opional*) – An optional uuid. If a resource already exists with +the same uuid, it will be replaced. + + + +Returns: +The imported resource object. + + + +Return type: +[Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource") + + + +Raises: +* **ValueError** – If parameters validation failed. +* **RuntimeError** – If import failed. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +is_crawling() → bool +Check if this shelf is currently discovering resources in folders. + + + +Returns: +`True` if this shelf is discovering resources, `False` otherwise. + + + +Return type: +bool + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[`substance_painter.event.ShelfCrawlingEnded`](event.html#substance_painter.event.ShelfCrawlingEnded "substance_painter.event.ShelfCrawlingEnded"). + + + + + + +name() → str + +Returns: +The shelf name. +Each shelf is identified by a unique name. + + + + + + + +path() → str + +Returns: +The associated path + + + +Raises: +* **ValueError** – If the shelf doesn’t exist anymore. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +resources(*query: str = ''*) → List[[Resource](#substance_painter.resource.Resource "substance_painter.resource.Resource")] +Get resources contained in this shelf. An optional query string can be given +to narrow the results. + + + +Parameters: +**query** (*str**,* *optional*) – A resource query string. + + + +Returns: +This shelf’s list of resources. + + + + + +See also + + +[`search()`](#substance_painter.resource.search "substance_painter.resource.search"). + + + + + + + + +------ + + +*class* substance_painter.resource.Shelves +Collection of static methods to manipulate shelves. + + + + +*static* add(*name: str*, *path: str*) → [Shelf](#substance_painter.resource.Shelf "substance_painter.resource.Shelf") +Add a new shelf. This shelf will only be valid during the application session. +The shelf will not be visible from application general settings menu. + + + +Parameters: +* **name** (*str*) – Name of the new shelf. This name must be unique and must only +contain lowercase letters, numbers, underscores or hyphens. +Use [`Shelves.exists()`](#substance_painter.resource.Shelves.exists "substance_painter.resource.Shelves.exists") to check if name is already used. +* **path** (*str*) – Folder path to monitor. + + + +Returns: +Newly added shelf. + + + +Return type: +[Shelf](#substance_painter.resource.Shelf "substance_painter.resource.Shelf") + + + +Raises: +* **ValueError** – If `name` or `str` are invalid. See logs for details. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[`Shelves.exists()`](#substance_painter.resource.Shelves.exists "substance_painter.resource.Shelves.exists"). + + + + + + +*static* all() → List[[Shelf](#substance_painter.resource.Shelf "substance_painter.resource.Shelf")] +List all shelves. + + + +Returns: +List of existing shelves. + + + +Return type: +*List*[[Shelf](#substance_painter.resource.Shelf "substance_painter.resource.Shelf")] + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +*static* application_shelf() → [Shelf](#substance_painter.resource.Shelf "substance_painter.resource.Shelf") +This is the shelf containing the default content shipped with the application. + + + + + +*static* exists(*name: str*) → bool +Tell whether a shelf with the given name exists. + + + +Parameters: +**name** (*str*) – Shelf name to searh for. + + + +Returns: +`True` if a shelf with the given name exists. + + + +Return type: +bool + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +*static* refresh_all() +Forces discovering of resources in all shelves folders. +Discovering is also done automatically when the application window gets focus. + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + + + +*static* remove(*name: str*) +Removes a shelf. +No project must be opened. +Deleting a shelf which was not created by the Python API is not possible and +will raise an exception. + + + +Parameters: +**name** (*str*) – Name of the shelf to delete. +Use [`Shelves.exists()`](#substance_painter.resource.Shelves.exists "substance_painter.resource.Shelves.exists") to check if a shelf exists. + + + +Raises: +* [**ProjectError**](exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If a project is opened. +* **ValueError** – If the shelf doesn’t exist. +* **ValueError** – If the shelf was not created with the Python API. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[`Shelves.exists()`](#substance_painter.resource.Shelves.exists "substance_painter.resource.Shelves.exists"). + + + + + + +*static* user_shelf() → [Shelf](#substance_painter.resource.Shelf "substance_painter.resource.Shelf") +This is the shelf located in the user Documents folder where new resources +are created by default. The user can select a different default shelf in the +settings, and this will be reflected when using this function. + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its + services yet. + + + + + +See also + + +[Default shelf documentation](https://docs.substance3d.com/spdoc/shelf-configuration-124059665.html). + + + + + + + +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`](event.html#module-substance_painter.event "substance_painter.event") for more details. + + + + + +------ + + +*class* substance_painter.event.ShelfCrawlingStarted(*shelf_name: str*) +Event triggered when a shelf starts reading the file system to discover +new resources. + + + +See also + + +`Shelf.is_crawling()`. + + + + + +shelf_name*: str* +Name of the shelf discovering resources. + + + +Type: +str + + + + + + + + + +------ + + +*class* substance_painter.event.ShelfCrawlingEnded(*shelf_name: str*) +Event triggered when a shelf has finished discovering new resources and +loading their thumbnails. + + + +See also + + +`Shelf.is_crawling()`. + + + + + +shelf_name*: str* +Name of the shelf that has finished discovering resources. + + + +Type: +str + + + + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/textureset/channel.md b/src/pages/api/substance_painter/textureset/channel.md new file mode 100644 index 0000000..0240ad6 --- /dev/null +++ b/src/pages/api/substance_painter/textureset/channel.md @@ -0,0 +1,250 @@ +--- +title: channel - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +Channel class — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +Channel class +============= + + + +> +> + + +------ + +> +> *class* substance_painter.textureset.Channel(*channel_id: int | None = None*) +> A Substance 3D Painter channel. +> +> +> A channel can be one of the predefined types (BaseColor, Specular, Roughness, +> etc.) or a user defined type (User0 to User7), corresponding to the material. +> The channel belongs to a stack. The stack can have one or more of them, but it +> can have only one channel of each [`ChannelType`](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType"). +> +> +> Example +> +> +> +> ```python +> import substance_painter.textureset +> +> # Get the unnamed stack of "TextureSetName": +> paintable_stack = substance_painter.textureset.Stack.from_name("TextureSetName") +> +> # Get the channel "BaseColor" of that stack: +> base_color_channel = paintable_stack.get_channel( +> substance_painter.textureset.ChannelType.BaseColor) +> +> # Print the color format and bit depth of the base color channel: +> print("The channel format uses {0} {1}.".format( +> "RGB" if base_color_channel.is_color() else "L", +> base_color_channel.bit_depth())) +> +> # Change the format and bit depth of the base color channel: +> base_color_channel.edit( +> channel_format = substance_painter.textureset.ChannelFormat.RGB16) +> +> ``` +> +> +> +> +> format() → [ChannelFormat](index.html#substance_painter.textureset.ChannelFormat "substance_painter.textureset.ChannelFormat") +> Get the channel format. The format indicates both if the channel is color +> or grayscale, its dynamic range, its bits per component, and if the storage +> is linear or sRGB. +> +> +> +> Returns: +> This channel format. +> +> +> +> Return type: +> [ChannelFormat](index.html#substance_painter.textureset.ChannelFormat "substance_painter.textureset.ChannelFormat") +> +> +> +> +> +> +> +> label() → str +> Get the user label for User channels (User0 to User7). +> +> +> +> Returns: +> This channel user label. This is the empty string for non User channels. +> +> +> +> Return type: +> str +> +> +> +> +> +> See also +> +> +> [`Channel.type()`](#substance_painter.textureset.Channel.type "substance_painter.textureset.Channel.type"), +> [`ChannelType`](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType"). +> +> +> +> +> +> +> is_color() → bool +> Check if the channel is in color or grayscale format. +> +> +> +> Returns: +> `True` if the channel format is a color format. +> +> +> +> Return type: +> bool +> +> +> +> +> +> +> +> is_floating() → bool +> Check if the channel is in floating point or normalized fixed point format. +> +> +> +> Returns: +> `True` if the channel format is a floating point format. +> +> +> +> Return type: +> bool +> +> +> +> +> +> +> +> bit_depth() → int +> Get the number of bits per component. +> +> +> +> Returns: +> The channel bit depth per component. +> +> +> +> Return type: +> int +> +> +> +> +> +> +> +> type() → [ChannelType](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType") +> Get the channel type. +> +> +> +> Returns: +> This channel type. +> +> +> +> Return type: +> [ChannelType](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType") +> +> +> +> +> +> See also +> +> +> [`Channel.label()`](#substance_painter.textureset.Channel.label "substance_painter.textureset.Channel.label"). +> +> +> +> +> +> +> edit(*channel_format: [ChannelFormat](index.html#substance_painter.textureset.ChannelFormat "substance_painter.textureset.ChannelFormat")*, *label: str | None = None*) → None +> Change the channel format and label. +> +> +> +> Parameters: +> * **channel_format** ([*ChannelFormat*](index.html#substance_painter.textureset.ChannelFormat "substance_painter.textureset.ChannelFormat")) – The new texture format of the channel. +> * **label** (*str**,* *optional*) – Label of the channel in case of User channel as type. +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * **ValueError** – If there is no stack labeled `stack_id` in this Texture Set. +> * **ValueError** – If there is no channel of type `channel_type` in this Texture Set. +> * **ValueError** – If a label was provided but `channel_type` is not a user type. +> Standard channel types have fixed labels. +> * **ValueError** – If the channel is invalid. +> +> +> +> +> +> +> + + + + + + + + + + diff --git a/src/pages/api/substance_painter/textureset/stack.md b/src/pages/api/substance_painter/textureset/stack.md new file mode 100644 index 0000000..9ec26e5 --- /dev/null +++ b/src/pages/api/substance_painter/textureset/stack.md @@ -0,0 +1,505 @@ +--- +title: stack - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +Stack class — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +Stack class +=========== + + + +> +> + + +------ + +> +> *class* substance_painter.textureset.Stack(*stack_id: int | None = None*) +> A Substance 3D Painter paintable stack. +> +> +> A stack can contain a number of channels (BaseColor, Specular, Roughness, +> etc.), that correspond to the material. The stack belongs to a Texture Set, +> which may contain one or more stacks. +> +> +> Typically, only one stack is used and that stack is transparent to the user. +> Selecting the Texture Set will select its stack. However, a Texture Set can +> use layered materials with custom shaders, in which case a specific stack +> needs to be selected. +> +> +> If the Texture Set doesn’t use material layering, you can retrieve its stack +> as follows: +> +> +> +> ```python +> import substance_painter.textureset +> +> # Get the unnamed stack of "TextureSetName": +> paintable_stack = substance_painter.textureset.Stack.from_name("TextureSetName") +> +> # Alternatively, get the stack from a Texture Set instance: +> my_texture_set = substance_painter.textureset.TextureSet.from_name("TextureSetName") +> paintable_stack = my_texture_set.get_stack() +> +> ``` +> +> +> If the Texture Set does use material layering, you can retrieve its stacks +> as follows: +> +> +> +> ```python +> import substance_painter.textureset +> +> # Get the stack called "Mask1" from the Texture Set "TextureSetName": +> paintable_stack = substance_painter.textureset.Stack.from_name("TextureSetName", +> "Mask1") +> +> # Alternatively, get the stack from a Texture Set instance: +> my_texture_set = substance_painter.textureset.TextureSet.from_name("TextureSetName") +> paintable_stack = my_texture_set.get_stack("Mask1") +> +> # Show the name of the stack: +> print(paintable_stack.name()) +> +> ``` +> +> +> It is possible to query, add, remove or edit the channels of a stack: +> +> +> +> ```python +> import substance_painter.textureset +> +> # Get the unnamed stack of "TextureSetName": +> paintable_stack = substance_painter.textureset.Stack.from_name("TextureSetName") +> +> # List all the channels of the "TextureSetName" Texture Set: +> for k,v in paintable_stack.all_channels().items(): +> print("{0}: {1}".format(k, str(v.format()))) +> +> # Add a scattering channel to the "TextureSetName" Texture Set: +> paintable_stack.add_channel(substance_painter.textureset.ChannelType.Scattering, +> substance_painter.textureset.ChannelFormat.L8) +> +> # Query details of the added scattering channel: +> if paintable_stack.has_channel(substance_painter.textureset.ChannelType.Scattering): +> channel = paintable_stack.get_channel( +> substance_painter.textureset.ChannelType.Scattering) +> print("The Texture Set now has a scattering channel with {0} bits per pixel." +> .format(channel.bit_depth())) +> +> # Change the scattering channel to 16 bits inside the "TextureSetName" Texture Set: +> paintable_stack.edit_channel( +> channel_type = substance_painter.textureset.ChannelType.Scattering, +> channel_format = substance_painter.textureset.ChannelFormat.L16) +> +> # Remove the scattering channel from "TextureSetName": +> paintable_stack.remove_channel(substance_painter.textureset.ChannelType.Scattering) +> +> ``` +> +> +> +> See also +> +> +> [`TextureSet`](textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet"), +> [Texture Set documentation](https://www.adobe.com/go/painter-texture-set). +> +> +> +> +> +> *static* from_name(*texture_set_name: str*, *stack_name: str = ''*) +> Get a stack from its name. +> +> +> +> Parameters: +> * **texture_set_name** (*str*) – Texture Set name. +> * **stack_name** (*str*) – Stack name. +> Leave empty if the Texture Set does not use material layering. +> +> +> +> +> +> Note +> +> +> The Texture Set and stack names are case sensitive. +> +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +> * **ValueError** – If `texture_set_name` is not string. +> * **ValueError** – If there is no Texture Set with the name `texture_set_name`. +> * **ValueError** – If there is no stack with the name `stack_name`. +> +> +> +> +> +> See also +> +> +> [`TextureSet.all_stacks()`](textureset.html#substance_painter.textureset.TextureSet.all_stacks "substance_painter.textureset.TextureSet.all_stacks"), +> [`TextureSet.get_stack()`](textureset.html#substance_painter.textureset.TextureSet.get_stack "substance_painter.textureset.TextureSet.get_stack"). +> +> +> +> +> +> +> 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**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +> * **ValueError** – If the stack is invalid. +> +> +> +> +> +> +> +> material() +> Get the Texture Set this stack belongs to. +> +> +> +> Returns: +> The Texture Set this stack belongs to. +> +> +> +> Return type: +> [TextureSet](textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet") +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +> * **ValueError** – If the stack is invalid. +> +> +> +> +> +> See also +> +> +> [`TextureSet`](textureset.html#substance_painter.textureset.TextureSet "substance_painter.textureset.TextureSet"), +> [`all_texture_sets()`](index.html#substance_painter.textureset.all_texture_sets "substance_painter.textureset.all_texture_sets"). +> +> +> +> +> +> +> all_channels() → Dict[[ChannelType](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType"), [Channel](channel.html#substance_painter.textureset.Channel "substance_painter.textureset.Channel")] +> List all the channels of a stack. +> +> +> +> Returns: +> Map of all the channels of the stack. +> +> +> +> Return type: +> dict[[ChannelType](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType"), [Channel](channel.html#substance_painter.textureset.Channel "substance_painter.textureset.Channel")] +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +> +> +> +> +> +> See also +> +> +> [`Stack.add_channel()`](#substance_painter.textureset.Stack.add_channel "substance_painter.textureset.Stack.add_channel"), +> [`Stack.remove_channel()`](#substance_painter.textureset.Stack.remove_channel "substance_painter.textureset.Stack.remove_channel"). +> +> +> +> +> +> +> add_channel(*channel_type: [ChannelType](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")*, *channel_format: [ChannelFormat](index.html#substance_painter.textureset.ChannelFormat "substance_painter.textureset.ChannelFormat")*, *label: str | None = None*) → [Channel](channel.html#substance_painter.textureset.Channel "substance_painter.textureset.Channel") +> Add a new channel to a stack. +> +> +> +> Note +> +> +> add_channel is not available with material layering. +> +> +> +> +> Parameters: +> * **channel_type** ([*ChannelType*](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")) – The channel type. +> * **channel_format** ([*ChannelFormat*](index.html#substance_painter.textureset.ChannelFormat "substance_painter.textureset.ChannelFormat")) – The texture format of the new channel. +> * **label** (*str**,* *optional*) – The label of the channel in case of User channel as type. +> +> +> +> Returns: +> The created channel. +> +> +> +> Return type: +> [Channel](channel.html#substance_painter.textureset.Channel "substance_painter.textureset.Channel") +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * **ValueError** – If a channel of type `channel_type` already exists in this Texture Set. +> * **ValueError** – If a label was provided but `channel_type` is not a user type. +> Standard channel types have fixed labels. +> * **ValueError** – If the stack is invalid. +> * **ValueError** – If the Texture Set uses material layering. +> +> +> +> +> +> See also +> +> +> [`Stack.all_channels()`](#substance_painter.textureset.Stack.all_channels "substance_painter.textureset.Stack.all_channels"), +> [`Stack.remove_channel()`](#substance_painter.textureset.Stack.remove_channel "substance_painter.textureset.Stack.remove_channel"), +> [`Stack.edit_channel()`](#substance_painter.textureset.Stack.edit_channel "substance_painter.textureset.Stack.edit_channel"). +> +> +> +> +> +> +> remove_channel(*channel_type: [ChannelType](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")*) → None +> Remove a channel from a stack. +> +> +> +> Note +> +> +> remove_channel is not available with material layering. +> +> +> +> +> Parameters: +> **channel_type** ([*ChannelType*](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")) – The channel type. +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * **ValueError** – If there is no channel of type `channel_type` in this Texture Set. +> * **ValueError** – If the stack is invalid. +> * **ValueError** – If the Texture Set uses material layering. +> +> +> +> +> +> See also +> +> +> [`Stack.all_channels()`](#substance_painter.textureset.Stack.all_channels "substance_painter.textureset.Stack.all_channels"), +> [`Stack.add_channel()`](#substance_painter.textureset.Stack.add_channel "substance_painter.textureset.Stack.add_channel"), +> [`Stack.edit_channel()`](#substance_painter.textureset.Stack.edit_channel "substance_painter.textureset.Stack.edit_channel"). +> +> +> +> +> +> +> edit_channel(*channel_type: [ChannelType](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")*, *channel_format: [ChannelFormat](index.html#substance_painter.textureset.ChannelFormat "substance_painter.textureset.ChannelFormat")*, *label: str | None = None*) → None +> Change the texture format and label of a channel. +> +> +> +> Parameters: +> * **channel_type** ([*ChannelType*](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")) – The channel type. +> * **channel_format** ([*ChannelFormat*](index.html#substance_painter.textureset.ChannelFormat "substance_painter.textureset.ChannelFormat")) – The new texture format of the channel. +> * **label** (*str**,* *optional*) – The label of the channel in case of User channel as type. +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * **ValueError** – If there is no stack labeled `stack_id` in this Texture Set. +> * **ValueError** – If there is no channel of type `channel_type` in this Texture Set. +> * **ValueError** – If a label was provided but `channel_type` is not a user type. +> Standard channel types have fixed labels. +> * **ValueError** – If the stack is invalid. +> +> +> +> +> +> See also +> +> +> [`Stack.add_channel()`](#substance_painter.textureset.Stack.add_channel "substance_painter.textureset.Stack.add_channel"), +> [`Stack.remove_channel()`](#substance_painter.textureset.Stack.remove_channel "substance_painter.textureset.Stack.remove_channel"). +> +> +> +> +> +> +> has_channel(*channel_type: [ChannelType](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")*) → bool +> Check if a channel exists in a stack. +> +> +> +> Parameters: +> **channel_type** ([*ChannelType*](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")) – The channel type. +> +> +> +> Returns: +> `True` if the stack has a channel of the given type, `False` otherwise. +> +> +> +> Return type: +> bool +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * **ValueError** – If the stack is invalid. +> +> +> +> +> +> See also +> +> +> [`Stack.add_channel()`](#substance_painter.textureset.Stack.add_channel "substance_painter.textureset.Stack.add_channel"), +> [`Stack.remove_channel()`](#substance_painter.textureset.Stack.remove_channel "substance_painter.textureset.Stack.remove_channel"). +> +> +> +> +> +> +> get_channel(*channel_type: [ChannelType](index.html#substance_painter.textureset.ChannelType "substance_painter.textureset.ChannelType")*) → [Channel](channel.html#substance_painter.textureset.Channel "substance_painter.textureset.Channel") +> Get an existing channel from its type. +> +> +> +> Parameters: +> **channel_type** ([*Channel*](channel.html#substance_painter.textureset.Channel "substance_painter.textureset.Channel")) – The channel type. +> +> +> +> Returns: +> The channel. +> +> +> +> Return type: +> [Channel](channel.html#substance_painter.textureset.Channel "substance_painter.textureset.Channel") +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +> * **ValueError** – If the channel doesn’t exists. +> +> +> +> +> +> See also +> +> +> [`Stack.has_channel()`](#substance_painter.textureset.Stack.has_channel "substance_painter.textureset.Stack.has_channel"), +> [`Stack.add_channel()`](#substance_painter.textureset.Stack.add_channel "substance_painter.textureset.Stack.add_channel"), +> [`Stack.remove_channel()`](#substance_painter.textureset.Stack.remove_channel "substance_painter.textureset.Stack.remove_channel"). +> +> +> +> +> +> + + + + + + + + + + diff --git a/src/pages/api/substance_painter/textureset/textureset.md b/src/pages/api/substance_painter/textureset/textureset.md new file mode 100644 index 0000000..99ce54b --- /dev/null +++ b/src/pages/api/substance_painter/textureset/textureset.md @@ -0,0 +1,633 @@ +--- +title: textureset - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +TextureSet class — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +TextureSet class +================ + + + + + +------ + + +*class* substance_painter.textureset.TextureSet(*material_id: int*) +A Substance 3D Painter Texture Set. A Texture Set has a resolution and a +number of stacks, and can be layered or not. +It optionally also has a number of UV Tiles. + + +It uses a set of baked Mesh map textures. Each Mesh map has a defined MeshMapUsage. + + +If the corresponding material is not layered, the Texture Set has just one +stack, which is transparent to the user. If the material is layered, the +Texture Set has several stacks. + + +Example + + + +```python +import substance_painter.textureset + +# Get the Texture Set "TextureSetName": +my_texture_set = substance_painter.textureset.TextureSet.from_name("TextureSetName") + +# Show the resolution of the Texture Set: +resolution = my_texture_set.get_resolution() +print("The resolution is {0}x{1}".format(resolution.width, resolution.height)) + +# Change the resolution of the Texture Set: +my_texture_set.set_resolution(substance_painter.textureset.Resolution(512, 512)) + +# Show information about layering: +if my_texture_set.is_layered_material(): + print("{0} is a layered material".format(my_texture_set.name())) + + # Get the stack called "Mask1" from the Texture Set: + mask_stack = my_texture_set.get_stack("Mask1") + + # Print "TextureSetName/Mask1": + print(mask_stack) + +else: + print("{0} is not a layered material".format(my_texture_set.name())) + +# Show information about UV Tiles: +if my_texture_set.has_uv_tiles(): + print("{0} has UV Tiles:".format(my_texture_set.name())) + for tile in my_texture_set.all_uv_tiles(): + print("Tile {0} {1}".format(tile.u, tile.v)) + +# List all the stacks of the Texture Set "TextureSetName": +for stack in my_texture_set.all_stacks(): + print(stack) + +# Query ambiant occlusion Mesh map of the Texture Set "TextureSetName": +usage = substance_painter.textureset.MeshMapUsage.AO +meshMapResource = my_texture_set.get_mesh_map_resource(usage) + +if meshMapResource is None : + print("{0} does not have a Mesh map defined for usage {1}" + .format(my_texture_set.name(), usage)) +else: + print("{0} uses {1} Mesh map for usage {2}" + .format(my_texture_set.name(), meshMapResource, usage)) + +# Unset ambiant occlusion Mesh map of the Texture Set "TextureSetName": +my_texture_set.set_mesh_map_resource(usage, None) + +``` + + + +See also + + +[`Stack`](stack.html#substance_painter.textureset.Stack "substance_painter.textureset.Stack"), +[`UVTile`](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile"), +[`MeshMapUsage`](index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage"), +[Texture Set documentation](https://www.adobe.com/go/painter-texture-set). + + + + + +*static* from_name(*texture_set_name: str*) +Get the Texture Set from its name. + + + +Parameters: +**texture_set_name** (*str*) – The name of the Texture Set. + + + + + +Note + + +The Texture Set name is case sensitive. + + + + +Raises: +* [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* **TypeError** – If `texture_set_name` is missing or not a string. +* **ValueError** – If `texture_set_name` is empty. +* **ValueError** – If there is no Texture Set with the name `texture_set_name`. + + + + + + + +name() → str +Get the Texture Set name. + + + +Returns: +The name of the Texture Set. + + + +Return type: +str + + + +Raises: +* [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* **ValueError** – If the Texture Set is invalid. + + + + + + + +is_layered_material() → bool +Query if this Texture Set uses material layering. + + + +Returns: +`True` if the Texture Set uses material layering, `False` otherwise. + + + +Return type: +bool + + + +Raises: +* [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* **ValueError** – If the Texture Set is invalid. + + + + + + + +all_stacks() → List[[Stack](stack.html#substance_painter.textureset.Stack "substance_painter.textureset.Stack")] +List all the stacks from this Texture Set. + + + +Returns: +All the stacks of this Texture Set. + + + +Return type: +list[[Stack](stack.html#substance_painter.textureset.Stack "substance_painter.textureset.Stack")] + + + +Raises: +* [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* **ValueError** – If the Texture Set is invalid. + + + + + +See also + + +[`TextureSet.get_stack()`](#substance_painter.textureset.TextureSet.get_stack "substance_painter.textureset.TextureSet.get_stack"). + + + + + + +get_stack(*stack_name: str = ''*) → [Stack](stack.html#substance_painter.textureset.Stack "substance_painter.textureset.Stack") +Get a stack of this Texture Set from its name. + + + +Parameters: +**stack_name** (*str*) – The stack name. +Leave empty if the Texture Set does not use material layering. + + + + + +Note + + +The stack name is case sensitive. + + + + +Returns: +The stack. + + + +Return type: +[Stack](stack.html#substance_painter.textureset.Stack "substance_painter.textureset.Stack") + + + +Raises: +* [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* **ValueError** – If the Texture Set is invalid. + + + + + +See also + + +[`TextureSet.all_stacks()`](#substance_painter.textureset.TextureSet.all_stacks "substance_painter.textureset.TextureSet.all_stacks"). + + + + + + +get_resolution() → [Resolution](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution") +Get the Texture Set resolution. + + + +Returns: +The resolution of this Texture Set in pixels. + + + +Return type: +[Resolution](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution") + + + +Raises: +* [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* **ValueError** – If the Texture Set is invalid. + + + + + +See also + + +[`TextureSet.set_resolution()`](#substance_painter.textureset.TextureSet.set_resolution "substance_painter.textureset.TextureSet.set_resolution"), +[`set_resolutions()`](index.html#substance_painter.textureset.set_resolutions "substance_painter.textureset.set_resolutions"). + + + + + + +set_resolution(*new_resolution: [Resolution](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution")*) +Set the resolution of the Texture Set. + + +See resolution restrictions: [`Resolution`](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution"). + + + +Note + + +For any Texture Set, you can find its accepted resolutions in the +“Texture Set Settings” window, in the “Size” menu. + + + + +Parameters: +**new_resolution** ([*Resolution*](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution")) – The new resolution for this Texture Set. + + + +Raises: +* [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started all its services yet. +* **ValueError** – If `new_resolution` is not a valid resolution. +* **ValueError** – If the Texture Set is invalid. + + + + + +See also + + +[`TextureSet.get_resolution()`](#substance_painter.textureset.TextureSet.get_resolution "substance_painter.textureset.TextureSet.get_resolution"), +[`set_resolutions()`](index.html#substance_painter.textureset.set_resolutions "substance_painter.textureset.set_resolutions"). + + + + + + +has_uv_tiles() → bool +Check if the Texture Set uses the UV Tiles workflow. + + + +Returns: +`True` if the Texture Set uses the UV Tiles workflow, `False` otherwise. + + + +Return type: +bool + + + +Raises: +[**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + +See also + + +[`all_uv_tiles()`](#substance_painter.textureset.TextureSet.all_uv_tiles "substance_painter.textureset.TextureSet.all_uv_tiles") + + + + + + +uv_tile(*u_coord: int*, *v_coord: int*) → [UVTile](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile") +Get the Texture Set UV Tile at (u, v) coordinates. + + + +Parameters: +* **u_coord** (*int*) – The u coordinate of the UV Tile. +* **v_coord** (*int*) – The v coordinate of the UV Tile. + + + +Returns: +The Texture Set UV Tile at (u, v) coordinate. + + + +Return type: +[UVTile](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile") + + + +Raises: +[**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + + + +all_uv_tiles() → List[[UVTile](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")] +Get the list of the Texture Set UV Tiles, ordered by U then V coordinates. + + + +Returns: +List of the Texture Set UV Tiles, ordered by U then V coordinates. + + + +Return type: +*List*[[UVTile](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")] + + + +Raises: +[**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + +See also + + +[`has_uv_tiles()`](#substance_painter.textureset.TextureSet.has_uv_tiles "substance_painter.textureset.TextureSet.has_uv_tiles") + + + + + + +get_uvtiles_resolution() → Dict[[UVTile](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile"), [Resolution](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution")] +Get all UV Tiles that have a different resolution from the Texture Set, associated +to their effective resolution. + + + +Returns: +The dictionary of uvtiles and their associated resolution. + + + +Return type: +*Dict*[[UVTile](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile"), [Resolution](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution")] + + + +Raises: +[**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + +See also + + +[`UVTile.get_resolution()`](uvtile.html#substance_painter.textureset.UVTile.get_resolution "substance_painter.textureset.UVTile.get_resolution") + + + + + + +set_uvtiles_resolution(*resolutions: Dict[[UVTile](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile"), [Resolution](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution")]*) +Set the resolution of the given UV Tiles to the associated resolution. + + + +Parameters: +**resolutions** (*Dict**[*[*UVTile*](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")*,* [*Resolution*](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution")*]*) – The dictionary of UV Tiles +and their associated resolution. + + + +Raises: +[**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + +See also + + +[`UVTile.set_resolution()`](uvtile.html#substance_painter.textureset.UVTile.set_resolution "substance_painter.textureset.UVTile.set_resolution") + + + + + + +reset_uvtiles_resolution(*uvtiles: List[[UVTile](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")]*) +Reset the resolution of the given UV Tiles to the parent Texture Set’s resolution. + + + +Parameters: +**uvtiles** (*List**[*[*UVTile*](uvtile.html#substance_painter.textureset.UVTile "substance_painter.textureset.UVTile")*]*) – The list of UV Tiles to be reset. + + + +Raises: +[**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. + + + + + +See also + + +[`UVTile.reset_resolution()`](uvtile.html#substance_painter.textureset.UVTile.reset_resolution "substance_painter.textureset.UVTile.reset_resolution") + + + + + + +all_mesh_names() → List[str] +Get the list of meshes of the Texture Set. +When using UV Tiles, the result is the union of the mesh names of every UV Tiles. + + + +Raises: +* [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +* [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance Painter has not started all its services yet. + + + + + +See also + + +[`UVTile.all_mesh_names()`](uvtile.html#substance_painter.textureset.UVTile.all_mesh_names "substance_painter.textureset.UVTile.all_mesh_names") + + + + + + +get_mesh_map_resource(*usage: [MeshMapUsage](index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*) → [ResourceID](../resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") | None +Query the Mesh map for the given usage of the Texture Set. + + + +Parameters: +**usage** ([*MeshMapUsage*](index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")) – Which Mesh map usage is queried. + + + +Returns: +The Mesh map resource or None. + + + +Return type: +[ResourceID](../resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") + + + + + + + +set_mesh_map_resource(*usage: [MeshMapUsage](index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")*, *new_mesh_map: [ResourceID](../resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID") | None*) → None +Replace the Mesh map for the given usage of the Texture Set. + + + +Parameters: +* **usage** ([*MeshMapUsage*](index.html#substance_painter.textureset.MeshMapUsage "substance_painter.textureset.MeshMapUsage")) – Which Mesh map usage to replace. +* **new_mesh_map** ([*ResourceID*](../resource.html#substance_painter.resource.ResourceID "substance_painter.resource.ResourceID")*,* *optional*) – The new Mesh map or None to unset. + + + +Raises: +* [**ResourceNotFoundError**](../exception.html#substance_painter.exception.ResourceNotFoundError "substance_painter.exception.ResourceNotFoundError") – If the resource `new_mesh_map` is not found or is not of type + IMAGE. +* **ValueError** – If the resource is already used for another Mesh map usage for the + Texture Set. + + + + + + + + + + + + + + diff --git a/src/pages/api/substance_painter/textureset/uvtile.md b/src/pages/api/substance_painter/textureset/uvtile.md new file mode 100644 index 0000000..4900565 --- /dev/null +++ b/src/pages/api/substance_painter/textureset/uvtile.md @@ -0,0 +1,249 @@ +--- +title: uvtile - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +UVTile class — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + + +UVTile class +============ + + + +> +> + + +------ + +> +> *class* substance_painter.textureset.UVTile(*u: int*, *v: int*, *_material_id: int*) +> A UV Tile coordinates. +> +> +> +> +> u +> The U coordinate of the UV Tile. +> +> +> +> Type: +> int +> +> +> +> +> +> +> +> v +> The V coordinate of the UV Tile. +> +> +> +> Type: +> int +> +> +> +> +> +> +> See also +> +> +> [`TextureSet.all_uv_tiles()`](textureset.html#substance_painter.textureset.TextureSet.all_uv_tiles "substance_painter.textureset.TextureSet.all_uv_tiles") +> +> +> +> +> +> get_resolution() → [Resolution](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution") +> Get the UV Tile resolution. +> +> +> +> Returns: +> The resolution of this UV Tile in pixels. +> +> +> +> Return type: +> [Resolution](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution") +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance Painter has not started all its services yet. +> * **ValueError** – If the UV Tile is invalid. +> +> +> +> +> +> Note +> +> +> The time complexity of this function is linear in the number of UV Tiles in the parent +> Texture Set. If you need to process multiple UV Tiles, please see +> `TextureSet.get_uvtiles_resolution`. +> +> +> +> +> See also +> +> +> [`UVTile.set_resolution()`](#substance_painter.textureset.UVTile.set_resolution "substance_painter.textureset.UVTile.set_resolution") +> [`UVTile.reset_resolution()`](#substance_painter.textureset.UVTile.reset_resolution "substance_painter.textureset.UVTile.reset_resolution") +> [`TextureSet.get_uvtiles_resolution()`](textureset.html#substance_painter.textureset.TextureSet.get_uvtiles_resolution "substance_painter.textureset.TextureSet.get_uvtiles_resolution"), +> +> +> +> +> +> +> set_resolution(*new_resolution: [Resolution](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution")*) +> Set the resolution of the UV Tile. +> +> +> See resolution restrictions: [`Resolution`](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution"). +> +> +> +> Parameters: +> **new_resolution** ([*Resolution*](index.html#substance_painter.textureset.Resolution "substance_painter.textureset.Resolution")) – The new resolution for this UV Tile. +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance Painter has not started all its services yet. +> * **ValueError** – If `new_resolution` is not square. +> * **ValueError** – If `new_resolution` is not a valid resolution. +> * **ValueError** – If the UV Tile is invalid. +> +> +> +> +> +> Note +> +> +> The time complexity of this function is linear in the number of UVTiles in the parent +> Texture Set. If you need to process multiple UVTiles, please see +> `TextureSet.set_uvtiles_resolution`. +> +> +> +> +> See also +> +> +> [`UVTile.get_resolution()`](#substance_painter.textureset.UVTile.get_resolution "substance_painter.textureset.UVTile.get_resolution"), +> [`UVTile.reset_resolution()`](#substance_painter.textureset.UVTile.reset_resolution "substance_painter.textureset.UVTile.reset_resolution"), +> [`TextureSet.set_resolution()`](textureset.html#substance_painter.textureset.TextureSet.set_resolution "substance_painter.textureset.TextureSet.set_resolution"), +> [`TextureSet.set_uvtiles_resolution()`](textureset.html#substance_painter.textureset.TextureSet.set_uvtiles_resolution "substance_painter.textureset.TextureSet.set_uvtiles_resolution"), +> +> +> +> +> +> +> reset_resolution() +> Reset the resolution of the UV Tile to match the parent Texture Set. +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance Painter has not started all its services yet. +> * **ValueError** – If the UV Tile is invalid. +> +> +> +> +> +> Note +> +> +> The time complexity of this function is linear in the number of UVTiles in the parent +> Texture Set. If you need to process multiple UVTiles, please see +> `TextureSet.reset_uvtiles_resolution`. +> +> +> +> +> See also +> +> +> [`UVTile.get_resolution()`](#substance_painter.textureset.UVTile.get_resolution "substance_painter.textureset.UVTile.get_resolution"), +> [`UVTile.set_resolution()`](#substance_painter.textureset.UVTile.set_resolution "substance_painter.textureset.UVTile.set_resolution"), +> [`TextureSet.reset_uvtiles_resolution()`](textureset.html#substance_painter.textureset.TextureSet.reset_uvtiles_resolution "substance_painter.textureset.TextureSet.reset_uvtiles_resolution"), +> +> +> +> +> +> +> all_mesh_names() → List[str] +> Get the list of meshes of the UV Tile. +> +> +> +> Raises: +> * [**ProjectError**](../exception.html#substance_painter.exception.ProjectError "substance_painter.exception.ProjectError") – If no project is opened. +> * [**ServiceNotFoundError**](../exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance Painter has not started all its services yet. +> * **ValueError** – If the UV Tile is invalid. +> +> +> +> +> +> See also +> +> +> [`TextureSet.all_mesh_names()`](textureset.html#substance_painter.textureset.TextureSet.all_mesh_names "substance_painter.textureset.TextureSet.all_mesh_names") +> +> +> +> +> +> + + + + + + + + + + diff --git a/src/pages/api/substance_painter/ui.md b/src/pages/api/substance_painter/ui.md new file mode 100644 index 0000000..9d8f1de --- /dev/null +++ b/src/pages/api/substance_painter/ui.md @@ -0,0 +1,430 @@ +--- +title: ui - Painter Python API +description: Substance 3D Painter - Python API +keywords: + - Creative Cloud + - API Documentation + - Substance 3D + - Painter +--- + + + + + + +ui module — Substance 3D Painter Python API 0.2.11 documentation + + + + + + + + + + + + + + + +ui module +========= + + +Entry points to customize Substance 3D Painter UI. + + + + + +------ + + +*class* substance_painter.ui.UIMode(*value*) +UI configurations enumeration. + + +Members: + + + + +| Name | Value | Description | +| --- | --- | --- | +| `Edition` | `1` | Project edition mode | +| `Visualisation` | `2` | (Iray) mode | +| `Baking` | `4` | Baking mode | + + + + + + +------ + + +*class* substance_painter.ui.ApplicationMenu(*value*) +Standard application menus enumeration. + + +Members: + + + + +| Name | Description | +| --- | --- | +| `File` | File menu | +| `Edit` | Edit menu | +| `Mode` | Mode menu | +| `Window` | Window menu | +| `Viewport` | Viewport menu | +| `Help` | Help menu | + + + + + +substance_painter.ui.show_main_window() +Show Substance 3D Painter main window in the windowing system and give it the focus. + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.get_main_window() → PySide2.QtWidgets.QMainWindow +Get access to Substance 3D Painter main window. + + + +Returns: +The application main window. + + + +Return type: +PySide2.QtWidgets.QMainWindow + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.get_layout(*mode: [UIMode](#substance_painter.ui.UIMode "substance_painter.ui.UIMode")*) → bytes +Get Substance 3D Painter layout state for the given UI mode. + + + +Parameters: +**mode** ([*UIMode*](#substance_painter.ui.UIMode "substance_painter.ui.UIMode")) – Selected UI mode. + + + +Returns: +The layout state. + + + +Return type: +bytes + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.get_layout_mode(*layout: bytes*) → [UIMode](#substance_painter.ui.UIMode "substance_painter.ui.UIMode") +Get the Substance 3D Painter UI layout mode of a given state. + + + +Parameters: +**layout** (*bytes*) – The layout state, obtained with [`get_layout()`](#substance_painter.ui.get_layout "substance_painter.ui.get_layout"). + + + +Returns: +The state associated UI mode. + + + +Return type: +[UIMode](#substance_painter.ui.UIMode "substance_painter.ui.UIMode") + + + +Raises: +* **RuntimeError** – In case of incorrect layout data. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.set_layout(*layout: bytes*) → [UIMode](#substance_painter.ui.UIMode "substance_painter.ui.UIMode") +Restore a Substance 3D Painter layout state optained with [`get_layout()`](#substance_painter.ui.get_layout "substance_painter.ui.get_layout"). + + + +Parameters: +**layout** (*bytes*) – The layout state to be restored. + + + +Returns: +The restored UI mode. + + + +Return type: +[UIMode](#substance_painter.ui.UIMode "substance_painter.ui.UIMode") + + + +Raises: +* **RuntimeError** – In case of incorrect layout data. +* [**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.reset_layout(*mode: [UIMode](#substance_painter.ui.UIMode "substance_painter.ui.UIMode")*) +Reset Substance 3D Painter layout to default for a selected UI mode. + + + +Parameters: +**mode** ([*UIMode*](#substance_painter.ui.UIMode "substance_painter.ui.UIMode")) – Selected UI mode. + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.add_dock_widget(*widget: PySide2.QtWidgets.QWidget*, *ui_modes: int = UIMode.Edition*) → PySide2.QtWidgets.QDockWidget +Add a widget as a QDockWidget to the main window. + + +If the widget has a `windowIcon`, it will be used as a quick button to easily +reopen the QDockWidget when closed. If the widget has a unique `objectName` it +will be used to properly save and restore the dock widget location and geometry. + + + +Parameters: +* **widget** (*PySide2.QtWidgets.QWidget*) – The widget to be added as a dock widget. +* **ui_modes** (*int**,* *optional*) – A combination of UIMode flags. + + + +Returns: +The corresponding dock widget. + + + +Return type: +PySide2.QtWidgets.QDockWidget + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.add_plugins_toolbar_widget(*widget: PySide2.QtWidgets.QWidget*) +Add a widget to the plugins toolbar. + + + +Parameters: +**widget** (*PySide2.QtWidgets.QWidget*) – The widget to be added. + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.add_menu(*menu: PySide2.QtWidgets.QMenu*) +Add the given menu to the application main window. + + + +Parameters: +**menu** (*PySide2.QtWidgets.QMenu*) – The menu to be added. + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.add_toolbar(*title: str*, *object_name: str*, *ui_modes: int = UIMode.Edition*) → PySide2.QtWidgets.QToolBar +Create and add a toolbar to the application main window. + + + +Parameters: +* **title** (*str*) – The title of the toolbar. +* **object_name** (*str*) – The toolbar object name. A unique object name is mandatory for proper +save and restore of the UI layout. +* **ui_modes** (*int*) – A combination of UIMode flags. + + + +Returns: +The newly created toolbar. + + + +Return type: +PySide2.QtWidgets.QToolBar + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.add_action(*menu: [ApplicationMenu](#substance_painter.ui.ApplicationMenu "substance_painter.ui.ApplicationMenu")*, *action: PySide2.QtWidgets.QAction*) +Add the given action to the given application menu. + + +This will clear the action tooltip. + + + +Parameters: +* **menu** ([*ApplicationMenu*](#substance_painter.ui.ApplicationMenu "substance_painter.ui.ApplicationMenu")) – One of the predefined ApplicationMenu. +* **action** (*PySide2.QtWidgets.QAction*) – The action to be added. + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.delete_ui_element(*element: PySide2.QtWidgets.QWidget*) +Delete a UI element. + + +The element passed as parameter is deleted. After that, any attempt to call a +method on `element` will throw an exception. + + + +Parameters: +**element** – The UI element to delete. + + + + + + + +substance_painter.ui.get_current_mode() → [UIMode](#substance_painter.ui.UIMode "substance_painter.ui.UIMode") +Get the current UI mode. + + + +Returns: +The current UI mode. + + + +Return type: +[UIMode](#substance_painter.ui.UIMode "substance_painter.ui.UIMode") + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + +substance_painter.ui.switch_to_mode(*mode: [UIMode](#substance_painter.ui.UIMode "substance_painter.ui.UIMode")*) → None +Switch to some UI mode. + + + +Parameters: +**mode** ([*UIMode*](#substance_painter.ui.UIMode "substance_painter.ui.UIMode")) – UI mode to switch to. + + + +Raises: +[**ServiceNotFoundError**](exception.html#substance_painter.exception.ServiceNotFoundError "substance_painter.exception.ServiceNotFoundError") – If Substance 3D Painter has not started its UI service. + + + + + + + + + + + + + diff --git a/src/pages/guides/creating-python-plugin.md b/src/pages/guides/creating-python-plugin.md index 006c821..2f6599d 100644 --- a/src/pages/guides/creating-python-plugin.md +++ b/src/pages/guides/creating-python-plugin.md @@ -1,5 +1,5 @@ --- -title: creating-python-plugin | Painter Python API +title: creating-python-plugin - Painter Python API description: Substance 3D Painter - Python API keywords: - Creative Cloud diff --git a/src/pages/guides/index.md b/src/pages/guides/index.md index 45b97b8..4bafbd7 100644 --- a/src/pages/guides/index.md +++ b/src/pages/guides/index.md @@ -1,5 +1,5 @@ --- -title: index | Painter Python API +title: index - Painter Python API description: Substance 3D Painter - Python API keywords: - Creative Cloud diff --git a/src/pages/guides/loading-external-plugins.md b/src/pages/guides/loading-external-plugins.md index eec35f4..ed09392 100644 --- a/src/pages/guides/loading-external-plugins.md +++ b/src/pages/guides/loading-external-plugins.md @@ -1,5 +1,5 @@ --- -title: loading-external-plugins | Painter Python API +title: loading-external-plugins - Painter Python API description: Substance 3D Painter - Python API keywords: - Creative Cloud diff --git a/src/pages/guides/using-external-modules.md b/src/pages/guides/using-external-modules.md index 637e15a..9f60005 100644 --- a/src/pages/guides/using-external-modules.md +++ b/src/pages/guides/using-external-modules.md @@ -1,5 +1,5 @@ --- -title: using-external-modules | Painter Python API +title: using-external-modules - Painter Python API description: Substance 3D Painter - Python API keywords: - Creative Cloud