c4d.modules.substance

class c4d.modules.substance

New in version R18.020.

Functions Signatures

c4d.modules.substance.ImportSubstance(doc, fn, copyFile, ...)	Imports a Substance asset file (.sbsar) into doc.
c4d.modules.substance.CreateMaterial(asset, graphIndex, mode)	Creates a Cinema 4D standard material from asset.
c4d.modules.substance.CreateSubstanceShader(asset)	Creates a Substance shader linked to asset.
c4d.modules.substance.AssignChannelToMaterial(asset, mat, channelId, ...)	type asset c4d.BaseList2D
c4d.modules.substance.GetFirstSubstance(doc)	Retrieves the first Substance asset in doc.
c4d.modules.substance.GetSubstances(doc, onlySelected)	Retrieves all (or only selected) Substance assets in doc.
c4d.modules.substance.InsertLastSubstance(doc, asset)	Inserts asset into doc as last element.
c4d.modules.substance.GetSubstanceGraph(asset[, prevGraph])	Retrieves the Substance graph. This function may be used to iterate over the graphs of asset.
c4d.modules.substance.GetSubstanceInput(asset, graph[, prevInput])	Retrieves the Substance input of an asset. This function may be used to iterate over the inputs of graph for asset.
c4d.modules.substance.GetSubstanceOutput(asset, graph, getBitmap)	Retrieves the Substance output of an asset. This function may be used to iterate over the outputs of graph for asset.
c4d.modules.substance.PrefsGetMaterialModeSetting()	Convenience function to get the material creation mode set in Substance preferences.
c4d.modules.substance.PrefsGetPreviewSetting()	Convenience function to get the preview mode for Content Browser set in Substance preferences.
c4d.modules.substance.MaterialUsesSubstance(mat)	Checks if mat contains any Substance shaders.
c4d.modules.substance.GetSubstanceMosaicPreview(asset, w, h)	Returns an image with previews of the output channels of asset.

Functions Documentation

c4d.modules.substance.ImportSubstance(doc, fn, copyFile, errPopup, addUndo, createMaterial)

Imports a Substance asset file (.sbsar) into doc.

Parameters

• doc (c4d.documents.BaseDocument) – The document to import into.

• fn (str) – The Substance asset file.

• copyFile (int) –

  The copy file flag:

  SUBSTANCE_IMPORT_COPY_YES	Automatically copy file to project directory (relative file path).
  SUBSTANCE_IMPORT_COPY_NO	Do not copy file to project directory (absolute file path).
  SUBSTANCE_IMPORT_COPY_ASK	Ask user.

  If set to ASK, user’s choice will be returned.

  Note: When set to ASK, the function obviously has to be called in a context where user interaction is allowed.

• errPopup (bool) –

  If set to True, problems will be communicated to the user with a message requester.

  Note: When set to True, the function obviously has to be called in a context where user interaction is allowed.

• addUndo (bool) – If set to True, an undo step will be added for the import. Caller has to care for the surrounding BaseDocument.StartUndo() and BaseDocument.EndUndo() calls.

• createMaterial (bool) – Set to True, to have a material created based on the configuration in preferences. Set to False, to suppress any creation of materials.

Return type

Tuple[int, c4d.BaseList2D, int]

Returns

A tuple with the following information:

int: The result for the import:

SUBSTANCE_IMPORT_RESULT_SUCCESS	Success.
SUBSTANCE_IMPORT_RESULT_DOESNOTEXIST	File not found.
SUBSTANCE_IMPORT_RESULT_NOTANASSET	Wrong file format.
SUBSTANCE_IMPORT_RESULT_UNKNOWNERROR	On memory error or when invalid parameters were passed.

c4d.BaseList2D: The imported Substance asset.

int: User’s choice if copyFile was ASK. Otherwise same as passed to copyFile.

c4d.modules.substance.CreateMaterial(asset, graphIndex, mode)

Creates a Cinema 4D standard material from asset.

Parameters

• asset (c4d.BaseList2D) – The Substance asset.

• graphIndex (int) – The index of the graph to use (for multi-graph Substances).

• mode (int) –

  The material creation mode

  SUBSTANCE_MATERIAL_MODE_STANDARD	Create standard material.
  SUBSTANCE_MATERIAL_MODE_METALLIC	Create metallic material.
  SUBSTANCE_MATERIAL_MODE_GLOSSY	Create glossy material.
  SUBSTANCE_MATERIAL_MODE_AUTO	Use heuristic to choose one of the three above (see Cinema 4D’s user manual).
  SUBSTANCE_MATERIAL_MODE_NONE	Do not create material.

Return type

c4d.BaseMaterial

Returns

The created material.

c4d.modules.substance.CreateSubstanceShader(asset)

Creates a Substance shader linked to asset.

Parameters

asset (Optional[c4d.BaseList2D]) – The Substance asset. Can be None (since R18.039).

Return type

c4d.BaseShader

Returns

The created Substance shader.

c4d.modules.substance.AssignChannelToMaterial(asset, mat, channelId, outputUid, addUndo)

Parameters

• asset (c4d.BaseList2D) – The Substance asset. Needs to be part of the document.

• mat (c4d.Material) – The material.

• channelId (int) –

  The channel ID:

  CHANNEL_COLOR	The color channel of a material.
  CHANNEL_LUMINANCE	The luminance channel of a material.
  CHANNEL_TRANSPARENCY	The transparency channel of a material.
  CHANNEL_REFLECTION	The reflection channel of a material.
  CHANNEL_ENVIRONMENT	The environment channel of a material.
  CHANNEL_FOG	The fog channel of a material.
  CHANNEL_BUMP	The bump channel of a material.
  CHANNEL_ALPHA	The alpha channel of a material.
  CHANNEL_SPECULAR	The specular channel of a material.
  CHANNEL_SPECULARCOLOR	The specular color channel of a material.
  CHANNEL_GLOW	The glow channel of a material.
  CHANNEL_DISPLACEMENT	The displacement channel of a material.
  CHANNEL_DIFFUSION	The diffusion channel of a material.
  CHANNEL_NORMAL	The normal channel of a material.
  CHANNEL_ANY	An unlabeled plugin channel.

• outputUid (int) – The unique ID of the Substance output to use.

• addUndo (bool) – If set to True, an undo step will be added for the import. Caller has to care for the surrounding BaseDocument.StartUndo() and BaseDocument.EndUndo() calls.

Return type

bool

Returns

True if successful, otherwise False.

c4d.modules.substance.GetFirstSubstance(doc)

Retrieves the first Substance asset in doc.

Parameters

doc (c4d.documents.BaseDocument) – The document.

Return type

Optional[c4d.BaseList2D]

Returns

The first Substance asset, or None if none exists.

c4d.modules.substance.GetSubstances(doc, onlySelected)

Retrieves all (or only selected) Substance assets in doc.

Parameters

• doc (c4d.documents.BaseDocument) – The document.

• onlySelected (bool) – Set to True to get only selected Substance assets.

Return type

List[c4d.C4DAtom]

Returns

The retrieved Substance assets.

c4d.modules.substance.InsertLastSubstance(doc, asset)

Inserts asset into doc as last element.

Parameters

• doc (c4d.documents.BaseDocument) – The document.

• asset (c4d.BaseList2D) – The Substance asset.

Return type

bool

Returns

True if successful, otherwise False.

c4d.modules.substance.GetSubstanceGraph(asset, prevGraph=None)

Retrieves the Substance graph. This function may be used to iterate over the graphs of asset.

Parameters

• asset (c4d.BaseList2D) – The Substance asset.

• prevGraph (Optional[PyCObject]) – Pass None (default) to get the first graph, pass a graph object to get the following graph.

Return type

Tuple[PyCObject, str]

Returns

The Substance graph and its name.

c4d.modules.substance.GetSubstanceInput(asset, graph, prevInput=None)

Retrieves the Substance input of an asset. This function may be used to iterate over the inputs of graph for asset.

Parameters

• asset (c4d.BaseList2D) – The Substance asset.

• graph (PyCObject) – The graph.

• prevInput (Optional[PyCObject]) – Pass None (default) to get the first input, pass an input object to get the following input.

Return type

Tuple[Optional[PyCObject], int, int, int, int, str]

Returns

A tuple with the following information:

The Substance input, or None if input is not available.

The unique ID of the input. Only valid if the function does not return None.

The ID of the first component of the input parameter in Cinema 4D. This ID can be used to create a c4d.DescID for C4DAtom.SetParameter(). Only valid if the function does not return None.

The number of description elements used in Cinema 4D to represent the Substance input parameter. Only valid if the function does not return None.

The data type of the input. Only valid if the function does not return None.

SUBSTANCE_INPUT_TYPE_INTEGER	int Integer, one c4d.DescID.
SUBSTANCE_INPUT_TYPE_INTEGER_2	int Two component integer vector, two c4d.DescID.
SUBSTANCE_INPUT_TYPE_INTEGER_3	int Three component integer vector, three c4d.DescID.
SUBSTANCE_INPUT_TYPE_INTEGER_4	int Four component integer vector, four c4d.DescID.
SUBSTANCE_INPUT_TYPE_BOOL	bool Boolean, one c4d.DescID.
SUBSTANCE_INPUT_TYPE_FLOAT	float Float, one c4d.DescID.
SUBSTANCE_INPUT_TYPE_FLOAT_2	float Two component float vector, two c4d.DescID.
SUBSTANCE_INPUT_TYPE_FLOAT_3	float Three component float vector, three c4d.DescID.
SUBSTANCE_INPUT_TYPE_FLOAT_4	float Four component float vector, four c4d.DescID.
SUBSTANCE_INPUT_TYPE_IMAGE	str Image input, one c4d.DescID.
SUBSTANCE_INPUT_TYPE_STRING	str String, one c4d.DescID.
SUBSTANCE_INPUT_TYPE_COLOR_RGB	c4d.Vector RGB color vector, one c4d.DescID.
SUBSTANCE_INPUT_TYPE_COLOR_RGBA	c4d.Vector and float RGBA color vector, two c4d.DescID.
SUBSTANCE_INPUT_TYPE_RESOLUTION	int Substance output resolution, two c4d.DescID, integer, range 4 to 11, 2^n pixels (16 pixels to 2048 pixels).

Name of the returned input. Only valid if the function does not return None as Substance input.

c4d.modules.substance.GetSubstanceOutput(asset, graph, getBitmap, prevOutput=None)

Retrieves the Substance output of an asset. This function may be used to iterate over the outputs of graph for asset.

Parameters

• asset (c4d.BaseList2D) – The Substance asset.

• graph (PyCObject) – The graph.

• getBitmap (bool) – Set to True, to get a clone of the output channel bitmap.

• prevOutput (Optional[PyCObject]) – Pass None (default) to get the first output, pass an output object to get the following output.

Return type

Tuple[Optional[PyCObject], int, int, str, c4d.bitmaps.BaseBitmap]

Returns

A tuple with the following information:

The Substance output, or None if output is not available.

The unique ID of the output. Only valid if the function does not return None.

The output type ID. Only valid if the function does not return None as Substance output.

SUBSTANCE_OUTPUT_TYPE_DIFFUSE
SUBSTANCE_OUTPUT_TYPE_BASECOLOR
SUBSTANCE_OUTPUT_TYPE_OPACITY
SUBSTANCE_OUTPUT_TYPE_EMISSIVE
SUBSTANCE_OUTPUT_TYPE_AMBIENT
SUBSTANCE_OUTPUT_TYPE_AMBIENTOCCLUSION
SUBSTANCE_OUTPUT_TYPE_MASK
SUBSTANCE_OUTPUT_TYPE_NORMAL
SUBSTANCE_OUTPUT_TYPE_BUMP
SUBSTANCE_OUTPUT_TYPE_HEIGHT
SUBSTANCE_OUTPUT_TYPE_DISPLACEMENT
SUBSTANCE_OUTPUT_TYPE_SPECULAR
SUBSTANCE_OUTPUT_TYPE_SPECULARLEVEL
SUBSTANCE_OUTPUT_TYPE_SPECULARCOLOR
SUBSTANCE_OUTPUT_TYPE_GLOSSINESS
SUBSTANCE_OUTPUT_TYPE_ROUGHNESS
SUBSTANCE_OUTPUT_TYPE_ANISOTROPYLEVEL
SUBSTANCE_OUTPUT_TYPE_ANISOTROPYANGLE
SUBSTANCE_OUTPUT_TYPE_TRANSMISSIVE
SUBSTANCE_OUTPUT_TYPE_REFLECTION
SUBSTANCE_OUTPUT_TYPE_REFRACTION
SUBSTANCE_OUTPUT_TYPE_ENVIRONMENT
SUBSTANCE_OUTPUT_TYPE_IOR
SUBSTANCE_OUTPUT_TYPE_SCATTERING0
SUBSTANCE_OUTPUT_TYPE_SCATTERING1
SUBSTANCE_OUTPUT_TYPE_SCATTERING2
SUBSTANCE_OUTPUT_TYPE_SCATTERING3
SUBSTANCE_OUTPUT_TYPE_METALLIC
SUBSTANCE_OUTPUT_TYPE_ANY
SUBSTANCE_OUTPUT_TYPE_UNKNOWN
SUBSTANCE_OUTPUT_TYPE_INTERNAL_COUNT

The name of the returned output. Only valid if the function does not return None.

The clone of the output channel bitmap. Only valid if the function does not return None and getBitmap was passed True.

c4d.modules.substance.PrefsGetMaterialModeSetting()

Convenience function to get the material creation mode set in Substance preferences.

Return type

int

Returns

The material creation mode:

SUBSTANCE_MATERIAL_MODE_STANDARD	Create standard material.
SUBSTANCE_MATERIAL_MODE_METALLIC	Create metallic material.
SUBSTANCE_MATERIAL_MODE_GLOSSY	Create glossy material.
SUBSTANCE_MATERIAL_MODE_AUTO	Use heuristic to choose one of the three above (see Cinema 4D’s user manual).
SUBSTANCE_MATERIAL_MODE_NONE	Do not create material.

c4d.modules.substance.PrefsGetPreviewSetting()

Convenience function to get the preview mode for Content Browser set in Substance preferences.

Return type

int

Returns

0 for mosaic preview, otherwise rendered preview scene.

c4d.modules.substance.MaterialUsesSubstance(mat)

Checks if mat contains any Substance shaders.

Parameters

mat (c4d.BaseMaterial) – The material to check for Substance shaders.

Return type

bool

Returns

True if the material uses a Substance shader, otherwise False.

c4d.modules.substance.GetSubstanceMosaicPreview(asset, w, h)

Returns an image with previews of the output channels of asset.

Note

While the Substance asset won’t have to be re-rendered, this operation still involves downscaling of all Substance outputs.

Parameters

• asset (c4d.BaseList2D) – The Substance asset.

• w (int) – The width of the preview image.

• h (int) – The height of the preview image.

Return type

c4d.bitmaps.BaseBitmap

Returns

The resulting preview bitmap.