IrayPlusMaterialEditorBuilder Class — NXOpen Python API Reference 12.0.0 documentation

# IrayPlusMaterialEditorBuilder Class

class `NXOpen.Display.``IrayPlusMaterialEditorBuilder`

  Bases: `NXOpen.Builder`

  Represents a `NXOpen.Display.IrayPlusMaterialEditorBuilder`

  This class is restricted to being called from a program running during an Interactive NX session. If run from a non-interactive session it will return None.

  The IrayPlusMaterialEditorBuilder used to manipulate specific material for IrayPlus. It maintained an IrayPlusMatAttribute based hierarchical structure corresponding to the xml structure of IrayPlus material.

  The example of the hierarchical structure for material Varnished Cherry is:

  Material-Layers -ClearCoat -Attribute1 -Attribute2 -… -Base -Attribute1 -Attribute2 -… -Geometry -Attribute1 -Attribute2 -… -Global Texture Space -Attribute1 -Attribute2 -… Each node in the hierarchy is an IrayPlusMatAttribute object. This structure been created when the IrayPlusMaterialEditorBuilder creating process.

  Example for general workflow of set parameter show bellow: (1)Use GetMaterialLayersInfo() to get names and unique names of all the layers and components of the material. For the example Varnished Cherry material. It will return 4 names:[ClearCoat,Base,Geometry,Global Texture Space] and 4 unique names:[ model2_’Varnished Cherry_Layer_198, Matte, BaseGeometry,Box].

  (2)Then we can use these name to call GetComponentInfo() to get the parameters of each component: If we use ‘Base’ as component name. The attribute number will return 18. The attribute list will return array like:[Base-Base Type, Base-Colour-Interface Type,…]

  (3)Use GetComponentParameter() to get attribute object of specific attribute name. We can use ‘Base-Colour-Interface Type’ as parameter to call GetComponentParameter(). It will return the pointer of IrayPlusMatAttribute object of this attribute.User can modify the value of the IrayPlusMatAttribute object.

  (4)Use SetComponentParameter() to set the value of attribute. After modify IrayPlusMatAttribute object returned by GetComponentParameter(). We can use ‘Base-Colour-Interface Type’ and the pointer to IrayPlusMatAttribute object that been modified as parameter to call SetComponentParameter() to set the value into hierarchy.

  (5)If you did any change of hierarchy. You need to call builder’s commit() function to make hierarchy apply to IrayPlus Rendeing engine to make all your modification have effect.

  NOTE: The detail rule of using each function see comments of specific function.

  New in version NX11.0.0.

# Properties

Property | Description
--- | ---
MaterialName | Returns or sets the current material name of material editor builder.
PreviewToggle | Returns or sets a boolean value that indicate whether the preview toggle is ON.
Tag | Returns the Tag for this object.

# Methods

Method | Description
--- | ---
AddComponent | Adds a component to layers for specific layer type.
Commit | Commits any edits that have been applied to the builder.
Destroy | Deletes the builder, and cleans up any objects created by the builder.
ExportToXMLFile | Exports current material of material editor builder into a XML file.
GetCommittedObjects | For builders that create more than one object, this method returns the objects that are created by commit.
GetComponentInfo | Get all the attribute name of a component.
GetComponentParameter | Gets single attribute object for specific fomatted attribute name The string attribute name format should be : layer name-interface name-attribute name Let material ‘’Varnished Cherry’ for example: If user wants to get ‘Base’ component’s attribueObject of ‘Base-Colour-Colour’.
GetComponentParameterValue | Gets attribute’s value as string for specific fomatted attribute name The string attribute name format should be : layer name-interface name-attribute name Let material ‘’Varnished Cherry’ for example: If user wants to get ‘Base’ component’s value of ‘Base-Colour-Colour’.
GetImageParameterFullPath | To return the absolute path of specific image type parameter.
GetMaterialLayersInfo | Get all the components unique name and type name of this material.
GetObject | Returns the object currently being edited by this builder.
MoveComponent | Moves a component of layers up and down of layers stack.
RemoveComponent | Removes a component to layers for specific layer index Let material ‘’Varnished Cherry’ for example: If use changed the material has two Layers: Dir1 and ClearCoat.
SaveToSystemStudioMaterials | Saves the material to System Studio Materials which is a directory under ugphoto/IrayPlus_ug_canned_mattex.
SetComponentParameter | Sets attribute object for specific fomatted attribute name The string attribute name format should be : layer name-interface name-attribute name Let material ‘’Varnished Cherry’ for example: If user wants to set ‘Base’ component’s attribueObject of ‘Base-Colour-Colour’.
SetComponentParameterValue | Sets attribute value for specific fomatted attribute name The string attribute name format should be : layer name-interface name-attribute name Let material ‘’Varnished Cherry’ for example: If user wants to set ‘Base’ component’s value of ‘Base-Colour-Colour’.
ShowResults | Updates the model to reflect the result of an edit to the model for all builders that support showing results.
Validate | Validate whether the inputs to the component are sufficient for commit to be called.

# Enumerations

IrayPlusMaterialEditorBuilderLayerType Enumeration | Layer types used in iray plus material

# Property Detail

## MaterialName

`IrayPlusMaterialEditorBuilder.``MaterialName`

  Returns or sets the current material name of material editor builder.

  NOTE: the returned materialName should be freed via TEXT_free by caller.

  `-------------------------------------`

  Getter Method

  Signature `MaterialName`

  Returns: |
  Return type: | str

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

  `-------------------------------------`

  Setter Method

  Signature `MaterialName`

  Parameters: | materialName (str) –

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## PreviewToggle

`IrayPlusMaterialEditorBuilder.``PreviewToggle`

  Returns or sets a boolean value that indicate whether the preview toggle is ON.

  If preview toggle is true. then the preview image of the material will be generated.

  `-------------------------------------`

  Getter Method

  Signature `PreviewToggle`

  Returns: |
  Return type: | bool

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

  `-------------------------------------`

  Setter Method

  Signature `PreviewToggle`

  Parameters: | toggleOn (bool) –

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

# Method Detail

## AddComponent

`IrayPlusMaterialEditorBuilder.``AddComponent`

  Adds a component to layers for specific layer type.

  Let material ‘’Varnished Cherry’ for example:

  If user wants to add ‘Dir1’ layer into Layers. They should use ‘Dir1’ to componentType paramter. Then the added_layer_index output the added layer’s new index. It will return 1 for ‘Dir1’ index .Because the ‘ClearCoat’ will be index 0.

  componentUniqueName parameter will return the unique name of ‘Dir1’: ‘model2_’Varnished Cherry_Layer_262’.

  You can also add more than one layers for same type. You can add ‘Dir1’ into ‘’Varnished Cherry’ again. The added_layer_index would return 2. The componentUniqueName parameter will return the unique name of new added ‘Dir2’ : ‘model2_’Varnished Cherry_Layer_281’

  Signature `AddComponent(componentType)`

  Parameters: | componentType (str) –
  Returns: | a tuple
  Return type: | A tuple consisting of (componentUniqueName, addedLayerIndex) componentUniqueName is a str. addedLayerIndex is a int.

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## ExportToXMLFile

`IrayPlusMaterialEditorBuilder.``ExportToXMLFile`

  Exports current material of material editor builder into a XML file.

  Signature `ExportToXMLFile(exportXmlFileName)`

  Parameters: | exportXmlFileName (str) –

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## GetComponentInfo

`IrayPlusMaterialEditorBuilder.``GetComponentInfo`

  Get all the attribute name of a component.

  The string attribute name format should be the component name.

  Let material ‘’Varnished Cherry’ for example:

  If user wants to get component’s sub attribute names of ‘Base’ component. They should input ‘Base’ as componentName paramter. Then the attribueObject output the pointer to the IrayPlusMatAttribute object of ‘Base’ component in the hierarchy. The attrib_list will return array of all the attribute name of the ‘Base’ component like [Base-Base Type, Base-Colour-Interface Type,…]

  If user wants to get layer’s sub attribute names of ‘ClearCoat’. They should use ‘0’ as componentName paramter. Then the attribueObject output the pointer to the IrayPlusMatAttribute object of ‘ClearCoat’ layer in the hierarchy. The attrib_list will return array of all the attribute name of the ‘ClearCoat’ layer like [model2_’Varnished Cherry_Layer_198-Layer Type, model2_’Varnished Cherry_Layer_198-Colour-Interface Type,…]

  NOTE:User use ‘model2_’Varnished Cherry_Layer_198’ as paramter name to get and set attribute can ONLY in same session. User should NOT use name like ‘ClearCoat’ or ‘model2_’Varnished Cherry_Layer_198’ as name parameter. Instead they should use index as name. The index value of each Layers is same as name position in unique_name_list. This is because the unique name for each layers would change between each session.

  Signature `GetComponentInfo(componentName)`

  Parameters: | componentName (str) –
  Returns: | a tuple
  Return type: | A tuple consisting of (attribueObject, attribList). attribueObject is a `NXOpen.Display.IrayPlusMaterialAttribute`. attribList is a list of str.

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## GetComponentParameter

`IrayPlusMaterialEditorBuilder.``GetComponentParameter`

  Gets single attribute object for specific fomatted attribute name The string attribute name format should be : “layer name-interface name-attribute name”

  Let material ‘’Varnished Cherry’ for example:

  If user wants to get ‘Base’ component’s attribueObject of ‘Base-Colour-Colour’.

  They should input ‘Base-Colour-Colour’ as componentName paramter. Then the attribueObject output the pointer to the IrayPlusMatAttribute object of ‘Base-Colour-Colour’ component in the hierarchy.

  If user wants to get layer’s sub attribute of ‘ClearCoat’. They should use index in componentName paramter: ‘Layers-0-ReflectionColour-ColourOffset’ Then the attribueObject output the pointer to the IrayPlusMatAttribute object of ‘ReflectionColour-ColourOffset’ attribute of ‘ClearCoat’ layer in the hierarchy.

  NOTE:User use ‘model2_’Varnished Cherry_Layer_198’ as paramter name to get and set attribute can ONLY in same session. User should NOT use name like ‘ClearCoat’ or ‘model2_’Varnished Cherry_Layer_198’ as name parameter. Instead they should use index as name. The index value of each Layers is same as name position in unique_name_list. This is because the unique name for each layers would change between each session.

  Signature `GetComponentParameter(attribueName)`

  Parameters: | attribueName (str) –
  Returns: |
  Return type: | `NXOpen.Display.IrayPlusMaterialAttribute`

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## GetComponentParameterValue

`IrayPlusMaterialEditorBuilder.``GetComponentParameterValue`

  Gets attribute’s value as string for specific fomatted attribute name The string attribute name format should be : “layer name-interface name-attribute name”

  Let material ‘’Varnished Cherry’ for example:

  If user wants to get ‘Base’ component’s value of ‘Base-Colour-Colour’.

  They should input ‘Base-Colour-Colour’ as componentName paramter. attribueValue parameter will return the string for the value of ‘Base-Colour-Colour’: “0.000000000000000,1.000000000000000,1.000000000000000”

  If user wants to get layer’s sub attribute of ‘ClearCoat’. They should use index in componentName paramter: ‘Layers-0-ReflectionColour-ColourOffset’

  attribueValue parameter will return the value of ‘ClearCoat’’s ‘ReflectionColour-ColourOffset’ as a string : “1.000000000000000,0.000000000000000,0.000000000000000”

  NOTE:User use ‘model2_’Varnished Cherry_Layer_198’ as paramter name to get and set attribute can ONLY in same session. User should NOT use name like ‘ClearCoat’ or ‘model2_’Varnished Cherry_Layer_198’ as name parameter. Instead they should use index as name. The index value of each Layers is same as name position in unique_name_list. This is because the unique name for each layers would change between each session.

  Signature `GetComponentParameterValue(attribueName)`

  Parameters: | attribueName (str) –
  Returns: |
  Return type: | str

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## GetImageParameterFullPath

`IrayPlusMaterialEditorBuilder.``GetImageParameterFullPath`

  To return the absolute path of specific image type parameter.

  The format of imageAttribueName should be : “layer name-interface name-attribute name”

  Let material ‘’Varnished Cherry’ for example:

  If user wants to get image’s full path of ‘Base-Colour-TextureSpace-Image’. User should input ‘Base-Colour-TextureSpace-Image’ as imageAttribueName paramter. imageFullPath parameter will return the string of full path.

  If user wants to get layer’s sub attribute of ‘ClearCoat’. They should use index in imageAttribueName paramter: ‘Layers-0-TextureSpace-Image’

  NOTE:User use ‘model2_’Varnished Cherry_Layer_198’ as paramter name to get and set attribute can ONLY in same session. User should NOT use name like ‘ClearCoat’ or ‘model2_’Varnished Cherry_Layer_198’ as name parameter. Instead they should use index as name. The index value of each Layers is same as name position in unique_name_list. This is because the unique name for each layers would change between each session.

  If the

  Signature `GetImageParameterFullPath(imageAttribueName)`

  Parameters: | imageAttribueName (str) –
  Returns: |
  Return type: | str

  New in version NX11.0.2.

  License requirements: studio_render (“UG STUDIO RENDER”)

## GetMaterialLayersInfo

`IrayPlusMaterialEditorBuilder.``GetMaterialLayersInfo`

  Get all the components unique name and type name of this material.

  The order in list have meanings. The Layers’s components are put into the list first. So the index of component in list are same of index in Layers. Other Base, Global TextureSplace are insert into the list after Layer’s components.

  Use system material ‘Varnished Cherry’ as example. Set attribueName paramter to ‘’Varnished Cherry’. It will return 4 items in type_list:[ClearCoat,Base,Geometry,Global Texture Space] and 4 item in unique_name_list:[model2_’Varnished Cherry_Layer_198, Matte, BaseGeometry,Box].

  The type_list output the type for sublayer in Layers and name for Base,Geometry,Global Texture Space. The unique_name_list output the unique name of each layers and types for Base,Geometry,Global Texture Space.

  When user use these name to get or set attribute for the specific components. They should use ‘Base’ ‘Geometry’ ‘Global Texture Space’ for fixed components. But for components in Layers.

  NOTE:User use ‘model2_’Varnished Cherry_Layer_198’ as paramter name to get and set attribute can ONLY in same session. User should NOT use name like ‘ClearCoat’ or ‘model2_’Varnished Cherry_Layer_198’ as name parameter. Instead they should use index as name. The index value of each Layers is same as name position in unique_name_list. This is because the unique name for each layers would change between each session.

  For example if user want to set or get the attribute of ClearCoat of material ‘’Varnished Cherry’. They should use ‘0’ as the paramter name to call GetComponentParameter or SetComponentParameter.

  Signature `GetMaterialLayersInfo()`

  Returns: | a tuple
  Return type: | A tuple consisting of (typeList, uniqueNameList) typeList is a list of str. uniqueNameList is a list of str.

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## MoveComponent

`IrayPlusMaterialEditorBuilder.``MoveComponent`

  Moves a component of layers up and down of layers stack.

  Let material ‘’Varnished Cherry’ for example: If use changed the material has two Layers: Dir1 and ClearCoat. Then user wants to move ‘Dir1’ layer down in Layers. They should use 1 as index paramter.

  The parameter componentType should input the layer type of the layer that you want to move. This make the deleting more type safe. User should set ‘Dir1’ as componentType for this example.

  move_up parameter should be ‘false’ for this example.

  Signature `MoveComponent(index, componentType, moveUp)`

  Parameters:

  - index (int) –
  - componentType (str) –
  - moveUp (bool) –

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## RemoveComponent

`IrayPlusMaterialEditorBuilder.``RemoveComponent`

  Removes a component to layers for specific layer index

  Let material ‘’Varnished Cherry’ for example: If use changed the material has two Layers: Dir1 and ClearCoat.

  Then user wants to remove ‘Dir1’ layer from Layers. They should use 1 as index paramter.

  The parameter componentType should input the layer type of the layer that you want to remove. This make the deleting more type safe. User should set ‘Dir1’ as componentType for this example.

  Signature `RemoveComponent(index, componentType)`

  Parameters:

  - index (int) –
  - componentType (str) –

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## SaveToSystemStudioMaterials

`IrayPlusMaterialEditorBuilder.``SaveToSystemStudioMaterials`

  Saves the material to System Studio Materials which is a directory under ugphoto/IrayPlus_ug_canned_mattex.

  Signature `SaveToSystemStudioMaterials(saveXmlFileName)`

  Parameters: | saveXmlFileName (str) –

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## SetComponentParameter

`IrayPlusMaterialEditorBuilder.``SetComponentParameter`

  Sets attribute object for specific fomatted attribute name The string attribute name format should be : “layer name-interface name-attribute name”

  Let material ‘’Varnished Cherry’ for example:

  If user wants to set ‘Base’ component’s attribueObject of ‘Base-Colour-Colour’.

  They should input ‘Base-Colour-Colour’ as attribueName paramter. The attribueObject point to the IrayPlusMatAttribute which should have modified value for Colour.

  If user wants to set layer’s sub attribute of ‘ClearCoat’. They should use index in attribueName paramter: ‘Layers-0-ReflectionColour-ColourOffset’ The attribueObject point to the IrayPlusMatAttribute which should have modified value for ColourOffset.

  The changed_attrib parameter will return all the attributs names effected by current modification. then user could use this to figure out what should to requery.

  If user use ‘Base-Base Type’ to change base type to ‘Metal’. Then all the attribute name in ‘Base’ will be listed in changed_attrib. Because the interface type change will cause the sub attributes been changed either.

  NOTE:User use ‘model2_’Varnished Cherry_Layer_198’ as paramter name to get and set attribute can ONLY in same session. User should NOT use name like ‘ClearCoat’ or ‘model2_’Varnished Cherry_Layer_198’ as name parameter. Instead they should use index as name. The index value of each Layers is same as name position in unique_name_list. This is because the unique name for each layers would change between each session.

  Signature `SetComponentParameter(attribueName, attribueObject)`

  Parameters:

  - attribueName (str) –
  - attribueObject (`NXOpen.Display.IrayPlusMaterialAttribute`) –

  Returns: |
  Return type: | list of str

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## SetComponentParameterValue

`IrayPlusMaterialEditorBuilder.``SetComponentParameterValue`

  Sets attribute value for specific fomatted attribute name The string attribute name format should be : “layer name-interface name-attribute name”

  Let material ‘’Varnished Cherry’ for example:

  If user wants to set ‘Base’ component’s value of ‘Base-Colour-Colour’.

  They should input ‘Base-Colour-Colour’ as attribueName paramter. attribueValue parameter will return the string for the value of ‘Base-Colour-Colour’: “0.000000000000000,1.000000000000000,1.000000000000000”

  If user wants to set layer’s sub attribute value of ‘ClearCoat’. They should use index in attribueName paramter: ‘Layers-0-ReflectionColour-ColourOffset’ attribueValue parameter will return the string for the value of ‘ReflectionColour-ColourOffset’ in ‘ClearCoat’: “1.000000000000000,0.000000000000000,0.000000000000000”

  The changed_attrib parameter will return all the attributs names effected by current modification. then user could use this to figure out what should to requery.

  If user use ‘Base-Base Type’ to change base type to ‘Metal’. Then all the attribute name in ‘Base’ will be listed in changed_attrib. Because the interface type change will cause the sub attributes been changed either.

  NOTE:User use ‘model2_’Varnished Cherry_Layer_198’ as paramter name to get and set attribute can ONLY in same session. User should NOT use name like ‘ClearCoat’ or ‘model2_’Varnished Cherry_Layer_198’ as name parameter. Instead they should use index as name. The index value of each Layers is same as name position in unique_name_list. This is because the unique name for each layers would change between each session.

  Signature `SetComponentParameterValue(attribueName, attribueValue)`

  Parameters:

  - attribueName (str) –
  - attribueValue (str) –

  Returns: |
  Return type: | list of str

  New in version NX11.0.0.

  License requirements: studio_render (“UG STUDIO RENDER”)

## Validate

`IrayPlusMaterialEditorBuilder.``Validate`

  Validate whether the inputs to the component are sufficient for commit to be called.

  If the component is not in a state to commit then an exception is thrown. For example, if the component requires you to set some property, this method will throw an exception if you haven’t set it. This method throws a not-yet-implemented NXException for some components.

  Signature `Validate()`

  Returns: | Was self validation successful
  Return type: | bool

  New in version NX3.0.1.

  License requirements: None.