vrMaterialService

class vrMaterialService

(Inherits vrBaseService)

Interface to access materials in VRED.

This is the basic interface to access, create or delete materials. It also provides functionality to access the material graph by using vrMaterialService.getMaterialRoot().

See also: Node graphs in VRED

Some examples how to work with materials:

# add a group node
groupNode = vrMaterialService.createMaterialGroup()

# create a plastic material and add it to the group
mat = vrMaterialService.createMaterial("plasticmat", vrMaterialTypes.Plastic, groupNode)

# search for a material by name
mat = vrMaterialService.findMaterial("plasticmat")

# if there are multiple materials with the same name you can collect all of them
materials = vrMaterialService.findMaterials("plasticmat")

# to search for a group you can use the generic findNode / findNodes functions
group = vrNodeService.findNode("Group", root=vrMaterialService.getMaterialRoot())
For more complex group operations, see also: Material groups

Note:
Several functions take vrdMaterialEntryIds as parameter.
These ids are used to reference materials in the UI and should not be used when writing
scripts that run without UI. They are typically obtained by fetching the
the selected nodes with getSelection().

Summary

Functions:
Signals:

Functions

vrMaterialService.addToDefaultEnvironmentSwitch(environmentMaterial)

Adds the given environment material to the default environment switch.

Parameters:environmentMaterial (vrdEnvironmentMaterial) – Environment material to add.
vrMaterialService.applyEnvironmentToAllMaterials(environment, name)

Apply the given environment or environment switch material to all materials.

Parameters:
  • environment (vrdMaterial) – The environment material to apply
  • name (string) – A name filter for the environment to replace. Empty string for no filter.
vrMaterialService.applyEnvironmentToNodes(material, nodes)

Apply the given environment or environment switch material to the materials of the given nodes.

Parameters:
  • material (vrdMaterial) – The environment material to apply
  • nodes (List[vrdNode]) – The nodes where the environment should be applied to
vrMaterialService.applyMaterialToNodes(material, nodes)

Apply a material to a list of nodes.

Parameters:
  • material (vrdMaterial) – The material to be applied
  • nodes (List[vrdNode]) – The nodes where the material should be applied to
vrMaterialService.compressTextures()

Compresses all textures with BC6H or BC7 format.

vrMaterialService.convertMaterial(material, type)

Converts a material to another type.

Parameters:
Returns:

The converted material
Return type:

vrdMaterial
vrMaterialService.copyMaterialAttributes(source, targets)

Copy material attributes from one material to other materials.

Parameters:
vrMaterialService.copyMaterialChunks(chunks)

Copy a list of material chunks to the clipboard.

Parameters:chunks (List[vrdMaterialChunk]) – A list of material chunks
vrMaterialService.copyTextureSize(source, targets)

Copy material texture size from one material to other materials.

Parameters:
vrMaterialService.createMaterial(name, type, materialGroup=vrdNode())

Creates a material.

Parameters:
  • name (string) – Name of the material
  • type (vrMaterialTypes.MaterialType) – Material type
  • materialGroup (vrdNode) – Material group to add the new created material (optional)
Returns:

The created material
Return type:

vrdMaterial
vrMaterialService.createMaterialGroup(nodes=List[vrdNode], parent=vrdNode())

Creates a new material group.

If called without parameters it will create a new group below the root node with a unique name. Optionally it takes a list of group nodes or material nodes and moves those directly under the new group.

Parameters:
  • nodes (List[vrdNode]) – The nodes to be added to the new group
  • parent (vrdNode) – If empty, add group to common parent, otherwise add to existing group
Returns:

The created group node
Return type:

vrdNode
vrMaterialService.createSwitchMaterial(materials=List[vrdMaterial], parent=vrdNode())

Creates a new switch material.

Parameters:
  • materials (List[vrdMaterial]) – The materials to be added to the new switch
  • parent (vrdNode) – If empty, create a toplevel group otherwise add to an existing group
Returns:

The created material switch
Return type:

vrdMaterial
vrMaterialService.deleteEntries(entries, keepVariants=False)

Removes the entries from the tree.

Parameters:
  • entries (List[vrMaterialEntryId]) – The material tree entries
  • keepVariants (bool) – If True, keep material variants of deleted switch materials. Set to False to delete corresponding material variants from Variants module and from variant sets using the material variant.
vrMaterialService.deleteMaterials(materials, keepVariants=False)

Delete materials.

Only materials that are not referenced can be deleted. Referenced materials will be skipped by this function.

Parameters:
  • materials (List[vrdMaterial]) – The materials to be deleted.
  • keepVariants (bool) – If True, keep material variants of deleted switch materials. Set to False to delete corresponding material variants from Variants module and from variant sets using the material variant.
vrMaterialService.duplicateEntries(entries)

Duplicate the given material graph entries.

Parameters:entries (List[vrMaterialEntryId]) – The entries to be duplicated
Returns:List of duplicated entries
Return type:List[vrMaterialEntryId]
vrMaterialService.duplicateMaterials(materials)

Duplicates the given materials.

Parameters:materials (List[vrdMaterial]) – The materials to be duplicated.
Returns:The list of duplicated materials
Return type:List[vrdMaterial]
vrMaterialService.findMaterial(name)

Find a material by name.

Parameters:name (string) – Name of the material to be searched for
Returns:The first material with the given name or an invalid object, if nothing is found
Return type:vrdMaterial
vrMaterialService.findMaterialNode(material, root=vrdNode())

Find the vrdMaterialNode for the given material.

A vrdMaterialNode is a helper node to present vrdMaterials in a tree structure as materials itself are not derived from vrdNode.

Parameters:
  • material (vrdMaterial) – Search for a node with this material
  • root (vrdNode) – Search in the given sub graph. If root is missing, the whole material tree is searched.
Returns:

The found node, otherwise an invalid node
Return type:

vrdMaterialNode
vrMaterialService.findMaterials(name)

Find all materials with the given name.

Parameters:name (string) – Name of the material to be searched
Returns:A list of all materials with the given name
Return type:List[vrdMaterial]
vrMaterialService.findMaterialsUsedInVariants(root=vrdNode())

Find materials in the material tree that are used in variants.

Parameters:root (vrdNode) – The root node of the tree to search. If empty, all materials are searched.
Returns:A list of materials, that are referenced in variants
Return type:List[vrdMaterial]
vrMaterialService.findNodesWithMaterial(material)

Searches the scene for node with the given material.

Parameters:material (vrdMaterial) –
Returns:The list of all found ndoes
Return type:List[vrdNode]
vrMaterialService.findUnusedMaterials()

Find materials in the material tree that are not used in the scene graph, i.e. that are not assigned to any node or are not a sub material of an assigned material.

Returns:A list of materials not used in the scene graph
Return type:List[vrdMaterial]
vrMaterialService.getAllMaterials()

Returns a list of all materials.

Returns:A list of all materials
Return type:List[vrdMaterial]
vrMaterialService.getAllMaterialTags()
Returns:Gets a list of all material tags
Return type:List[string]
vrMaterialService.getDefaultEnvironment()
Returns:The default environment material
Return type:vrdMaterial
vrMaterialService.getDefaultEnvironmentSwitchMaterial()

Returns the default environment switch material.

Returns:Default environment switch material
Return type:vrdEnvironmentSwitchMaterial
vrMaterialService.getEntries(materials)

Get material graph entries for given materials.

Parameters:materials (List[vrdMaterial]) – Material list
Returns:List of material graph entries
Return type:List[vrMaterialEntryId]
vrMaterialService.getGroupPath(node)

Returns the path of a node within the material tree.

The path starts with the name of the group root.

Parameters:node (vrdNode) – The node which path should be retrieved.
Returns:The path of given node. If the node is not below the root group of the material tree, an empty path will be returned.
Return type:List[string]
vrMaterialService.getImportMetadata(type)

Returns whether metadata for the specified material type will be imported or not.

Parameters:type (vrMaterialTypes.MaterialType) – The material type.
Returns:True, if metadata will be imported for the specified material type.
Return type:bool
vrMaterialService.getMaterialFromId(materialId)

Gets a material by its identifier.

You can convert from an old vrMaterialPtr to a vrdMaterial by taking the ID from the old material like this: This returns a vrdMaterial for a given material identifier.

newMat = vrMaterialService.getMaterialFromId(oldMat.getID())

To convert a vrdMaterial to a vrMaterialPtr object, use toMaterial(id)

oldMatPtr = toMaterial(newMat.getObjectId())

or the vrMaterialPtr(id) constructor from API v1:

oldMatPtr = vrMaterialPtr(newMat.getObjectId())
Parameters:materialId (integer) – The material identifier.
Returns:The material from identifier.
Return type:vrdMaterial
vrMaterialService.getMaterialNodes(root=vrdNode())

Returns all material nodes in the given sub tree.

Parameters:root (vrdNode) – Root node, if missing search whole tree
Returns:A list of all nodes in the subtree.
Return type:List[vrdMaterialNode]
vrMaterialService.getMaterialRoot()

Returns the root for all materials in the material tree.

Returns:The root node.
Return type:vrdNode
vrMaterialService.getMaterials(root)

Get all materials used in the given tree.

Parameters:root (vrdNode) –
Returns:A list of materials found in the given tree
Return type:List[vrdMaterial]
vrMaterialService.getMaterialSelection()
Returns:Returns a list of all currently selected materials
Return type:List[vrdMaterial]
vrMaterialService.getMaterialsWithAllTags(tags)

Get the materials that have all the given tags.

Parameters:tags (List[string]) – The set of tags to search for.
Returns:The list of materials.
Return type:List[vrdMaterial]
vrMaterialService.getMaterialsWithAnyTag(tags)

Get the materials that have any of the given tags.

Parameters:tags (List[string]) – The set of tags to search for.
Returns:The list of materials.
Return type:List[vrdMaterial]
vrMaterialService.getNumberOfMaterials()

Returns the number of materials used in the current scene.

Returns:The number of materials in scene.
Return type:integer
vrMaterialService.getNumberOfTextures()

Returns the number of textures used in all materials.

Returns:The number of textures.
Return type:integer
vrMaterialService.getPlanarManipulatorTransparency()

Returns the transparency value [0.0 to 1.0] of the planar manipulator plane.

Returns:The transparency value
Return type:float
vrMaterialService.getPreviewScenes()
Returns:Get all available material preview scene names
Return type:List[string]
vrMaterialService.getSelection()
Returns:The currently selected items in the material editor tree view
Return type:List[vrMaterialEntryId]
vrMaterialService.getSupportedMaterialTypes()
Returns:A list of all supported material types
Return type:List[vrMaterialTypes.MaterialType]
vrMaterialService.getTireManipulatorTransparency()

Returns the transparency value [0.0 to 1.0] of the tire manipulator cylinder geometry.

Returns:The transparency value
Return type:float
vrMaterialService.getTreeDepth(material)

Returns the depth of a material subtree.

Parameters:material (vrdMaterial) – The root material of the subtree.
Returns:The depth of the subtree.
Return type:integer
vrMaterialService.getTreeDepth(root)

Returns the depth of a material subtree.

Parameters:root (vrdNode) – The root node of the subtree.
Returns:The depth of the subtree.
Return type:integer
vrMaterialService.getUniqueName(name, forceHighestIndex=True)

Creates a unique name by appending an index.

Example: There are materials “Phong2” and “Phong9”.
Therefore the highest index is 9.

Calling this function with “Phong” or “Phong7” will
* return the given name, if forceHighestIndex is set to False.
* return “Phong10”, if forceHighestIndex is set to True.
Parameters:
  • name (string) – If necessary, a suffix is added to the given name to make it unique
  • forceHighestIndex (bool) – If the given name is not used, but there is a node with the same base name, the name will be adapted to have a higher index than the given one.
Returns:

The unique name.
Return type:

string
vrMaterialService.getUsedTextureMemory()

The currently used texture memory in bytes.

Returns:The used texture memory.
Return type:integer
vrMaterialService.loadAnimationToMaterials(materials, animation)

Apply an animation from a file to a list of materials.

Parameters:
  • materials (List[vrdMaterial]) – The materials
  • animation (string) – The animation (as .osb/.vpb file)
vrMaterialService.loadEnvironmentAssetToDefaultSwitch(uuid)

Loads an environment asset by uuid into the default switch.

Parameters:uuid (string) –
vrMaterialService.loadMaterialAsset(uuid, parent=vrdNode())

Loads a material asset by uuid into a given node.

Parameters:
  • uuid (string) – Unique asset identifier
  • parent (vrdNode) – Parent node or if empty, add to top level group
Returns:

The created material node
Return type:

vrdMaterialNode
vrMaterialService.loadMaterials(fileNames, materialGroup=vrdNode())

Loads materials from disk.

Suffixes for all supported file types:
- osb: OpenSG Binary Geometry
- vpb: VRED Project Binary
- vpe: VRED Essentials Project Binary
- pbrdf: Office Color Science BTF measurement
- axf, cpa, btf: X-Rite measurement
- mdl: Material Definition Language module
- mtlx, MaterialX Document
- sbsar: Substance Archive
- hdr, exr, mtd: Sphere Environment
Parameters:
  • fileNames (List[string]) – The material file names to load
  • materialGroup (vrdNode) – Material group to add the new created material to (optional)
Returns:

The loaded materials
Return type:

List[vrdMaterial]
vrMaterialService.mergeDuplicateMaterials(options=vrMaterialTypes.MergeOptions.Default)

Share materials with the same properties.

Parameters:options (vrMaterialTypes.MergeOptions) – Options for merging
vrMaterialService.optimizeTextures()

Shares image objects used by materials that have the same image data.

vrMaterialService.pasteEntries(sources, targets)

Pastes the given entries to the given target in the tree.

Parameters:
vrMaterialService.pasteMaterialChunks(chunkMaterial)

Paste the stored material chunks from the clipboard into a chunk material.

Parameters:chunkMaterial (vrdChunkMaterial) – The chunk material which receives the chunks from the clipboard.
vrMaterialService.referenceUnusedMaterials()

Reference materials not used in the scene by adding material groups to the scene graph.

Returns:The number of new references created
Return type:integer
vrMaterialService.removeAllGroups()

Remove all material groups. Material nodes in groups will be moved to the root node.

vrMaterialService.removeUnusedMaterials()

Remove unused materials.

vrMaterialService.renderMultiPreview(materials, totalCount, size, text='')

Create an image with multiple material previews.

Parameters:
  • materials (List[vrdMaterial]) – A list of materials that should be painted as a stack
  • totalCount (integer) – This number will be printed at top of the image
  • size (QSize) – The requested image size
  • text (string) – An optional prefix text for the painted image
Returns:

The painted image
Return type:

QImage
vrMaterialService.saveMaterials(materials, path)

Saves materials to disk.

The materials will be saved as individual .osb files to the folder specified as ‘path’.

Parameters:
  • materials (List[vrdMaterial]) – The materials to save
  • path (string) – The path where to save the materials
Returns:

False if either one of the materials could not be saved or the directory does not exist. Otherwise True is returned.
Return type:

bool
vrMaterialService.selectNodes(materials, clearSelection)

Select all nodes in the scene graph that reference the given materials.

Parameters:
  • materials (List[vrdMaterial]) – A list of materials
  • clearSelection (bool) – If True, clear current selection
vrMaterialService.setImportMetadata(type, value)

Sets whether to import metadata for the specified material type.

Currently, only Substance and XRite material support metadata. Setting other material types will have no effect.

Parameters:
vrMaterialService.setMaterialSelection(materials, scrollTo=False)

Changes the material selection.

Parameters:
  • materials (List[vrdMaterial]) – A list of vrdMaterial objects to be selected
  • scrollTo (bool) – If true, scroll to the first selected material
vrMaterialService.setPlanarManipulatorTransparency(transparency)

Sets the transparency value of the planar manipulator plane.

Parameters:transparency (float) – Transparency value [0.0 to 1.0]
vrMaterialService.setSelection(ids, scrollTo=False, edit=False)

Changes the material selection.

Parameters:
  • ids (List[vrMaterialEntryId]) – A list of vrMaterialEntryIds that represents items in the material tree view
  • scrollTo (bool) – If true, scroll to the first selected item
  • edit (bool) – If true, starts editing the corresponding item
vrMaterialService.setSwitchChoiceByAllTags(switchMaterial, tags)

Sets the choice of a switch material to the first child with all of the given tags. If not found the choice stays unchanged.

Parameters:
  • switchMaterial (vrdSwitchMaterial) – The switch material to modify.
  • tags (List[string]) – The set of tags determining the child material to select.
Returns:

True if matching child material found.
Return type:

bool
vrMaterialService.setSwitchChoiceByAnyTag(switchMaterial, tags)

Sets the choice of a switch material to the first child with any of the given tags. If not found the choice stays unchanged.

Parameters:
  • switchMaterial (vrdSwitchMaterial) – The switch material to modify.
  • tags (List[string]) – The set of tags determining the child material to select.
Returns:

True if matching child material found.
Return type:

bool
vrMaterialService.setTireManipulatorTransparency(transparency)

Sets the transparency value of the tire manipulator cylinder geometry.

Parameters:transparency (float) – Transparency value [0.0 to 1.0]
vrMaterialService.updatePreviews(materials)

Update the preview for the given materials, if necessary.

Parameters:materials (List[vrdMaterial]) – List of materials

Signals

vrMaterialService.materialsChanged()

Notifies about changes in the material tree.

vrMaterialService.planarManipulatorTransparencyChanged(transparency)

Notifies about changes of the manipulator transparency.

Parameters:transparency (float) –
vrMaterialService.previewsChanged()

Notifies about changes of the material preview images.

vrMaterialService.selectionChanged(ids, scrollTo, edit)

This signal is emitted, whenever the material selection changes.

Parameters:
  • ids (List[vrMaterialEntryId]) – The list of selected vrMaterialEntryIds
  • scrollTo (bool) – If true, scroll to the first selected item is requested
  • edit (bool) – If true, starting to edit the corresponding item is requested
vrMaterialService.tireManipulatorTransparencyChanged(transparency)

Notifies about changes of the manipulator transparency.

Parameters:transparency (float) –