Add material interfaces and make materials instanceable

- Use GetValueProducingAttributes() in the material tests
    - this verifies that we can get the shader input values regardless of whether we're using material interfaces or not
- Fix material interface texture paths when there's no layer structure

Author: LouRohanNV

mujoco_usd_converter/_impl/_flatten.py

@@ -17,18 +17,18 @@ def export_flattened(asset_stage: Usd.Stage, output_dir: str, asset_dir: str, as
     asset_identifier = f"{output_path.absolute().as_posix()}/{asset_stem}.{asset_format}"
     usdex.core.exportLayer(layer, asset_identifier, get_authoring_metadata(), comment)
 
-    # fix all PreviewMaterial inputs:file to ./Textures/xxx
+    # fix all PreviewMaterial material interface asset inputs from abs to rel paths (./Textures/xxx)
     stage = Usd.Stage.Open(asset_identifier)
     for prim in stage.Traverse():
-        if prim.IsA(UsdShade.Shader):
-            shader = UsdShade.Shader(prim)
-            file_input = shader.GetInput("file")
-            if file_input and file_input.Get() is not None:
-                file_path = pathlib.Path(file_input.Get().path if hasattr(file_input.Get(), "path") else file_input.Get())
-                tmpdir = pathlib.Path(tempfile.gettempdir())
-                if file_path.is_relative_to(tmpdir):
-                    new_path = f"./{Tokens.Textures}/{file_path.name}"
-                    file_input.Set(Sdf.AssetPath(new_path))
+        if prim.IsA(UsdShade.Material):
+            material = UsdShade.Material(prim)
+            for input in material.GetInputs(onlyAuthored=True):
+                if input.GetTypeName() == Sdf.ValueTypeNames.Asset:
+                    file_path = pathlib.Path(input.Get().path)
+                    tmpdir = pathlib.Path(tempfile.gettempdir())
+                    if file_path.is_relative_to(tmpdir):
+                        new_path = f"./{Tokens.Textures}/{file_path.name}"
+                        input.Set(Sdf.AssetPath(new_path))
     stage.Save()
     # copy texture to output dir
     temp_textures_dir = pathlib.Path(asset_dir) / Tokens.Payload / Tokens.Textures

mujoco_usd_converter/_impl/material.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 The Newton Developers
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 The Newton Developers
 # SPDX-License-Identifier: Apache-2.0
 import pathlib
 import shutil
@@ -82,6 +82,13 @@ def convert_material(parent: Usd.Prim, name: str, material: mujoco.MjsMaterial,
 
     if not material_prim:
         Tf.RaiseRuntimeError(f'Failed to convert material "{name}"')
+
+    result = usdex.core.addPreviewMaterialInterface(material_prim)
+    if not result:
+        Tf.RaiseRuntimeError(f'Failed to add material instance to material prim "{material_prim.GetPath()}"')
+
+    material_prim.GetPrim().SetInstanceable(True)
+
     return material_prim
 
 

tests/testAssetStructure.py

@@ -380,6 +380,10 @@ def test_no_layer_structure_material_texture(self):
 
         texture_input: UsdShade.Input = shader.GetInput("diffuseColor")
         connected_source = texture_input.GetConnectedSource()
-        texture_prim = connected_source[0].GetPrim()
-        texture_file_attr = texture_prim.GetAttribute("inputs:file")
+        texture_shader_prim = UsdShade.Shader(connected_source[0].GetPrim())
+
+        # The values are defined in the material interface, not in the shader
+        value_attrs = UsdShade.Utils.GetValueProducingAttributes(texture_shader_prim.GetInput("file"))
+        self.assertEqual(value_attrs[0].GetPrim(), material_prim)
+        texture_file_attr = value_attrs[0]
         self.assertEqual(texture_file_attr.Get().path, "./Textures/grid.png")

tests/testMaterial.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 The Newton Developers
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 The Newton Developers
 # SPDX-License-Identifier: Apache-2.0
 
 import pathlib
@@ -31,23 +31,31 @@ def _get_shader(self, material_name: str) -> UsdShade.Shader:
         self.assertTrue(material_prim)
         return usdex.core.computeEffectivePreviewSurfaceShader(UsdShade.Material(material_prim))
 
+    def _get_input_value(self, shader: UsdShade.Shader, input_name: str):
+        value_attrs = UsdShade.Utils.GetValueProducingAttributes(shader.GetInput(input_name))
+
+        # The values are defined in the material interface, not in the shader
+        self.assertEqual(value_attrs[0].GetPrim(), shader.GetPrim().GetParent())
+
+        return value_attrs[0].Get()
+
     def test_metallic_material(self):
         shader = self._get_shader("BlueMetallic")
-        self.assertEqual(shader.GetInput("diffuseColor").Get(), Gf.Vec3f(0, 0, 1))
-        self.assertEqual(shader.GetInput("opacity").Get(), 1)
-        self.assertAlmostEqual(shader.GetInput("roughness").Get(), 0.7)
-        self.assertAlmostEqual(shader.GetInput("metallic").Get(), 0.8)
+        self.assertEqual(self._get_input_value(shader, "diffuseColor"), Gf.Vec3f(0, 0, 1))
+        self.assertEqual(self._get_input_value(shader, "opacity"), 1)
+        self.assertAlmostEqual(self._get_input_value(shader, "roughness"), 0.7)
+        self.assertAlmostEqual(self._get_input_value(shader, "metallic"), 0.8)
         self.assertFalse(shader.GetInput("useSpecularWorkflow"))
 
     def test_specular_material(self):
         shader = self._get_shader("GreenSpecular")
-        self.assertEqual(shader.GetInput("useSpecularWorkflow").Get(), 1)
-        self.assertAlmostEqual(shader.GetInput("specularColor").Get(), Gf.Vec3f(0.8))
+        self.assertEqual(self._get_input_value(shader, "useSpecularWorkflow"), 1)
+        self.assertAlmostEqual(self._get_input_value(shader, "specularColor"), Gf.Vec3f(0.8))
 
     def test_emissive_material(self):
         shader = self._get_shader("RedEmissive")
-        self.assertEqual(shader.GetInput("diffuseColor").Get(), Gf.Vec3f(1, 0, 0))
-        self.assertEqual(shader.GetInput("emissiveColor").Get(), Gf.Vec3f(0.5, 0, 0))
+        self.assertEqual(self._get_input_value(shader, "diffuseColor"), Gf.Vec3f(1, 0, 0))
+        self.assertEqual(self._get_input_value(shader, "emissiveColor"), Gf.Vec3f(0.5, 0, 0))
 
     def test_textured_material(self):
         shader = self._get_shader("Grid")
@@ -60,9 +68,8 @@ def test_textured_material(self):
 
         # Check that the connected source is a relative asset path to the expected texture
         connected_source = texture_input.GetConnectedSource()
-        texture_prim = connected_source[0].GetPrim()
-        texture_file_attr = texture_prim.GetAttribute("inputs:file")
-        self.assertEqual(texture_file_attr.Get().path, "./Textures/grid.png")
+        texture_shader = UsdShade.Shader(connected_source[0].GetPrim())
+        self.assertEqual(self._get_input_value(texture_shader, "file").path, "./Textures/grid.png")
 
     def test_material_binding(self):
         textured_box_prim = self.stage.GetPrimAtPath(f"/{self.model_name}/Geometry/TexturedBox")
@@ -79,13 +86,21 @@ def test_material_binding(self):
         # materials are references to the material library layer
         self.assertTrue(material.GetPrim().HasAuthoredReferences())
 
+    def test_instanceable_material(self):
+        shader = self._get_shader("BlueMetallic")
+        self.assertTrue(shader)
+        material_prim = shader.GetPrim().GetParent()
+        self.assertTrue(material_prim)
+        self.assertTrue(material_prim.GetPrim().IsInstanceable())
+        self.assertTrue(material_prim.GetPrim().IsInstance())
+        self.assertTrue(shader.GetPrim().IsInstanceProxy())
+
     def test_unnamed_texture_material(self):
         shader = self._get_shader("UnnamedTexture")
         self.assertTrue(shader)
         texture_input: UsdShade.Input = shader.GetInput("diffuseColor")
         self.assertTrue(texture_input.HasConnectedSource())
 
         connected_source = texture_input.GetConnectedSource()
-        texture_prim = connected_source[0].GetPrim()
-        texture_file_attr = texture_prim.GetAttribute("inputs:file")
-        self.assertEqual(texture_file_attr.Get().path, "./Textures/grid.png")
+        texture_shader = UsdShade.Shader(connected_source[0].GetPrim())
+        self.assertEqual(self._get_input_value(texture_shader, "file").path, "./Textures/grid.png")