Summary

This is a placeholder parent issue for sub-issues related to improving the interop between MaterialX to USD.
Specifically for the workflow for referencing or loading in MaterialX to create UsdShade shader graphs.

These are observations based on this prototype: https://github.com/kwokcb/materialxusd

• See associated issue for MaterialX: Improve Robustness of MaterialX to USD Interoperability AcademySoftwareFoundation/MaterialX#2291

Some pre-processing prototype logic is provided here in an attempt to work around issues.

Note: Sub-issues need to be split out.

Sub-Issues

• usdMtlx creates NodeGraphs for top level Nodes

  • UsdShade can support such configurations so appears to be an artificial constraint.
  • This complicates the graph and changes the original topology and exposure of nodes and inputs. e.g. in this Slack thread

• usdMtlx can fail if top level nodes found (not in NodeGraphs).

  • Some nodes are not grouped under NodeGraphs and the import will fail. Seems PBR, BXDF nodes are not. e.g. in this Slack thread

• usdMtlx will create nothing if there is a connection failure

  • There is no concept of allowing for valid parts to be imported.

• usdMtlx imports nothing if there is no Materials in the MaterialX document.

  • This makes it impossible to import valid documents which for instance may non material elements used to build up build up more complex graphs. This even includes documents with NodeGraphs only which would affect the current initialtive for glTF nodegraph support of MaterialX.

• usdMtlx has no API to get warnings / errors back.

  • This appears true for referencing or using Stage.Load() so there is no way to catch and handle this.

• Syntax for referencing MaterialX appears to not be documented.

  • You need to specify the default prim as </MaterialX> otherwise "defaultPrim" is looked for which does not exist since usdMtlx does not create this. The error messaging is not very clear on this as well.

• usdMtlx forms can form incorrect connections between NodeGraphs and downstream nodes.

  • This occurs if there are NodeGraph inputs with the same name as internal nodes. It appears to try to connect with the interior node and fails.

• usdMtlx / UsdShade does not allow for BXDF / PBR nodes which have valid type surfaceshader, volumeshader, displacementshader outputs to be connected to downstream materials if they are not: glTF, USDPreview, std surface or OpenPBR.

  • This includes nodes which definition these shaders as their terminal node. This means related MaterialX conversion nodes are not supported. e.g. "convert float to surface shader".
  • Documentation is not clear on what is allowed.

• usdMtlx will fail to import if MaterialX inputs doe not specify an explicit output port qualifier.

  • UsdShade requires output port specifiers for a valid connection. MaterialX does not always require this
    so there appears to be an inconsistent interpretation.

• usdMtlx defaults to "out" as default upstream node / nodegraph output for connections

  • This may not be the case in which case connection creation fails and import aborts.
  • This is inconsistent with MaterialX which takes the first valid output.

• HDStorm seems to not considered defaultgeomprop on node definitions and hence requires explicit upstream stream node nodes to be connected. Unsure if this is a general issue for all render delegates but was found here.

• usdMtlx supported" graph configurations is not well documented.

  • Per node features are documented, but graph configurations are not.

• usdMtlx does not create a valid stage on Stage.Load(). Could not find any documentation on this but would be useful to have it noted somewhere. This could affect support for real world units when this is supoprted as metresPerUnit is never defined causing a validation failure. Unsure if defaultPrim should be specified -- assume not.

• usdMtlx gives no indication as to what meta-data is not transferred. e.g. real world units which can greatly affect the computation is not transferred but no indication is provided.