MaterialXLab API

MaterialXLab Javascript API

The Javascript API provides a set of libraries and interfaces used by the MaterialXLab site.

Current functionality includes:

Documents

• Support for basic text editor widget for modifying MaterialX documents
• This includes supporting document validation, and preview in a 3D interactive viewer widget.
  

Graphing

• Ability to extract out graph connectivity information from a MaterialX document.
• Ability to create Mermaid graphs from the connectivity information.
• Ability to create new node definitions from node graph implementations.

Node Graph Editing

• A component to allow support interactive node graph editing from a web page.
• Interfaces to connect up MaterialX (or other storage format) serialization and deserialization.
• Interfaces to allow the monitoring of modifications to a node graph. This includes add/removal of nodes, renaming, value and connection changes.
• Interfaces to allow connection to a 3D interactive viewer and underlying renderer.

Material Libraries

• Ability to pull MaterialX materials from library repositories such as PhysicallyBased
• Ability to unpack MaterialX materials which are stored as zip files.

LiteGraph Customizations and Extensions

MaterialX Definition Generation

Node definitions for usage with LiteGraph are created by reading in MaterialX documents.

At startup all of the "standard library" definitions are loaded in. Additional definitions can be loaded in by the user either by explicitly specifying a document with definitions or implicitly loading in any definitions which are part of a working document.

The resulting output is a set of Javascript functions, such that each function provides the logic to create a node in LiteGraph.

A number of specializations have been added as follows:

• Adding custom port types as supported by MaterialX. For example "filename".
• Add metadata attributes as property information. This includes UI attributes such as "uimin", "uiname"; "colorspace" and "units", and "defaultgeomprop".
• Keeping track of the original MaterialX nodedef identifier. This is the unique identifier which can be used to retrieve all related information for the definition of a node.
• Various callback functions are provided for monitoring the state of the node. This includes:
  • onPropertyChanged : This is used to monitor when values change on an input.
  • onPropertyInfoChanged : This is a custom function added to all LightGraph Nodes. It is used for monitor when attributes on an input are changed. For example when "colorspace" or "units" change.
  • onConnectOutput: This is used to monitor when an output port is connected to another nodes port.
  • onConnnectInput: This is used to monitor when an input port is connected to another nodes port.
  • onNodeCreated: This is used to monitor when a node is created. Currently this is empty logic as it is handled at the graph level.
• UI information such as icons, swatches and references to external documentation are provided.
• Node UI preferences such as node shape, title color.

Example

Below is an example for the MaterialX definition for a tiled image node which outputs a float value.

Javascript

 
function mtlx_texture2d_tiledimage_float() {
  this.nodedef_icon = '';
  this.nodedef_name = 'ND_tiledimage_float';
  this.nodedef_type = 'float';
  this.nodedef_node = 'tiledimage';
  this.nodedef_href = 'https://kwokcb.github.io/MaterialX_Learn/documents/definitions/tiledimage.html';
  this.nodedef_swatch = 'https://kwokcb.github.io/MaterialX_Learn/resources/mtlx/nodedef_materials/material_tiledimage_float_out_genglsl.png';
  this.nodedef_group = 'texture2d';
  this.addInput('file','filename');
  this.addProperty('file', '', 'filename',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addInput('default','float');
  this.addProperty('default', 0.0, 'float',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addInput('texcoord','vector2');
  this.addProperty('texcoord', [0.0, 0.0], 'vector2',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":"UV0"});
  this.addInput('uvtiling','vector2');
  this.addProperty('uvtiling', [1.0, 1.0], 'vector2',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addInput('uvoffset','vector2');
  this.addProperty('uvoffset', [0.0, 0.0], 'vector2',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addInput('realworldimagesize','vector2');
  this.addProperty('realworldimagesize', [1.0, 1.0], 'vector2',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addInput('realworldtilesize','vector2');
  this.addProperty('realworldtilesize', [1.0, 1.0], 'vector2',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addInput('filtertype','string');
  this.addProperty('filtertype', 'linear', 'string',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addInput('framerange','string');
  this.addProperty('framerange', '', 'string',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addInput('frameoffset','integer');
  this.addProperty('frameoffset', 0, 'integer',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addInput('frameendaction','string');
  this.addProperty('frameendaction', 'constant', 'string',{"colorspace":"","unit":"","unittype":"","uiname":"","uimin":null,"uimax":null,"uifolder":"","defaultgeomprop":""});
  this.addOutput('out','float');
  this.title = 'tiledimage_float';
  this.desc = "MaterialX:mtlx/texture2d/tiledimage_float";
  this.onNodeCreated = function() {
  //console.log('Node created:', this);
}
  this.onRemoved = function() {
  //console.log('Node removed:', this);
  }
  this.onPropertyChanged = function(name, value, prev_value) {
 MxShadingGraphEditor.theEditor.monitor.onPropertyChanged(this.title, name, value, prev_value, this);
  }
  this.onPropertyInfoChanged = function(name, info, value, prev_value) {
 MxShadingGraphEditor.theEditor.monitor.onPropertyInfoChanged(this.title, name, info, value, prev_value, this);
  }
  this.onConnectOutput = function(slot, input_type, input, target_node, target_slot) {
 MxShadingGraphEditor.theEditor.monitor.onConnectOutput(slot, input_type, input, target_node, target_slot, this);
  }
  this.onConnectInput = function(target_slot, output_type, output, source, slot) {
 MxShadingGraphEditor.theEditor.monitor.onConnectInput(target_slot, output_type, output, source, slot, this);
  }
  this.bgcolor = '#111';
  this.color = '#222';
  this.shape = LiteGraph.ROUND_SHAPE;
  this.boxcolor = '#161';
}
mtlx_texture2d_tiledimage_float.nodedef_name = 'ND_tiledimage_float';
mtlx_texture2d_tiledimage_float.nodedef_node = 'tiledimage';
mtlx_texture2d_tiledimage_float.nodedef_href = 'https://kwokcb.github.io/MaterialX_Learn/documents/definitions/tiledimage.html';
LiteGraph.registerNodeType('mtlx/texture2d/tiledimage_float',mtlx_texture2d_tiledimage_float);