API Reference

grill.cook

Inspecting, authoring and editing foundational tools for the pipeline.

grill.cook.Repository

contextvars.ContextVar for the global asset repository location.

It’s value must always be set to a pathlib.Path.

Attention

By default, no value has been set. Ensure to set it before performing any creation operation.

Example:

>>> Repository.get()  # not set
Traceback (most recent call last):
  File "<input>", line 1, in <module>
LookupError: <ContextVar name='Repository' at 0x00000207F0A12B88>
>>> import tempfile
>>> from pathlib import Path
>>> Repository.set(Path(tempfile.mkdtemp()))
<Token var=<ContextVar name='Repository' at 0x00000213A46FF900> at 0x00000213C6A9F0C0>
>>> Repository.get()
WindowsPath('C:/Users/CHRIST~1/AppData/Local/Temp/tmp767wqaya')

grill.cook.create_many(taxon, names, labels=())

Create a new taxon member for each of the provided names.

When creating hundreds or thousands of members, this provides a considerable performance improvement over create_unit().

The new members will be created as prims on the given taxon’s stage. :rtype: List[Prim]

See also

define_taxon() create_unit()

grill.cook.create_unit(taxon, name, label='')

Create a unit member of the given taxon, with an optional display label.

The new member will be created as a prim on the given taxon’s stage.

See also

define_taxon() and create_many()

Parameters:

• taxon (Prim) –

• name (str) –

• label (str) –

Return type:

Prim

grill.cook.define_taxon(stage, name, *, references=(), id_fields=mappingproxy({}))

Define a new taxon group for asset taxonomy.

If an existing taxon with the provided name already exists in the stage, it is used.

The new taxon can extend from existing taxa via the references argument.

Optional field=value items can be provided for identification purposes via id_fields.

Return type:

Prim

Returns:

Prim representing the taxon group.

Parameters:

• stage (Stage) –

• name (str) –

• references (tuple[Prim]) –

• id_fields (Mapping[str, str]) –

grill.cook.fetch_stage(identifier, context=None, load=Usd.Stage.LoadAll)

Retrieve the stage whose root layer matches the given identifier.

If the layer does not exist, it is created in the repository.

If an open matching stage is found on the global cache, return it. Otherwise open it, populate the cache and return it.

Attention

identifier must be a valid grill.names.UsdAsset name.

Parameters:

context (Optional[ResolverContext]) –

Return type:

Stage

grill.cook.itaxa(prims, taxon, *taxa)

Yields prims that are part of the given taxa.

grill.cook.spawn_many(parent, child, paths, labels=[])

Spawn many instances of a prim unit as descendants of another.

• Both parent and child must be existing units in the catalogue.

• paths can be relative or absolute. If absolute, they must include parent’s path as a prefix.

• A valid Model Hierarchy is preserved by:

  1. Turning parent into an assembly if child is a Model.

  2. Ensuring intermediate prims between parent and spawned children are also models.

  3. Setting explicit instanceable. on spawned children that are components.

See also

spawn_unit() and create_unit()

Parameters:

• parent (Prim) –

• child (Prim) –

• paths (list[Path]) –

• labels (list[str]) –

grill.cook.spawn_unit(parent, child, path=Sdf.Path.emptyPath, label='')

Spawn a unit prim as a descendant of another.

• Both parent and child must be existing units in the catalogue.

• If path is not provided, the name of child will be used.

• A valid Model Hierarchy is preserved by:

  1. Turning parent into an assembly.

  2. Ensuring intermediate prims between parent and child are also models.

  3. Setting explicit instanceable. on spawned children that are components.

See also

spawn_many() and create_unit()

grill.cook.taxonomy_context(stage)

Get an edit context where edits will target this stage’s taxonomy layer.

Attention

If a valid taxonomy layer is not found on the layer stack, one is added to the stage.

Parameters:

stage (Stage) –

Return type:

EditContext

grill.cook.unit_asset(prim)

Get the asset layer that acts as the ‘entry point’ for the given prim.

Parameters:

prim (Prim) –

Return type:

Layer

grill.cook.unit_context(prim)

Get an edit context where edits will target this prim’s unit root layer.

Parameters:

prim (Prim) –

Return type:

EditContext

class grill.cook.UsdAsset(*args, sep='-', **kwargs)

Specialized grill.names.CGAssetFile name object for USD asset resources.

Inheritance Diagram for UsdAsset

This is the currency for USD asset identifiers in the pipeline.

Examples:

>>> asset_id = UsdAsset.get_default()
>>> asset_id
UsdAsset("demo-3d-abc-entity-rnd-main-atom-lead-base-whole.1.usda")
>>> asset_id.suffix = 'usdc'
>>> asset_id.version = 42
>>> asset_id
UsdAsset("demo-3d-abc-entity-rnd-main-atom-lead-base-whole.42.usdc")
>>> asset_id.suffix = 'abc'
Traceback (most recent call last):
...
ValueError: Can't set invalid name 'demo-3d-abc-entity-rnd-main-atom-lead-base-whole.42.abc' on UsdAsset("demo-3d-abc-entity-rnd-main-atom-lead-base-whole.42.usdc"). Valid convention is: '{code}-{media}-{kingdom}-{cluster}-{area}-{stream}-{item}-{step}-{variant}-{part}.{pipe}.{suffix}' with pattern: '^(?P<code>\w+)\-(?P<media>\w+)\-(?P<kingdom>\w+)\-(?P<cluster>\w+)\-(?P<area>\w+)\-(?P<stream>\w+)\-(?P<item>\w+)\-(?P<step>\w+)\-(?P<variant>\w+)\-(?P<part>\w+)(?P<pipe>(\.(?P<output>\w+))?\.(?P<version>\d+)(\.(?P<index>\d+))?)(\.(?P<suffix>sdf|usd|usda|usdc|usdz))$'

See also

grill.names.CGAsset for a description of available fields, naming.Name for an overview of the core API.

Note

This class is defined on the grill.names module but is exposed here for convenience.

Hint

For quick prototyping, grill.names.UsdAsset.get_anonymous() can be used to get temporary but valid grill identifiers.

grill.usd

Helpers for USD workflows which do not know anything about the pipeline.

grill.usd.common_paths(paths)

For the given paths, get those which are the common parents.

Parameters:

paths (Iterable[Path]) –

Return type:

List[Path]

grill.usd.edit_context(obj, /, *args, **kwargs)

Composition arcs target layer stacks. These functions help create EditTargets for the first matching node’s root layer stack from prim’s composition arcs.

This allows for “chained” context switching while preserving the same stage objects. :rtype: EditContext

Tip

You can try the below code snippet on USDView (or any other USD DCC application) Just swap the main = Usd.Stage.CreateInMemory() assignment for a stage on the viewport, e.g, for USDView:

>>> main = usdviewApi.stage

Then paste the rest of the code as-is:

Example:

>>> from pxr import Usd, UsdGeom, Sdf
>>> main = Usd.Stage.CreateInMemory()
>>> # Jump between 3 different layer stacks adding variants to the same set
>>> # main [variant blue] -> reference [variant green] -> payload [variant red]
>>> referenced = Usd.Stage.CreateInMemory()
>>> referenced.SetDefaultPrim(referenced.DefinePrim("/Referenced"))
>>> reference = Sdf.Reference(referenced.GetRootLayer().identifier)
>>>
>>> payloaded = Usd.Stage.CreateInMemory()
>>> payloaded.SetDefaultPrim(payloaded.DefinePrim("/Payloaded"))
>>> payload = Sdf.Payload(payloaded.GetRootLayer().identifier)
>>>
>>> top = main.DefinePrim("/Top")
>>> top.GetReferences().AddReference(reference)
True
>>> import grill.usd as gusd
>>> with gusd.edit_context(reference, top):
...     top.GetPayloads().AddPayload(payload)
...     with gusd.edit_context(payload, top):
...         geom = UsdGeom.Sphere.Define(main, top.GetPath().AppendPath("inner/child"))
...         color = geom.GetDisplayColorAttr()
...         color_set = geom.GetPrim().GetVariantSets().AddVariantSet("color")
...         color_set.AddVariant("from_payload")
...         color_set.SetVariantSelection("from_payload")
...         with gusd.edit_context(color_set, payloaded.GetRootLayer()):  # color_set.GetVariantEditContext() would fail here
...             color.Set([(1,0,0)])
...         color_set.ClearVariantSelection()
...     color_set.AddVariant("from_reference")
...     color_set.SetVariantSelection("from_reference")
...     with gusd.edit_context(color_set, referenced.GetRootLayer()):
...         color.Set([(0,1,0)])
...     color_set.ClearVariantSelection()
...
True
>>> color_set.AddVariant("from_top")
>>> color_set.SetVariantSelection("from_top")
>>> with color_set.GetVariantEditContext():
...     color.Set([(0,0,1)])
...
>>> color_set.ClearVariantSelection()
True
>>> for each in main, referenced, payloaded:
...     print(each.GetRootLayer().ExportToString())
...
#usda 1.0
def "Top" (
    prepend references = @anon:0000019B6BE92A70:tmp.usda@
)
{
    over "inner"
    {
        over "child" (
            prepend variantSets = "color"
        )
        {
            variantSet "color" = {
                "from_top" {
                    color3f[] primvars:displayColor = [(0, 0, 1)]
                }
            }
        }
    }
}
#usda 1.0
(
    defaultPrim = "Referenced"
)
def "Referenced" (
    prepend payload = @anon:0000019B6BE93270:tmp.usda@
)
{
    over "inner"
    {
        over "child" (
            prepend variantSets = "color"
        )
        {
            variantSet "color" = {
                "from_reference" {
                    color3f[] primvars:displayColor = [(0, 1, 0)]
                }
            }
        }
    }
}
#usda 1.0
(
    defaultPrim = "Payloaded"
)
def "Payloaded"
{
    def "inner"
    {
        def Sphere "child" (
            prepend variantSets = "color"
        )
        {
            variantSet "color" = {
                "from_payload" {
                    color3f[] primvars:displayColor = [(1, 0, 0)]
                }
            }
        }
    }
}

grill.usd.iprims(stage, root_paths=(), prune_predicate=None, traverse_predicate=<pxr.Usd._PrimFlagsConjunction object>)

Convenience function that creates a generator useful for common prim traversals.

Without keyword arguments, this is the same as calling Usd.Stage.Traverse(…), so use that instead when no root_paths or prune_predicates are needed.

Parameters:

• stage (Stage) –

• root_paths (Iterable[Path]) –

• prune_predicate (Optional[Callable]) –

Return type:

Iterator[Prim]