Guía de estudio: de Stage Setting a Beyond Basics

El Stage Usd.Stage

El Stage es el scenegraph ya compuesto: el resultado de ensamblar uno o más layers, no un archivo en sí mismo. Es la vista unificada que USD te entrega para leer o autorar la jerarquía de prims.

• Composición es el algoritmo que ensambla layers en un stage; el root layer es el primer layer abierto y el ancla de la layer stack.
• Ventajas de trabajar sobre un stage: edición no destructiva (modularidad) y escalabilidad de datos grandes vía payloads.
• Los sublayers de un mismo stage pueden mezclar formatos (.usda + .usdc conviviendo).

Crear, abrir y guardar un stage

from pxr import Usd

stage = Usd.Stage.CreateNew("scene.usda")     # nuevo stage respaldado en disco
stage = Usd.Stage.Open("scene.usda")          # abre un stage existente
stage = Usd.Stage.CreateInMemory()            # solo en memoria, no toca disco

stage.GetRootLayer()                          # Sdf.Layer ancla de la layer stack
stage.Save()                                  # guarda todos los layers editados
stage.GetRootLayer().subLayerPaths.append("./lighting.usda")

Prims Usd.Prim

El prim es el bloque de construcción central: un contenedor que agrupa attributes y relationships, y que puede estar tipado (Sphere, Xform, Cube…) o quedar typeless como contenedor vacío.

• DefinePrim(path) sin tipo produce un prim typeless; para un tipo con API dedicada se usa el schema (p. ej. UsdGeom.Xform.Define).
• GetChild("Name") solo busca hijos directos, nunca nietos; si no existe devuelve un prim inválido.

Definir e inspeccionar prims

from pxr import UsdGeom

stage.DefinePrim("/World/Empty")              # prim typeless
UsdGeom.Xform.Define(stage, "/World/Xf")      # prim tipado vía schema API

prim = stage.GetPrimAtPath("/World/Xf")
prim.GetTypeName()
prim.GetChildren()
prim.GetProperties()
child = prim.GetChild("NoExiste")
bool(child)                                    # False si el prim es inválido

Prim & property paths Sdf.Path

Un path ubica de forma única un prim o una propiedad en el scenegraph. La raíz del stage es el pseudo-root /.

• Prim path: segmentos separados por / (/geo/box). Property path: un . tras el prim path (/geo/box.weight). Variant: llaves (/geo/box{size=large}).
• Usos típicos: identificar de forma única, navegar la jerarquía, especificar dónde autorar, y filtrar/query con Sdf.PathExpression.

Construir y validar paths

from pxr import Sdf

path = Sdf.Path("/World").AppendChild("Geometry")
path.IsPrimPath()
path.GetParentPath()

prim = stage.GetPrimAtPath("/World/NoExiste")
prim.IsValid()                                 # SIEMPRE validar tras GetPrimAtPath

prop_path = sphere.GetPath().AppendProperty("userProperties:tag")
owner_prim.CreateAttribute("userProperties:tag", Sdf.ValueTypeNames.String)

Attributes UsdAttribute

Un attribute es un par nombre–valor con un único tipo de dato (definido vía Sdf), que puede tener un valor por defecto y/o time samples para animación.

• Se prefiere la API específica del schema (GetRadiusAttr()) sobre manipular UsdAttribute genéricos a mano: es más clara y menos frágil ante cambios.
• Si nunca se autoró un valor, Get() devuelve el fallback del schema — ese valor no aparece escrito en el .usda.

Leer y escribir un attribute

sphere.GetRadiusAttr().Get()          # aplica value resolution
sphere.GetRadiusAttr().Set(100.0)     # autora un valor

cube.GetPrim().GetPropertyNames()
cube.GetPrim().GetAttributes()

Relationships UsdRelationship

Una relationship es una propiedad sin tipo de dato: almacena uno o más target paths que apuntan a otros prims, attributes u otras relationships, y se remapea automáticamente si el target cambia de ubicación.

• No es lo mismo que una attribute connection (que conecta dos attributes existentes entre sí); una relationship apunta desde cero a otros objetos.
• Ejemplo built-in: proxyPrim en UsdGeom.Imageable, que apunta un prim costoso a un proxy liviano para vista previa.

Crear y usar una relationship

from pxr import UsdShade

group.CreateRelationship("members", custom=True).SetTargets(
    [sphere.GetPath(), cube.GetPath()]
)
rel.GetTargets()
rel.AddTarget(path)

# material:binding es una relationship gestionada por una API schema
UsdShade.MaterialBindingAPI.Apply(prim).Bind(material)

Metadata

Pares nombre–valor no animables, adjuntos a prims, properties o layers, que viven fuera del modelo de datos del schema y se acceden como un diccionario.

• Metadata vs. attribute: metadata es info suplementaria fuera del schema y nunca tiene time samples; attribute es dato core del objeto y sí puede animarse.
• Las keys más comunes son assetInfo y customData; se pueden agregar keys nuevas vía schemas adicionales.

Leer y escribir metadata

prim.GetMetadata("customData")
prim.SetMetadata("customData", {"reviewed": True})
stage.SetMetadata("comment", "revisión interna")

prim.GetMetadataByDictKey("customData", "reviewed")   # más eficiente para 1 valor

Time codes & time samples

Un time code es un punto en el tiempo sin unidad intrínseca (como un frame), escalado por timeCodesPerSecond. Un time sample es el valor de un attribute en un time code puntual; entre samples se interpola linealmente.

• Con timeCodesPerSecond = 24, el time code 48.0 equivale a 2 segundos reales (48/24).
• Los time samples son animación "horneada" por frame — buenos para intercambio reproducible, no para reemplazar curvas de animación complejas (eso se hace en la DCC).

Autorar valores en el tiempo

stage.SetStartTimeCode(1)
stage.SetEndTimeCode(60)

cube.GetDisplayColorAttr().GetTimeSamples()
attr.Set(value, time=30)
xform_api.SetTranslate((0, -4.5, 0), time=30)

Formatos de archivo

USD define cuatro formatos nativos, cada uno pensado para un rol distinto en el pipeline.

• .usda — ASCII, legible por humanos; ideal para capas pequeñas de interfaz/agregación y para debugging o diffing.
• .usdc (Crate binary) — binario comprimido y memory-mapped; carga rápido y usa poca memoria, ideal para geometría pesada.
• .usd — puede ser ASCII o binario por dentro; se puede cambiar el formato interno sin romper referencias.
• .usdz — paquete zip atómico sin comprimir, pensado como read-only para distribución (p. ej. XR); no se usa mientras se sigue editando el asset.

Módulos de USD pxr

Para autoría y lectura básica alcanza con los paquetes base y usd; los módulos imaging/usdImaging entran en juego al renderizar.

• Usd — módulo cliente central: Stage, Prims, Properties, Metadata, arcos de composición.
• Sdf (Scene Description Foundation) — serialización a texto, SdfLayer, manejo de paths, creación de layers.
• Gf (Graphics Foundation) — álgebra lineal y tipos básicos (Gf.Vec3d, matrices) usados al leer/escribir attributes.
• Módulos de schema por dominio: UsdGeom, UsdShade, UsdPhysics, UsdLux…

from pxr import Usd, Sdf, Gf, UsdGeom

Schemas: IsA vs. API

Un schema es un blueprint que le da significado y capacidades a un prim. No necesariamente implementa comportamiento (p. ej. UsdPhysics no trae un motor de física): define el modelo de datos y las reglas de interpretación.

• IsA schemas dicen qué es el prim, vía metadata typeName. Un prim solo puede tener una. Pueden ser concretas (instanciables: UsdGeomMesh) o abstractas (solo sirven de base: UsdGeomPointBased).
• API schemas dicen qué puede hacer además: no tienen typeName, se listan en la metadata apiSchemas y se consultan con HasAPI. Pueden ser applied/non-applied y single/multiple-apply.
• Convención de nombre: sufijo "API"; propiedades namespaced en camelCase (RigidBodyAPI.CreateVelocityAttr() → atributo physics:velocity).

IsA vs. API en código

from pxr import UsdGeom, UsdPhysics

# IsA schema: define qué es el prim (typeName = Sphere)
sphere = UsdGeom.Sphere.Define(stage, "/World/Sphere")
sphere.GetRadiusAttr().Set(10)

# API schema: suma comportamiento a un prim ya tipado
rb_api = UsdPhysics.RigidBodyAPI.Apply(cube.GetPrim())
rb_api.CreateVelocityAttr(5)
cube.GetPrim().HasAPI(UsdPhysics.RigidBodyAPI)

Scope UsdGeom.Scope

Un contenedor puro de agrupación, análogo a una carpeta vacía: no es transformable ni representa geometría renderizable por sí mismo.

• Se usa para organizar materiales, geometría, animación o grupos de actores/entorno dentro de la jerarquía.
• Los hijos transformables dentro de un Scope se evalúan con normalidad, aunque el Scope mismo no aporte transform.

from pxr import UsdGeom

a_scope = UsdGeom.Scope.Define(stage, "/World/A_Scope")
prim.IsA(UsdGeom.Scope)

a_scope.GetPrim().SetActive(False)   # desactiva el scope y TODO su contenido

Xform UsdGeom.Xform

Un prim que almacena datos de transformación — traslación, rotación, escala — que afectan a todos sus hijos en la jerarquía. "Xform" es literalmente "transform".

• UsdGeomImageable es la base de todo lo visualizable; UsdGeomXformable encapsula el schema de lo transformable; UsdGeomXform es el schema concreto de un transform puro.
• Toda la geometría de UsdGeom es directamente transformable, porque hereda de Xformable.

xf = UsdGeom.Xform.Define(stage, "/World/Xf")
xf.GetXformOpOrderAttr()          # orden de las operaciones de transform
xf.AddXformOp(UsdGeom.XformOp.TypeTranslate)

XformCommonAPI

Una API schema no aplicada que estandariza un set común de operaciones — translate, rotate, scale y pivote — compatible entre herramientas de import/export.

• Fija el orden y el set de operaciones permitidas: se pierde la flexibilidad total de AddXformOp, se gana interoperabilidad y queries simples ("¿posición en el frame 101?").
• Compatibilidad se verifica evaluando el objeto como booleano.

xform_api = UsdGeom.XformCommonAPI(prim)
if not xform_api:
    raise ValueError("prim no compatible con XformCommonAPI")

xform_api.SetTranslate((10.0, 20.0, 30.0))
xform_api.SetRotate((45.0, 0.0, 90.0), UsdGeom.XformCommonAPI.RotationOrderXYZ)
xform_api.SetScale((2.0, 2.0, 2.0))

Lights UsdLux

UsdLux agrupa los schemas de iluminación: DistantLight (direccional), luces de área (Cylinder, Rect, Disk, Sphere), DomeLight y PortalLight. Todas son Xformable.

• Combinan atributos propios (color, vía su IsA schema) con atributos comunes de LightAPI (intensity).
• DistantLight emite a lo largo del eje -Z local del prim; por eso su dirección se controla rotando el prim, no moviéndolo.

from pxr import UsdLux, Gf

light = UsdLux.DistantLight.Define(stage, "/World/Sun")
light.GetColorAttr().Set(Gf.Vec3f(1.0, 0.95, 0.9))
light.GetIntensityAttr().Set(120.0)
UsdGeom.XformCommonAPI(light).SetRotate((45.0, 0.0, 0.0))

Materials & shaders UsdShade

UsdShade es el schema para crear materiales y hacerles bind a geometría. UsdShadeMaterial es el contenedor que guarda los datos de shading para un renderer.

• Definir un material no es lo mismo que aplicarlo: sin bind, el material existe en la jerarquía pero no afecta el render.
• El tratamiento completo de shaders/networks queda para módulos posteriores; aquí es solo otro ejemplo de "API específica de schema".

mat_scope = UsdGeom.Scope.Define(stage, box.GetPath().AppendPath("Materials"))
box_mat = UsdShade.Material.Define(stage, mat_scope.GetPath().AppendPath("BoxMat"))
# todavía sin bind: existe en la jerarquía, no se ve en el render

Layers Sdf.Layer

Un layer es un archivo o recurso único que contiene un subconjunto de datos de escena (geometría, materiales, animación…). Un Stage se compone combinando layer stacks en runtime.

• Puede ser .usd(a/c), un formato con plugin (.gltf, .fbx) o incluso no basarse en archivo (una base de datos).

layer.Reload()   # descarta opiniones no guardadas de esa capa
layer.Save()      # guarda el contenido de esa capa a disco

Default prim

El prim de nivel superior guardado como metadata de layer: el punto de entrada de un stage cuando se lo referencia sin especificar un prim path explícito.

• Vive como metadata del layer, no del prim.
• usdchecker marca error si falta; si se referencia un layer sin default prim, resuelve vacío + warning.

from pxr import Usd, UsdGeom, Sdf

stage = Usd.Stage.CreateInMemory()
root = UsdGeom.Xform.Define(stage, "/World").GetPrim()
stage.SetDefaultPrim(root)
assert stage.GetDefaultPrim() == root

Specifiers def / over / class

El specifier declara la intención de un prim spec: def (concreto, visitado por traversals por defecto), over (override de opiniones existentes, edición no destructiva, no crea el prim original) y class (abstracto/blueprint, target típico de reference/inherit/specialize).

• class se compone en el stage pero no es visitado por traversals por defecto.
• over es el specifier más débil: resuelve a def o class según lo que exista en otras capas.

prim.GetSpecifier()          # Sdf.SpecifierDef / SpecifierOver / SpecifierClass
prim.GetPrimStack()          # SdfPrimSpecs, de más fuerte a más débil
stage.CreateClassPrim("/_box")

-- usda --
def Cube "Box" { double size = 4 }
over "Box" { double size = 10 }
class "_box" { double size = 4 }

References

El arco de composición ("R" de LIVRPS) que compone un prim y sus descendientes sobre otro prim — la forma principal de ensamblar escenas grandes a partir de unidades modulares.

• Un arco de reference incluye identificador de layer (omitible si es interna) + prim path (omitible si el layer externo tiene default prim).
• Orden de composición: primero se compone el layer stack del prim referenciado, luego se agrega ese resultado al prim destino, y por último se aplican overrides adicionales sobre el destino.

ref_prim = stage.DefinePrim("/World/Box")
ref_prim.GetReferences().AddReference("./cube.usda")   # usa el default prim de cube.usda
ref_prim.GetReferences().ClearReferences()

-- usda --
def Xform "Box" ( prepend references = @./cubebox_a02/cubebox_a02.usd@ ) {}

Variant sets

Un conjunto nombrado de representaciones alternativas para un prim, intercambiables sin duplicar datos — útil para variantes de forma, de look/material o de LOD.

• La selección de variante puede autorearse en la misma capa que define el set, o en otra capa distinta que referencia el prim — cada referencia puede elegir una opción distinta.
• Las opiniones "dentro de una variante" solo se autoran usando el VariantEditContext.

vsets = prim.GetVariantSets()
vset = vsets.AddVariantSet("look")
vset.AddVariant("Painted")
vset.SetVariantSelection("Painted")

with vset.GetVariantEditContext():
    # las opiniones autoreadas aquí solo aplican si "Painted" está activa
    prim.GetAttribute("displayColor").Set([(0.8, 0.1, 0.1)])

Strength ordering: LIVRPS

El orden exacto, de más fuerte a más débil, en que USD resuelve opiniones en conflicto entre arcos de composición.

• Local — opiniones autoreadas directamente en una capa/sublayer.
• Inherits — propaga opiniones de un prim fuente a todo lo que le hace inherit (p. ej. cambiar todos los pinos de un bosque desde un único prim fuente).
• Variant sets — elige entre jerarquías alternativas.
• References — compone contenido de otra capa como subgrafo.
• Payloads — como reference, pero cargable/descargable en runtime.
• Specializes — autora un fallback: gana solo si nada más define un valor (típico en librerías de materiales).

Active / inactive prims

Todos los prims son active por defecto. Desactivar un prim es un borrado no destructivo (pruning) del stage compuesto: el prim sigue existiendo en la scene description.

• Desactivar excluye al prim (y a todos sus descendientes) de los traversals por defecto y de la composición visible.
• Es reversible por composición: una opinión más fuerte en otra capa puede reactivar un subárbol desactivado.

stage.GetPrimAtPath("/World/Parent").SetActive(False)
prim.IsActive()

Model kinds Kind

Kind es metadata a nivel de prim — no un tipo de schema — que clasifica el rol de un prim dentro de la jerarquía de modelo.

• component — asset autocontenido y referenceable; hoja del árbol de modelos.
• group / assembly — unidades organizativas de models relacionados; assembly combina varias partes en una entidad mayor.
• subcomponent — outlier: no es un model kind, solo marca nodos interiores relevantes dentro de un component (que no puede contener otros components).

from pxr import Usd, Kind

model_api = Usd.ModelAPI(prim)
model_api.SetKind(Kind.Tokens.component)
model_api.GetKind()
prim.IsModel()          # predicado: Usd.PrimIsModel

Custom properties

Propiedades definidas por el usuario, fuera de cualquier schema. custom=True es solo metadata informativa: no cambia el comportamiento del attribute.

• Custom properties vs. schemas custom: properties son rápidas y flexibles sin planificación previa; un schema requiere más diseño pero estandariza y agrupa datos de forma reutilizable.
• Como USD no tiene structs nativos, los namespaces anidados (organización:grupo:propiedad) son la convención estándar para agrupar datos compuestos.

attr = prim.CreateAttribute(
    "acme:sensor:temperature", Sdf.ValueTypeNames.Float, custom=True
)
attr.IsCustom()               # True
attr.SetDocumentation("Temperatura del sensor, en °C")

Primvars UsdGeom.PrimvarsAPI

"Primitive variables": attributes especiales bindeados a primitivas geométricas y disponibles para los shaders, con interpolación por vértice/cara y herencia por namespace.

• Usos típicos: UVs, vertex colors, datos de deformación/animación.
• Modos de interpolación: constant (un valor para todo el gprim), uniform (uno por cara), vertex (uno por punto).

primvar_api = UsdGeom.PrimvarsAPI(prim)
primvar_api.CreatePrimvar(
    "displayColor", Sdf.ValueTypeNames.Color3fArray, interpolation="vertex"
).Set([Gf.Vec3f(0.0, 1.0, 0.0)])

Units

No toda la metadata de unidades se reconcilia igual entre capas: timeCodesPerSecond se reescala automáticamente; upAxis, metersPerUnit y kilogramsPerUnit no — los valores geométricos se copian literalmente sin conversión.

• Fallbacks si no se autora nada: metersPerUnit = 0.01 (cm), upAxis = "Y".
• Tabla de metersPerUnit: km=1000, m=1.0, cm=0.01, mm=0.001, in=0.0254, ft=0.3048.

UsdGeom.SetStageMetersPerUnit(stage, 0.0254)     # pulgadas
UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.z)
UsdPhysics.SetStageKilogramsPerUnit(stage, 0.001)  # kg vía UsdPhysics, no UsdGeom

Value resolution

Cómo USD determina el valor final de una property o metadata combinando todas las capas que opinan sobre ella. No es lo mismo que composición.

• La composición se cachea por prim; la value resolution no se cachea — se recalcula en cada Get() (usar UsdAttributeQuery para cachear manualmente).
• Reglas por tipo de dato: metadata general gana la opinión más fuerte; customData se combina elemento por elemento (merge por key); relationships combinan todos los targets vía list-editing.

attr.Get()                              # == Get(Usd.TimeCode.Default()) -> valor NO animado
attr.Get(100)                           # valor resuelto en el timecode 100
attr.Get(Usd.TimeCode.EarliestTime())   # primer sample real

Stage traversal Usd.PrimRange

Recorrer el scenegraph en profundidad (depth-first). Stage.Traverse() es un wrapper que arranca en el pseudo-root; Usd.PrimRange(prim) arranca en un prim dado.

• Predicados combinables con operadores bitwise (&, |, ~) — nunca and/or/not.
• Predicado default de Traverse(): active + loaded + defined + no abstracto.
• PruneChildren() sobre el iterador salta la visita a todo un subárbol.

predicate = Usd.PrimIsActive & Usd.PrimIsLoaded    # bitwise, no 'and'

stage.Traverse()                       # con predicado default
stage.TraverseAll()                    # sin filtrar, incluye inactive/abstract

it = iter(Usd.PrimRange(root_prim, predicate))
for prim in it:
    if prim.GetName() == "Hidden":
        it.PruneChildren()

Hydra

La arquitectura de rendering de OpenUSD: el puente entre los datos de escena y un backend de render concreto.

• Scene delegate — provee la información de la escena.
• Render index — rastrea cambios y gestiona la escena a renderizar.
• Render delegate — combina render index + scene delegate para generar la imagen final (ej. HdStorm, usado por usdview; también Arnold, RenderMan vía plugins).