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:
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.