UsdPreviewSurface.inputs:diffuseColor connection does not serialize (typed-attr connect ignored;

[execomrt]

When authoring a connection to UsdPreviewSurface.inputs:diffuseColor, TinyUSDZ does not serialize the relationship into USDA. I tested both ways:

Setting the connection on the typed attribute (UsdPreviewSurface::diffuseColor.connect.set(Path(...)))

Setting a relationship via Shader.props["inputs:diffuseColor.connect"]

In both cases, the generated USDA is missing the expected

rel inputs:diffuseColor.connect = </.../Image_Texture.outputs:rgb>

Note: A connection for UsdUVTexture.inputs:st does serialize correctly when authored as texShader.props["inputs:st.connect"], so the issue appears specific to UsdPreviewSurface.inputs:diffuseColor.

To Reproduce

#include <iostream>
#include "tinyusdz.hh"

int main() {
  using namespace tinyusdz;

  Stage stage;

  // /Materials scope
  Scope s; s.name = "Materials";
  Prim matScope(s);
  stage.add_root_prim(Prim(s));
  stage.commit();

  // Material "M"
  Material m; m.name = "M";
  Prim matPrim(m);

  // Shader "Principled_BSDF" (UsdPreviewSurface)
  Shader pbr; pbr.name = "Principled_BSDF"; pbr.info_id = kUsdPreviewSurface;
  UsdPreviewSurface surf;
  surf.outputsSurface.set_authored(true);
  // IMPORTANT: do NOT author a default diffuseColor when connecting
  pbr.value = surf;
  Prim pbrPrim(pbr);
  matPrim.add_child(std::move(pbrPrim), /*rename=*/true, nullptr);

  // Shader "Image_Texture" (UsdUVTexture)
  Shader tex; tex.name = "Image_Texture"; tex.info_id = kUsdUVTexture;
  UsdUVTexture uvtex;
  uvtex.outputsRgb.set_authored(true);
  uvtex.file = value::AssetPath("./textures/bk.png");
  tex.value = uvtex;
  Prim texPrim(tex);
  matPrim.add_child(std::move(texPrim), /*rename=*/true, nullptr);

  // Shader "uvmap" (UsdPrimvarReader_float2)
  Shader uv; uv.name = "uvmap"; uv.info_id = kUsdPrimvarReader_float2;
  UsdPrimvarReader_float2 stnode;
  stnode.result.set_authored(true);
  stnode.varname.set_value(std::string("st"));
  uv.value = stnode;
  Prim uvPrim(uv);
  matPrim.add_child(std::move(uvPrim), /*rename=*/true, nullptr);

  // Put Material under /Materials and commit to stabilize paths
  // (re-fetch scope since we moved it into Stage)
  Prim *materials = nullptr;
  for (auto &r : stage.root_prims()) if (r.element_name() == "Materials") materials = &r;
  materials->add_child(std::move(matPrim), /*rename=*/true, nullptr);
  stage.commit();

  // Resolve children
  Prim &addedMat = materials->children().back();
  Prim *pPrincipled=nullptr, *pTex=nullptr, *pUvmap=nullptr;
  for (auto &ch : addedMat.children()) {
    if (const Shader* s = ch.as<Shader>()) {
      if (s->info_id == kUsdPreviewSurface)       pPrincipled = &ch;
      else if (s->info_id == kUsdUVTexture)       pTex        = &ch;
      else if (s->info_id == kUsdPrimvarReader_float2) pUvmap  = &ch;
    }
  }

  // Hook Material.outputs:surface -> Principled_BSDF.outputs:surface
  if (pPrincipled) {
    Material mm = *addedMat.as<Material>();
    mm.surface.set(Path(pPrincipled->absolute_path().full_path_name(), "outputs:surface"));
    addedMat.set_primdata(addedMat.element_name(), mm);
  }

  // inputs:st.connect (works)
  if (pTex && pUvmap) {
    Shader texS = *pTex->as<Shader>();
    Relationship r; r.set(Path(pUvmap->absolute_path().full_path_name(), "outputs:result"));
    texS.props["inputs:st.connect"] = Property(r);
    pTex->set_primdata(pTex->element_name(), texS);
  }

  // inputs:diffuseColor.connect (DOES NOT SERIALIZE)

  // A) Typed-attribute way (expected to work, but currently does not)
  if (pPrincipled && pTex) {
    Shader pv = *pPrincipled->as<Shader>();
    if (auto *node = pv.value.as<UsdPreviewSurface>()) {
      node->diffuseColor.connect.set(
            Path(pTex->absolute_path().full_path_name(), "outputs:rgb"));
      pv.value = *node;
      pPrincipled->set_primdata(pPrincipled->element_name(), pv);
    }
  }

  // // B) Props way (also does not serialize for UsdPreviewSurface)
  // if (pPrincipled && pTex) {
  //   Shader pv = *pPrincipled->as<Shader>();
  //   Relationship r; r.set(Path(pTex->absolute_path().full_path_name(), "outputs:rgb"));
  //   pv.props["inputs:diffuseColor.connect"] = Property(r);
  //   pPrincipled->set_primdata(pPrincipled->element_name(), pv);
  // }

  stage.commit();

  std::string warn, err;
  usda::SaveAsUSDA("repro.usda", stage, &warn, &err);
  if (!warn.empty()) std::cout << "WARN: " << warn << "\n";
  if (!err.empty())  std::cout << "ERR : " << err << "\n";

  return 0;
}

Actual USDA

def Material "M" {
    token outputs:surface.connect = </Materials/M/Principled_BSDF.outputs:surface>

    def Shader "Principled_BSDF" {
        uniform token info:id = "UsdPreviewSurface"
        token outputs:surface
        // Missing: rel inputs:diffuseColor.connect = </Materials/M/Image_Texture.outputs:rgb>
    }

    def Shader "Image_Texture" {
        uniform token info:id = "UsdUVTexture"
        asset inputs:file = @./textures/bk.png@
        float3 outputs:rgb
    }

    def Shader "uvmap" {
        uniform token info:id = "UsdPrimvarReader_float2"
        string inputs:varname = "st"
        float2 outputs:result
    }
}

Expected behavior / Expected USDA

def Material "M" {
    token outputs:surface.connect = </Materials/M/Principled_BSDF.outputs:surface>

    def Shader "Principled_BSDF" {
        uniform token info:id = "UsdPreviewSurface"
        token outputs:surface
        rel inputs:diffuseColor.connect = </Materials/M/Image_Texture.outputs:rgb>
    }

    def Shader "Image_Texture" {
        uniform token info:id = "UsdUVTexture"
        asset inputs:file = @./textures/bk.png@
        float3 outputs:rgb
    }

    def Shader "uvmap" {
        uniform token info:id = "UsdPrimvarReader_float2"
        string inputs:varname = "st"
        float2 outputs:result
    }
}

[syoyo]

You first better to ask coding agent(Copilot, Claude code, etc) about the issue.

[syoyo]

@claude

[claude]

Claude finished @syoyo's task —— View job • claude/issue-259-20250925-1550 • Create PR ➔

---

Analysis Complete ✅

I've identified the root cause of the issue with UsdPreviewSurface.inputs:diffuseColor connection serialization and provided a solution.

Root Cause

The problem is not with the serialization code itself, but with how connections are set up in user code. The TypedAttributeWithFallback class requires two steps to create a proper connection:

1. set_connection(path) - sets the connection path
2. set_value_empty() - marks the attribute as having no value

The Issue in Detail

Looking at the is_connection() method in src/prim-types.hh:1889:

bool is_connection() const { return _paths.size() && !has_value(); }

For an attribute to be considered a connection, it must:

• Have connection paths (_paths.size() > 0)
• AND not have a value (!has_value())

The reproduction code was only calling set_connection() but not set_value_empty(), so has_value() still returned true, making is_connection() return false. This caused the serialization code to skip the connection printing.

Correct Usage

The correct way to set up a connection (as shown in src/tydra/usd-export.cc:979-980):

// CORRECT - both steps required
surfaceShader.diffuseColor.set_connection(connPath);
surfaceShader.diffuseColor.set_value_empty();

Fixed Reproduction Code

The original issue had this incorrect code:

// INCORRECT - trying to access non-existent .connect member
node->diffuseColor.connect.set(Path(...));

The correct fix is:

// CORRECT
node->diffuseColor.set_connection(Path(pTex->absolute_path().full_path_name(), "outputs:rgb"));
node->diffuseColor.set_value_empty(); // CRITICAL: Required for proper connection

Solution Summary

This is a user API issue, not a bug in TinyUSDZ. The serialization works correctly when connections are properly set up. The issue occurs because:

1. The original reproduction code tried to use a non-existent .connect member
2. Even when using the correct set_connection() method, users must also call set_value_empty()
3. The API is somewhat unintuitive - requiring two separate calls to set up a connection

The serialization itself works correctly and produces the proper USD format: color3f inputs:diffuseColor.connect = <path> (not rel inputs:diffuseColor.connect as suggested in the issue).

Changes Made

✅ Added documentation comments to TypedAttributeWithFallback::set_connection() and set_connections() methods
✅ Created a fixed reproduction example showing the correct connection setup
✅ Committed changes and pushed to branch claude/issue-259-20250925-1550