The Content Layer

✨ New in Katana 8.5

Introduction

The Content Layer is a usg.Layer that acts as the source of truth for the UsdSuperLayer and its derived node types. The Content Layer can be interacted with and edited directly via Katana’s Python API, or via the Parameter UI of the UsdSuperLayer-derived node types.

When a change occurs in the Content Layer via Python, it is not automatically reflected in the UI and it is necessary to manually sync the changes to the node’s parameters to ensure that the UI reflects the contents of the Content Layer and that parity between the two is maintained. This is because when the Content Layer is edited, the mechanism that normally updates the node’s parameters is bypassed. This is in contrast to node types in the Geolib family, where changes to a node’s attributes are automatically synced with the UI and the node’s parameters are updated accordingly.

Changes made in the UI of the UsdSuperLayer-derived node and its parameters are automatically synced to the Content Layer, and do not require an additional sync.

If a change is present in the Content Layer, that change is treated as the source of truth regardless of if a sync occurs. To validate changes, the values of attributes can be viewed via the Attributes tab, or by calling the value of a specified Attribute, Relationship or Metadata type via the Python tab and the data type’s appropriate API calls.

Overview

This section describes how to sync attributes between the Content Layer and the UsdSuperLayer-derived node type.

To access the Content Layer, it is required to retrieve the StageSubtreeController. The StageSubtreeController is the counterpart to the Scene Tree present on UsdSuperLayer-derived nodes, and must be declared before the Content Layer can be accessed and updated.

For more information on the StageSubtreeController, see Basic API Usage.

Examples

UsdSuperLayerExampleParametersHandlerPlugin.py

# Copyright (c) 2025 The Foundry Visionmongers Ltd. All Rights Reserved.
"""
Module containing an example UsdSuperLayer Content Layer.
"""

import usg
from Katana import NodegraphAPI

light_types = [
    "CylinderLight",
    "DiskLight",
    "DistantLight",
    "DomeLight",
    "DomeLight_1",
    "GeometryLight",
    "MeshLight",
    "PortalLight",
    "RectLight",
    "SphereLight",
    "VolumeLight",
]

super_tool = NodegraphAPI.CreateNode("UsdSuperLayer", NodegraphAPI.GetRootNode())
controller = super_tool.getStageSubtreeController()

# Check if the super_tool is a UsdSuperLayer and create the Material prim
if super_tool.getType() == "UsdSuperLayer":
    controller.createPrim("Material", "Material", usg.PrimSpecifier.Def)

for light in light_types:
    if light == "MeshLight":
        prim = controller.createPrim(f"{light}_{light}", "Cube", usg.PrimSpecifier.Def)
        prim.addAppliedSchema("MeshLightAPI", usg.ListPosition.PrependFront)

    elif light == "VolumeLight":
        prim = controller.createPrim(f"{light}_{light}", "Sphere", usg.PrimSpecifier.Def)
        prim.addAppliedSchema("VolumeLightAPI", usg.ListPosition.PrependFront)

    else:
        controller.createPrim(f"{light}_{light}", light, usg.PrimSpecifier.Def)

super_tool.syncLayerAndParameters()

API

UsdLayerSuperTool.syncLayerAndParameters() → bool

Reserializes the content layer, updates the internal state in the node, and rebuilds parameters for the target prim if the serialized content layer has changed.

Returns:: bool – Whether the serialized content layer has changed compared to the previous call.