c4d.modules.substance ¶

New in version R18.020.

Functions ¶

• ImportSubstance()
• CreateMaterial()
• CreateSubstanceShader()
• AssignChannelToMaterial()

• GetFirstSubstance()
• GetSubstances()
• InsertLastSubstance()

• GetSubstanceGraph()
• GetSubstanceInput()
• GetSubstanceOutput()

• PrefsGetMaterialModeSetting()
• PrefsGetPreviewSetting()

• MaterialUsesSubstance()
• GetSubstanceMosaicPreview()

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 ( 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 the material. CHANNEL_LUMINANCE The luminance channel of the material. CHANNEL_TRANSPARENCY The transparency channel of the material. CHANNEL_REFLECTION The reflection channel of the material. CHANNEL_ENVIRONMENT The environment channel of the material. CHANNEL_FOG The fog channel of the material. CHANNEL_BUMP The bump channel of the material. CHANNEL_ALPHA The alpha channel of the material. CHANNEL_SPECULAR The specular channel of the material. CHANNEL_SPECULARCOLOR The specular color channel of the material. CHANNEL_GLOW The glow channel of the material. CHANNEL_DISPLACEMENT The displacement channel of the material. CHANNEL_DIFFUSION The diffusion channel of the material. CHANNEL_NORMAL The normal channel of the material. CHANNEL_ANY This specifies 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:	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 of 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 ( 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 ( PyCObject ) – Pass None (default) to get the first input, pass an input object to get the following input.
Return type:	tuple(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 ( PyCObject ) – Pass None (default) to get the first output, pass an output object to get the following output.
Return type:	tuple(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.

Table Of Contents

• c4d.modules.substance
  • Functions