DocumentazioneSubstance 3DSubstance 3D Designer

Riferimento API script

Ultimo aggiornamento: 11 settembre 2026

Questa pagina descrive i concetti principali dell’API.

Per ulteriori informazioni, consulta la documentazione fornita con l’applicazione e accessibile in Guida > Documentazione Python API…. In questa documentazione, esegui una ricerca rapida per i nomi dei moduli (tra parentesi di seguito) per trovarne facilmente la definizione.

Contesto

L’oggetto contesto (Context) è il punto di ingresso principale dell’API. Viene creato la prima volta che l’utente lo ottiene utilizzando il metodo ‘getContext()’ dal modulo ‘sd’.

Questo oggetto consente essenzialmente di recuperare l’oggetto applicazione (SDApplication).

Applicazione (SDApplication)

L’applicazione (SDApplication) è l’oggetto che consente a l’accesso ai principali gestori API, ad esempio:

  • Package Manager (SDPackageMgr) che gestisce tutti i pacchetti dell’applicazione;
  • Modulo Manager (SDModuleMgr) che gestisce tutti i moduli dell’applicazione;
  • UI Manager (SDUIMgr) che può creare menu e dock nella finestra dell’applicazione.

È possibile registrare callback con l’applicazione che verrà chiamata quando si verificano determinati eventi.

Gestione pacchetti (SDPackageMgr)

Questo oggetto gestisce tutti i pacchetti dell’applicazione. I pacchetti vengono visualizzati nel componente ‘Explorer’.

Consente di:

  • creare un nuovo pacchetto;
  • caricare/scaricare un pacchetto;
  • salvare un pacchetto;
  • trova un pacchetto.

Pacchetto (SDPackage)

Un pacchetto (SDPackage) è una raccolta di risorse (SDResource).

Il contenuto di un pacchetto può essere archiviato in un file con estensione .sbs tramite l’oggetto ‘SDPackageMgr’. Questo oggetto consente di recuperare risorse specifiche.

Per creare una risorsa specifica, vedere i metodi statici oggetto correlati (ad esempio: ‘SDSBSCompGraph.sNew()’).

Un pacchetto contiene anche un dizionario dei metadati (SDMetadataDict). Ulteriori informazioni sui metadati sono disponibili qui.

Risorsa (SDResource)

Una risorsa (SDResource) è un oggetto a cui un’altra risorsa può fare riferimento .

Sono presenti più tipi di risorsa:

  • Cartelle (SDResourceFolder);
  • grafici (SDGraph);
  • Bitmap (SDResourceBitmap);
  • Immagini SVG (SDResourceSVG);
  • Font (SDResourceFont);
  • Scene (SDResourceScene);
  • Misurazioni BSDF (SDResourceBSDFMeasurement);
  • Profili chiari (SDResourceLightProfile).

È possibile creare una risorsa dal metodo statico ‘sNew()’ in:

  • un collo;
  • una cartella.

Una risorsa può avere diverse proprietà (SDProperty).

Gestione interfaccia utente (SDUIMgr)

Il gestore dell’interfaccia utente consente di creare elementi dell’interfaccia utente nella finestra principale del Substance Designer, ad esempio menu, docks e di registrare callback da chiamare quando si verificano eventi correlati all’interfaccia utente.

Inoltre, il gestore dell’interfaccia utente ha accesso al grafico attivo corrente e alla selezione del grafico attivo.

Grafici (SDGraph)

Un grafico (SDGraph) è un oggetto che contiene:

  • nodi (SDNode);
  • oggetti grafici (SDGraphObjects);
  • proprietà (SDProperty).

Esistono 4 tipi di grafici diversi:

  • Substance grafico (SDSBSCompGraph)
  • Substance grafico funzioni (SDSBSFunctionGraph)
  • Substance grafico FXMap (SDSBSFxMapGraph)

Un grafico può avere uno o più nodi output. I nodi di output rappresentano i risultati del grafico.

Tutti i nodi disponibili per un grafico possono essere recuperati con il metodo ‘getNodeDefinitions()’.

È possibile creare un nuovo nodo con il metodo ‘newNode()’.

È possibile creare un nuovo nodo istanza da una risorsa (SDResource) con il metodo ‘newInstanceNode()’.

Nodo (SDNode)

Un nodo (SDNode) rappresenta una operazione eseguita su un oggetto.

Può essere creato da:

  • una definizione (SDDefinition) (vedere 'SDGraph.newNode()');
  • una risorsa (SDResource) (vedere 'SDGraph.newInstanceNode()').

Un nodo può avere più proprietà.

Sono presenti più tipi di nodo:

  • SDSBSCompNode: nodo del Grafico Substance (SDSBSCompGraph);
  • SDSBSFunctionNode: nodo del Grafico delle funzioni Substance (SDSBSFunctionGraph);
  • SDSBSFxMapNode: nodo del grafico FXMap di Substance (SDSBSFxMapGraph);

Oggetti grafico (SDGraphObjects)

Un oggetto grafico (SDGraphObject) è un oggetto che aggiunge informazioni aggiuntive al grafico, ma che è non considerato durante il processo di valutazione del grafico.

Esistono 3 tipi di oggetti grafici:

  • Segnaposto (SDGraphObjectPin)
  • Commento (SDGraphObjectComment)
  • Fotogramma (SDGraphObjectFrame)

Per ulteriori informazioni su come crearli, vedere il metodo statico ‘sNew()’ su questi oggetti.

Proprietà (SDProperty)

Una proprietà (SDProperty) è un oggetto che descrive una proprietà di un altro oggetto (un grafico, un nodo, una risorsa e così via).

Appartiene a una categoria specifica (SDPropertyCategory):

  • Input: classifica le proprietà di input di un oggetto, che in genere influiscono sull’operazione eseguita dall’oggetto corrente;
    • Esempio: la proprietà ‘color’ di un nodo di Colore uniforme in un grafico a Substance è una proprietà di input.
  • Output: classifica le proprietà di output di un oggetto. Viene utilizzato per identificare un risultato di un oggetto;
  • Annotazione: classifica le proprietà che non influiscono sull’operazione eseguita da un oggetto;
    • Esempio: ‘label’ di un grafico è una proprietà di annotazione, in quanto non influisce sul calcolo del grafico.

Contiene i seguenti membri:

  • Id: identificatore della proprietà nel contesto della categoria;
  • Tipi: tipi supportati dalla proprietà corrente. Alcune proprietà possono supportare più tipi: ‘int’, ‘float’ e così via.;
    • Esempio: le proprietà di input di un nodo ‘sbs::add’ possono supportare tipi diversi: 'int’, 'int2’, 'int3’, 'int4’, 'float’, 'float2’, 'float3’, 'float4’, ecc.;
  • Categoria: la categoria a cui appartiene la proprietà (input, output, annotazione);
  • Etichetta: etichetta della proprietà, utilizzata per visualizzare solo;
  • Descrizione: descrizione della proprietà;
  • Valore predefinito: valore predefinito;
  • IsConnectable: indica se è possibile eseguire una connessione (SDConnection) su questa proprietà;
  • isReadyOnly: indica se la proprietà è di sola lettura. Se è true, il valore associato non sarà modificabile;
  • isVariadic: se è true, questa proprietà verrà rappresentata come proprietà multiple nell’oggetto;
  • isPrimary: indica se la proprietà specificata è la proprietà principal che controlla altre proprietà. Nota: specifica della Substance Composizione nodi (SDSBSCompNode).

Esempi:

  • Proprietà del nodo ‘sbs::input’:
sbs::input
Input
Annotazione
Output
$outputsize
etichetta
unique_filter_output (CONNETTIBILE)
$format
descrizione
$pixelsize
identificatore
$pixelratio
userdata
$tiling
gruppo
$randomseed
visibleif
bitmapresourcepath
utilizzi
  • Proprietà del nodo ‘sbs::blend’:
sbs::blend
Input
Annotazione
Output
$outputsize
unique_filter_output (CONNETTIBILE)
$format
$pixelsize
$pixelratio
$tiling
$randomseed
source.connector (COLLEGABILE)
destination.connector (CONNETTIBILE)
opacity.connector (COLLEGABILE)
opacitimulto
metodo fusione
colorblending
maskrectangle

Tipo (SDType)

Un tipo (SDType) contiene informazioni di un valore type, ad esempio:

  • Id: identificatore del tipo;

  • Modificatore: modificatore di tipo che può essere uno dei valori 'SDTypeModifier’ enum:

    • Automatico;
    • Uniforme: il valore viene valutato una volta per operazione;
    • Variabile: il valore viene valutato più volte per operazione (ad esempio, per ogni testo).

Sono definiti più tipi, ad esempio:

  • enum (SDTypeEnum): descrive un tipo enumerazione con tutte le relative proprietà;
  • strutture (SDTypeStruct): descrive un tipo struttura con tutte le relative proprietà;
  • matrice (SDTypeArray): descrive una matrice.
  • ecc.

Per un elenco completo, consulta la documentazione Python API del Substance Designer.

Valori (SDValue)

Un valore (SDValue) è un oggetto che incapsula un valore di tipo base.

Ad esempio:

  • un oggetto ‘SDValueInt’ incapsula un valore ‘int’;
  • un oggetto ‘SDValueFloat4’ incapsula un valore ‘float4’;
  • ecc.

Il valore del tipo di base può essere in genere recuperato con il metodo ‘get()’, ma può dipendere dal tipo di 'SDValue’ restituito.

Connessione (SDConnection)

Una connessione (SDConnection) rappresenta un collegamento tra due diverse proprietà di due diversi nodi.

Contiene:

  • nodo di destinazione;
  • proprietà di destinazione del nodo di destinazione;

Tutte le operazioni di connessione vengono eseguite in un nodo:

  • creazione di una nuova connessione. Vedere ‘SDNode.newPropertyConnection()’
  • eliminazione di una connessione esistente. Vedere ‘SDNode.deletePropertyConnection()’
  • recupero delle connessioni di una proprietà. Vedere ‘SDNode.getPropertyConnections()’

Modulo (SDModule)

Un modulo è una raccolta di definizioni e tipi.

Consente di recuperare facilmente tutte le informazioni sui nodi che è possibile creare, nonché su enumerazioni e strutture.

Contiene:

  • un identificatore (Id) univoco nel contesto del gestore del modulo (SDModuleMgr);
  • un elenco di definizioni (SDDefinition);
  • un elenco di tipi (SDType).

Definizione (definizione SDD)

Un oggetto definizione (SDDefinition) contiene informazioni sulla definizione di un particolare oggetto in base a proprietà ('SDNode’ e così via).

Contiene:

  • Id: identificatore della definizione;
  • Etichetta: etichetta della definizione;
  • Descrizione: descrizione della definizione;
  • Proprietà: proprietà di tutte le proprietà disponibili categorie (SDPropertyCategory).
recommendation-more-help
substance-3d-designer-help-guide