User Guide Cancel

Example Scripts | Substance 3D Sampler

  1. Substance 3D home
  2. Home
  3. Getting Started
    1. Getting Started overview
    2. Activation and licenses
    3. System requirements
    4. Shortcuts
    5. Importing Resources
    6. Report a bug
    7. Project Management
    8. Export
      1. Export overview
      2. Export Window
      3. Default Presets
        1. Default Presets overview
        2. Arnold 5
        3. Blender Cycles/Eevee
        4. Corona Renderer
        5. Enscape - Revit
        6. Keyshot9+
        7. Lens Studio
        8. Spark AR Studio
        9. Unity HDRP Standard
        10. Unity HDRP Specular
        11. Unity Standard
        12. Unity Specular
        13. Unreal Engine 4
        14. Redshift
        15. V-Ray Next
      4. Managing custom presets
      5. Managing Presets
  4. Interface
    1. Interface overview
    2. The Home Screen
    3. 2D and 3D Viewport
    4. Sidebars
    5. Panels
      1. Panels overview
      2. Project panel
      3. Assets panel
      4. Layers panel
      5. Properties panel
      6. Viewer Settings panel
      7. Shader Settings panel
      8. Channel Settings panel
      9. Metadata panel
      10. Export panel
      11. Physical Size Panel
      12. Exposed Parameters Panel
      13. Resources
    6. Tools and Widgets
      1. Tools and Widgets overview
      2. Sliders
      3. Color Picker
    7. Preferences
      1. Preferences overview
      2. Normal Format
      3. Layer Resolution
  5. Filters
    1. Filters overview
    2. Custom Filters
    3. Compound Filters
    4. Generators
      1. Generators overview
      2. Atlas Scatter
      3. Brickwall
      4. Cloth Weave
      5. Decal
      6. Embossing
      7. Embroidery
      8. Floor Tiles
      9. Gravel
      10. Panel
      11. Parquet
      12. Pattern
      13. Pavement
      14. Perforate
      15. Quilt Stitch
      16. Splatter
      17. Stonewall
      18. Surface Relief
      19. Weave
    5. Adjustments
      1. Adjustments overview
      2. Blur
      3. Brightness/Contrast
      4. Colorize
      5. Color Replace
      6. Color Variation
      7. Equalize
      8. Fill
      9. Hue/Saturation
      10. Invert
      11. Sharpen
      12. Vibrance
    6. Tools
      1. Tools overview
      2. Atlas Creator
      3. Atlas Splitter
      4. Channels Generation
      5. Channel Switch
      6. Clone Stamp
      7. Crop tool
      8. Delight (AI Powered)
      9. Height to AO
      10. Height to Normal
      11. Image To Material
      12. Make it Tile
      13. Match
      14. Multiangle To Material
      15. Normal to Height
      16. Paint Wrap *missing*
      17. PBR Validate
      18. Perspective Correction
      19. Tiling
      20. Transform
      21. Warp
      22. Warp Transform
      23. Upscale
    7. HDRI Tools
      1. HDRI Tools overview
      2. Color Temperature Adjustment
      3. Exposure
      4. Exposure Preview
      5. HDR Merge
      6. Line Light
      7. Nadir Extract
      8. Nadir Patch
      9. Panorama Patch
      10. Plane Light
      11. Shape Light
      12. Sphere Light
      13. Straighten Horizon
    8. Wear and Finish
      1. Wear and Finish overview
      2. Corrode
      3. Cracks
      4. Dirt
      5. Discarded Gums
      6. Dust
      7. Erode
      8. Metal Finish
      9. Moss
      10. Oxidate
      11. Paint
      12. Rust
      13. Scratch
      14. Snow
      15. Stylization
      16. Water
      17. Varnish
  6. Technical Support
    1. Technical Support overview
    2. Exporting the log file
    3. Configuration
      1. Configuration overview
      2. Retrieving the installation path
      3. Update Checker
      4. NVIDIA Driver Settings
      5. 3D Capture set-up on Linux  
    4. Technical Issues
      1. Technical Issues overview
    5. Data or project issues
      1. Data or project issues overview
      2. Import Substance Alchemist projects in Substance 3D Sampler
    6. Filter issues
      1. Filter issues overview
      2. Image to Material and Delighter are missing
      3. Image to Material visual artefacts
    7. Interface issues
      1. Interface issues overview
      2. Fonts are not displayed correctly
      3. Main interface is transparent
    8. Performance issues
      1. Performance issues overview
      2. Color picker takes long time to open the first time
      3. Interface lags when interacting with the layer stack or other elements
    9. Stability issues
      1. Stability issues overview
      2. Crash when exporting a material
      3. Crash when using the Image to Material or Delighter
    10. Startup issues
      1. Startup issues overview
      2. Application doesn't start on Linux
      3. Crash at start up - Old OBS version
  7. Features and workflows
    1. Features and workflows overview
    2. 3D Capture
    3. Export parametric assets
    4. End to end Physical Size Workflow
    5. Generative Workflow
    6. Texture Import
    7. Texture Generators
    8. Use As Bitmap
    9. Adobe Standard Material
  8. Pipeline and integrations
    1. Pipeline and integrations overview
    2. Environment variables
    3. Substance Send-to
    4. HP Z Captis support
      1. HP Z Captis support overview
      2. Your first capture, step by step
      3. System requirements to use the HP Z Captis device
      4. FAQ for HP Z support in Sampler
      5. Known issues and limitations
  9. Scripting and Development
    1. Scripting and Development overview
    2. Manage installed plugins and scripts
    3. Create a Plugin with Python and QML
    4. Create a Script with Python
      1. Create a Script with Python overview
      2. Example Scripts
  10. 3D Capture
    1. 3D Capture equipment
    2. Camera settings - Exposure
    3. Camera settings - Focus
    4. 3D Capture lighting
    5. Cross-polarizing for 3D Capture
    6. Processing advanced 3D Captures
    7. Editing 3D Captured meshes
  11. Release Notes
    1. Release Notes overview
    2. All Changes
    3. Beta
    4. Version 4.5
    5. Version 4.4
    6. Version 4.3
    7. Version 4.2
    8. Version 4.1
    9. Version 4.0
    10. Version 3.4
    11. Version 3.3
    12. Old Versions
      1. Version 3.2
      2. Version 3.1
      3. Version 3.0
      4. Version 2020.3 (2.3)
      5. Version 2020.2 (2.2)
      6. Version 2020.1 (2.1)
      7. Version 2019.1
      8. Version 0.8.1
      9. Version 0.8.0
      10. Version 0.7.0
      11. Version 0.6.1
      12. 0.6.0
      13. 0.5.4
      14. 0.5.3
      15. 0.5.2
      16. 0.5.1
      17. 0.5.0
  12. FAQ
    1. FAQ  Overview

Example Scripts

The scripts below can be used to build an understanding of how the Sampler API works. Feel free to use and add to these scripts as needed for your workflow.

Export all

Export material with various export presets.

export_all.py
import substance_sampler as ssa 
import os 
import sys 
 
 
# Function to export as SBSAR with default options 
def export_as_sbsar(asset_to_export, w_res, h_res, destination_path): 
    asset_to_export.export(w_resolution=w_res, 
                           h_resolution=h_res, 
                           path=destination_path) 
 
 
# Function to export as PNG with Unreal Engine 4 export preset 
def export_as_png_with_ue4_preset(asset_to_export, w_res, h_res, destination_path): 
    [ue4_export_preset] = ssa.get_export_presets("Unreal Engine 4") 
    asset_to_export.export(w_resolution=w_res, 
                           h_resolution=h_res, 
                           path=destination_path, 
                           format=ssa.png, 
                           preset=ue4_export_preset) 
 
# Verify if the project is already saved to get its path 
if ssa.save_project(): 
    ssa.save_project() 
 
    # Get the folder path of the project 
    export_path = os.path.dirname(ssa.get_project_path()) 
 
    # Get all assets of your project in a list 
    all_project_assets = ssa.get_project_assets() 
 
    # Go Through the list of all assets 
    for asset in all_project_assets: 
        # Export each asset with the resolution 2048x2048px next to the project file (.ssa) 
        export_as_sbsar(asset, 2048, 2048, export_path) 
 
        # Export each asset with the resolution 2048x2048px in a folder "textures" next to the project file (.ssa) 
        export_as_png_with_ue4_preset(asset, 2048, 2048, os.path.join(export_path, "textures")) 
else: 
    print("Save first your project", file=sys.stderr) 
 
 

Import Metadata from a CSV file

This script imports and creates custom metadata from a csv file: material_physical_property_clo.csv

export_all.py
import os 
import csv 
import substance_sampler as ssa 
 
# Set the path where the csv is stored 
csv_path = os.path.expanduser('~DocumentsAdobeAdobe Substance 3D Samplermaterial_physical_property_clo.csv') 
print(csv_path) 
 
# Open the CSV file 
with open(csv_path, newline='') as csvfile: 
     
    # Create a CSV reader object 
    reader = csv.DictReader(csvfile) 
     
    current_asset = ssa.get_selected_asset() 
    current_asset.metadata.custom_metadata = {} 
 
 # Create an empty dictionnary to store custom metadata 
    my_custom_metadata = {} 
    # Iterate over each row in the CSV file 
    for row in reader: 
        if row['Material'] == current_asset.name: 
            print(current_asset.name) 
 
            for key,value in row.items(): 
    # Add a new metadata for each column of the csv file 
                my_custom_metadata[key] = value 
                print(key,value) 
            
            current_asset.metadata.custom_metadata = my_custom_metadata   

Expose all color parameters

This script exposes the color parameter of each layer in the layer stack. 

expose_all_color_parameters.py
import substance_sampler as ssa 
 
# Get the current asset loaded in the layer stack 
my_asset = ssa.get_selected_asset() 
 
# Get all layers of the current asset in the layer stack 
my_asset_layers = my_asset.get_layers() 
 
# Go through all layers 
for layer in my_asset_layers: 
    # Go through all parameters of each layer 
    for parameter in layer.parameters: 
        # Select color parameters that are visible 
        if parameter.widget_type == ssa.color and parameter.visible: 
            # Expose the parameter 
            parameter.expose(exposed_label=f"{layer.name} - {parameter.label}", exposed_group="") 
 

Layer stack template

This script automatically adds a set of filters (defined within the script) to the current material. 

layer_stack_template.py
import substance_sampler as ssa 
 
# Get the current asset loaded in the layer stack 
my_current_asset = ssa.get_selected_asset() 
 
# Define my list of filters 
[equalizer_filter] = ssa.get_filters("Equalize") 
[tiling_filter] = ssa.get_filters("Tiling") 
[brightness_contrast_filter] = ssa.get_filters("Brightness/Contrast") 
[normal_height_adjustment_filter] = ssa.get_filters("Normal/Height Adjustment") 
[height_to_normal_filter] = ssa.get_filters("Height To Normal") 
 
# Create a list of all filters, starting from bottom to top 
layer_stack_template = [equalizer_filter, tiling_filter, brightness_contrast_filter, normal_height_adjustment_filter, 
                        height_to_normal_filter] 
 
# Insert all filters of my template on top of the layer stack 
for filter_layer in layer_stack_template: 
    # Get the number of layers 
    number_of_layers = len(my_current_asset.get_layers()) 
    # insert a filter on top of the layer stack (position O is bottom, number of layers is top) 
    my_current_asset.insert_filter(filter_layer, number_of_layers) 
    print(f"number of layers: {len(my_current_asset.get_layers())}...")  
 
# Get all layers 
my_asset_layers = my_current_asset.get_layers() 
 
# Update two parameters of the Tiling Layer 
for layer in my_asset_layers: 
    # Filter all layers by the layer name 
    if layer.name == "Tiling": 
        print("Layer:", layer.name) 
 
        # Check the list of all parameters of the Tiling layer 
        for parameter in layer.parameters: 
            # Filter the parameters list by the parameter name 
            if parameter.label in {"Threshold", "Transform"}: 
                print("Parameter:", parameter.label) 
 
                if parameter.label == "Threshold": 
                    print("Before", parameter.value) 
                    parameter.value = 0.1 
                    print("After:", parameter.value) 
 
                elif parameter.label == "Transform": 
                    print("Before:", parameter.value) 
                    parameter.value = (1.1, 0, 0, 1.1) 
                    print("After:", parameter.value)

Get help faster and easier

New user?